跳转到内容

发送与下载附件

在桌面端或 Web 客户端中,可点击附件按钮、直接粘贴文件或图片,或将文件拖放到消息输入框中。可在发送前检查或移除已暂存的文件,点击 发送 会将输入文本和各个文件作为独立消息分别发出。JPEG、PNG、GIF 和 WebP 文件将作为图片发送;MOV、MP4、3GP、3G2 和 MJ2 文件将作为视频发送;其他格式均作为普通文件附件发送。客户端会校验所连接 Hub 的规格上限;本地合成预览的限制较原生 Hub 更小。

可通过 CLI、HTTP API 或 OpenClaw 发送各类附件。普通文件上限为 512 MiB (536,870,912 字节)。具体限制视选择的发送类型而定:

发送类型最大原始体积
普通文件 (File)536,870,912 字节
视频 (Video)536,870,912 字节 (512 MiB)
图片 (Image) 或语音 (Voice)各 26,214,383 字节 (25 MiB 减 17 字节)
表情 (Sticker)准备好的 GIF,以及可用的“我的表情”或已添加表情包引用;参见表情

文件附件会严格保留源文件的每一个原始字节。发送图片时可能会缩放或重新编码。语音发送支持 WAV、MP3、M4A、AAC、FLAC、Ogg(包含 .opus)、WebM、CAF 或 AMR 音频,并将其转为语音消息。参考视频与图片画质了解发送前的预处理,以及接收时如何选择画质副本。

CLI

  1. 发送文件,并允许最长 1 小时用于上传、下载校验及提交:

    Terminal window
    wx messages send filehelper --file ./report.pdf --wait 3600 \
    --idempotency-key report-2026-10

    --wait 单位为秒;默认为 30 秒,附件发送任务支持最长等待 3,600 秒。--detach 可使命令立即返回。

  2. 等待结束后,可通过命令查询任务详情:

    Terminal window
    wx jobs get JOB_ID

    在 Daemon 校验已上传字节期间,任务信息会包含以下字段:

    Phase: readback
    State: running

    请妥善保存任务 ID 和幂等键。结束等待不会影响 Daemon 继续处理。

HTTP API 与 SDK

  1. 通过 GET /v1/accounts/{account}/capabilities 检查当前连接的 Daemon 的限制指标:

    {
    "mediaUploadMaxBytes": 536870912,
    "mediaSendMaxBytes": {
    "file": 536870912,
    "image": 26214383,
    "video": 536870912,
    "voice": 26214383
    }
    }

    mediaUploadMaxBytes 限制暂存大小。在为特定发送类型暂存数据前,请检查 mediaSendMaxBytes[kind]。

  2. 先暂存单个文件,随后将其返回的 id 作为 sourceId 进行提交:

    Terminal window
    curl -H "Authorization: Bearer $TOKEN" -F 'file=@report.pdf' \
    "$WX/accounts/$ACCOUNT/uploads"
    curl -X POST -H "Authorization: Bearer $TOKEN" \
    -H 'Content-Type: application/json' -H 'Idempotency-Key: report-2026-10' \
    -d '{"threadId":"filehelper","kind":"file","sourceId":"SOURCE_ID"}' \
    "$WX/accounts/$ACCOUNT/sends"

    此处 WX 变量以 /v1 结尾。发送接口返回 HTTP 202 及任务信息。轮询 GET /jobs/{id};对于大文件最多可等待 1 小时。

    TypeScript SDK 提供了相同的工作流封装:

    const source = await client.upload(accountId, bytes, "report.pdf");
    const job = await client.sendMedia(accountId, {
    threadId: "filehelper", kind: "file", sourceId: source.id,
    standardSourceId: null, thumbnailSourceId: null,
    playSeconds: null, durationMs: null,
    }, "report-2026-10");
    const progress = await client.job(accountId, job.id);

    SDK 上传支持字节数组或 Blob;使用 Node 的 openAsBlob 可以避免一次性将整个大文件读入内存。由 @agent-wechat/shared 导出的 NATIVE_MAX_SOURCE_BYTES 为暂存上限。

下载文件

普通文件与接收到的视频下载最高支持 512 MiB。文件及原始视频副本必须与消息中声明的大小和 MD5 一致。对于普通视频,微信可能会选择另一份副本;Daemon 会在提供该副本之前校验其返回的校验值和大小。请使用以下命令下载:

Terminal window
wx messages media filehelper MESSAGE_ID --output ./saved.pdf --wait 3600

CLI 会在发布输出文件前校验大小与 SHA-256。SDK 客户端可以使用 mediaContentStream 并传入 { maxBytes: NATIVE_MAX_SOURCE_BYTES };默认拉取上限为 128 MiB。保存数据流时请检查所选资源的大小和 SHA-256。

微信视频号卡片包含两项资源:封面(image 缩略图)和帖子中的视频(video,normal)。视频不会自动下载。请像请求其他附件一样请求它:

Terminal window
wx messages media filehelper MESSAGE_ID --quality normal --output ./post.mp4 --wait 600

每次请求都会向微信重新获取一份帖子副本,因此已删除或设为私密的帖子会返回 channels_post_unavailable。已下载的视频保存在 Daemon 自己的媒体文件中,而不在微信 Profile 中。如果该文件被删除,下次请求时会重新下载。

OpenClaw

在配置中设置 channels.agent-wechat.mediaMaxMb 以放行预期的附件大小。例如设为 512 允许最高 512 MiB 的文件。扩展在暂存前会取该配置与具体发送类型上限的较小值。调高该值无法突破 Daemon 对各发送类型的限制。

普通音频文件将作为文件发送;若指定 audioAsVoice 则作为语音消息发送。对于较大的普通文件,OpenClaw 会进行最长一小时的任务轮询。若轮询超时,请记录返回的任务 ID 并主动查询,切勿直接重复发起发送。

使用 OpenClaw 的 asDocument/forceDocument 选项可以将媒体文件作为普通文件发送。视频质量选项仅适用于视频发送。

当有人发送视频号卡片时,智能体会获得该帖子的发布者、描述和时长,以及封面图片。只有通过卡片的消息 ID 调用 wechat_media(或 wechat_archive_media)时,它才会下载视频;quality: "thumbnail" 则返回封面。