@sunnoy/wecom 2.3.0 → 2.4.1

package/README.md

@@ -150,6 +150,7 @@ npm test
         "mentionPatterns": ["@"]
       },
       "workspaceTemplate": "/path/to/template-dir",
+      "mediaLocalRoots": ["/tmp/openclaw"],
       "agent": {
         "corpId": "wwxxxxxxxxxxxxxxxx",
         "corpSecret": "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
@@ -208,6 +209,7 @@ npm test
 | `channels.wecom.groupChat.requireMention` | boolean | 否 | 群聊是否要求 @ 才响应，默认 `true` |
 | `channels.wecom.groupChat.mentionPatterns` | string[] | 否 | 群聊触发前缀，默认 `["@"]` |
 | `channels.wecom.workspaceTemplate` | string | 否 | 动态 Agent 工作区模板目录 |
+| `channels.wecom.mediaLocalRoots` | string[] | 否 | 额外允许被动回复读取的宿主机目录列表。用于放行 `MEDIA:/abs/path` 或 `FILE:/abs/path` 指向的本地文件；默认只允许当前 Agent workspace 和浏览器产物目录。多账号模式下也可配置在 `channels.wecom.<accountId>.mediaLocalRoots`。修改后需重启 Gateway 生效 |
 
 ### 增强出站配置
 
@@ -247,6 +249,7 @@ Agent 增强出站不需要 `token`、`encodingAesKey`、回调 URL；只有需
         "botId": "aib-support-xxx",
         "secret": "secret-support-xxx",
         "dmPolicy": "pairing",
+        "mediaLocalRoots": ["/tmp/openclaw"],
         "agent": {
           "corpId": "wwxxxxxxxxxxxxxxxx",
           "corpSecret": "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
@@ -377,6 +380,15 @@ Webhook 只负责群通知。
 - 最终回复 `finish=true` 时可附带图片 `msg_item`
 - 若最终回复包含 WS 不支持的媒体（文件等），会先文本提示再通过 Agent API 补发
 
+本插件会自动解析模型输出中的 `MEDIA:` / `FILE:` 指令，并在回复完成后上传对应文件：
+
+- 图片使用 `MEDIA:/abs/path`
+- PDF、音频、视频、压缩包、Office 文档等非图片文件使用 `FILE:/abs/path`
+- 沙箱内当前工作区文件可直接写成 `MEDIA:/workspace/...` 或 `FILE:/workspace/...`
+- 浏览器生成的文件默认允许从 OpenClaw 状态目录下的浏览器媒体目录读取
+- 宿主机其他目录默认不放行；如果需要回复 `/tmp/openclaw/report.pdf` 这类文件，请把其父目录加入 `channels.wecom.mediaLocalRoots`，多账号模式可配在 `channels.wecom.<accountId>.mediaLocalRoots`
+- 更新 `mediaLocalRoots` 后需重启 Gateway 生效
+
 ### 主动发送与后备策略
 
 主动发送分层：
@@ -557,6 +569,29 @@ openclaw pairing approve wecom <code>
 - WS 断连后的 pending 回复通过 Agent API 补发
 - WS 文本主动发送失败时，尝试回退到 Agent
 
+### Q: 回复本地文件时提示“没有权限访问路径”怎么办？
+
+先确认文件路径是否在允许目录里：
+
+- 当前 Agent 工作区文件默认允许，可直接用 `FILE:/workspace/...` 或 `MEDIA:/workspace/...`
+- 浏览器生成的文件默认允许
+- 宿主机其他目录需要把父目录加入 `channels.wecom.mediaLocalRoots`
+- 多账号模式如果只想对某个账号生效，可配置 `channels.wecom.<accountId>.mediaLocalRoots`
+
+例如：
+
+```json
+{
+  "channels": {
+    "wecom": {
+      "mediaLocalRoots": ["/tmp/openclaw"]
+    }
+  }
+}
+```
+
+修改后重启 Gateway。`v2.2.1+` 已支持把 `mediaLocalRoots` 并入被动回复文件允许目录。
+
 ### Q: `60020 not allow to access from your ip` 是什么问题？
 
 企业微信自建应用 API 的可信 IP 限制。把当前服务器出口 IP 加入企业微信应用的可信 IP 白名单即可。

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@sunnoy/wecom",
-    "version": "2.3.0",
+    "version": "2.4.1",
     "description": "Enterprise WeChat AI Bot channel plugin for OpenClaw",
     "type": "module",
     "main": "index.js",

package/skills/wecom-msg/SKILL.md

@@ -0,0 +1,115 @@
+---
+name: wecom-msg
+description: 企业微信消息技能。提供会话列表查询、消息记录拉取（支持文本/图片/文件/语音/视频）、多媒体文件获取和文本消息发送能力。当用户需要“查看消息”、”看聊天记录”、”发消息给某人”、”最近有什么消息”、”给群里发消息”、”看看发了什么图片/文件”时触发。
+---
+
+# 企业微信消息技能
+
+> `wecom_mcp` 是一个 MCP tool，所有操作通过调用该 tool 完成。
+
+> ⚠️ **前置条件**：首次调用 `wecom_mcp` 前，必须按 `wecom-preflight` 技能执行前置条件检查，确保工具已加入白名单。
+
+> ⚠️ **路径与停止规则**：
+> - 如果要读取本 skill，必须直接使用 `<available_skills>` 或 `skillsSnapshot` 中给出的精确绝对路径。
+> - 不要猜测或改写为 `/data/openclaw/skills/wecom-*`、`/workspace/.openclaw/skills/...`、`/root/.openclaw/workspace-*/.openclaw/skills/...`，也不要用 `exec` + `ls/find` 探路。
+> - 若 `wecom_mcp` 返回 `errcode: 846609` 或 `unsupported mcp biz type`，表示当前 bot 未开通 `msg` category，不是路径、白名单或 sandbox 问题；立即停止继续 `read`、`list`、`find`、memory fallback 探索，直接告知用户当前机器人未开通消息能力。
+
+通过 `wecom_mcp call msg <接口名> '<json入参>'` 与企业微信消息系统交互。
+
+## 接口列表
+
+### 1. 获取会话列表
+
+使用 `wecom_mcp` tool 调用 `wecom_mcp call msg get_msg_chat_list '{"begin_time": "2026-03-11 00:00:00", "end_time": "2026-03-17 23:59:59"}'`
+
+按时间范围查询有消息的会话列表，支持分页。详情见 `references/api-get-msg-chat-list.md`。
+
+### 2. 拉取聊天记录
+
+使用 `wecom_mcp` tool 调用 `wecom_mcp call msg get_messages '{"chat_type": 1, "chatid": "zhangsan", "begin_time": "2026-03-17 09:00:00", "end_time": "2026-03-17 18:00:00"}'`
+
+根据会话类型和会话 ID 拉取指定时间范围内的消息记录，支持分页。详情见 `references/api-get-messages.md`。
+
+### 3. 发送文本消息
+
+使用 `wecom_mcp` tool 调用 `wecom_mcp call msg send_message '{"chat_type": 1, "chatid": "zhangsan", "msgtype": "text", "text": {"content": "hello world"}}'`
+
+向单聊或群聊发送文本消息。详情见 `references/api-send-message.md`。
+
+## 核心规则
+
+### 时间范围
+
+- 所有时间参数使用 `YYYY-MM-DD HH:mm:ss` 格式。
+- 用户未指定时间时，默认使用最近 7 天。
+- `get_messages` 只支持当前时刻往前 7 天内的数据。
+- 如果用户给出的开始时间早于 7 天窗口，要主动调整到有效范围并明确告知。
+
+### 会话定位
+
+- 当用户直接提供 `chatid` 时，直接使用。
+- 当用户提供人名或群名而不是 ID 时，先调用 `get_msg_chat_list` 获取候选会话，再按 `chat_name` 在本地筛选。
+- 精确匹配唯一结果时可直接使用。
+- 模糊匹配多个结果时，必须先向用户展示候选项，不要擅自决定。
+- 没有匹配结果时，要明确告知未找到对应会话。
+- `get_msg_chat_list` 返回里没有 `chat_type`，若用户明确说“群”“群聊”“项目群”等，优先用 `chat_type=2`；否则默认 `chat_type=1`。
+
+### 消息展示
+
+- `get_messages` 当前只按文档约定处理文本消息；遇到非文本字段时，不要编造内容，按原始结构说明。
+- 展示消息时优先把 `userid` 转成可读姓名。
+- 如需做 `userid -> 姓名/别名` 映射，调用 `wecom-contact-lookup` 的 `get_userlist`，并在本地建立映射。
+- 若无法映射，保留 `userid` 原样展示。
+
+### 发送规则
+
+- `send_message` 仅用于发送文本消息。
+- 用户要求发送图片、PDF、视频、语音或其它文件时，不要误用 `wecom_mcp msg send_message`；应改用本插件原生的 `MEDIA:` / `FILE:` 路径投递能力。
+- 发送消息前必须先做一次面向用户的确认，至少确认发送对象和发送内容。
+- 用户确认前，不要执行 `send_message`。
+
+## 典型工作流
+
+### 查看最近有哪些会话
+
+1. 确定时间范围。
+2. 调用 `get_msg_chat_list`。
+3. 按“会话名称 + 最后消息时间 + 消息数量”整理结果。
+4. 若 `has_more=true`，提示用户还可以继续翻页。
+
+### 查看某个聊天对象的记录
+
+1. 确定时间范围。
+2. 如需，先通过 `get_msg_chat_list` 定位 `chatid`。
+3. 调用 `get_messages`。
+4. 如需，调用 `wecom-contact-lookup` 获取通讯录，把 `userid` 映射为姓名/别名。
+5. 按时间顺序展示消息。
+6. 若 `next_cursor` 非空，提示还有更多消息可继续查看。
+
+### 给某人或某个群发文本
+
+1. 如需，先定位 `chatid` 与 `chat_type`。
+2. 向用户确认发送对象和文本内容。
+3. 用户确认后，调用 `send_message`。
+4. 返回发送结果。
+
+### 看完消息后代发回复
+
+1. 先执行“查看聊天记录”流程。
+2. 从上下文中提取待回复对象和回复内容。
+3. 再执行“给某人或某个群发文本”流程。
+
+## 错误处理
+
+- 若返回 `tool not allowed`、`unknown tool: wecom_mcp`、`permission denied`，说明问题在宿主机工具放行，不要继续试探，按 `wecom-preflight` 规则处理。
+- 若返回 `unsupported mcp biz type` 或 `errcode: 846609`，说明当前 bot 未开通 `msg` category，不要继续尝试其它 category。
+- 若返回 API 业务错误，直接展示 `errcode` 和 `errmsg`，必要时最多重试 1 次。
+- 若查询结果为空，要明确告知“当前时间范围内没有找到消息/会话”，不要编造。
+
+## 快速参考
+
+| 接口 | 用途 | 关键输入 | 关键输出 |
+|------|------|----------|----------|
+| `get_msg_chat_list` | 查询时间范围内有消息的会话列表 | `begin_time`, `end_time`, `cursor?` | `chats`, `has_more`, `next_cursor` |
+| `get_messages` | 拉取指定会话消息 | `chat_type`, `chatid`, `begin_time`, `end_time`, `cursor?` | `messages`, `next_cursor` |
+| `send_message` | 发送文本消息 | `chat_type`, `chatid`, `msgtype=text`, `text.content` | `errcode`, `errmsg` |

package/skills/wecom-msg/references/api-get-messages.md

@@ -0,0 +1,74 @@
+# `get_messages` API
+
+根据会话类型和会话 ID 拉取指定时间范围内的消息记录。
+
+## 参数说明
+
+| 参数 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| `chat_type` | integer | 是 | 会话类型，`1` 表示单聊，`2` 表示群聊 |
+| `chatid` | string | 是 | 会话 ID。单聊时通常为 userid，群聊时为群 ID |
+| `begin_time` | string | 是 | 拉取开始时间，格式：`YYYY-MM-DD HH:mm:ss`，仅支持最近 7 天内 |
+| `end_time` | string | 是 | 拉取结束时间，格式：`YYYY-MM-DD HH:mm:ss`，必须大于等于 `begin_time` |
+| `cursor` | string | 否 | 分页游标。首次请求不传，后续传上次响应的 `next_cursor` |
+
+## 请求示例
+
+单聊：
+
+```text
+wecom_mcp call msg get_messages '{"chat_type":1,"chatid":"zhangsan","begin_time":"2026-03-17 09:00:00","end_time":"2026-03-17 18:00:00"}'
+```
+
+群聊：
+
+```text
+wecom_mcp call msg get_messages '{"chat_type":2,"chatid":"wrxxxxxxxx","begin_time":"2026-03-17 09:00:00","end_time":"2026-03-17 18:00:00"}'
+```
+
+分页：
+
+```text
+wecom_mcp call msg get_messages '{"chat_type":1,"chatid":"zhangsan","begin_time":"2026-03-17 09:00:00","end_time":"2026-03-17 18:00:00","cursor":"CURSOR_xxxxxx"}'
+```
+
+## 返回字段
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| `errcode` | integer | 返回码，`0` 表示成功 |
+| `errmsg` | string | 错误信息 |
+| `messages` | array | 消息列表 |
+| `messages[].userid` | string | 发送者 userid |
+| `messages[].send_time` | string | 发送时间，格式：`YYYY-MM-DD HH:mm:ss` |
+| `messages[].msgtype` | string | 消息类型 |
+| `messages[].text.content` | string | 文本消息内容；仅在 `msgtype=text` 时存在 |
+| `next_cursor` | string | 下一页游标；为空表示已拉取完毕 |
+
+## 响应示例
+
+```json
+{
+  "errcode": 0,
+  "errmsg": "ok",
+  "messages": [
+    {
+      "userid": "zhangsan",
+      "send_time": "2026-03-17 09:30:00",
+      "msgtype": "text",
+      "text": {
+        "content": "你好"
+      }
+    },
+    {
+      "userid": "lisi",
+      "send_time": "2026-03-17 09:35:00",
+      "msgtype": "text",
+      "text": {
+        "content": "你好，有什么可以帮助你的？"
+      }
+    }
+  ],
+  "next_cursor": "CURSOR_xxxxxx"
+}
+```

package/skills/wecom-msg/references/api-get-msg-chat-list.md

@@ -0,0 +1,64 @@
+# `get_msg_chat_list` API
+
+获取指定时间范围内有消息的会话列表，支持分页查询。
+
+## 参数说明
+
+| 参数 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| `begin_time` | string | 是 | 拉取开始时间，格式：`YYYY-MM-DD HH:mm:ss` |
+| `end_time` | string | 是 | 拉取结束时间，格式：`YYYY-MM-DD HH:mm:ss` |
+| `cursor` | string | 否 | 分页游标。首次请求不传，后续传上次响应的 `next_cursor` |
+
+## 请求示例
+
+使用 `wecom_mcp` tool 调用：
+
+```text
+wecom_mcp call msg get_msg_chat_list '{"begin_time":"2026-03-11 00:00:00","end_time":"2026-03-17 23:59:59"}'
+```
+
+分页请求：
+
+```text
+wecom_mcp call msg get_msg_chat_list '{"begin_time":"2026-03-11 00:00:00","end_time":"2026-03-17 23:59:59","cursor":"NEXT_CURSOR"}'
+```
+
+## 返回字段
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| `errcode` | integer | 返回码，`0` 表示成功 |
+| `errmsg` | string | 错误信息 |
+| `chats` | array | 会话列表 |
+| `chats[].chat_id` | string | 会话 ID |
+| `chats[].chat_name` | string | 会话名称 |
+| `chats[].last_msg_time` | string | 最后一条消息时间，格式：`YYYY-MM-DD HH:mm:ss` |
+| `chats[].msg_count` | integer | 消息数量 |
+| `has_more` | boolean | 是否还有更多数据 |
+| `next_cursor` | string | 下一页游标 |
+
+## 响应示例
+
+```json
+{
+  "errcode": 0,
+  "errmsg": "ok",
+  "chats": [
+    {
+      "chat_id": "zhangsan",
+      "chat_name": "张三",
+      "last_msg_time": "2026-03-17 15:30:45",
+      "msg_count": 128
+    },
+    {
+      "chat_id": "wr123456",
+      "chat_name": "项目讨论群",
+      "last_msg_time": "2026-03-16 09:12:33",
+      "msg_count": 56
+    }
+  ],
+  "has_more": true,
+  "next_cursor": "NEXT_CURSOR"
+}
+```

package/skills/wecom-msg/references/api-get-msg-media.md

@@ -0,0 +1,44 @@
+# get_msg_media API
+
+获取消息文件内容。根据文件 ID 自动下载文件到本地，返回本地文件路径、文件名称、类型、大小及内容类型。
+
+## 参数说明
+
+| 参数 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| `media_id` | string | ✅ | 文件 ID，长度 1~256 |
+
+## 请求示例
+
+使用 `wecom_mcp` tool 调用 `wecom_mcp call msg get_msg_media '{"media_id": "MEDIAID_xxxxxx"}'`
+
+## 返回字段
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| `errcode` | Integer | 返回码，`0` 表示成功 |
+| `errmsg` | String | 错误信息 |
+| `media_item` | Object | 文件内容 |
+| `media_item.media_id` | String | 文件 ID |
+| `media_item.name` | String | 文件名称 |
+| `media_item.type` | String | 文件类型，`image`-图片，`voice`-语音，`video`-视频，`file`-普通文件 |
+| `media_item.local_path` | String | 文件下载后的本地路径 |
+| `media_item.size` | Integer | 文件大小（字节） |
+| `media_item.content_type` | String | 文件 MIME 类型，如 `image/png`、`application/pdf` 等 |
+
+## 响应示例
+
+```json
+{
+    "errcode": 0,
+    "errmsg": "ok",
+    "media_item": {
+        "media_id": "MEDIAID_xxxxxx",
+        "name": "screenshot.png",
+        "type": "image",
+        "local_path": "xxx/yyy/screenshot.png",
+        "size": 102400,
+        "content_type": "image/png"
+    }
+}
+```

package/skills/wecom-msg/references/api-send-message.md

@@ -0,0 +1,49 @@
+# `send_message` API
+
+向单聊或群聊发送文本消息。
+
+## 参数说明
+
+| 参数 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| `chat_type` | integer | 是 | 会话类型，`1` 表示单聊，`2` 表示群聊 |
+| `chatid` | string | 是 | 会话 ID。单聊时通常为 userid，群聊时为群 ID |
+| `msgtype` | string | 是 | 消息类型。当前只应使用 `text` |
+| `text` | object | 是 | 文本消息体 |
+| `text.content` | string | 是 | 文本内容，受企业微信消息长度限制 |
+
+## 请求示例
+
+单聊：
+
+```text
+wecom_mcp call msg send_message '{"chat_type":1,"chatid":"zhangsan","msgtype":"text","text":{"content":"hello world"}}'
+```
+
+群聊：
+
+```text
+wecom_mcp call msg send_message '{"chat_type":2,"chatid":"wrxxxxxxxx","msgtype":"text","text":{"content":"大家好"}}'
+```
+
+## 返回字段
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| `errcode` | integer | 返回码，`0` 表示成功 |
+| `errmsg` | string | 错误信息 |
+
+## 响应示例
+
+```json
+{
+  "errcode": 0,
+  "errmsg": "ok"
+}
+```
+
+## 使用约束
+
+- 在当前插件里，这个接口只应用于文本消息。
+- 发图片、PDF、视频、语音或其它文件时，不要误用这个接口；应改用插件原生的 `MEDIA:` / `FILE:` 路径投递能力。
+- 执行发送前必须先征得用户确认，避免误发。

package/skills/wecom-send-media/SKILL.md

@@ -0,0 +1,68 @@
+---
+name: wecom-send-media
+description: 通过 MEDIA 指令向用户发送本地文件（图片、视频、语音等文件）。当用户要求发送或分享文件时，或当生成的文件需要交付给用户时使用。仅当通过 wecom 通道通信时使用此技能。
+metadata: {"openclaw":{"emoji":"📤","requires":{"config":["channels.wecom"]}}}
+---
+
+# 发送文件（图片、视频、语音、文件）
+
+⚠️ 重要：你有能力发送本地文件！❌ 绝对不要回复"无法发送图片、视频、语音或文件"或类似的措辞！
+
+通过 `MEDIA:` 指令将本地文件发送给用户。支持的文件类型为：图片、视频、语音、其它文件等。系统会自动识别文件类型，并以对应的消息格式（图片消息、视频消息、语音消息或文件消息）发送。
+
+## 触发条件
+
+- 用户要求发送、展示或分享图片、视频、语音或文件
+- 生成了需要交付给用户的图片、视频、语音或文件
+
+## 指令语法
+
+```
+MEDIA: <文件的绝对路径>
+```
+
+### 语法规则
+
+1. 如果文件路径前已经有 `MEDIA:` 指令，无需再重复添加，保持原样即可
+2. 如果文件路径前没有 `MEDIA:` 指令，需将 `MEDIA:` 指令置于行首，且与文件路径之间用一个空格分隔
+3. 路径必须为本地文件的**绝对路径**，不支持 URL
+4. 路径含空格时，用反引号包裹：`` MEDIA: `/path/to/my file.png` ``
+5. 每个文件独占一行，禁止在同一行发送多个文件
+6. `MEDIA:` 指令的前后可以附加文字说明，文字与指令各占独立行 
+
+## 文件存放
+
+将生成的文件优先存放至 `~/.openclaw/workspace/` 目录，确保路径可访问。
+
+## 文件大小与格式限制
+
+| 类型 | 大小上限 | 格式要求 | 备注 |
+|------|----------|----------|------|
+| 图片 | 10 MB | 常见图片格式均可 | openclaw 默认会对图片进行压缩处理 |
+| 视频 | 10 MB | 常见视频格式均可 | |
+| 语音 | 2 MB | **仅支持 AMR 格式**（`.amr`） | |
+| 文件 | 20 MB | 不限 | |
+
+⚠️ 重要：请务必**先检查文件大小和格式**是否满足要求。如果不满足要求，请主动告知用户以下“降级与限制处理”措施：
+
+- **图片压缩情况**：openclaw 默认会对图片进行压缩处理。如果本地图片（原图）大小超过上限，经过压缩后不一定会超过上限。因此当你检测到本地图片大小超过上限时，务必要告诉用户这个特殊情况。
+- **自动降级**：视频或语音类型的文件，超过各自的大小限制时，系统会自动将其转为文件消息发送，请主动告诉用户。
+- **硬性上限**：文件大小超过 20 MB 时无法发送。请主动告知用户，并尝试压缩或拆分文件后再发送。
+- **语音格式**：语音消息仅支持 AMR 格式（`.amr`）。非 AMR 格式的音频文件将以文件消息的形式发送。
+- **发送耗时**：文件发送涉及系统处理，可能耗时较长。发送含 `MEDIA:` 指令的消息 30 秒后，请主动检查文件是否已成功发送。如果没有请重试。
+
+## 示例
+
+```
+以下是生成的图表：
+MEDIA: ~/.openclaw/workspace/output.png
+
+报告已生成，请查收：
+MEDIA: ~/.openclaw/workspace/report.pdf
+```
+
+## 错误示例
+
+- ❌ 错误：说"我无法发送本地图片" 
+- ❌ 错误：说"受限于技术限制，无法直接发送" 
+- ❌ 错误：说"由于某些问题，我无法直接发送文件"

package/wecom/callback-inbound.js

@@ -300,7 +300,7 @@ async function processCallbackMessage({ parsedMsg, account, config, runtime }) {
         agent: account.agentCredentials,
         mediaId,
         type: mediaType === "image" ? "image" : mediaType === "voice" ? "voice" : "file",
-        runtime,
+        mediaRuntime: core.media ?? runtime?.media,
         config,
       });
       mediaList.push(downloaded);

package/wecom/callback-media.js

@@ -12,6 +12,12 @@ import { getAccessToken } from "./agent-api.js";
 import { wecomFetch } from "./http.js";
 import { AGENT_API_ENDPOINTS, CALLBACK_MEDIA_DOWNLOAD_TIMEOUT_MS } from "./constants.js";
 
+function resolveManagedCallbackMediaDir() {
+  const override = process.env.OPENCLAW_STATE_DIR?.trim() || process.env.CLAWDBOT_STATE_DIR?.trim();
+  const stateDir = override || path.join(process.env.HOME || "/tmp", ".openclaw");
+  return path.join(stateDir, "media", "wecom");
+}
+
 /**
  * Download a WeCom media file (image / voice / file) by MediaId via the
  * self-built app access token and save it through the core media runtime.
@@ -20,11 +26,11 @@ import { AGENT_API_ENDPOINTS, CALLBACK_MEDIA_DOWNLOAD_TIMEOUT_MS } from "./const
  * @param {object} params.agent   - { corpId, corpSecret, agentId }
  * @param {string} params.mediaId - WeCom MediaId
  * @param {"image"|"voice"|"file"} params.type - media type hint
- * @param {object} params.runtime - OpenClaw runtime (for saveMediaBuffer)
+ * @param {object} [params.mediaRuntime] - OpenClaw media runtime (for saveMediaBuffer)
  * @param {object} params.config  - OpenClaw config (for mediaMaxMb)
  * @returns {Promise<{ path: string, contentType: string }>}
  */
-export async function downloadCallbackMedia({ agent, mediaId, type, runtime, config }) {
+export async function downloadCallbackMedia({ agent, mediaId, type, mediaRuntime, config }) {
   const token = await getAccessToken(agent);
   const url = `${AGENT_API_ENDPOINTS.DOWNLOAD_MEDIA}?access_token=${encodeURIComponent(token)}&media_id=${encodeURIComponent(mediaId)}`;
 
@@ -57,20 +63,22 @@ export async function downloadCallbackMedia({ agent, mediaId, type, runtime, con
     (type === "image" ? `${mediaId}.jpg` : type === "voice" ? `${mediaId}.amr` : mediaId);
 
   // Save via core media runtime when available
-  if (typeof runtime?.media?.saveMediaBuffer === "function") {
-    const saved = await runtime.media.saveMediaBuffer(buffer, contentType, "inbound", maxBytes, filename);
+  if (typeof mediaRuntime?.saveMediaBuffer === "function") {
+    const saved = await mediaRuntime.saveMediaBuffer(buffer, contentType, "inbound", maxBytes, filename);
     return { path: saved.path, contentType: saved.contentType };
   }
 
-  // Fallback: write to OS temp dir
-  const { tmpdir } = await import("node:os");
-  const { writeFile } = await import("node:fs/promises");
+  // Fallback: keep callback media under the managed OpenClaw media root so
+  // stageSandboxMedia can safely copy it into the agent sandbox later.
+  const { mkdir, writeFile } = await import("node:fs/promises");
   const ext = path.extname(filename) || (type === "image" ? ".jpg" : ".bin");
+  const mediaDir = resolveManagedCallbackMediaDir();
   const tempPath = path.join(
-    tmpdir(),
+    mediaDir,
     `wecom-cb-${Date.now()}-${Math.random().toString(36).slice(2, 8)}${ext}`,
   );
+  await mkdir(mediaDir, { recursive: true, mode: 0o700 });
   await writeFile(tempPath, buffer);
-  logger.debug(`[CB] Media saved to temp path: ${tempPath}`);
+  logger.debug(`[CB] Media saved to managed path: ${tempPath}`);
   return { path: tempPath, contentType };
 }

package/wecom/channel-plugin.js

@@ -24,7 +24,7 @@ import { wecomOnboardingAdapter } from "./onboarding.js";
 import { getAccountTelemetry, recordOutboundActivity } from "./runtime-telemetry.js";
 import { getOpenclawConfig, getRuntime, setOpenclawConfig } from "./state.js";
 import { resolveWecomTarget } from "./target.js";
-import { webhookSendFile, webhookSendImage, webhookSendMarkdown, webhookUploadFile } from "./webhook-bot.js";
+import { webhookSendFile, webhookSendImage, webhookSendMarkdown, webhookSendText, webhookUploadFile } from "./webhook-bot.js";
 import { loadOutboundMediaFromUrl as loadOutboundMediaFromUrlCompat } from "./openclaw-compat.js";
 import {
   CHANNEL_ID,
@@ -142,7 +142,7 @@ function applyNetworkConfig(cfg, accountId) {
   return account;
 }
 
-async function sendViaWebhook({ cfg, accountId, webhookName, text, mediaUrl, preparedMedia }) {
+async function sendViaWebhook({ cfg, accountId, webhookName, text, mediaUrl, preparedMedia, replyFormat }) {
   const account = resolveAccount(cfg, accountId);
   const raw = account?.config?.webhooks?.[webhookName];
   const url = raw ? (String(raw).startsWith("http") ? String(raw) : `${getWebhookBotSendUrl()}?key=${raw}`) : null;
@@ -150,8 +150,13 @@ async function sendViaWebhook({ cfg, accountId, webhookName, text, mediaUrl, pre
     throw new Error(`unknown webhook target: ${webhookName}`);
   }
 
+  const effectiveFormat = replyFormat || account?.agentReplyFormat || "markdown";
+  const sendWebhookText = effectiveFormat === "text"
+    ? (opts) => webhookSendText(opts)
+    : (opts) => webhookSendMarkdown(opts);
+
   if (!mediaUrl) {
-    await webhookSendMarkdown({ url, content: text });
+    await sendWebhookText({ url, content: text });
     recordOutboundActivity({ accountId });
     return { channel: CHANNEL_ID, messageId: `wecom-webhook-${Date.now()}` };
   }
@@ -160,7 +165,7 @@ async function sendViaWebhook({ cfg, accountId, webhookName, text, mediaUrl, pre
     preparedMedia ?? (await loadResolvedMedia(mediaUrl, { accountConfig: account?.config }));
 
   if (text) {
-    await webhookSendMarkdown({ url, content: text });
+    await sendWebhookText({ url, content: text });
   }
 
   if (mediaType === "image") {
@@ -178,15 +183,17 @@ async function sendViaWebhook({ cfg, accountId, webhookName, text, mediaUrl, pre
   return { channel: CHANNEL_ID, messageId: `wecom-webhook-${Date.now()}` };
 }
 
-async function sendViaAgent({ cfg, accountId, target, text, mediaUrl, preparedMedia }) {
-  const agent = resolveAccount(cfg, accountId)?.agentCredentials;
+async function sendViaAgent({ cfg, accountId, target, text, mediaUrl, preparedMedia, replyFormat }) {
+  const account = resolveAccount(cfg, accountId);
+  const agent = account?.agentCredentials;
   if (!agent) {
     throw new Error("Agent API is not configured for this account");
   }
 
+  const effectiveFormat = replyFormat || account?.agentReplyFormat || "markdown";
   if (text) {
     for (const chunk of splitTextByByteLimit(text)) {
-      await agentSendText({ agent, ...target, text: chunk });
+      await agentSendText({ agent, ...target, text: chunk, format: effectiveFormat });
     }
   }
 
@@ -618,6 +625,17 @@ export const wecomChannelPlugin = {
       setConfigProxyUrl(network.egressProxyUrl ?? "");
       setApiBaseUrl(network.apiBaseUrl ?? "");
 
+      // Callback-only accounts (Agent API) don't need WS monitor.
+      // Return a promise that stays alive until the gateway signals shutdown,
+      // so the account is marked as running (not exited → no auto-restart).
+      if (!ctx.account.botId && !ctx.account.secret) {
+        return new Promise((resolve) => {
+          if (ctx.abortSignal) {
+            ctx.abortSignal.addEventListener("abort", () => resolve(), { once: true });
+          }
+        });
+      }
+
       return startWsMonitor({
         account: ctx.account,
         config: ctx.cfg,

package/wecom/mcp-tool.js

@@ -85,9 +85,15 @@ function normalizeUnsupportedBizTypePayload(payload, category) {
     details:
       rawMessage ||
       `unsupported mcp biz type for category "${category}"`,
+    note:
+      category !== "doc"
+        ? `Per WeCom official policy, enterprises with >10 people only have access to the "doc" category. ` +
+          `Categories like contact, todo, meeting, schedule, msg are only available for small teams (<=10 people).`
+        : undefined,
     next_action:
       `Stop retrying category "${category}" with alternate read/list/find paths. ` +
-      `Ask an administrator to enable the "${category}" MCP category for this bot.`,
+      `Do NOT attempt other categories as a workaround. ` +
+      `Inform the user that the "${category}" MCP category is not available for their current bot/enterprise.`,
   };
 }
 
@@ -596,13 +602,22 @@ export function createWeComMcpTool() {
     label: "WeCom MCP Tool",
     description: [
       "Calls WeCom MCP servers over Streamable HTTP.",
+      "Common official categories: doc, contact, todo, meeting, schedule, msg.",
+      "",
+      "Category availability depends on enterprise size (WeCom official policy):",
+      "  - Small teams (<=10 people): all categories (doc, contact, todo, meeting, schedule, msg)",
+      "  - Enterprises (>10 people): doc only (documents & smart sheets)",
+      "If a category returns errcode 846609 / 'unsupported mcp biz type', it is NOT enabled for the current bot — stop retrying immediately.",
+      "",
       "Supported actions:",
       "  - list: list tools under a category",
       "  - call: call one tool under a category",
       "",
       "Examples:",
       "  wecom_mcp list contact",
+      "  wecom_mcp list msg",
       "  wecom_mcp call schedule create_schedule '{\"schedule\": {...}}'",
+      "  wecom_mcp call msg get_messages '{\"chat_type\": 2, \"chatid\": \"GROUP_ID\", \"begin_time\": \"2026-03-17 00:00:00\", \"end_time\": \"2026-03-20 23:59:59\"}'",
     ].join("\n"),
     parameters: {
       type: "object",
@@ -614,7 +629,8 @@ export function createWeComMcpTool() {
         },
         category: {
           type: "string",
-          description: "WeCom MCP category, such as doc, contact, schedule, todo, meeting.",
+          description:
+            "WeCom MCP category, such as doc, contact, todo, meeting, schedule, or msg. Actual availability depends on the current bot/runtime.",
         },
         method: {
           type: "string",

package/wecom/workspace-template.js

@@ -327,18 +327,25 @@ export async function ensureDynamicAgentListed(agentId, templateDir, baseAgentId
 
         // Persist to disk so `openclaw agents list` (separate process) can see
         // the dynamic agent and it survives gateway restarts.
-        // Write the mutated in-memory config directly (same pattern as logoutAccount).
-        // NOTE: loadConfig() returns runtimeConfigSnapshot in gateway mode — the same
-        // object we already mutated above — so a read-modify-write pattern silently
-        // skips the write (diskChanged=false). Writing directly avoids this.
-        try {
-          await configRuntime.writeConfigFile(openclawConfig);
-          logger.info("WeCom: dynamic agent persisted to config file", { agentId: normalizedId });
-        } catch (writeErr) {
-          logger.warn("WeCom: failed to persist dynamic agent to config file", {
+        // Safety check: refuse to write if critical config sections are missing,
+        // which would indicate the in-memory snapshot is incomplete and writing
+        // it would destroy the user's configuration (#136).
+        const hasChannels = openclawConfig.channels && typeof openclawConfig.channels === "object";
+        if (!hasChannels) {
+          logger.warn("WeCom: skipping config write — in-memory config is missing 'channels' section", {
             agentId: normalizedId,
-            error: writeErr?.message || String(writeErr),
+            keys: Object.keys(openclawConfig),
           });
+        } else {
+          try {
+            await configRuntime.writeConfigFile(openclawConfig);
+            logger.info("WeCom: dynamic agent persisted to config file", { agentId: normalizedId });
+          } catch (writeErr) {
+            logger.warn("WeCom: failed to persist dynamic agent to config file", {
+              agentId: normalizedId,
+              error: writeErr?.message || String(writeErr),
+            });
+          }
         }
       }
       

package/wecom/ws-monitor.js

@@ -39,7 +39,6 @@ import {
 import { setConfigProxyUrl } from "./http.js";
 import { checkDmPolicy } from "./dm-policy.js";
 import { checkGroupPolicy } from "./group-policy.js";
-import { fetchAndSaveMcpConfig } from "./mcp-config.js";
 import {
   clearAccountDisplaced,
   forecastActiveSendQuota,
@@ -449,6 +448,9 @@ function buildReplyMediaGuidance(config, agentId) {
       "For workspace-local images, always use /workspace/... paths when calling image_studio.",
       "Prefer n=1 unless the user explicitly asks for multiple images.",
       "If image_studio returns MEDIA: URLs, treat the image task as completed successfully.",
+      "If image_studio returns MEDIA: URLs, do NOT repeat those URLs in the visible reply.",
+      "Do NOT embed markdown images, raw image URLs, or OSS links in the text reply after image_studio succeeds.",
+      "Instead, tell the user the image will be sent separately, for example: 图片会单独发送，请查收。",
     );
   }
 
@@ -1958,8 +1960,6 @@ export async function startWsMonitor({ account, config, runtime, abortSignal, ws
       clearAccountDisplaced(account.accountId);
       setWsClient(account.accountId, wsClient);
 
-      void fetchAndSaveMcpConfig(wsClient, account.accountId, runtime);
-
       // Drain pending replies that failed due to prior WS disconnection.
       if (account?.agentCredentials && hasPendingReplies(account.accountId)) {
         void flushPendingRepliesViaAgentApi(account).catch((flushError) => {

package/wecom/mcp-config.js

@@ -1,146 +0,0 @@
-import os from "node:os";
-import path from "node:path";
-import { mkdir, readFile, rename, writeFile } from "node:fs/promises";
-import { generateReqId } from "@wecom/aibot-node-sdk";
-import { logger } from "../logger.js";
-
-const MCP_GET_CONFIG_CMD = "aibot_get_mcp_config";
-const MCP_CONFIG_FETCH_TIMEOUT_MS = 15_000;
-const MCP_CONFIG_KEY = "doc";
-const DEFAULT_MCP_TRANSPORT = "streamable-http";
-
-let mcpConfigWriteQueue = Promise.resolve();
-
-function withTimeout(promise, timeoutMs, message) {
-  if (!timeoutMs || !Number.isFinite(timeoutMs) || timeoutMs <= 0) {
-    return promise;
-  }
-
-  let timer = null;
-  const timeout = new Promise((_, reject) => {
-    timer = setTimeout(() => reject(new Error(message ?? `Timed out after ${timeoutMs}ms`)), timeoutMs);
-  });
-
-  promise.catch(() => {});
-
-  return Promise.race([promise, timeout]).finally(() => {
-    if (timer) {
-      clearTimeout(timer);
-    }
-  });
-}
-
-function getWecomConfigPath() {
-  return path.join(os.homedir(), ".openclaw", "wecomConfig", "config.json");
-}
-
-function resolveMcpTransport(body = {}) {
-  const candidate = String(
-    body.transport_type ??
-      body.transportType ??
-      body.config_type ??
-      body.configType ??
-      body.type ??
-      "",
-  )
-    .trim()
-    .toLowerCase();
-
-  return candidate || DEFAULT_MCP_TRANSPORT;
-}
-
-async function readJsonFile(filePath, fallback = {}) {
-  try {
-    const raw = await readFile(filePath, "utf8");
-    return JSON.parse(raw);
-  } catch (error) {
-    if (error?.code === "ENOENT") {
-      return fallback;
-    }
-    throw error;
-  }
-}
-
-async function writeJsonFileAtomically(filePath, value) {
-  const dir = path.dirname(filePath);
-  await mkdir(dir, { recursive: true });
-  const tempPath = `${filePath}.${process.pid}.${Date.now()}.tmp`;
-  await writeFile(tempPath, `${JSON.stringify(value, null, 2)}\n`, "utf8");
-  await rename(tempPath, filePath);
-}
-
-export async function fetchMcpConfig(wsClient) {
-  if (!wsClient || typeof wsClient.reply !== "function") {
-    throw new Error("WS client does not support MCP config requests");
-  }
-
-  const reqId = generateReqId("mcp_config");
-  const response = await withTimeout(
-    wsClient.reply({ headers: { req_id: reqId } }, { biz_type: MCP_CONFIG_KEY }, MCP_GET_CONFIG_CMD),
-    MCP_CONFIG_FETCH_TIMEOUT_MS,
-    `MCP config fetch timed out after ${MCP_CONFIG_FETCH_TIMEOUT_MS}ms`,
-  );
-
-  if (response?.errcode && response.errcode !== 0) {
-    throw new Error(`MCP config request failed: errcode=${response.errcode}, errmsg=${response.errmsg ?? "unknown"}`);
-  }
-
-  const body = response?.body;
-  if (!body?.url) {
-    throw new Error("MCP config response missing required 'url' field");
-  }
-
-  return {
-    key: MCP_CONFIG_KEY,
-    type: resolveMcpTransport(body),
-    url: body.url,
-    isAuthed: body.is_authed,
-  };
-}
-
-export async function saveMcpConfig(config, runtime) {
-  const configPath = getWecomConfigPath();
-
-  const saveTask = mcpConfigWriteQueue.then(async () => {
-    const current = await readJsonFile(configPath, {});
-    if (!current.mcpConfig || typeof current.mcpConfig !== "object") {
-      current.mcpConfig = {};
-    }
-
-    current.mcpConfig[config.key || MCP_CONFIG_KEY] = {
-      type: config.type,
-      url: config.url,
-    };
-
-    await writeJsonFileAtomically(configPath, current);
-    runtime?.log?.(`[WeCom] MCP config saved to ${configPath}`);
-  });
-
-  mcpConfigWriteQueue = saveTask.catch(() => {});
-  return saveTask;
-}
-
-export async function fetchAndSaveMcpConfig(wsClient, accountId, runtime) {
-  try {
-    runtime?.log?.(`[${accountId}] Fetching MCP config...`);
-    const config = await fetchMcpConfig(wsClient);
-    runtime?.log?.(
-      `[${accountId}] MCP config fetched: url=${config.url}, type=${config.type}, is_authed=${config.isAuthed ?? "N/A"}`,
-    );
-    await saveMcpConfig(config, runtime);
-  } catch (error) {
-    if (typeof wsClient?.reply !== "function") {
-      logger.debug?.(`[${accountId}] Skipping MCP config fetch because WS client has no reply() support`);
-      return;
-    }
-    runtime?.error?.(`[${accountId}] Failed to fetch/save MCP config: ${String(error)}`);
-  }
-}
-
-export const mcpConfigTesting = {
-  getWecomConfigPath,
-  resolveMcpTransport,
-  resetWriteQueue() {
-    mcpConfigWriteQueue = Promise.resolve();
-  },
-};