# OpenClaw WeChat Skill

微信智能体的 OpenClaw 技能集合。通过第三方 wechat-agent HTTP 后端实现微信消息收发、联系人管理、按来源（个人/群聊）分目录存储消息和自动应答。

> **v2.0 三件套已齐**：微信能力被拆成 **一个 channel plugin + 一个 CLI + 一个
> skill** 三部分，对标 OpenClaw 官方 `imsg` / `wacli` 的设计（见
> `node_modules/openclaw/skills/`）。
>
> | 组件 | 目录 | 职责 | 何时被调 |
> |-|-|-|-|
> | **Channel plugin** `@fmode/openclaw-wechat-agent@0.1.1` | [`channel-plugin/`](./channel-plugin) | 微信用户发消息进来 → agent 自动回 | 常驻 OpenClaw gateway |
> | **CLI** `@fmode/wechat-cli` (`wecli`, 本地) | [`cli/`](./cli) | 用户让 agent 主动操作微信（搜联系人、查历史、发给第三方…） | 被 skill 按需 spawn |
> | **Skill** `wechat` | [`skills/wechat/`](./skills/wechat) | 教 LLM "何时用 wecli、用哪个子命令、安全门禁" | 按 description 触发 |
>
> 三件共用同一个 `apiBase`（`http://8.138.37.248/api/wechat-agent`）和同一个 bot 账号，
> **互不冲突**：channel 负责 inbound-auto-reply 路径，CLI+skill 负责 out-of-band 路径。
>
> 历史设计文档：[`docs/channel-plugin-design.md`](./docs/channel-plugin-design.md)。
> 老 v1.2.x daemon 方案仍可跑（见 [`daemon/`](./daemon) 和本 README 主体），
> 但新用户应直接走 channel plugin + CLI + skill。

## 目录结构

```
openclaw-wechat-skill/
├── channel-plugin/                  # v2.0 ChannelPlugin（私聊+群聊触发，已交付 tgz）
│   ├── index.ts · openclaw.plugin.json
│   ├── src/channel.ts · monitor.ts · outbound.ts · client.ts · faq.ts · cooldown.ts ...
│   ├── scripts/build.mjs            # esbuild 单文件 bundle（消除 Cannot find package 'openclaw'）
│   ├── dist/index.js                # 装机产物
│   └── README.md                    # 插件安装 / 升级 / 配置 / 故障排查
├── cli/                             # v2.0 wecli CLI（本地，不发 npm）
│   ├── src/index.ts · client.ts · config.ts · output.ts
│   ├── src/commands/{check-online,contacts,messages,conversations}.ts
│   ├── scripts/build.mjs            # 同款 esbuild 单文件 bundle
│   ├── dist/wecli.js                # ~80 KiB，node 20+ 即可跑
│   └── README.md                    # CLI 子命令参考 + 开发指南
├── skills/
│   └── wechat/SKILL.md              # v2.0 Skill（Claude/Codex 风格，引用 wecli）
├── wechat/                          # v1.x 老 Skill 包（保留兼容，可被 skills/wechat/ 取代）
│   ├── wechat-check-online/ · wechat-send-text/ · wechat-get-messages/
│   └── wechat-get-conversations/ · wechat-get-contact-*/ · wechat-auto-reply-{start,stop,status}/
├── daemon/                          # v1.2.x 独立守护进程（老客户仍在用）
│   ├── auto-reply-daemon.js
│   └── wechat-auto-reply-config.template.json
├── __config/
│   └── wechat-credentials.template.json
├── docs/
│   └── channel-plugin-design.md     # 插件技术设计文档
├── deploy-to-openclaw.{js,ps1,sh}   # v1.x 老 skill 部署脚本
├── quick-start.sh                   # v1.x daemon 一键上线
├── check-deployment.js              # v1.x 部署诊断
└── README.md
```

## 自动应答编排 (Workflow)

```
workflows/
├── wechat-auto-reply.workflow.json   # 核心编排定义
└── pipeline.md                       # 流程图 + 回复策略文档
```

龙虾通过 workflow 知道自己要做什么：

```
每10秒轮询:
1. wechat-check-online           → 确认微信在线
2. wechat-get-messages(since)    → 增量拉取新消息
3. 分类消息来源:
   ├── 个人私聊 (wxid_xxx)       → AI生成个性化回复 → wechat-send-text
   └── 群聊 (xxx@chatroom)      → 仅被@或关键词触发时回复
4. 忽略: 系统消息/公众号/表情/语音等
```

### 回复策略
- **个人私聊**: 每条文字消息都AI回复，图片/语音回复确认
- **群聊**: 仅被@或包含关键词("帮我"/"请问")时回复，避免刷屏
- **忽略列表**: system/emoji/voice + weixin/fmessage/gh_*

详见 [`workflows/pipeline.md`](workflows/pipeline.md)

## 消息存储

后端自动按来源持久化消息到文件：
- 个人消息: `data/messages/personal/{wxid}.jsonl`
- 群聊消息: `data/messages/group/{chatroom_id}.jsonl`

## 客户部署（一步到位）

提供三种部署方式，**按你的系统任选其一**：

### 方式 1：Node.js（推荐，跨平台）

任何装了 Node.js 的系统（Windows / Linux / macOS）都能直接运行：

```bash
# 预览（不实际部署）
node deploy-to-openclaw.js --dry-run

# 正式部署
node deploy-to-openclaw.js
```

### 方式 2：Windows PowerShell

```powershell
# 预览
.\deploy-to-openclaw.ps1 -DryRun

# 正式部署
.\deploy-to-openclaw.ps1
```

> 注意：不要用 `node deploy-to-openclaw.ps1`，`.ps1` 是 PowerShell 脚本不是 JS。

### 方式 3：Linux / macOS Bash

```bash
chmod +x deploy-to-openclaw.sh
./deploy-to-openclaw.sh --dry-run   # 预览
./deploy-to-openclaw.sh              # 正式部署
```

### 部署产物

运行后自动完成：
- 多个技能（含自动回复管理与群聊规则配置）→ `~/.openclaw/skills/`
- 自动应答编排 → `~/.openclaw/workflows/`
- 凭证配置 → `~/.openclaw/wechat-credentials.json`（已预设后端地址）

**客户无需额外配置**，后端统一托管在 `http://8.138.37.248/api/wechat-agent`。

部署完成后龙虾即可开始工作：轮询消息 → 分类来源 → AI生成回复 → 自动发送。

## Skill 格式说明（重要）

OpenClaw 官方 skill 规范：
- 每个技能一个目录，必须包含 `SKILL.md`
- `SKILL.md` 用 YAML frontmatter 声明 `name` 和 `description`
- **正文是"LLM 运行手册"**——告诉 LLM 要用 `exec`/bash 工具跑什么命令，而不是 HTTP 接口文档
- 目录里的其他文件（例如我们保留的 `api-config.json`）OpenClaw **不读取**，仅作开发者参考

我们的 SKILL.md 已按此规范写成**可执行指令**：每个技能的正文都有 `curl` 示例，LLM 读到后直接通过 `exec` 工具调用微信后端 API，无需"渠道/插件"之类中间概念。

## 故障排查

### 症状 A：agent 说"没找到微信渠道配置" / "请提供插件 ID"

这是 **v1.0.0 的 SKILL.md 只写了接口规范、没写执行步骤**，LLM 读不到 bash 命令，只好凭空猜一个"channels"或"插件"概念。

**v1.1.0 已修复**——SKILL.md 改成运行手册，包含明确的 curl 示例。客户需要：

1. 解压最新 zip 覆盖旧文件
2. 重新运行 `node deploy-to-openclaw.js`
3. **重启 OpenClaw 服务**（skill 只在启动/watch 时加载）
4. 重新打开对话（旧会话的工具列表已缓存）

### 症状 B：agent 把 `wechat-check-online` 当 shell 命令跑

同症状 A，同修复。旧 SKILL.md 没有明示执行方式，LLM 看到技能名后尝试 `exec wechat-check-online` 当二进制文件。

### 诊断脚本

```bash
node check-deployment.js
```

脚本会逐项输出：
- `~/.openclaw/skills/` 下 6 个 skill 目录是否齐全
- 每个 `SKILL.md` 是否包含可执行的 curl 指令
- `wechat-credentials.json` 的 `wechatApiBase` 是否正确
- 微信后端 API 是否可达
- OpenClaw 服务是否在线

### 最终兜底

如果 skill 已正确部署、OpenClaw 已重启、但主 agent 仍不识别，按 [`AGENT-PROMPT.md`](AGENT-PROMPT.md) 给 `agents.list[].skills` 显式加入这 6 个 skill，或在 agent system prompt 里列出它们。

## 自动回复 daemon

v1.2.0 新增**独立后台 daemon** 和 3 个管理技能。旧版只给 agent 一份 workflow 描述文件让它自己写 daemon 代码——LLM 写出来的 daemon 有 bug，能启动但不回复。现在 daemon 预先写好、随 zip 交付，agent 只需调 `wechat-auto-reply-start` 启动即可。  
当前在此基础上补充了群聊规则配置技能 `wechat-auto-reply-group-config`，用于设置群聊触发关键词与默认回复。

### 新增文件

| 路径 | 作用 |
|------|------|
| `~/.openclaw/auto-reply-daemon.js` | 实际运行的 daemon（Node 原生，无 npm 依赖） |
| `~/.openclaw/wechat-auto-reply-config.json` | 可编辑的回复规则（热生效，无需重启） |
| `~/.openclaw/wechat-auto-reply-config.template.json` | 规则模板参考 |
| `~/.openclaw/wechat-auto-reply.pid` | 运行中 daemon 的 PID（由 daemon 自己写） |
| `~/.openclaw/wechat-auto-reply-state.json` | 增量拉取状态（lastCheckTime 等） |
| `~/.openclaw/logs/auto-reply.log` | 结构化日志 |

### 新增技能

| Skill | 作用 |
|-------|------|
| `wechat-auto-reply-start`  | 用 nohup 启动 daemon，写 PID 文件 |
| `wechat-auto-reply-stop`   | SIGTERM 优雅停，5s 没退出强杀 |
| `wechat-auto-reply-status` | 输出 PID 存活状态 + 最近 30 行日志 |
| `wechat-auto-reply-group-config` | 配置群聊回复规则（开关、关键词、默认回复） |

### 回复规则

默认配置（`~/.openclaw/wechat-auto-reply-config.json`，修改后**热加载**无需重启）：

- **FAQ 关键词**（v1.2.2+）：`faq` 数组按顺序匹配，命中就返回对应 `reply`。默认已内置 7 条示例（你好/你是谁/价格/地址/营业时间/人工/再见）
- **个人私聊 fallback**：FAQ 未命中时用 `personal.defaultReply`
- **群聊触发**：消息含 `group.keywords`（`@bot` / `帮我` / `请问` / `客服`）才回复；命中后同样先走 FAQ，未命中用 `group.defaultReply`
- **忽略**：`system` / `emoji` / 图片/语音/视频、`weixin` / `fmessage` / `gh_*` 公众号
- **冷却**：同一联系人 `replyCooldownSecPerWxid` 秒内不重复回复（默认 5s）

FAQ 规则示例（直接编辑 `faq` 数组即可）：

```json
{
  "faq": [
    {"keywords": ["你好", "hi"], "reply": "您好！很高兴为您服务~"},
    {"keywords": ["价格", "多少钱"], "reply": "稍后顾问联系您"},
    {"keywords": ["人工"], "reply": "正在转接人工客服..."}
  ]
}
```

日志里 `replied` 条目会标 `source`：`faq:关键词` 表示命中了 FAQ，`personal-default` / `group-default` 表示走了兜底。

### 典型故障

- **启动成功但不回复** → 看 `tail -f ~/.openclaw/logs/auto-reply.log`。常见原因：微信离线、没有新消息、规则过滤掉了、`replyCooldownSecPerWxid` 冷却中
- **PID 文件留下但进程死了** → 删 `~/.openclaw/wechat-auto-reply.pid` 重启
- **群里一直不回** → 加入关键词或把 `group.enabled: false` 关掉、或改 `keywords` 列表

## 一键上线（推荐，绕开 agent）

如果 agent 自己写 daemon 反复失败，**不要让 agent 启动自动回复**，客户直接在 Linux 服务器上跑：

```bash
unzip -o openclaw-wechat-skill-v1.2.2.zip -d openclaw-wechat-skill
cd openclaw-wechat-skill
bash quick-start.sh
```

脚本会自动：
1. 杀掉所有正在跑的 auto-reply daemon（我们的 + agent 自写的）
2. 部署最新 skills + daemon
3. **探测正确的 `wechatApiBase`**（尝试 `http://127.0.0.1:8138` / `http://8.138.37.248` / 带或不带 `/api/wechat-agent` 前缀 等变体），把成功的那个写入 `~/.openclaw/wechat-credentials.json`
4. 启动 v1.2.0 daemon
5. 等 15 秒并打印日志尾部，确认正在轮询

跑完后用户端让测试号发条消息，应该几秒内收到自动回复。如果日志里只有 `WARN wechat offline` → 后端本身没上线；如果有 `received` 但没有 `replied` → 看 `skip`/`cooldown`/`no-reply-rule` 的日志行。

强制指定 API 地址：

```bash
WECHAT_API_BASE=http://your-host:port bash quick-start.sh
```

## 版本

- **v1.2.2** (2026-04-18) - daemon 加 FAQ 关键词规则（不同问题返不同回答）；默认 cooldown 从 30s 降到 5s 更适合测试；`replied` 日志新增 `source` 字段标注命中来源；配置模板内置 7 条示例 FAQ
- **v1.2.1** (2026-04-18) - 新增 `quick-start.sh` 一键脚本：自动探测正确的 `wechatApiBase`、杀旧 daemon、部署、启动、看日志
- **v1.2.0** (2026-04-17) - 新增独立 `auto-reply-daemon.js` + 3 个管理技能（start/stop/status）；`api-config.json` 改为可选
- **v1.1.0** (2026-04-17) - 按 OpenClaw 官方 skill 规范重写 SKILL.md：正文改为 LLM 可直接执行的 bash+curl 运行手册
- **v1.0.0** (2026-04-12) - 初始版本，6 个核心技能 + 自动应答编排