@wecom/wecom-openclaw-plugin 2026.8.17 → 2026.9.15

package/README.md

@@ -1,3 +1,5 @@
+English | [中文版](./README.zh.md)
+
 > 💡 **快速上手指引 & 交流群**
 >
 > 📖 [点击查看完整接入指引文档](https://doc.weixin.qq.com/doc/w3_AFYA1wY6ACoCNRxfnyGRJQaSa6jjJ?scode=AJEAIQdfAAo0RJmzxLAFYA1wY6ACo) — 包含配置步骤、产品介绍、常见问题解答等。

package/README.zh.md

@@ -0,0 +1,627 @@
+[English](./README.md) | 中文版
+
+> 💡 **快速上手指引 & 交流群**
+>
+> 📖 [点击查看完整接入指引文档](https://doc.weixin.qq.com/doc/w3_AFYA1wY6ACoCNRxfnyGRJQaSa6jjJ?scode=AJEAIQdfAAo0RJmzxLAFYA1wY6ACo) — 包含配置步骤、产品介绍、常见问题解答等。
+>
+> 💬 扫码加入企业微信交流群：
+>
+> <img src="https://wwcdn.weixin.qq.com/node/wework/images/202603241759.3fb01c32cc.png" alt="扫码入群交流" width="200" />
+
+# 特别说明
+> ****2026.3.22 版本 OpenClaw 兼容说明****
+>
+> 如果你的 OpenClaw 是 2026.3.22 及以上的版本，请升级插件到 2026.3.24 及以上版本。
+>
+> 如果你的 OpenClaw 是 2026.3.22 以下的版本，请保持插件版本在 2026.3.20 版本。
+>
+> 你可以使用以下命令快速安装： `npx -y @wecom/wecom-openclaw-cli install --force`
+
+# 🤖 WeCom OpenClaw 插件
+
+**面向 [OpenClaw](https://github.com/openclaw) 的企业微信 Channel 与业务能力插件** — 由腾讯企业微信团队开发。
+
+> 一个由企业微信提供支持、兼具 Channel 与业务能力的插件。支持 **Bot 模式**（WebSocket 长轮询，或 JSON 回调的 HTTP webhook）与 **Agent 模式**（XML 加密回调的 HTTP webhook），以及单聊、群聊、流式回复、主动消息推送，并内置 `wecom-cli` 业务操作能力。
+
+---
+
+📖 [企业微信 AI Bot 官方文档](https://open.work.weixin.qq.com/help?doc_id=21657)
+
+
+## ✨ 特性
+
+- 🔗 **双模式**：Bot（WebSocket / Webhook）与 Agent（HTTP webhook）可独立或同时运行
+- 💬 同时支持单聊（DM）与群聊
+- 📤 向指定用户、群组、部门或标签主动推送消息
+- 🖼️ 接收并处理图片、语音、视频、文件及**图文混排**消息，并自动下载
+- 🗣️ 语音转文字：自动提取语音消息中的转写文本
+- 💬 引用消息支持：处理被引用的文本、图片、语音与文件消息
+- ⏳ 流式回复，支持"思考中"占位消息（Bot 模式）
+- 🔐 Agent 模式：AES-256-CBC 加密 XML 回调 + SHA1 签名校验
+- 📝 回复支持 Markdown 格式
+- 🃏 模板卡片消息（text_notice、news_notice、button_interaction、vote_interaction、multiple_interaction），支持**事件回调处理**
+- 🔒 内置访问控制：DM 策略（pairing / open / allowlist / disabled）与群组策略（open / allowlist / disabled）
+- 🔑 命令授权：按账号进行命令权限控制，支持访问组
+- 👥 多账号支持：可运行多个企业微信账号，各自独立的 bot/agent 配置
+- 🧰 内置业务 Skills，由插件提供的 `wecom-cli` 工具驱动
+- 🔀 动态 Agent 路由：按用户/群组自动创建隔离的 Agent
+- 📁 本地文件发送，支持可配置的媒体路径白名单（`mediaLocalRoots`）
+- 📊 智能媒体大小限制与自动降级（图片 10MB → 文件，视频 10MB → 文件，语音 2MB/仅 AMR → 文件，最大 20MB）
+- 🔄 **Bot 优先、Agent 兜底**的出站投递：Bot WS 不可用时自动回退到 Agent HTTP API
+- ⚡ 自动心跳保活与重连（最多 10 次重连，5 次鉴权失败重试）
+- 🛡️ 防踢保护：抑制服务端断连导致的自动重启，避免互相踢下线
+- 🧙 交互式 CLI 安装向导
+
+### 企业微信业务能力
+
+插件内置 `wecom-cli` 工具及对应的 Skills，覆盖以下企业微信业务品类：
+
+| 品类 | 能力 |
+|---|---|
+| 💬 消息 | 向机器人最近对话过的单聊/群聊主动推送消息，支持 Markdown/图片/文件/语音/视频消息 |
+| 📧 邮件 | 邮件发送/回复/转发，邮件搜索，获取邮件内容详情 |
+| 📄 文档 | 在线文档的新建、导入、读取、追加与覆盖写入 |
+| 🗂️ 文档管理 | 多种文档类型的搜索，在线文档/在线表格/智能表格/智能文档的重命名、成员权限与加入规则管理 |
+| 📊 在线表格 | 在线表格新建、CSV/Excel 导入、内容读改、追加行、子表管理 |
+| 🧮 智能表格 | 智能表格创建，子表/字段/记录/视图/图表管理，行列样式修改 |
+| 📰 智能文档 | 智能文档创建、获取页面内容、编辑文档内容、内置数据表信息获取 |
+| ✅ 待办 | 创建/读取/更新/删除待办，分派参与人与完成待办等 |
+| 📅 日程 | 日程增删改查、参与人管理、多成员闲忙查询、会议室查询预订等 |
+| 🎥 会议 | 创建预约会议、取消会议、更新参会人、查询列表与详情、读取会议纪要与转写原文 |
+| 💾 微盘 | 微盘文件的搜索、基础信息读取、上传、下载 |
+| 👤 通讯录 | 按姓名/拼音/别名搜索成员，获取成员基本信息，以用于会议、日程等多人场景 |
+
+---
+
+## 🚀 快速开始
+
+### 环境要求
+
+- OpenClaw `>= 2026.3.28`
+
+### 快速安装
+
+使用 CLI 工具一键完成插件安装与机器人配置：
+
+```shell
+# 自动安装 Channel 插件并快速完成配置，同时适用于升级
+npx -y @wecom/wecom-openclaw-cli install
+```
+
+更多选项
+```shell
+# 如果安装失败，尝试强制安装
+npx -y @wecom/wecom-openclaw-cli install --force
+
+# 使用 --help 了解该工具的更多用法
+npx -y @wecom/wecom-openclaw-cli --help
+```
+
+### 手动安装
+
+```shell
+openclaw plugins install @wecom/wecom-openclaw-plugin
+```
+
+### 配置
+
+#### 方式一：交互式配置
+
+```shell
+openclaw channels add
+```
+
+按提示输入机器人的 **Bot ID** 与 **Secret**。
+
+#### 方式二：CLI 快速配置
+
+```shell
+openclaw config set channels.wecom.botId <YOUR_BOT_ID>
+openclaw config set channels.wecom.secret <YOUR_BOT_SECRET>
+openclaw config set channels.wecom.enabled true
+openclaw gateway restart
+```
+
+### 启用业务工具
+
+以上企业微信业务能力通过插件提供的 `wecom-cli` 工具暴露。除非 `tools.profile` 设为 `full`，否则需要放行插件并重启 Gateway：
+
+```shell
+openclaw config set tools.alsoAllow '["wecom-openclaw-plugin"]'
+openclaw gateway restart
+```
+
+> 按插件 ID 放行会启用该插件当前及未来注册的全部工具。若 `tools.alsoAllow` 中已有其他条目，请将 `wecom-openclaw-plugin` 合并进现有数组，而不要覆盖。
+
+### 模式概览
+
+插件支持两种连接模式，可独立或同时使用：
+
+| 模式 | 连接方式 | 消息格式 | 适用场景 |
+|------|-----------|---------------|----------|
+| **Bot**（智能体） | WebSocket（默认）或 HTTP webhook | JSON | 快速接入、流式回复 |
+| **Agent**（自建应用） | HTTP webhook 回调 | XML | 企业应用、API 驱动的消息 |
+
+> **说明**：Bot 模式通过 `connectionMode` 支持两种连接方式：
+> - `websocket`（默认）— WebSocket 长轮询，需要 `botId` + `secret`
+> - `webhook` — HTTP 回调，需要 `token` + `encodingAESKey`
+
+### Bot 模式配置
+
+#### 核心设置
+
+| 配置路径 | 说明 | 可选值 | 默认值 |
+|---|---|---|---|
+| `channels.wecom.enabled` | 启用该 Channel | `true` / `false` | `false` |
+| `channels.wecom.connectionMode` | Bot 连接方式 | `websocket` / `webhook` | `websocket` |
+| `channels.wecom.name` | 账号显示名称 | — | `企业微信` |
+
+#### WebSocket 模式（默认）
+
+| 配置路径 | 说明 | 可选值 | 默认值 |
+|---|---|---|---|
+| `channels.wecom.botId` | 企业微信机器人 ID | — | — |
+| `channels.wecom.secret` | 企业微信机器人 secret | — | — |
+| `channels.wecom.websocketUrl` | WebSocket 端点 | — | `wss://openws.work.weixin.qq.com` |
+| `channels.wecom.sendThinkingMessage` | 发送"思考中"占位消息 | `true` / `false` | `true` |
+
+#### Webhook 模式（`connectionMode: "webhook"`）
+
+| 配置路径 | 说明 | 可选值 | 默认值 |
+|---|---|---|---|
+| `channels.wecom.token` | Webhook 校验 token | — | — |
+| `channels.wecom.encodingAESKey` | AES 加密密钥（43 字符 Base64） | — | — |
+| `channels.wecom.receiveId` | 接收方 ID（用于解密校验） | — | — |
+| `channels.wecom.welcomeText` | enter_chat 事件欢迎语 | — | — |
+| `channels.wecom.streamPlaceholderContent` | 流式占位内容 | — | — |
+
+#### 访问控制
+
+| 配置路径 | 说明 | 可选值 | 默认值 |
+|---|---|---|---|
+| `channels.wecom.dmPolicy` | 单聊访问策略 | `pairing` / `open` / `allowlist` / `disabled` | `open` |
+| `channels.wecom.allowFrom` | 单聊白名单（用户 ID） | — | `[]` |
+| `channels.wecom.groupPolicy` | 群聊访问策略 | `open` / `allowlist` / `disabled` | `open` |
+| `channels.wecom.groupAllowFrom` | 群聊白名单（群 ID） | — | `[]` |
+| `channels.wecom.groups` | 按群配置（如发送者白名单） | — | `{}` |
+
+#### 媒体设置
+
+| 配置路径 | 说明 | 默认值 |
+|---|---|---|
+| `channels.wecom.mediaLocalRoots` | 允许发送媒体的额外本地路径（支持 `~`） | `[]` |
+| `channels.wecom.media.maxBytes` | 媒体文件最大字节数 | `20971520`（20MB） |
+| `channels.wecom.media.tempDir` | 媒体处理临时目录 | — |
+| `channels.wecom.media.retentionHours` | 媒体文件保留时长（小时） | — |
+| `channels.wecom.media.cleanupOnStart` | 启动时清理临时媒体 | — |
+
+**媒体大小限制与自动降级：**
+
+| 媒体类型 | 最大大小 | 降级行为 |
+|---|---|---|
+| 图片 | 10 MB | 超出 → 以文件发送 |
+| 视频 | 10 MB | 超出 → 以文件发送 |
+| 语音 | 2 MB（仅 AMR） | 非 AMR 格式或超出 → 以文件发送 |
+| 文件 | 20 MB | 超出 → 拒绝（无法发送） |
+
+#### 网络设置
+
+| 配置路径 | 说明 | 默认值 |
+|---|---|---|
+| `channels.wecom.network.timeoutMs` | HTTP 请求超时（毫秒） | — |
+| `channels.wecom.network.retries` | 重试次数 | — |
+| `channels.wecom.network.retryDelayMs` | 重试间隔（毫秒） | — |
+| `channels.wecom.network.egressProxyUrl` | 可信 IP 场景的出站代理 URL | — |
+
+> **出站代理优先级**：`channels.wecom.network.egressProxyUrl` > `OPENCLAW_WECOM_EGRESS_PROXY_URL` > `WECOM_EGRESS_PROXY_URL` > `HTTPS_PROXY` > `ALL_PROXY` > `HTTP_PROXY`
+
+### Agent 模式配置
+
+Agent 模式使用 HTTP webhook 回调，消息为 XML 加密格式。需要在企业微信管理后台的「API 接收」设置中配置回调 URL。
+
+#### 前置条件
+
+1. 在 [企业微信管理后台](https://work.weixin.qq.com/wework_admin/frame#apps) 创建自建应用
+2. 记录 **CorpID**、**CorpSecret**（来自应用设置）与 **AgentId**
+3. 在应用设置的「API 接收」中：
+   - 记录 **Token** 与 **EncodingAESKey**（自动生成或自定义）
+   - **先不要点击保存** — 点击保存时企业微信会立即校验回调 URL
+
+#### 设置步骤
+
+> **重要**：必须先配置 Gateway，再在企业微信管理后台保存回调 URL。点击保存时企业微信会立即发送校验请求（带 `echostr` 的 GET 请求），Gateway 需要 `token` 和 `encodingAESKey` 才能正确解密并响应。
+
+**步骤 1：配置 Gateway**
+
+```shell
+openclaw config set channels.wecom.agent.corpId <YOUR_CORP_ID>
+openclaw config set channels.wecom.agent.corpSecret <YOUR_CORP_SECRET>
+openclaw config set channels.wecom.agent.agentId <YOUR_AGENT_ID>
+openclaw config set channels.wecom.agent.token <YOUR_CALLBACK_TOKEN>
+openclaw config set channels.wecom.agent.encodingAESKey <YOUR_ENCODING_AES_KEY>
+openclaw config set channels.wecom.enabled true
+openclaw gateway restart
+```
+
+**步骤 2：在企业微信管理后台保存回调 URL**
+
+回到「API 接收」设置，填入回调 URL：
+- **URL**：`https://<your-gateway-host>/plugins/wecom/agent/<accountId>`（例如 `/plugins/wecom/agent/default`）；单账号模式也可使用 `/plugins/wecom/agent`
+
+点击保存，校验应通过。
+
+#### JSON 配置
+
+```json
+{
+  "channels": {
+    "wecom": {
+      "enabled": true,
+      "agent": {
+        "corpId": "ww1234567890abcdef",
+        "corpSecret": "your-corp-secret",
+        "agentId": 1000002,
+        "token": "your-callback-token",
+        "encodingAESKey": "your-encoding-aes-key-43-chars"
+      }
+    }
+  }
+}
+```
+
+#### Agent 配置参考
+
+| 配置路径 | 说明 | 是否必填 |
+|---|---|---|
+| `channels.wecom.agent.corpId` | 企业 Corp ID | 是 |
+| `channels.wecom.agent.corpSecret` | 应用 secret | 是 |
+| `channels.wecom.agent.agentId` | 应用 Agent ID | 否（主动推送消息时需要） |
+| `channels.wecom.agent.token` | 回调校验 token | 是 |
+| `channels.wecom.agent.encodingAESKey` | 回调加密密钥（43 字符） | 是 |
+| `channels.wecom.agent.welcomeText` | 欢迎语 | 否 |
+| `channels.wecom.agent.dmPolicy` | 单聊访问策略（覆盖顶层） | 否 |
+| `channels.wecom.agent.allowFrom` | 单聊白名单（覆盖顶层） | 否 |
+
+#### Webhook 路径
+
+**Agent 模式：**
+
+| 路径 | 说明 |
+|---|---|
+| `/plugins/wecom/agent/<accountId>` | 推荐路径（例如 `/plugins/wecom/agent/default`） |
+| `/plugins/wecom/agent/default` | 多账号模式下自动路由到默认账号（即使默认账号 ID 不是 `default`） |
+| `/plugins/wecom/agent` | 兼容路径（单账号 / 多账号签名匹配） |
+| `/wecom/agent` | 旧版兼容路径 |
+
+**Bot Webhook 模式**（`connectionMode: "webhook"`）：
+
+| 路径 | 说明 |
+|---|---|
+| `/plugins/wecom/bot` | 推荐路径（单账号） |
+| `/plugins/wecom/bot/<accountId>` | 多账号路径 |
+| `/wecom/bot` | 旧版兼容路径 |
+| `/wecom` | 旧版兼容路径 |
+
+### 出站投递（Bot WS → Agent HTTP 兜底）
+
+插件采用 **Bot 优先、Agent 兜底** 的出站消息投递策略：
+
+1. **Bot WebSocket 可用** → 通过 WS 发送（支持 markdown、流式）
+2. **Bot WS 不可用** → 自动回退到 **Agent HTTP API**（`cgi-bin/message/send`）
+
+这意味着：
+- **仅 Agent 的账号**（未配置 Bot）仍可发送主动消息、Cron 投递与广播
+- **目标格式**如 `party:1`、`tag:Ops`、`user:zhangsan` 在两条路径中都完全支持
+- **媒体兜底**：当 Bot WS 不可用时，媒体文件先下载、通过 Agent API 上传到企业微信再发送；若上传失败则回退为文本 + URL
+- 无需手动切换 — 插件自动处理兜底
+
+### 双模式并用
+
+Bot 与 Agent 可在同一账号上同时运行。Bot 负责 WebSocket 流式；Agent 负责 HTTP webhook 回调与 API 驱动的回复。
+
+```json
+{
+  "channels": {
+    "wecom": {
+      "enabled": true,
+      "botId": "your-bot-id",
+      "secret": "your-bot-secret",
+      "agent": {
+        "corpId": "ww1234567890abcdef",
+        "corpSecret": "your-corp-secret",
+        "agentId": 1000002,
+        "token": "your-callback-token",
+        "encodingAESKey": "your-encoding-aes-key-43-chars"
+      }
+    }
+  }
+}
+```
+
+### 多账号配置
+
+使用 `accounts` 配置多个企业微信账号，每个账号可带可选的 bot 和/或 agent 子配置。账号级字段覆盖同名的顶层字段。
+
+```json
+{
+  "channels": {
+    "wecom": {
+      "enabled": true,
+      "defaultAccount": "main",
+      "dmPolicy": "open",
+      "accounts": {
+        "main": {
+          "botId": "bot-id-1",
+          "secret": "secret-1",
+          "agent": {
+            "corpId": "ww1234567890abcdef",
+            "corpSecret": "secret-a",
+            "agentId": 1000002,
+            "token": "token-a",
+            "encodingAESKey": "aes-key-a"
+          }
+        },
+        "support": {
+          "dmPolicy": "allowlist",
+          "allowFrom": ["admin1"],
+          "agent": {
+            "corpId": "ww1234567890abcdef",
+            "corpSecret": "secret-b",
+            "agentId": 1000003,
+            "token": "token-b",
+            "encodingAESKey": "aes-key-b"
+          }
+        }
+      }
+    }
+  }
+}
+```
+
+> **说明**：多账号模式下，没有显式 `bindings` 的账号不会回退到默认 agent。请为每个账号配置 bindings：
+> ```json
+> {
+>   "bindings": [
+>     { "agentId": "your-agent", "match": { "channel": "wecom", "accountId": "main" } }
+>   ]
+> }
+> ```
+
+### 动态 Agent 配置
+
+动态 Agent 路由按用户或群组自动创建隔离的 Agent，实现会话隔离。
+
+```json
+{
+  "channels": {
+    "wecom": {
+      "dynamicAgents": {
+        "enabled": true,
+        "dmCreateAgent": true,
+        "groupEnabled": true,
+        "adminUsers": ["admin_user_id"]
+      }
+    }
+  }
+}
+```
+
+| 配置路径 | 说明 | 默认值 |
+|---|---|---|
+| `channels.wecom.dynamicAgents.enabled` | 启用动态 Agent 路由 | `false` |
+| `channels.wecom.dynamicAgents.dmCreateAgent` | 为每个单聊用户创建隔离 Agent | `true` |
+| `channels.wecom.dynamicAgents.groupEnabled` | 为群聊启用动态 Agent | `true` |
+| `channels.wecom.dynamicAgents.adminUsers` | 管理员用户（绕过动态路由，使用主 Agent） | `[]` |
+
+---
+
+## 🔒 访问控制
+
+### 单聊（Direct Message）访问
+
+**默认**：`dmPolicy: "open"` — 所有用户无需审批即可发送单聊消息。
+
+#### 审批配对
+
+```shell
+openclaw pairing list wecom            # 查看待处理的配对请求
+openclaw pairing approve wecom <CODE>  # 审批配对请求
+```
+
+#### 白名单模式
+
+通过 `channels.wecom.allowFrom` 配置允许的用户 ID：
+
+```json
+{
+  "channels": {
+    "wecom": {
+      "dmPolicy": "allowlist",
+      "allowFrom": ["user_id_1", "user_id_2"]
+    }
+  }
+}
+```
+
+#### 开放模式
+
+设置 `dmPolicy: "open"` 允许所有用户无需审批即可发送单聊消息。
+
+#### 禁用模式
+
+设置 `dmPolicy: "disabled"` 完全屏蔽所有单聊消息。
+
+### 群聊访问
+
+#### 群组策略（`channels.wecom.groupPolicy`）
+
+- `"open"` — 允许所有群聊消息（默认）
+- `"allowlist"` — 仅允许 `groupAllowFrom` 中列出的群
+- `"disabled"` — 禁用所有群聊消息
+
+### 群组配置示例
+
+#### 允许所有群（默认行为）
+
+```json
+{
+  "channels": {
+    "wecom": {
+      "groupPolicy": "open"
+    }
+  }
+}
+```
+
+#### 仅允许指定群
+
+```json
+{
+  "channels": {
+    "wecom": {
+      "groupPolicy": "allowlist",
+      "groupAllowFrom": ["group_id_1", "group_id_2"]
+    }
+  }
+}
+```
+
+#### 仅允许群内指定发送者（发送者白名单）
+
+除群白名单外，还可限制群内哪些成员能与机器人交互。仅处理 `groups.<chatId>.allowFrom` 中列出的用户消息，其他成员的消息会被静默忽略。这是发送者级白名单，适用于**所有消息**。
+
+```json
+{
+  "channels": {
+    "wecom": {
+      "groupPolicy": "allowlist",
+      "groupAllowFrom": ["group_id_1"],
+      "groups": {
+        "group_id_1": {
+          "allowFrom": ["user_id_1", "user_id_2"]
+        }
+      }
+    }
+  }
+}
+```
+
+---
+
+## ⏰ Cronjob（定时任务）
+
+插件通过 OpenClaw 内置的 Cron 服务支持定时消息投递。Cron 任务走 **Agent 出站**通道，因此必须配置 Agent 模式。
+
+### 目标格式
+
+`delivery.to` 字段支持以下目标格式：
+
+| 格式 | 目标 | 示例 |
+|--------|--------|--------|
+| `party:<id>` | 部门（所有成员） | `party:1`（根部门 = 全体员工） |
+| `dept:<id>` | 部门（party 的别名） | `dept:5` |
+| `tag:<id>` | 标签组 | `tag:Ops` |
+| `user:<id>` | 指定用户 | `user:zhangsan` |
+| `group:<id>` | 外部群聊 | `group:wr123abc` |
+| `chat:<id>` | 群聊（group 的别名） | `chat:wc456def` |
+| 纯数字 | 自动识别为部门 | `1` → `party:1` |
+| `wr...` / `wc...` | 自动识别为群聊 | `wr123` → `chatid` |
+| 其他字符串 | 自动识别为用户 | `zhangsan` → `touser` |
+
+> **命名空间前缀**（`wecom:`、`qywx:`、`wework:`、`wechatwork:`、`wecom-agent:`）在解析前会自动去除。
+
+### 方式一：CLI（推荐 — 立即生效）
+
+```shell
+openclaw cron add \
+  --name "daily-report" \
+  --agent main \
+  --cron "0 9 * * 1-5" \
+  --tz "Asia/Shanghai" \
+  --message "Good morning! Here is your daily briefing." \
+  --announce \
+  --channel wecom \
+  --to "party:1"
+```
+
+> **说明**：`--announce` 启用投递模式（将 AI 回复广播到目标会话）。使用 `--no-deliver` 保持内部输出。已废弃的 `--deliver` 标志是 `--announce` 的别名。
+
+常用 CLI 命令：
+
+```shell
+openclaw cron list              # 列出所有 cron 任务
+openclaw cron show <id>         # 查看任务详情
+openclaw cron enable <id>       # 启用任务
+openclaw cron disable <id>      # 禁用任务
+openclaw cron remove <id>       # 删除任务
+openclaw cron run <id>          # 手动触发任务
+openclaw cron runs --id <id>    # 查看运行历史
+openclaw cron edit <id> --message "New prompt"  # 编辑任务
+```
+
+### 方式二：编辑 `jobs.json`（需重启 gateway）
+
+文件路径：`~/.openclaw/cron/jobs.json`
+
+```json
+{
+  "version": 1,
+  "jobs": [
+    {
+      "id": "daily-report",
+      "name": "Daily Report",
+      "agentId": "main",
+      "enabled": true,
+      "schedule": { "kind": "cron", "expr": "0 9 * * 1-5", "tz": "Asia/Shanghai" },
+      "sessionTarget": "isolated",
+      "wakeMode": "now",
+      "payload": {
+        "kind": "agentTurn",
+        "message": "Generate today's briefing and send it."
+      },
+      "delivery": {
+        "mode": "announce",
+        "channel": "wecom",
+        "to": "party:1",
+        "accountId": "main"
+      },
+      "state": {}
+    }
+  ]
+}
+```
+
+编辑后重启 gateway：
+
+```shell
+openclaw gateway restart
+```
+
+### 方式三：通过对话创建（立即生效）
+
+可以直接在企业微信会话中向 AI 智能体提问：
+
+> "创建一个定时任务：每个工作日早上 9 点向全公司发送每日简报"
+
+智能体会调用 Cron API 创建任务 — 无需重启。
+
+### 注意事项
+
+- Cron 任务使用 **Agent 出站**路径 — 必须配置 Agent 模式（`corpId` / `corpSecret` / `agentId`）。
+- 服务器 IP 必须在企业微信可信 IP 白名单内，或配置 `egressProxyUrl` 使用固定出站代理。
+- 通过 CLI 或对话 API 创建的任务立即生效。手动编辑 `jobs.json` 需要执行 `openclaw gateway restart`。
+- 多账号场景下，将 `delivery.accountId` 设为目标账号（如 `"main"`、`"support"`）。
+
+---
+
+## 📦 更新
+
+```shell
+openclaw plugins update wecom-openclaw-plugin
+```
+
+---
+
+## 📄 许可证
+
+MIT

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wecom/wecom-openclaw-plugin",
-  "version": "2026.8.17",
+  "version": "2026.9.15",
   "type": "module",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",

package/skills/wecomcli-doc/SKILL.md

@@ -35,8 +35,8 @@ description: 企微 doc 内容操作技能，包含新建在线文档、导入
 
 | 用户意图 | 参考位置                                                          |
 |---|---------------------------------------------------------------|
-| 新建doc文档（在线） | 见下方「新建doc文档」                                                  |
-| 导入本地文件为企微doc文档 | 见下方「导入doc文档」                                                  |
+| 从零开始新建doc文档 | 见下方「新建doc文档」                                                  |
+| 用户已有本地文件，要求写入 / 创建 / 新建企微doc文档 | 见下方「导入doc文档」                                                  |
 | 读取doc文档内容 | 见下方「读取doc文档内容」                                                |
 | 追加文本到doc文档末尾 | [+contents-append](references/doc-contents-append.md)       |
 | 全量覆盖doc文档内容 | [+contents-overwrite](references/doc-contents-overwrite.md) |
@@ -50,10 +50,10 @@ description: 企微 doc 内容操作技能，包含新建在线文档、导入
 
 ### 新建doc文档
 
-新建企微doc文档统一走「**生成 `.docx` → 导入**」两步流程：
+仅适用于用户**没有本地文件，需要从零开始创建doc文档**的场景，统一走「生成 `.docx` → 导入」两步流程：
 
 1. 生成 `.docx` 文件：按 [+doc-create](references/doc-create.md) 生成 `.docx` 文件。
-2. 导入为企微doc文档：使用下方「导入doc文档」接口将生成的 `.docx` 文件导入为企微doc文档。注意import导入的时候 `file_name` 应和文档标题保持一致。
+2. 导入为企微doc文档：使用下方「导入doc文档」接口将生成的 `.docx` 文件导入为企微doc文档。
 
 ### 导入doc文档
 
@@ -138,3 +138,8 @@ wecom-cli doc contents get --json '<JSON 参数>'
 1. 从文档链接提取（优先）：用户提供了企微文档 URL 时，直接从 URL 中解析。URL 格式为 `https://doc.weixin.qq.com/<type>/<docid>?scode=...`，取 `/<type>/` 后、`?` 前的部分即为 docid。
 2. 通过文档搜索获取（备选）：用户仅提供文档名称或关键词、未给链接时，先调用 `wecomcli-doc-manage` 搜索文档，从返回结果中取 `docid`。
 3. 用户直接提供：用户明确给出了完整 `docid`，可直接使用，无需再提取或搜索。
+
+
+## 安装依赖
+
+- `python-docx`：用于从零开始新建/生成一个docx文件。如果当前环境无此包，需要先安装。

package/skills/wecomcli-doc/references/doc-create.md

@@ -1,6 +1,6 @@
 # 创建 docx 文件
 
-模型只需写一份 JSONL 描述文件（**不需要写 Python 脚本**），由分发器 `build_docx.py` 把每条命令派发到对应函数完成 `.docx` 生成
+模型只需写一份 JSONL 描述文件（**不需要写 Python 脚本**），由分发器 `build_docx.py` 把每条命令派发到对应函数完成 `.docx` 生成。该脚本依赖 `python-docx`，需提前检查安装。
 
 # 整体工作流
 
@@ -9,7 +9,8 @@
 | 1. 写 jsonl | `Write` 工具                                                                       | 输出一个 `*.jsonl` 文件 |
 | 2. 生成 docx | `python build_docx.py <*.jsonl>` | 自动应用默认样式 → 按 `action` 派发 → 输出 `.docx` |
 
-> **`build_docx.py` 位置**：（即与 当前 `references/` 同级的 `scripts/` 目录下）
+`build_docx.py` 位置：位于 `wecom-unified` 技能目录的scripts子目录下 `/wecom-unified/scripts/`。
+最后生成的docx文件默认位于 JSONL 所在目录的 `docx/` 子目录。
 
 # JSONL 书写规范
 

package/skills/wecomcli-doc/scripts/build_docx.py

@@ -10,9 +10,8 @@ Workflow::
        （action 取值 / params 字段名 / 类型 / 取值范围）。
        任何偏差立即抛 ``TypeError``（"类型错误，无法执行"）。
     2. 校验通过后，再创建 docx 并按 action 派发到 ``DocxBuilder``。
-    3. 通过本地文件系统写出 ``.docx``，输出路径自动选取于
-       ``WECOMAGENT_WRITABLE_DIRS`` 的第一个目录；同名文件会追加
-       ``_1`` / ``_2`` … 后缀避免覆盖。
+    3. 通过本地文件系统写出 ``.docx``，默认输出到 JSONL 文件所在目录的
+       ``docx/`` 子目录；同名文件会追加时间戳与进程号后缀避免覆盖。
 
 Usage::
 
@@ -22,8 +21,6 @@ Usage::
 from __future__ import annotations
 
 import argparse
-import base64
-import functools
 import io
 import json
 import os
@@ -462,97 +459,22 @@ def _spec_validate_command(cmd: Any, line_no: int) -> tuple[str, dict]:
 
 
 # ===========================================================================
-# Sandboxed local IO helpers
+# Local IO helpers
 # ===========================================================================
-#
-# 所有 fs 读写都限制在
-# ``WECOMAGENT_READABLE_DIRS`` / ``WECOMAGENT_WRITABLE_DIRS`` 限定
-# （JSON 数组：``[{"path": "/abs/dir", "label": "..."}]``）。
-
-ENV_READABLE = "WECOMAGENT_READABLE_DIRS"
-ENV_WRITABLE = "WECOMAGENT_WRITABLE_DIRS"
 
 # 读入 / 写出文件的大小硬上限：30 MiB。
 # - 读入：避免一次性把巨型 JSONL 拉进内存撑爆进程；
-# - 写出：避免生成过大的 .docx 写入磁盘（base64 后体积更大）。
+# - 写出：避免生成过大的 .docx 写入磁盘。
 MAX_FILE_SIZE_BYTES = 30 * 1024 * 1024
 
 
-@functools.lru_cache(maxsize=None)
-def _parse_roots(env_name: str) -> tuple[str, ...]:
-    """Parse a JSON-array env var into a tuple of realpath roots (cached)."""
-    raw = os.environ.get(env_name, "")
-    if not raw:
-        raise RuntimeError(f"环境变量 {env_name} 未设置或为空")
-    parsed = json.loads(raw)
-    if not isinstance(parsed, list):
-        raise RuntimeError(
-            f"{env_name} 必须是 JSON 数组，实际为 {type(parsed).__name__}"
-        )
-    roots: list[str] = []
-    for it in parsed:
-        if isinstance(it, str):
-            it = json.loads(it)
-        if not isinstance(it, dict):
-            raise RuntimeError(
-                f"{env_name} 元素必须是 dict 或 dict 的 JSON 字符串，"
-                f"实际为 {type(it).__name__}"
-            )
-        p = it.get("path")
-        if not isinstance(p, str) or not p.strip():
-            raise RuntimeError(f"{env_name} 元素缺少有效的 path 字段: {it!r}")
-        roots.append(os.path.realpath(p.strip()))
-    if not roots:
-        raise RuntimeError(f"环境变量 {env_name} 解析后为空")
-    return tuple(roots)
-
-
-def _reject_relative_segments(path: str) -> None:
-    """Reject path strings that include ``.`` or ``..`` segments such as
-    ``./foo``, ``../bar`` or ``/abs/path/../x``.
-
-    Although ``os.path.realpath`` would silently normalize these away,
-    accepting them would bypass the contract that callers must hand in
-    explicit, fully-qualified paths inside the sandboxed roots — and
-    could be abused to escape the intended directory in edge cases where
-    symlinks are present.
-    """
-    if not path:
-        return
-    for seg in path.replace("\\", "/").split("/"):
-        if seg in (".", ".."):
-            raise ValueError(
-                f"路径不允许包含 './' 或 '../' 这类相对路径片段: {path!r}"
-            )
-
-
-def _ensure_within(path: str, env_name: str) -> str:
-    """Realpath ``path`` and ensure it lies within one of ``env_name``'s roots."""
-    if not path:
-        raise ValueError("path 不能为空")
-    _reject_relative_segments(path)
-    real = os.path.realpath(path)
-    roots = _parse_roots(env_name)
-    for root in roots:
-        try:
-            common = os.path.commonpath([real, root])
-        except ValueError:
-            continue
-        if common == root:
-            return real
-    raise PermissionError(
-        f"路径越权: {real} 不在 {env_name} 范围 {roots} 之内"
-    )
-
-
 def _read_text(path: str) -> str:
-    """Read a UTF-8 text file from an allowed readable directory.
+    """Read a UTF-8 text file without applying directory restrictions.
 
     最多读取 ``MAX_FILE_SIZE_BYTES + 1`` 字节，以便在不把超大文件
     整体载入内存的前提下判断是否超限。
     """
-    real = _ensure_within(path, ENV_READABLE)
-    with open(real, "rb") as f:
+    with open(path, "rb") as f:
         data = f.read(MAX_FILE_SIZE_BYTES + 1)
     if len(data) > MAX_FILE_SIZE_BYTES:
         raise ValueError(
@@ -562,38 +484,17 @@ def _read_text(path: str) -> str:
     return data.decode("utf-8")
 
 
-def _write_b64(path: str, data_b64: str, overwrite: bool = False) -> None:
-    """Write a base64-encoded binary blob to an allowed writable directory.
-
-    这里在写入前对路径做 ``os.path.islink`` 检查并显式拒绝：
-      - 检查 ``path``（原始入参）：拦截 "目标位置本身就是软链" 的常见情况；
-      - 检查 ``real``（realpath 结果）：作为防御纵深，覆盖悬挂软链 /
-        竞态等 realpath 仍可能返回软链的边缘情况。
-    """
-    real = _ensure_within(path, ENV_WRITABLE)
-    if os.path.islink(path) or os.path.islink(real):
-        raise PermissionError(
-            f"拒绝写入符号链接以避免跨目录覆盖: {path!r}"
-        )
-    data = base64.b64decode(data_b64, validate=True)
+def _write_bytes(path: str, data: bytes) -> None:
+    """Write binary data without applying directory restrictions."""
     if len(data) > MAX_FILE_SIZE_BYTES:
         raise ValueError(
-            f"输出文件过大：解码后 {len(data)} 字节，"
+            f"输出文件过大：{len(data)} 字节，"
             f"超过上限 {MAX_FILE_SIZE_BYTES} 字节（30 MiB）"
         )
 
-    parent = os.path.dirname(real)
+    parent = os.path.dirname(os.path.abspath(path))
     os.makedirs(parent, exist_ok=True)
-
-    # 创建父目录后再次解析路径，防止目录在检查和写入之间变为软链。
-    real = _ensure_within(path, ENV_WRITABLE)
-    if os.path.islink(path) or os.path.islink(real):
-        raise PermissionError(
-            f"拒绝写入符号链接以避免跨目录覆盖: {path!r}"
-        )
-
-    mode = "wb" if overwrite else "xb"
-    with open(real, mode) as f:
+    with open(path, "xb") as f:
         f.write(data)
 
 
@@ -736,10 +637,10 @@ class DocxBuilder:
     def save(self, path: str) -> None:
         """Persist the document to the local filesystem.
 
-        ``overwrite=False`` enforces the "never clobber an existing .docx"
+        Exclusive-create mode enforces the "never clobber an existing .docx"
         guarantee that ``_pick_output_path`` makes when picking the filename.
 
-        在编码 / 写入之前校验序列化后的 docx 体积不得超过
+        在写入之前校验序列化后的 docx 体积不得超过
         ``MAX_FILE_SIZE_BYTES``；超限直接抛 ``ValueError`` 中止保存。
         """
         buf = io.BytesIO()
@@ -750,8 +651,7 @@ class DocxBuilder:
                 f"输出文件过大：序列化后 {size} 字节，"
                 f"超过上限 {MAX_FILE_SIZE_BYTES} 字节（30 MiB）"
             )
-        data_b64 = base64.b64encode(buf.getvalue()).decode("ascii")
-        _write_b64(path, data_b64, overwrite=False)
+        _write_bytes(path, buf.getvalue())
 
     # -- 2. Page setup ----------------------------------------------------
 
@@ -1317,14 +1217,16 @@ def run_jsonl(spec_path: str, output: str) -> str:
 
 
 def _pick_output_path(spec_path: str) -> str:
-    """Pick a non-conflicting ``.docx`` path under the writable root.
+    """Pick a non-conflicting path beside the JSONL file.
 
-    Filename derives from the spec's stem (``report.jsonl`` → ``report.docx``);
-    on conflict a timestamp suffix is appended to avoid overwriting.
+    The document is written to a ``docx/`` subdirectory of the JSONL file's
+    directory. Its filename derives from the spec's stem
+    (``report.jsonl`` → ``report.docx``); on conflict a timestamp suffix is
+    appended to avoid overwriting.
     """
-    target_dir = os.path.join(_parse_roots(ENV_WRITABLE)[0], "docx")
-    target_dir = _ensure_within(target_dir, ENV_WRITABLE)
-    stem = Path(spec_path).stem or "document"
+    spec = Path(spec_path).expanduser().resolve()
+    target_dir = str(spec.parent / "docx")
+    stem = spec.stem or "document"
     if not re.fullmatch(r"[A-Za-z0-9_.\-]{1,128}", stem):
         stem = "document"
 
@@ -1350,7 +1252,7 @@ def main() -> None:
 
     try:
         output = _pick_output_path(args.spec)
-    except Exception as e:
+    except Exception:
         print("Error: failed to pick output path")
         sys.exit(2)
 
@@ -1361,9 +1263,6 @@ def main() -> None:
         # 转译成 "类型错误，无法执行" 提示。
         print(f"Error: 类型错误，无法执行: {e}", file=sys.stderr)
         sys.exit(2)
-    except PermissionError:
-        print("Error: 路径不在允许范围内", file=sys.stderr)
-        sys.exit(2)
     except Exception:
         print("Error: 执行失败，请检查输入文件格式或稍后重试", file=sys.stderr)
         sys.exit(2)

package/skills/wecomcli-sheet/SKILL.md

@@ -45,53 +45,18 @@ description: 企业微信在线表格文档管理：新建在线表格、导入
 
 ### 新建在线表格
 
-从零新建一篇企微在线表格：空白，或带初始数据（二维表格数据）。**本接口不接受任何文件路径参数**——"用本地文件建/导入"走「导入在线表格」。
+从零新建企微在线表格时，先按用户需求创建一个本地 `.xlsx`，完成质量校验后，再通过 `wecom-cli sheet import` 导入为企微在线表格。
 
-#### 调用方式
-
-使用 wecom-cli 工具按照下面格式调用
-
-```
-wecom-cli sheet create --json '<JSON 参数>'
-```
+#### 标准流程
 
-#### 参数
-
-| 字段 | 类型 | 必填 | 默认值 | 语义 |
-|---|---|---|---|---|
-| `doc_name` | string | 是 | — | 表格标题 |
-| `grid_data` | object | 否 | — | 默认子表初始化数据；子结构见下方 |
-
-`grid_data` 对象结构：
-
-| 子字段 | 类型 | 必填 | 默认值 | 语义 |
-|---|---|---|---|---|
-| `start_row` / `start_column` | int | 否 | `0` | 起始行 / 列号，从 0 起 |
-| `rows` | array | 否 | — | 各行数据；每项 `values` 为单元格数组 |
-| `rows[].values[].cell_value` | object | 否 | — | 单元格值，见下方「cell_value 类型选择」 |
-| `rows[].values[].data_type` | string | 否 | — | 枚举：`TEXT` / `NUMBER` / `LINK` / `FORMULA` |
-
-##### cell_value 类型选择
-
-> 硬规则：选择 `cell_value` 形态后，必须同时把同级的 `data_type` 设置为下表对应值。
-
-| 形态 | 对应 `data_type` | 结构 | 适用场景 |
-|---|---|---|---|
-| `text` | `TEXT` | `{"text": "<纯文本>"}` | 纯文本内容（如姓名、说明、标签、编号字符串等） |
-| `number` | `NUMBER` | `{"number": 123.45}` | 数值，用于金额、数量、比率等需要参与公式计算或聚合的数据；值为 JSON 数字类型，不加引号 |
-| `formula` | `FORMULA` | `{"formula": "=SUM(A1,A2)"}` | 任何以 `=` 开头的公式，包括 `=SUM(...)`、`=A1+B1`、`=IF(...)`、`=VLOOKUP(...)` 等 |
-| `link` | `LINK` | `{"link": {"url": "<URL>", "text": "<显示文本>"}}` | 超链接 |
-
-#### 返回
-
-| 字段 | 类型 | 说明 |
-|---|---|---|
-| `docid` | string | 新建表格 ID |
-| `url` | string | 表格访问链接 |
+1. 使用 `openpyxl` 创建本地 `.xlsx`  
+2. 导入前校验本地 `.xlsx`：文件存在且非空、可正常打开、工作表名称与数量正确、关键数据/公式/格式符合用户要求。校验不通过时先修复本地文件，不得导入未验证产物。  
+3. 调用下方「导入在线表格」的 `wecom-cli sheet import`，把已校验的 `.xlsx` 导入为企微在线表格。  
+4. 确认导入结果的 `task_status` 为成功状态。向用户返回企微在线表格 URL。除非用户明确要求保留或接收本地文件，否则不要把本地 `.xlsx` 当作最终交付物。
 
 #### 使用规则
 
-- **何时走 import 而非本接口**：用户提到具体文件路径、或明确说"导入 / 用这个文件建"，一律走「导入在线表格」。
+- 不要混淆编辑场景：上述流程只适用于从零新建。修改已有企微在线表格时，继续使用读取、修改、追加、子表管理等在线接口，不得重新生成 XLSX 后覆盖导入
 
 ### 导入在线表格
 
@@ -159,7 +124,7 @@ wecom-cli sheet get --json '<JSON 参数>'
 
 > 必填参数缺失 / `docid` 多候选 / 新建 vs 导入等歧义场景，用简洁自然语言仅追问缺失或有歧义的信息；有候选项时在文字中列出供用户选择，不得自行猜测。
 
-#### `docid` 使用规则
+## `docid` 使用规则
 
 `docid`仅cli使用。
 最终展示用户时，不应展示 `docid`，而是使用文档 URL：
@@ -175,3 +140,7 @@ wecom-cli sheet get --json '<JSON 参数>'
 1. 从文档链接提取（优先）：用户提供了企微文档 URL 时，直接从 URL 中解析。URL 格式为 `https://doc.weixin.qq.com/<type>/<docid>?scode=...`，取 `/<type>/` 后、`?` 前的部分即为 docid。
 2. 通过文档搜索获取（备选）：用户仅提供文档名称或关键词、未给链接时，先调用 `wecomcli-doc-manage` 搜索文档，从返回结果中取 `docid`。
 3. 用户直接提供：用户明确给出了完整 `docid`，可直接使用，无需再提取或搜索。
+
+## 安装依赖
+
+- `openpyxl`: 用于创建本地xlsx文件 / 在线表格。如果环境没有此包，必须先安装。