---
name: qiwei-webhook-relay
description: 企微 Webhook 与 Relay：支持企业版中央 Relay 自动接入，以及隔离部署下的显式直连模式。
---

# Webhook 与 Relay

## 使用边界

先调用 `qiwei_product_mode_status` 判断产品模式。个人版默认使用本地主动监听；企业版才进入中央 Relay 注册和服务端回调流程。

本 skill 负责：

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

> 默认禁止本地进程直接覆盖企微回调。独立部署确需直连时，必须显式设置 `QIWEI_ALLOW_DIRECT_CALLBACK=true`。

## 模式说明

### 中央 Relay 模式（默认）

企微平台把事件推送到 Fmode 中央 Relay 服务器，本地 Skill 默认通过 `https://8.138.37.248` 加密连接并长轮询取回属于自己的事件。适合 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`；事件在服务端持久排队，本地处理成功后才 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 的全局回调被个人电脑覆盖。