---
name: qiwei-webhook-relay
description: 企微消息运行时：个人版在客户主机主动轮询，企业版接入中央 Relay 统一回调。
---

# Webhook 与 Relay

## 使用边界

先调用 `qiwei_product_mode_status` 判断产品模式。个人版由技能包内置 ESM Runtime 在客户主机主动轮询；企业版由同一 Runtime 进入中央 Relay 注册和服务端回调流程。

本 skill 负责：

- 查询 Relay 回调配置状态；
- 在中央 Relay 服务端注册租户、保存凭证；
- 通过 Fmode 服务端专用接口配置企微全局回调；
- 管理 Relay 配置。

标准产品流程只有 `local_polling` 和 `server_relay` 两种传输方式。旧的显式直连工具仅保留兼容，不作为个人版交付步骤。

## 模式说明

### 个人版本地轮询

运行 `npm run runtime` 后，ESM Runtime 复用现有 Agent Poller，通过 Fmode/Future Server 网关主动同步新消息，并将画像、待办、预警、草稿和会话数据保存在客户项目中。用户不需要配置公网地址。

### 企业版中央 Relay

企微平台把事件推送到 Fmode 中央 Relay 服务器（默认 `http://8.138.37.248:4000`），本地 Skill 通过长轮询主动取回属于自己的事件。适合 Skill 运行在本地电脑、内网或无固定公网 IP 的场景。

## 数据存储

- Relay 配置：`outputs/webhook/relay-config.json`
- 回调事件：`outputs/webhook/<date>/<time>-<source>/event-...json`

## 标准流程

### 首次使用自动配置

1. 确保 `.env.local` 已配置 `QIWEI_AUTH_TOKEN`。
2. 调用 `qiwei_login_start` → 用户扫码登录。
3. 登录成功后，调用 `qiwei_webhook_auto_setup` 或 `qiwei_relay_connect`：
   - 提取并保存设备 `guid`；
   - 在中央 Relay 注册租户（如未注册）；
   - 保存租户凭证到 `.env.local`；
   - 将当前设备注册到 Relay，用真实 `guid` 建立租户路由；
   - 调用 Fmode 专用接口 `POST /relay/connect`；
   - 由 Fmode 服务端使用服务端密钥，把 Token 级全局回调设为 `{RELAY_BASE_URL}/api/webhook/ingest`；
   - 客户端不会接触或提交全局回调签名密钥；
   - 返回配置结果，并由 MCP/Skill 自动确保 Relay 消费守护进程常驻。
4. 企业版无需启动 Dashboard 或手工执行 `npm run relay`；守护进程使用 ESM Runtime，事件在服务端持久排队，本地处理成功后才 ACK。

### 手动注册 Relay 租户

```json
{
  "name": "qiwei_relay_register",
  "arguments": {
    "description": "本地 Skill",
    "force": false
  }
}
```

返回 `tenantId`、`apiKey`、`apiSecret`、`privateKey`，并自动保存到 `.env.local`。

### 手动配置 Relay 回调

```json
{
  "name": "qiwei_relay_connect",
  "arguments": {
    "guid": "已登录设备 guid"
  }
}
```

## Relay 客户端持久化运行

### systemd

```ini
[Unit]
Description=Qiwei Relay Client
After=network.target

[Service]
Type=simple
User=ubuntu
WorkingDirectory=/opt/qiwei-assistant
EnvironmentFile=/opt/qiwei-assistant/.env.local
ExecStart=/usr/bin/node /opt/qiwei-assistant/scripts/start-relay-client.js
Restart=always
RestartSec=5

[Install]
WantedBy=multi-user.target
```

启动：

```bash
sudo systemctl daemon-reload
sudo systemctl enable qiwei-relay
sudo systemctl start qiwei-relay
```

### pm2

```bash
pm2 start scripts/start-relay-client.js --name qiwei-relay
pm2 save
```

## MCP 工具

- `qiwei_webhook_status` — 查询 Relay 回调配置状态
- `qiwei_webhook_auto_setup` — 注册设备并通过 Fmode 专用接口接入中央 Relay
- `qiwei_relay_config` — 读取 Relay 配置
- `qiwei_relay_save_config` — 保存 Relay 公钥/租户配置
- `qiwei_relay_register` — 注册 Relay 租户并保存凭证
- `qiwei_relay_connect` — 配置 Relay 回调地址

> 本地模式工具仅供隔离部署使用；默认调用会被拒绝，防止共享 Token 的全局回调被个人电脑覆盖。