OpenClaw 企业微信插件报错“Media exceeds 5MB limit”的解决方法

最近在使用 OpenClaw 企业微信插件接收音频文件时，遇到了一个文件大小限制问题。

当用户通过企业微信发送一个超过 5MB 的音频文件时，OpenClaw 日志显示文件已经成功下载和解密，但随后又报错：

[wecom] Downloading and decrypting file...
[wecom] File downloaded successfully
[wecom] File downloaded and decrypted successfully
[wecom] File downloaded: size=9020176, contentType=video/mp4, filename=20260624_085423.m4a
[wecom] Failed to download file: Error: Media exceeds 5MB limit

这个音频文件大约为 9MB，因此触发了企业微信插件默认的 5MB 媒体文件限制。

本文介绍如何将 OpenClaw 企业微信插件的媒体文件上限从 5MB 修改为 20MB。

一、问题原因

从日志可以看出，文件下载和解密其实都已经成功：

File downloaded successfully
File downloaded and decrypted successfully

真正失败的位置是：

Media exceeds 5MB limit

这说明问题不是企业微信无法下载文件，也不是 M4A 音频格式不支持，而是 OpenClaw 企业微信插件在保存媒体文件前进行了大小检查。

在部分版本的 @wecom/wecom-openclaw-plugin 中，媒体文件大小会读取下面这个配置：

agents.defaults.mediaMaxMb

如果没有设置，插件会使用默认值：

5MB

因此，只需要在 openclaw.json 中增加 mediaMaxMb 配置即可。

二、修改 openclaw.json

找到 OpenClaw 的配置文件：

/home/node/.openclaw/openclaw.json

在下面的位置：

"agents": {
  "defaults": {
  }
}

添加：

"mediaMaxMb": 20

修改后的配置示例：

{
  "agents": {
    "defaults": {
      "model": "qwen3.5-plus/qwen3.5-plus",
      "mediaMaxMb": 20,
      "workspace": "/home/node/.openclaw/workspace",
      "compaction": {
        "mode": "safeguard"
      },
      "maxConcurrent": 4,
      "subagents": {
        "maxConcurrent": 8
      }
    }
  }
}

需要注意，配置项必须放在：

agents.defaults.mediaMaxMb

不要放到下面这些位置：

channels.wecom.mediaMaxMb
tools.mediaMaxMb
gateway.mediaMaxMb

否则当前版本的企微插件可能读取不到。

三、通过命令行修改

如果不想手动编辑 JSON，也可以使用 OpenClaw 命令修改：

openclaw config set agents.defaults.mediaMaxMb 20

查看配置是否生效：

openclaw config get agents.defaults.mediaMaxMb

正常情况下会返回：

20

然后重启 OpenClaw Gateway：

openclaw gateway restart

四、Docker 部署环境的修改方法

如果 OpenClaw 运行在 Docker 容器中，需要特别注意：

在宿主机直接执行 openclaw config set，可能修改的是宿主机上的配置，而不是容器正在读取的配置。

假设容器名称是：

openclaw1-openclaw-gateway-1

可以直接在运行中的容器内执行：

docker exec openclaw1-openclaw-gateway-1 \
  openclaw config set agents.defaults.mediaMaxMb 20

检查配置：

docker exec openclaw1-openclaw-gateway-1 \
  openclaw config get agents.defaults.mediaMaxMb

返回结果应为：

20

然后重启容器：

docker restart openclaw1-openclaw-gateway-1

五、检查容器实际读取的配置文件

如果修改后依然提示 5MB，可以直接读取容器内的配置：

docker exec openclaw1-openclaw-gateway-1 sh -lc \
'node -e "const c=require(\"/home/node/.openclaw/openclaw.json\"); console.log(c.agents?.defaults?.mediaMaxMb)"'

正确结果应该是：

20

如果返回：

undefined

说明配置没有写入容器实际使用的 openclaw.json。

此时可以查看 Docker 的目录挂载关系：

docker inspect openclaw1-openclaw-gateway-1 \
  --format '{{range .Mounts}}{{println .Source "->" .Destination}}{{end}}'

可能会看到：

/opt/openclaw/data -> /home/node/.openclaw

这表示容器中的：

/home/node/.openclaw/openclaw.json

实际对应宿主机的：

/opt/openclaw/data/openclaw.json

应当修改宿主机左侧目录中的配置文件，然后重新启动容器：

docker restart openclaw1-openclaw-gateway-1

六、使用 Docker Compose 时的注意事项

如果通过 Docker Compose 部署，需要确认配置目录是否做了持久化挂载。

例如：

services:
  openclaw-gateway:
    volumes:
      - ./openclaw-data:/home/node/.openclaw

此时应修改：

./openclaw-data/openclaw.json

如果只在容器内部修改文件，但没有持久化挂载，那么重新创建容器后，配置可能会丢失。

修改配置后可以执行：

docker compose restart

如果需要重新创建容器：

docker compose up -d --force-recreate

重新创建前，要确保 openclaw.json 已经保存在宿主机挂载目录中。

七、可选：同时设置音频处理上限

agents.defaults.mediaMaxMb 主要解决企微插件接收文件时的 5MB 限制。

如果后续还需要让 OpenClaw 的音频识别工具处理大文件，可以同时设置：

{
  "tools": {
    "media": {
      "audio": {
        "enabled": true,
        "maxBytes": 20971520
      }
    }
  }
}

其中：

20971520 = 20 × 1024 × 1024

也就是 20MB。

命令行设置方式：

openclaw config set tools.media.audio.enabled true
openclaw config set tools.media.audio.maxBytes 20971520

但是需要注意：

tools.media.audio.maxBytes

和：

agents.defaults.mediaMaxMb

是两个不同阶段的限制。

如果日志明确显示：

Media exceeds 5MB limit

应该优先修改：

agents.defaults.mediaMaxMb

八、如何确认问题已经解决

重启容器后，再通过企业微信发送一个超过 5MB、小于 20MB 的音频文件。

例如发送一个大约 9MB 的 M4A 文件。

之前的日志会显示：

File downloaded: size=9020176
Failed to download file: Error: Media exceeds 5MB limit

修改成功后，不应该再出现：

Media exceeds 5MB limit

文件应该能够继续进入 OpenClaw 的媒体保存、音频识别或消息处理流程。

可以实时查看日志：

docker logs -f openclaw1-openclaw-gateway-1

如果使用 Docker Compose：

docker compose logs -f openclaw-gateway

九、仍然报 5MB 限制怎么办

如果已经设置了：

"mediaMaxMb": 20

但依然提示 5MB，可以按照下面的顺序排查。

1. 配置位置是否正确

必须是：

{
  "agents": {
    "defaults": {
      "mediaMaxMb": 20
    }
  }
}

2. JSON 是否有效

可以使用 Node.js 检查：

node -e "JSON.parse(require('fs').readFileSync('/home/node/.openclaw/openclaw.json','utf8')); console.log('JSON OK')"

3. 容器是否读取了另一份配置

执行：

docker inspect openclaw1-openclaw-gateway-1 \
  --format '{{range .Mounts}}{{println .Source "->" .Destination}}{{end}}'

确认真实的宿主机挂载目录。

4. 容器是否已经重启

执行：

docker restart openclaw1-openclaw-gateway-1

5. 插件是否存在硬编码限制

可以搜索插件代码：

docker exec openclaw1-openclaw-gateway-1 sh -lc \
'grep -Rni "mediaMaxMb\|5MB limit\|DEFAULT_MEDIA_MAX_MB" /home/node/.openclaw/extensions/wecom-openclaw-plugin | head -30'

如果代码中出现类似：

const mediaMaxMb =
  config.agents?.defaults?.mediaMaxMb ?? 5;

说明配置项正确，只是当前运行实例没有读取到新配置。

十、关于 M4A 显示为 video/mp4

日志中可能出现：

contentType=video/mp4
filename=20260624_085423.m4a

这通常不代表文件被识别成了真正的视频。

M4A 使用的是 MP4 容器格式，因此部分系统会把 MIME 类型识别为：

video/mp4

这次失败的直接原因不是 MIME 类型，而是：

Media exceeds 5MB limit

只要文件能够正常保存，后续仍然可以根据扩展名或实际编码进行音频识别。

十一、安全提醒

排查 OpenClaw 配置时，不要把完整的 openclaw.json 直接发布到公开论坛或 GitHub Issue。

配置文件通常包含：

模型 API Key
企业微信 Secret
机器人 Secret
Gateway Token
第三方服务访问地址

分享配置前，应替换为：

{
  "apiKey": "***",
  "secret": "***",
  "token": "***"
}

如果已经公开过真实密钥，应立即在对应平台中将旧密钥作废，并重新生成。

总结

OpenClaw 企业微信插件出现：

Media exceeds 5MB limit

通常是因为插件默认使用了 5MB 的媒体文件上限。

核心解决方法是在 openclaw.json 中增加：

{
  "agents": {
    "defaults": {
      "mediaMaxMb": 20
    }
  }
}

Docker 用户还需要确认修改的是容器实际读取的配置文件，并在修改后重启容器：

docker restart openclaw1-openclaw-gateway-1

完成后，原本被 5MB 限制拦截的 9MB M4A 音频文件就可以继续进入 OpenClaw 的后续处理流程。