openclaw-voc-skill/claude-code/claude-code-qiwe-assistant/docs/specs/qiwei-relay-local-integration-guide.md

---

title: 企微 Webhook Relay 本地 Skill 接入指南 updated: 2026-07-27 project: claude-code-qiwe-assistant

scope: local-skill-integration

企微 Webhook Relay 本地 Skill 接入指南

本地 Skill 不暴露 Webhook 端口。企微事件先进入中央 Relay，本地通过长轮询领取属于当前租户和设备的事件。

一、正式链路

企微消息
  -> Token 级全局回调 /api/webhook/ingest
  -> Relay 按消息体真实 guid 找到租户
  -> 加密、去重并进入租户队列
  -> 本地 Relay Client 长轮询
  -> 解密、落盘、业务处理并 ACK

企微上游的回调配置对服务 Token 全局生效，不是每个客户或设备一条。因此回调地址固定为：

{RELAY_BASE_URL}/api/webhook/ingest

不要把回调设置成 /api/webhook/ingest/{tenantId}/{guid}。最后一次设置会覆盖此前客户，造成消息错投或中断。

二、首次接入

1. 配置 Fmode 鉴权 Token。
2. 启动登录页并完成企业微信扫码登录。
3. Skill 自动注册 Relay 租户，并把真实设备 guid 注册到该租户。

4. Skill 调用 Fmode 专用接口：

   POST {QIWEI_API_BASE}/relay/connect
   Authorization: Bearer <Fmode Token>
   Content-Type: application/json
   
   {"uid":"本地设备 uid"}
   

5. Fmode 服务端校验订阅和设备后，使用服务端保存的回调地址与签名密钥调用企微 /client/setCallback。

6. MCP/Skill 自动确保本地 Relay 消费守护进程运行；无需启动 Dashboard。手工诊断时仍可执行：

   npm run relay
   

客户端请求中只能出现 uid，不能提交任意回调 URL、签名密钥、上游 Token 或设备 guid。

三、Fmode 服务端配置

Future Server 需要由运维设置以下环境变量：

QIWEI_RELAY_CALLBACK_URL=http://8.138.37.248:4000/api/webhook/ingest
QIWEI_RELAY_CALLBACK_SECRET=<服务端全局回调签名密钥>

签名密钥只保存在 Future Server 和 Relay 服务端，不能进入 Skill、浏览器、npm 包、日志或客户配置文件。

四、本地凭据

本地 Relay Client 只保存本租户的领取和解密凭据：

RELAY_BASE_URL
TENANT_ID
TENANT_API_KEY
TENANT_API_SECRET
RELAY_PRIVATE_KEY
RELAY_DEVICE_GUID

这些内容写入 .env.local，不得提交 Git 或打进 npm 包。RELAY_PRIVATE_KEY 使用 \n 表示 PEM 换行。

五、验证

1. qiwei_webhook_status 显示 relayRunning=true；默认服务端队列保留 7 天，处理成功后才 ACK。
2. 让另一个企微账号给当前登录账号发送一条新的真实消息。
3. Relay 服务日志应出现全局入口的接收记录和对应 guid 路由。
4. 本地客户端应完成 poll、解密、业务处理和 ACK。
5. 4320 工作台应只在正确客户或群聊会话中出现该消息。

历史消息不通过回调补采，产品口径为“从接入完成后开始接收”。

六、故障排查

现象	检查项
/relay/connect 返回未配置	Future Server 是否设置两项 Relay 环境变量并重启
Relay 收到消息但本地没有	设备 guid 是否属于当前租户，Relay Client 是否在线
本地能 poll 但不能解密	本地私钥是否属于当前租户，PEM 换行是否正确
消息进入错误客户会话	检查事件真实 guid、会话 ID 和群/私聊类型，禁止按当前页面会话兜底
回调突然中断	排查是否有个人进程再次调用 /client/setCallback 覆盖全局地址

七、隔离部署

客户自有服务器的独立服务 Token 可以使用自定义回调，但必须显式开启：

QIWEI_ALLOW_DIRECT_CALLBACK=true

共享 Token 环境禁止开启。默认关闭是为了避免个人版或本地测试覆盖企业版全局回调。