openclaw-wx-skills

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/ | 微信用户发消息进来 → agent 自动回 | 常驻 OpenClaw gateway | | CLI @fmode/wechat-cli (wecli, 本地) | cli/ | 用户让 agent 主动操作微信（搜联系人、查历史、发给第三方…） | 被 skill 按需 spawn | | Skill 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。 老 v1.2.x daemon 方案仍可跑（见 daemon/ 和本 README 主体）， 但新用户应直接走 channel plugin + CLI + skill。

目录结构

openclaw-wechat-skill/
├── channel-plugin/                  # v2.0 ChannelPlugin（MVP，已交付 0.1.1 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

消息存储

后端自动按来源持久化消息到文件：

• 个人消息: data/messages/personal/{wxid}.jsonl
• 群聊消息: data/messages/group/{chatroom_id}.jsonl

客户部署（一步到位）

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

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

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

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

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

方式 2：Windows PowerShell

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

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

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

方式 3：Linux / macOS Bash

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

部署产物

运行后自动完成：

• 6个技能 → ~/.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 当二进制文件。

诊断脚本

node check-deployment.js

脚本会逐项输出：

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

最终兜底

如果 skill 已正确部署、OpenClaw 已重启、但主 agent 仍不识别，按 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 启动即可。

新增文件

路径	作用
~/.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 行日志

回复规则

默认配置（~/.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 数组即可）：

{
  "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 服务器上跑：

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 地址：

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 个核心技能 + 自动应答编排