关键词：OpenClaw、WorkTool、企业微信、Agent、插件架构、Webhook、RPA

---

一、背景

在企业内部落地 Agent（智能体）系统时，最后一公里永远是“接入业务沟通渠道”。

相比直接对接企业微信官方 API，很多团队会选择：

• WorkTool（无障碍服务方案）
• 私有化机器人
• 非官方增强能力

本方案就是：
通过 WorkTool → Webhook → OpenClaw → Agent → 再回推 WorkTool，实现闭环对话能力

项目已完整开源：https://github.com/answerlink/openclaw-plugin-worktool

---

二、整体架构（纯文本版）

Wechat / WorkTool 平台
    |
    |  POST https://xxx/wechat/webhook
    |  Headers:
    |    Content-Type: application/json
    |    x-worktool-token: <robotId 或 webhookToken>
    |  Body:
    |    spoken/rawSpoken/receivedName/groupName/groupRemark/roomType/atMe/textType/fileBase64
    v
Nginx
    |
    |  反代到
    v
宿主机 OpenClaw 进程
    |
    +-- openclaw-plugin-worktool
        |
        +-- index.ts/js
        |    - 注册 channel(worktool)
        |    - 注入 runtime(setWorktoolRuntime)
        |
        +-- src/channel.ts/js
        |    - ChannelPlugin 定义（meta/capabilities/configSchema）
        |    - outbound.sendText/sendMedia（调用 WorkTool bridge）
        |    - gateway.startAccount -> 启动 monitor
        |
        +-- src/monitor.ts/js
        |    - 启动 HTTP server (默认 0.0.0.0:18799/wechat/webhook)
        |    - 鉴权：
        |        1) webhookToken（若配置）
        |        2) 否则 robotId（来自 x-worktool-token）
        |    - 校验 Content-Type / body 大小 / 超时
        |    - 交给 inbound.handleInboundWebhook
        |
        +-- src/inbound.ts/js
        |    - 回调标准化 normalizeInboundWebhook：
        |        A) WorkTool 字段（spoken...）
        |        B) feishu-like envelope
        |        C) 兜底 raw/simple
        |    - 生成会话键（无 senderId 时用 receivedName/group 信息）
        |    - 调 OpenClaw runtime:
        |        routing.resolveAgentRoute
        |        reply.dispatchReplyFromConfig
        |    - deliver 回调里再次调用 postBridge 发回微信
        |
        +-- src/runtime.ts/js
             - 保存 runtime 单例，供 inbound/dispatch 使用

OpenClaw Runtime 内部链路（插件调用）
    |
    | inbound ctx (Body/From/To/SessionKey/MessageSid...)
    v
Agent 路由与会话
    |
    v
LLM 生成回复（可分片）
    |
    v
worktool deliver() 回调
    |
    | POST bridgeBaseUrl/api/v1/openclaw/push/{robotId}
    | payload.list[].receiver = 群名/群备注/联系人名
    v
WorkTool 发送到微信

---

三、核心设计思想

1. “渠道插件化”而不是“业务耦合”

整个设计严格分层：

层级	职责
channel / monitor / inbound	只做消息接入
runtime	调 OpenClaw 能力
Agent	做决策
tools / skills	做业务

👉 结论：插件不承载业务，只承载“通信协议”

---

2. 去 senderId 设计（关键亮点）

WorkTool 并没有稳定的 senderId，因此我们做了：

senderId = sender:{receivedName}

并结合：

• 群：groupRemark > groupName
• 单聊：receivedName

构造 sessionKey

👉 这样实现了：

• 无侵入兼容
• 会话稳定
• 不依赖外部唯一 ID

---

3. 会话路由策略

roomType:
  1 / 3 -> 群聊
  2 / 4 -> 单聊

路由规则：

• 群聊：优先 groupRemark
• 单聊：receivedName

👉 本质是：“谁是接收者”决定 Agent 上下文

---

4. 鉴权双模式（兼容不同部署）

优先级：
1. webhookToken（强校验）
2. robotId（弱校验）

Header：

x-worktool-token

👉 适配两种场景：

• SaaS：token 模式
• 私有化：robotId 模式

---

四、数据流详解

入站（Webhook → OpenClaw）

WorkTool
  -> monitor.ts（鉴权 + 限流）
  -> inbound.ts（标准化）
  -> runtime（进入 OpenClaw）

字段映射：

WorkTool字段	内部字段
spoken/rawSpoken	msg.text
receivedName	senderName
groupRemark/name	chatId
roomType	chatType
atMe	mentionedBot
fileBase64	media

---

出站（Agent → WorkTool）

LLM Reply
  -> deliver()
  -> postBridge()
  -> WorkTool API
  -> 微信

核心调用：

POST /api/v1/openclaw/push/{robotId}

---

五、关键模块拆解

1. monitor.ts（网关层）

职责：

• HTTP Server
• 鉴权
• 限流
• 安全校验

本质：👉 轻量 API Gateway

---

2. inbound.ts（协议适配层）

核心能力：

• 多协议兼容（WorkTool / Feishu-like / raw）
• 统一结构
• 构建 sessionKey

👉 是整个系统的“翻译器”

---

3. channel.ts（能力声明层）

定义：

• 能发什么（text / media）
• 怎么发（bridge）

👉 类似“驱动层”

---

4. runtime.ts（桥接层）

作用：

• 存 OpenClaw runtime
• 给 inbound 使用

👉 解决依赖注入问题

---

六、一次完整调用链

用户在微信群 @机器人
    ↓
WorkTool 捕获消息
    ↓
POST /wechat/webhook
    ↓
monitor 校验
    ↓
inbound 标准化
    ↓
构造 sessionKey
    ↓
OpenClaw 路由 Agent
    ↓
LLM 生成回复
    ↓
deliver()
    ↓
调用 WorkTool push API
    ↓
发回微信

👉 完整闭环，延迟主要在 LLM

---

七、工程最佳实践

1. 插件目录分层（强烈建议）

openclaw-plugin-worktool/

  src/
    channel/
    inbound/
    monitor/
    runtime/

  tools/        <-- 业务API封装
  skills/       <-- 提示词 & 能力描述

---

2. 日志建议（下一步优化）

建议增加：

messageId + 脱敏日志

用于：

• 排障
• 回放
• 审计

---

3. 安全建议

• webhookToken 必开（生产环境）
• body size 限制
• timeout 控制
• IP 白名单（可选）

---

八、curl 联调示例

curl -X POST 'https://aistudio.asiainfo.tech/wechat/webhook' \
  -H 'Content-Type: application/json' \
  -H 'x-worktool-token: 893724599f7244febceeb66b03825677' \
  -d '{
    "spoken": "你好啊",
    "rawSpoken": "@me 你好啊",
    "receivedName": "仑哥",
    "groupName": "测试群1",
    "groupRemark": "测试群1备注名",
    "roomType": "1",
    "atMe": true,
    "textType": "1",
    "fileBase64": ""
  }'

---

九、总结

这套方案的本质是：

用插件机制，把“微信能力”抽象成 OpenClaw 的一个 Channel

核心价值：

• 解耦业务与渠道
• 适合企业私有化 Agent 架构