vault backup: 2026-07-08 10:56:58

OpenClaw/OpenClaw 企业微信机器人部署与Skills指南.md

@@ -0,0 +1,443 @@
+---
+tags:
+  - openclaw
+  - 企业微信
+  - wecom
+  - 机器人
+  - skill
+created: 2026-07-04
+---
+
+# OpenClaw 企业微信机器人部署与 Skills 指南
+
+## 一、概述
+
+OpenClaw 企业微信插件（`@wecom/wecom-openclaw-plugin`）由腾讯企业微信团队官方维护，支持两种模式：
+
+| 模式 | 连接方式 | 消息格式 | 适用场景 |
+|------|----------|----------|----------|
+| **Bot 模式**（智能机器人） | WebSocket 长连接 | JSON | 快速接入，流式回复 |
+| Agent 模式（自建应用） | HTTP Webhook 回调 | XML 加密 | 企业应用，API 驱动 |
+
+> 本文档聚焦 Bot 模式（WebSocket），这也是最常用的方式。
+
+---
+
+## 二、前提条件
+
+- OpenClaw >= 2026.3.28
+- 企业微信管理后台创建「长连接方式」智能机器人，获取 **Bot ID** 和 **Secret**
+  - 创建入口：https://open.work.weixin.qq.com/help2/pc/cat?doc_id=21657#2.1
+
+---
+
+## 三、部署步骤
+
+### 3.1 安装插件
+
+```bash
+# 一键安装（推荐）
+npx -y @wecom/wecom-openclaw-cli install
+
+# 强制重装
+npx -y @wecom/wecom-openclaw-cli install --force
+```
+
+### 3.2 启用插件
+
+安装后插件默认处于 **disabled** 状态，需两步启用：
+
+```bash
+# 1. 将插件加入白名单
+openclaw config set plugins.allow '["deepseek","searxng","memory-core","wecom-openclaw-plugin"]'
+
+# 2. 重启 gateway
+openclaw daemon restart
+```
+
+> 验证：`openclaw plugins list | grep wecom` 应显示 `enabled`
+
+### 3.3 配置 Bot 凭证
+
+```bash
+openclaw config set channels.wecom.botId "你的BotID"
+openclaw config set channels.wecom.secret "你的Secret"
+openclaw config set channels.wecom.enabled true
+openclaw daemon restart
+```
+
+### 3.4 配置 wecom_mcp 工具白名单
+
+Skills 依赖 `wecom_mcp` MCP 工具，需确保在 `tools.alsoAllow` 中：
+
+```bash
+openclaw config set tools.alsoAllow '["wecom_mcp"]'
+```
+
+### 3.5 验证
+
+```bash
+openclaw status
+# 应看到：WeCom | ON | OK | configured
+```
+
+---
+
+## 四、配置参考
+
+### Bot 模式核心配置
+
+| 配置项 | 说明 | 默认值 |
+|--------|------|--------|
+| `channels.wecom.enabled` | 启用通道 | `false` |
+| `channels.wecom.botId` | 机器人 Bot ID | — |
+| `channels.wecom.secret` | 机器人 Secret | — |
+| `channels.wecom.connectionMode` | 连接模式 | `websocket` |
+| `channels.wecom.websocketUrl` | WebSocket 端点 | `wss://openws.work.weixin.qq.com` |
+| `channels.wecom.sendThinkingMessage` | 发送"思考中"占位 | `true` |
+
+### 访问控制
+
+| 配置项 | 说明 | 可选值 | 默认值 |
+|--------|------|--------|--------|
+| `channels.wecom.dmPolicy` | 私聊策略 | `pairing`/`open`/`allowlist`/`disabled` | `open` |
+| `channels.wecom.groupPolicy` | 群聊策略 | `open`/`allowlist`/`disabled` | `open` |
+| `channels.wecom.allowFrom` | 私聊白名单 | userid 数组 | `[]` |
+| `channels.wecom.groupAllowFrom` | 群聊白名单 | chatid 数组 | `[]` |
+
+---
+
+## 五、内置 Skills 详解（12个）
+
+> 所有 Skill 通过 `wecom_mcp` MCP 工具调用，格式：`wecom_mcp call <品类> <接口> '<JSON入参>'`
+
+### 5.1 wecom-contact — 通讯录查询
+
+**触发词**：查同事、找某人、通讯录
+
+| 接口 | 用途 |
+|------|------|
+| `get_userlist` | 获取可见范围内全部成员（userid、姓名、别名） |
+
+```
+wecom_mcp call contact get_userlist '{}'
+```
+
+### 5.2 wecom-msg — 消息管理 💬
+
+**触发词**：查看消息、看聊天记录、发消息、最近有什么消息
+
+| 接口 | 用途 | chat_type |
+|------|------|-----------|
+| `get_msg_chat_list` | 按时间范围查会话列表 | — |
+| `get_message` | 拉取会话消息（7天内） | 1=单聊 2=群聊 |
+| `get_msg_media` | 下载图片/文件/语音/视频 | — |
+| `send_message` | 发送文本消息 | 1=单聊 2=群聊 |
+
+```
+# 获取会话列表
+wecom_mcp call msg get_msg_chat_list '{"begin_time":"2026-07-01 00:00:00","end_time":"2026-07-04 23:59:59"}'
+
+# 拉取群消息
+wecom_mcp call msg get_message '{"chat_type":2,"chatid":"群ID","begin_time":"2026-07-01 00:00:00","end_time":"2026-07-04 23:59:59"}'
+
+# 发送消息
+wecom_mcp call msg send_message '{"chat_type":2,"chatid":"群ID","msgtype":"text","text":{"content":"你好"}}'
+```
+
+> **限制**：消息拉取仅支持最近 7 天，时间格式 `YYYY-MM-DD HH:mm:ss`
+
+### 5.3 wecom-doc — 文档管理
+
+**触发词**：企业微信文档、创建文档、写个文档、改写文档
+
+| 接口 | 用途 |
+|------|------|
+| `create_doc` | 新建空白文档 |
+| `get_doc_content` | 以 Markdown 读取文档内容 |
+| `edit_doc_content` | 用 Markdown 覆写文档内容 |
+
+```
+wecom_mcp call doc create_doc '{"doc_name":"会议纪要"}'
+wecom_mcp call doc get_doc_content '{"docid":"xxx"}'
+wecom_mcp call doc edit_doc_content '{"docid":"xxx","content":"# 新内容"}'
+```
+
+> 支持通过 `docid` 或文档 URL 定位。URL 格式：`https://doc.weixin.qq.com/doc/xxx`
+
+### 5.4 wecom-sheet — 在线表格
+
+**触发词**：企业微信表格、在线表格、Excel
+
+| 接口 | 用途 |
+|------|------|
+| `create_doc` | 新建在线表格（doc_type=3） |
+| `get_doc_content` | 读取为 Markdown |
+| `sheet_get_info` | 获取子表列表和基础信息 |
+
+```
+wecom_mcp call doc create_doc '{"doc_type":3,"doc_name":"数据统计"}'
+```
+
+> URL 格式：`https://doc.weixin.qq.com/sheet/xxx`
+
+### 5.5 wecom-smartsheet — 智能表格
+
+**触发词**：智能表格、smartsheet
+
+| 接口 | 用途 |
+|------|------|
+| `create_doc` | 新建智能表格（doc_type=10） |
+| `smartsheet_get_sheet` | 查询子表 |
+| `smartsheet_add_sheet` | 添加子表 |
+| `smartsheet_get_fields` | 查询字段 |
+| `smartsheet_add_fields` | 添加字段 |
+| `smartsheet_get_records` | 查询记录 |
+
+```
+wecom_mcp call doc create_doc '{"doc_type":10,"doc_name":"项目管理"}'
+```
+
+> URL 格式：`https://doc.weixin.qq.com/smartsheet/xxx`
+
+### 5.6 wecom-smartpage — 智能文档
+
+**触发词**：智能文档、智能主页
+
+| 接口 | 用途 |
+|------|------|
+| `smartpage_create` | 将 Markdown 发布为智能文档 |
+| `smartpage_export_task` | 提交导出任务（异步） |
+| `smartpage_get_export_result` | 查询导出结果 |
+
+```
+wecom_mcp call doc smartpage_create '{"doc_name":"周报","content":"# 本周工作总结"}'
+```
+
+> URL 格式：`https://doc.weixin.qq.com/smartpage/xxx`
+
+### 5.7 wecom-meeting — 会议管理
+
+**触发词**：创建会议、预约会议、查看会议、取消会议
+
+| 接口 | 用途 |
+|------|------|
+| `create_meeting` | 创建预约会议 |
+| `list_user_meetings` | 查询会议列表（±30天） |
+| `get_meeting_info` | 获取会议详情 |
+| `cancel_meeting` | 取消会议 |
+| `set_invite_meeting_members` | 更新参与人 |
+
+```
+wecom_mcp call meeting create_meeting '{"title":"项目评审","start_time":1719993600,"end_time":1719997200}'
+```
+
+### 5.8 wecom-schedule — 日程管理 📅
+
+**触发词**：创建日程、安排日程、查看日程、闲忙查询
+
+| 接口 | 用途 |
+|------|------|
+| `get_schedule_list_by_range` | 查询日程列表 |
+| `get_schedule_detail` | 获取日程详情 |
+| `create_schedule` | 创建日程 |
+| `update_schedule` | 修改日程 |
+| `cancel_schedule` | 取消日程 |
+| `check_availability` | 查询成员闲忙状态 |
+
+```
+wecom_mcp call schedule create_schedule '{"subject":"团队周会","start_time":"2026-07-05 10:00:00","end_time":"2026-07-05 11:00:00"}'
+```
+
+### 5.9 wecom-todo — 待办事项
+
+**触发词**：创建待办、分派任务、标记完成、查看待办
+
+| 接口 | 用途 |
+|------|------|
+| `search_todo_userid` | 按姓名搜索 userid |
+| `create_todo` | 创建待办 |
+| `update_todo` | 更新待办内容/时间 |
+| `change_todo_user_status` | 更改用户状态（接受/拒绝/完成） |
+| `get_todo_list` | 获取待办列表 |
+| `get_todo_detail` | 批量获取待办详情 |
+| `delete_todo` | 删除待办 |
+
+```
+wecom_mcp call todo create_todo '{"content":"完成Q3报告","follower":[{"userid":"zhangsan"}]}'
+```
+
+### 5.10 wecom-send-media — 发送文件
+
+**触发词**：发送文件、分享图片、传个文件
+
+在回复中使用 `MEDIA:` 指令发送本地文件：
+
+```
+MEDIA:/path/to/image.png
+MEDIA:/path/to/document.pdf
+```
+
+> 大小限制：图片 10MB、视频 10MB、语音 2MB（AMR）、文件 20MB。超限自动降级。
+
+### 5.11 wecom-send-template-card — 模板卡片
+
+**触发词**：发通知、投票、方案选择、多维度选择
+
+| 卡片类型 | 用途 |
+|----------|------|
+| `text_notice` | 文本通知 |
+| `news_notice` | 图文通知 |
+| `button_interaction` | 按钮交互 |
+| `vote_interaction` | 投票表决 |
+| `multiple_interaction` | 多维度选择 |
+
+```
+# 投票
+wecom_mcp call msg send_template_card '{"chat_type":2,"chatid":"群ID","template_card_type":"vote_interaction",...}'
+```
+
+### 5.12 wecom-preflight — 前置检查
+
+**用途**：首次使用前检查 `wecom_mcp` 是否已加入工具白名单。其他 Skill 会自动触发此检查。
+
+---
+
+## 六、文档品类 URL 识别速查
+
+| URL 模式 | 品类 | 对应 Skill |
+|----------|------|------------|
+| `doc.weixin.qq.com/doc/*` | 普通文档 | `wecom-doc` |
+| `doc.weixin.qq.com/sheet/*` | 在线表格 | `wecom-sheet` |
+| `doc.weixin.qq.com/smartsheet/*` | 智能表格 | `wecom-smartsheet` |
+| `doc.weixin.qq.com/smartpage/*` | 智能文档 | `wecom-smartpage` |
+
+---
+
+## 七、群消息获取
+
+### 方式一：被动接收（默认）
+
+把机器人加入群聊即可。群策略默认 `open`，所有群都能 @机器人 对话。
+
+```bash
+# 查看/设置群策略
+openclaw config get channels.wecom.groupPolicy
+openclaw config set channels.wecom.groupPolicy open
+```
+
+### 方式二：主动拉取历史消息
+
+通过 `wecom-msg` Skill 的 `get_message`（chat_type=2）拉取 7 天内的群消息：
+
+```bash
+# 先获取会话列表找到群 chatid
+wecom_mcp call msg get_msg_chat_list '{"begin_time":"2026-07-01 00:00:00","end_time":"2026-07-04 23:59:59"}'
+
+# 拉取该群消息
+wecom_mcp call msg get_message '{"chat_type":2,"chatid":"群的chatid","begin_time":"2026-07-01 00:00:00","end_time":"2026-07-04 23:59:59"}'
+```
+
+### 群消息处理流程
+
+1. `get_msg_chat_list` → 查找目标群的 chatid
+2. `get_message(chat_type=2)` → 拉取消息
+3. `wecom-contact get_userlist` → userid 转姓名
+4. 展示消息（文本 / 图片 / 文件 / 语音 / 视频）
+5. 非文本消息需调用 `get_msg_media` 下载
+
+---
+
+## 八、调试与维护
+
+### 查看状态
+
+```bash
+openclaw status                    # 快速状态
+openclaw plugins list              # 插件列表
+openclaw config get channels       # 通道配置
+openclaw doctor                    # 诊断修复
+```
+
+### 查看日志
+
+```bash
+openclaw logs --follow             # 实时日志
+openclaw logs --follow | grep wecom  # 只看 WeCom 相关
+```
+
+### 更新插件
+
+```bash
+openclaw plugins update wecom-openclaw-plugin
+```
+
+### 更新安装工具
+
+```bash
+npx -y @wecom/wecom-openclaw-cli install --force
+```
+
+### 重启 Gateway
+
+```bash
+openclaw daemon restart
+```
+
+---
+
+## 九、常见问题
+
+### Q1: 安装后机器人没反应？
+
+按以下顺序排查：
+
+1. `openclaw plugins list` — 确认 wecom-openclaw-plugin 状态为 `enabled`
+2. `openclaw config get channels.wecom` — 确认 botId/secret/enabled 已配置
+3. `openclaw status` — 确认 WeCom 通道 State=OK
+4. `openclaw logs --follow` — 查看实时日志
+
+> 常见根因：插件 installed 但 disabled，需要两步：加入 `plugins.allow` + 重启 gateway。
+
+### Q2: 插件 enabled 但仍无法使用 Skills？
+
+检查 `tools.alsoAllow` 是否包含 `wecom_mcp`：
+
+```bash
+openclaw config get tools.alsoAllow
+# 应包含 "wecom_mcp"
+```
+
+### Q3: 消息拉取不到？
+
+- 仅支持最近 **7 天** 内的消息
+- 时间格式必须为 `YYYY-MM-DD HH:mm:ss`
+- chat_type: 1=单聊, 2=群聊
+
+### Q4: Skills 调用报错？
+
+所有 Skill 需先通过 `wecom-preflight` 检查。确保 `tools.allow` 或 `tools.alsoAllow` 中包含 `wecom_mcp`。
+
+### Q5: 群消息不想所有人都能用？
+
+```bash
+# 白名单模式（仅指定群可用）
+openclaw config set channels.wecom.groupPolicy allowlist
+openclaw config set channels.wecom.groupAllowFrom '["群chatid1","群chatid2"]'
+```
+
+---
+
+## 十、参考链接
+
+- [企业微信 AI Bot 官方文档](https://open.work.weixin.qq.com/help?doc_id=21657)
+- [企业微信 CLI 开源项目](https://open.work.weixin.qq.com/help2/pc/21676)
+- [OpenClaw 文档](https://docs.openclaw.ai/)
+- [插件完整 README](https://github.com/WeCom/wecom-openclaw-plugin)
+- [WeCom 插件配置指引（腾讯文档）](https://doc.weixin.qq.com/doc/w3_AFYA1wY6ACoCNRxfnyGRJQaSa6jjJ?scode=AJEAIQdfAAo0RJmzxLAFYA1wY6ACo)
+
+## 相关笔记
+
+- [[Openclaw 手册]] — OpenClaw 基础操作
+- [[Openclaw Skill]] — 插件与技能生态
+- [[Openclaw 技巧]] — 使用技巧与提示词