OpenClaw 接入微信实现 AI 自动回复实战指南

SyNodeAi OpenClaw Plugin

SyNodeAi OpenClaw Plugin 用于将微信私聊和群聊接入 OpenClaw，使每一条消息都能进入 Agent Runtime，触发 Tool、Skill 或 Workflow 调度。

为什么做这个插件

在 OpenClaw 体系里，微信不仅是聊天工具，更是：

• 高活跃入口：天然承载真实用户会话
• 事件源：每条消息都可以转换为 Agent Event
• 执行环境：每个会话都可以成为独立上下文 Runtime
• 能力承载层：可以继续挂载 Tool、Skill、Workflow、ACP 持久会话

可以理解为：

WeChat = Event Source OpenClaw = Runtime Agent = Execution Unit Tool / Skill = Capability Layer

架构概览

WeChat ↓ Channel (SyNodeAi) ↓ OpenClaw Runtime ↓ Agent ↓ Tool / Skill / Workflow → Response → WeChat

功能特性

通道能力

• 支持微信私聊/群聊接入
• 支持 SyNodeAi API + Webhook 回调
• 支持消息转 Event
• 支持接入 OpenClaw Channel 体系

Agent 执行能力

• 每个会话独立上下文
• 支持 bindings 路由到指定 Agent
• 支持 ACP 持久会话
• 支持群聊/私聊细粒度触发策略

微信特性支持

• 支持 @ 触发/引用触发
• 支持引用回复/普通回复/@发送者
• 支持撤回消息
• 支持转发已有富消息
• 支持表情/名片/小程序/appmsg/链接等富消息
• 支持群成员目录读取与已知对象缓存

媒体与语音能力

• 支持媒体上传
• 支持 mediaPublicUrl 本地反代
• 支持 S3 兼容上传
• 支持语音自动转 silk
• 支持自动下载 rust-silk
• 支持 ffmpeg/ffprobe 处理媒体

快速开始

只需要几分钟，你就可以让微信跑起一个 AI Agent。

1. 安装插件

推荐使用 npm 安装：

openclaw plugins install synodeai

其他安装方式包括本地目录安装、软链接（开发调试）或归档安装。安装或启用插件后需要重启 Gateway。

2. 登录并获取 Token

打开地址登录微信并完成绑定，获取 token：

http://synodeai.webotchat.com/quickstart

3. 配置 JSON 文件

将配置文件复制到 ~/.openclaw/openclaw.json：

{
  "channels": {
    "synodeai": {
      "enabled": true,
      "token": "<synodeai-token>",
      "webhookHost": "0.0.0.0",
      "webhookPort": 4399,
      "webhookPath": "/webhook",
      "autoQuoteReply": false,
      "allowFrom": [],
      "dmPolicy": "open",
      "groupPolicy": "open",
      "groups": {
        "*": {
          "trigger": { "mode": "at" },
          "reply": { "mode": "quote_source" }
        }
      }
    }
  }
}

4. 配置 Webhook（内网穿透）

Webhook 是 SyNodeAi 将微信消息推送到你本地 OpenClaw 的入口地址，必须公网可访问。如在本地环境使用，推荐用 ngrok 做内网穿透。

4.1 安装 ngrok

brew install ngrok

4.2 配置 token

注册 ngrok 后获取 token，然后执行：

ngrok config add-authtoken YOUR_TOKEN

4.3 启动穿透

ngrok http 4399

你会看到类似输出：

https://xxxx.ngrok-free.app -> http://localhost:4399

这个 https://xxxx.ngrok-free.app 就是你的公网地址。

5. 填写 webhook

把上一步的公网地址按下面格式填写到 SyNodeAi：

https://xxxx.ngrok-free.app/webhook

6. 启动 OpenClaw

openclaw start

7. 验证

向机器人发一条微信消息测试：

• 私聊直接发消息
• 群聊中 @机器人
• 群聊中引用机器人上一条消息继续追问

正确顺序是：登录微信（SyNodeAi）→ 安装 OpenClaw plugin（synodeai）→ 复制 json 配置文件 → 配置 ngrok 拿到公网地址 → 在 SyNodeAi 填写 webhook → 最后启动 openclaw start。

配置项说明

核心配置位于 ~/.openclaw/openclaw.json 的 channels.synodeai 段落中：

• webhookHost/webhookPort/webhookPath：SyNodeAi 回调入口（需公网可达，常配合 FRP）。
• mediaPath：本地媒体服务的路由前缀（默认 /synodeai-media）。
• mediaPublicUrl：本地反代回退时的公网地址前缀（可选）。
• s3Enabled：是否启用 S3 兼容上传。
• voiceAutoConvert：自动将音频转为 silk（默认开启）。
• silkAutoDownload：自动下载 rust-silk（默认开启）。
• autoQuoteReply：是否开启 replyToId + 纯文本 自动引用回复（默认开启）。
• allowFrom：允许私聊触发的微信 ID。

群聊/私聊触发与回复规则

groups 和 dms 都支持 * 默认项 + 精确项覆写。

群聊触发

groups[*].trigger.mode 支持：

• at：只有被 @ 时触发
• quote：只有引用机器人消息时触发
• at_or_quote：@ 或引用机器人消息都触发
• any_message：任何消息都触发

群聊默认值是 at。

群聊回复

groups[*].reply.mode 支持：

• plain：普通回复
• quote_source：首条回复自动引用当前入站消息
• at_sender：首条文本回复自动 @ 发送者
• quote_and_at：首条文本回复同时引用并 @

群聊默认值会跟随 autoQuoteReply：未配置或为 true 时默认 quote_source；显式设为 false 时默认 plain。

私聊触发与回复

• 触发模式：any_message 或 quote
• 回复模式：plain 或 quote_source

私聊默认触发是 any_message。私聊默认回复也会跟随 autoQuoteReply 回退到 quote_source 或 plain。

绑定到 Agent / ACP

除了 channels.synodeai 这一段插件配置，SyNodeAi 还支持配合 OpenClaw 顶层 bindings[] 使用。

绑定到普通 Agent

示例表示：ops-room@chatroom 这个群固定交给 ops agent 处理。

{
  "bindings": [
    {
      "type": "route",
      "agentId": "ops",
      "match": {
        "channel": "synodeai",
        "accountId": "work",
        "peer": { "kind": "group", "id": "ops-room@chatroom" }
      }
    }
  ],
  "channels": {
    "synodeai": {
      "accounts": {
        "work": {
          "groups": {
            "ops-room@chatroom": {
              "trigger": { "mode": "at_or_quote" },
              "reply": { "mode": "quote_and_at" }
            }
          }
        }
      }
    }
  }
}

绑定到 ACP 持久会话

示例表示：这个群固定进入 codex agent 的一个 ACP 持久会话。

{
  "bindings": [
    {
      "type": "acp",
      "agentId": "codex",
      "match": {
        "channel": "synodeai",
        "accountId": "work",
        "peer": { "kind": "group", "id": "repo-room@chatroom" }
      },
      "acp": {
        "label": "repo-room",
        "mode": "persistent",
        "cwd": "/workspace/repo-a",
        "backend": "acpx"
      }
    }
  ]
}

发送媒体与富消息

URL 策略

• 本地文件：优先上传 S3，失败回退 mediaPublicUrl 本地反代
• 公网 URL：先尝试原 URL 发送，失败后再尝试上传 S3，仍失败回退本地反代

富消息与消息复用

可以通过共享 message 工具走标准动作：send、reply、unsend，并在参数里附带一个 synodeai 对象来表达微信专属语义。

示例：在当前群里回复并做部分引用

{
  "action": "reply",
  "message": "收到，我接着处理",
  "synodeai": {
    "quote": { "partialText": "需要继续跟进的那一段" }
  }
}

示例：撤回一条已经发出的消息

{
  "action": "unsend",
  "to": "ops-room@chatroom",
  "messageId": "10001",
  "newMessageId": "10002",
  "createTime": "1710000002"
}

插件支持通过 channelData["synodeai"] 传入 SyNodeAi 专有消息语义，结构如下：

• appMsg：直接发送 <appmsg> XML
• quoteReply：发送引用回复
• emoji：发送表情
• nameCard：发送名片
• miniApp：发送小程序
• revoke：撤回指定消息
• forward：复用已存在消息 XML 进行二次转发

如果希望让模型主动发'部分引用'，SyNodeAi 通道会识别回复末尾的一行隐藏指令：

[[GEWE_QUOTE_PARTIAL:要引用的原文片段]]

插件会在发送前剥离这行指令，并自动转成 quoteReply.partialText。

依赖

npm 依赖

• zod

peer 依赖

• openclaw (>= 2026.1.29)

系统级工具

• ffmpeg / ffprobe（用于视频缩略图与时长）
• rust-silk（出站语音转 silk + 入站语音解码；支持自动下载）

网络 / 服务依赖

• SyNodeAi API 服务
• Webhook 回调需要公网可达（可配合 FRP）
• 媒体对外地址（mediaPublicUrl）

配置变更后需重启 Gateway。