---
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 技巧]] — 使用技巧与提示词