---
name: wecom-agent-setup
description: 一键创建 OpenClaw Agent 并对接企业微信（WeCom），支持 VIP 一对一服务场景
enabled: true
version: 1.0.0
allowed-tools: Bash(openclaw:*) Read Write Edit
---

# 企业微信 Agent 对接 Skill

快速创建一个 OpenClaw Agent 并通过企业微信（WeCom）提供服务。基于 `@sunnoy/wecom` 插件的 WebSocket 长连接模式，无需公网服务器。

## 适用场景

- VIP 用户一对一专属服务（如直播打赏大哥管家）
- 企业内部 AI 助手
- 客服 / 运营 Agent
- 每个企业微信机器人绑定一个 Agent，服务一个或一组用户

## 前置条件

- OpenClaw `2026.3.2+` 已安装运行
- `@sunnoy/wecom` 插件已安装（若未安装，执行 `openclaw plugins install @sunnoy/wecom`）
- 企业微信管理后台权限
- 机器可出站访问 `wss://openws.work.weixin.qq.com`

## 完整流程

### 第 1 步：企业微信后台 — 创建 AI 机器人

1. 登录 [企业微信管理后台](https://work.weixin.qq.com/wework_admin/frame)
2. 左侧菜单 → **「应用管理」** → **「智能机器人」**
3. 点击 **「创建机器人」**
4. 填写机器人名称（与 Agent 名称一致便于识别）
5. **连接方式必须选「长连接」**（不是 HTTP 回调）
6. 创建完成后记录：
   - **BotId**（形如 `aib_xxxxxxxxxx`）
   - **Secret**

> 参考：[企业微信 AI 机器人长连接模式](https://open.work.weixin.qq.com/help2/pc/cat?doc_id=21657)

### 第 2 步：创建 Agent workspace

用实际值替换下方所有 `<placeholder>`。

**需要的参数：**

| 参数 | 说明 | 示例 |
|------|------|------|
| `AGENT_ID` | Agent 唯一标识（小写+连字符） | `hellodage` |
| `AGENT_NAME` | 显示名称 | `HelloDage` |
| `AGENT_EMOJI` | 标识 emoji | `🎯` |
| `AGENT_THEME` | 一句话人设描述 | `热情贴心、VIP专属服务` |
| `AGENT_ROLE` | 角色定位 | `VIP 大哥专属管家` |
| `WECOM_BOT_ID` | 企业微信 BotId | `aib_xxxxxxxxxx` |
| `WECOM_SECRET` | 企业微信 Secret | `xxxxxxxxxxxxxxxx` |
| `WECOM_ACCOUNT_ID` | 配置中的账号标识（小写） | `hellodage` |

**2.1 创建目录结构：**

```bash
mkdir -p ~/.openclaw/workspace-<AGENT_ID>/memory
mkdir -p ~/.openclaw/agents/<AGENT_ID>/agent/sessions
```

**2.2 创建 IDENTITY.md：**

写入 `~/.openclaw/workspace-<AGENT_ID>/IDENTITY.md`：

```markdown
# IDENTITY.md - <AGENT_NAME>

- **Name:** <AGENT_NAME>
- **Role:** <AGENT_ROLE>
- **Emoji:** <AGENT_EMOJI>
- **Channel:** 企业微信

## Core Responsibilities

（根据业务场景填写）
```

**2.3 创建 SOUL.md：**

写入 `~/.openclaw/workspace-<AGENT_ID>/SOUL.md`，定义 Agent 的性格、沟通方式、行为边界等。这是 Agent 的灵魂文件，需要根据具体业务场景精心设计。

**2.4 创建其他 workspace 文件：**

从已有 Agent 复制模板（推荐从 `~/.openclaw/workspace-emily-pm/` 复制以下文件并修改）：

- `AGENTS.md` — workspace 使用说明
- `TOOLS.md` — 工具和资源索引
- `MEMORY.md` — 长期记忆初始化
- `USER.md` — 用户画像模板
- `HEARTBEAT.md` — 心跳任务（初始留空）

**2.5 创建 models.json：**

写入 `~/.openclaw/agents/<AGENT_ID>/agent/models.json`：

```json
{
  "providers": {
    "openrouter": {
      "baseUrl": "https://openrouter.ai/api/v1",
      "api": "openai-completions",
      "models": [
        {
          "id": "auto",
          "name": "OpenRouter Auto",
          "reasoning": false,
          "input": ["text", "image"],
          "cost": { "input": 0, "output": 0, "cacheRead": 0, "cacheWrite": 0 },
          "contextWindow": 200000,
          "maxTokens": 8192
        }
      ],
      "apiKey": "<OPENROUTER_API_KEY>"
    }
  }
}
```

> API Key 可从已有 Agent 的 models.json 复制：`~/.openclaw/agents/emily-pm/agent/models.json`

### 第 3 步：更新 openclaw.json

编辑 `~/.openclaw/openclaw.json`，添加三处配置：

**3.1 agents.list — 注册 Agent：**

```json
{
  "id": "<AGENT_ID>",
  "name": "<AGENT_ID>",
  "workspace": "/Users/gloom/.openclaw/workspace-<AGENT_ID>",
  "agentDir": "/Users/gloom/.openclaw/agents/<AGENT_ID>/agent",
  "identity": {
    "name": "<AGENT_NAME>",
    "theme": "<AGENT_THEME>",
    "emoji": "<AGENT_EMOJI>"
  }
}
```

**3.2 channels.wecom — 添加企业微信账号：**

如果是第一个企业微信 Agent（`channels.wecom` 还不存在），添加完整 channel 配置：

```json
"channels": {
  "wecom": {
    "enabled": true,
    "dmPolicy": "pairing",
    "groupPolicy": "open",
    "accounts": {
      "<WECOM_ACCOUNT_ID>": {
        "enabled": true,
        "botId": "<WECOM_BOT_ID>",
        "secret": "<WECOM_SECRET>",
        "dmPolicy": "pairing",
        "welcomeMessage": "你好，我是你的专属管家 <AGENT_NAME>！有什么需要随时找我 <AGENT_EMOJI>",
        "commands": {
          "enabled": true,
          "allowlist": ["/new", "/compact", "/help", "/status"]
        }
      }
    }
  }
}
```

如果 `channels.wecom` 已存在（已有其他企业微信 Agent），只需在 `accounts` 下添加新账号即可。

**3.3 bindings — 绑定 Agent 到企业微信账号：**

```json
{
  "type": "route",
  "agentId": "<AGENT_ID>",
  "match": {
    "channel": "wecom",
    "accountId": "<WECOM_ACCOUNT_ID>"
  }
}
```

**3.4 plugins — 确保 wecom 插件启用（首次添加时需要）：**

```json
"plugins": {
  "entries": {
    "wecom": {
      "enabled": true
    }
  }
}
```

### 第 4 步：重启 Gateway

```bash
openclaw gateway restart
```

### 第 5 步：验证

```bash
# 检查 gateway 状态
openclaw gateway status

# 检查 channel 状态
openclaw channels status

# 查看日志确认 WeCom WebSocket 连接成功
tail -20 ~/.openclaw/logs/gateway.log | grep -i wecom

# 检查错误日志
tail -10 ~/.openclaw/logs/gateway.err.log
```

成功标志：日志中出现 `[wecom] WebSocket connected` 或类似连接成功消息。

### 第 6 步：配对用户

在企业微信中找到机器人，发送第一条消息。如果 `dmPolicy` 是 `pairing`：

1. 机器人会回复一个配对码
2. 在终端执行：`openclaw pairing approve wecom <CODE>`
3. 配对完成，用户即可正常对话

如果 `dmPolicy` 设为 `open`，则跳过配对，任何可见成员可直接使用。

## 批量创建（VIP 场景）

当需要为多个 VIP 用户各创建一个专属 Agent 时：

1. 在企业微信后台为每个 VIP 创建一个独立机器人（每个有独立 BotId + Secret）
2. 对每个 VIP 重复上述第 2-3 步（不同 AGENT_ID 和 WECOM_ACCOUNT_ID）
3. 所有 Agent 共享同一个 `channels.wecom` 配置块，各自是 `accounts` 下的不同条目
4. 统一重启一次 gateway 即可

## 常见问题

### Q: 插件未安装怎么办？
```bash
openclaw plugins install @sunnoy/wecom
```

### Q: WebSocket 连接失败？
- 确认机器人是「长连接」模式（不是 HTTP 回调）
- 确认 BotId 和 Secret 正确
- 确认网络可出站访问 `wss://openws.work.weixin.qq.com`

### Q: 企业微信发消息没回复？
1. 检查 `openclaw channels status` 看 WeCom 是否 OK
2. 检查 `~/.openclaw/logs/gateway.err.log` 有无错误
3. 确认 binding 的 `accountId` 与 `channels.wecom.accounts` 中的 key 完全一致
4. 确认 `dmPolicy` 配置正确且已完成配对

### Q: 如何切换到 open 模式（跳过配对）？
将对应账号的 `dmPolicy` 改为 `"open"`，然后 `openclaw gateway restart`。

## 配置模板速查

**最小可用配置（单账号）：**

```json
{
  "agents": { "list": [{ "id": "my-agent", "name": "my-agent", "workspace": "...", "agentDir": "...", "identity": { "name": "MyAgent", "theme": "...", "emoji": "🤖" } }] },
  "bindings": [{ "type": "route", "agentId": "my-agent", "match": { "channel": "wecom", "accountId": "my-agent" } }],
  "channels": { "wecom": { "enabled": true, "accounts": { "my-agent": { "enabled": true, "botId": "aib_xxx", "secret": "xxx", "dmPolicy": "pairing" } } } },
  "plugins": { "entries": { "wecom": { "enabled": true } } }
}
```