# OpenClaw WeCom 插件 v2.3.19 变更简报

> [!TIP]
> `v2.3.19` 主要修了四件和真实使用强相关的问题：第一，本机图片/文件终于能更自然地发出去，不再默认只认 OpenClaw 自己目录里的文件；第二，走 Bot WebSocket 时，`dynamicAgents` 也会真正生效，不会再出现“同样开了动态路由，但 WS 会话还是串到主 Agent”这种割裂行为；第三，媒体大小上限开始统一跟随 OpenClaw 标准配置 `mediaMaxMb`，不再是 WeCom 插件自己一套、OpenClaw 主配置又是一套；第四，Bot WS 对话里的图片/文件现在会尽量留在当前 Bot WS 对话里发送，不再静默切到 Agent 私聊链路。

## 2026-03-19（v2.3.19）
- 【修复 WS 不走 dynamicAgents】**[重要修复]** 之前 `dynamicAgents` 只在旧消息链路上生效，新的 Bot WebSocket 统一运行时没有把这层路由覆盖带进去。结果就是，同样一份配置，在 Webhook 或 Agent 路径上能按“每个用户 / 每个群”隔离会话，但走 WS 时却可能重新落回主 Agent。现在 WS 运行时也会执行同样的动态路由逻辑，单聊、群聊的隔离行为终于统一了。
- 【修正 Bot WS 对话里的媒体回落策略】**[重要修复]** 如果当前消息本来就在 Bot WS 对话流里，图片/文件发送现在会优先并固定留在同一个 Bot WS 会话内处理。一旦已经尝试过 WS 发送，就不再静默回落到 Agent 私聊链路，避免用户明明在一个 Bot 对话里操作，结果媒体却从另一个 Agent 会话发出来。这个调整只针对 Bot WS，对 Bot Webhook 模式没有影响。
- 【统一媒体大小配置到 OpenClaw 标准】之前 WeCom 插件内部主要认自己的 `channels.wecom.media.maxBytes`，而不是 OpenClaw 通用的 `mediaMaxMb`。这会带来一个很直接的问题：你明明已经在 OpenClaw 里把媒体大小放宽了，WeCom 这边却还像没看见一样。现在插件会优先读取 `channels.wecom.mediaMaxMb`，并支持 `channels.wecom.accounts.<accountId>.mediaMaxMb` 做账号级覆盖；旧的 `channels.wecom.media.maxBytes` 仍然保留兼容，但只作为历史配置兜底。
- 【补齐 Bot WS 媒体发送链路的大小透传】Bot WS 在读取本地文件、下载远程媒体并上传到企业微信前，现在会真正带上解析后的 `mediaMaxMb` 上限，而不是继续走内部固定值。换句话说，媒体大小限制终于从“写在配置里”和“运行时真的执行”两边对齐了。
- 【放宽本地文件默认可发送目录】之前本地媒体白名单更偏向 OpenClaw 自己的状态目录，所以像 `~/Downloads/01.png` 这种很自然的用户文件路径，虽然文件确实存在，也会被当成“不允许发送”。现在插件默认额外放行常见用户目录：`~/Desktop`、`~/Documents`、`~/Downloads`、`~/Movies`、`~/Pictures`。对普通用户来说，这意味着“桌面、下载、图片目录里的文件”现在默认就更符合直觉地可发送了。
- 【支持继续追加自定义本地媒体目录】除了默认目录外，现在仍然可以通过 `channels.wecom.media.localRoots` 继续追加共享盘、挂载盘、业务导出目录等自定义路径。这里的设计原则很简单：默认给出大多数人会用到的目录，但不假设所有企业的数据都在同一个地方。
- 【文案与排障提示同步更新】当媒体太大或解密失败时，提示语现在会直接指向 `channels.wecom.mediaMaxMb` 这套推荐配置，避免用户继续被旧的 `media.maxBytes` 误导。

## 这次改动背后的最小理解模型

把这次版本理解成四句话就够了：

1. **会话该隔离的，要真的隔离。**  
   你开了 `dynamicAgents`，系统就应该不管走 Webhook、Agent Callback 还是 Bot WS，都稳定地把“不同用户 / 不同群”落到不同会话上，而不是不同链路表现不一致。

2. **从哪个对话开始，就该尽量在哪个对话里发回去。**  
   如果用户是在 Bot WS 对话里让系统发图，那么结果也应该优先回到这个 Bot WS 对话，而不是悄悄切到 Agent 私聊。否则用户看到的“会话边界”和系统内部实际走的链路会分裂。

3. **配置写在哪里，运行时就该认哪里。**  
   OpenClaw 既然已经把媒体大小的标准字段定成 `mediaMaxMb`，WeCom 插件就不该再偷偷主要走自己那套 `media.maxBytes`。统一之后，用户只需要记住一套规则。

4. **用户的文件，默认应该在用户常用目录里。**  
   大多数人发文件，不会先把图拷进 `.openclaw/media`，而是直接从下载目录、桌面、图片目录发。默认路径如果违背这个常识，系统虽然“安全”，但体验是不成立的。

## 推荐配置

```json
{
  "channels": {
    "wecom": {
      "mediaMaxMb": 50,
      "media": {
        "tempDir": "/tmp/openclaw-wecom-media",
        "localRoots": [
          "/srv/company-share",
          "/data/reports"
        ]
      },
      "dynamicAgents": {
        "enabled": true,
        "dmCreateAgent": true,
        "groupEnabled": true,
        "adminUsers": ["your-admin-userid"]
      }
    }
  }
}
```

## 升级后你应该感受到的变化

- 从 `Downloads`、`Desktop` 这类常见目录直接发图、发文件，更容易一次成功。
- 同样开启 `dynamicAgents` 的前提下，Bot WS 会话也会像其他链路一样稳定隔离，不再更容易串上下文。
- 如果当前就是 Bot WS 对话流，发图、发文件会优先留在这个对话里处理，不会再更容易“跳”到 Agent 私聊。
- 调整 `mediaMaxMb` 后，WeCom 插件的上传 / 解密 / 读取链路会真正跟着变化，而不是“配置改了，行为没改”。

## 仍然需要知道的边界

- `mediaMaxMb` 控制的是 OpenClaw 这边愿意读取和处理多大的媒体，不代表企业微信协议本身没有限制。
- 企业微信自身的媒体限制仍然存在，例如图片 / 视频超过 10MB、语音超过 2MB、文件超过 20MB 时，最终行为仍受企业微信接口约束。
- 旧配置 `channels.wecom.media.maxBytes` 目前还兼容，但新配置建议统一迁移到 `channels.wecom.mediaMaxMb`。

## 升级提示

- 执行 `openclaw plugins update wecom` 即可升级到 `v2.3.19`。
- 如果你之前遇到“WS 开了 dynamicAgents 但还是串到主 Agent”“明明在 Bot WS 对话里发图，结果却从 Agent 私聊发出来”，或“明明改了媒体大小配置却没有生效”，这一版就是针对这些问题的直接修复。
- 如果你的文件仍然不在默认目录内，例如 NAS、共享盘或业务导出盘，请继续在 `channels.wecom.media.localRoots` 中追加对应路径。