---
name: qiwei-webhook-relay
description: 企微 Webhook 与 Relay：仅支持中央 Relay 模式自动注册/配置、Relay 长轮询客户端。
---

# Webhook 与 Relay

## 使用边界

本 skill 负责：

- 查询 Relay 回调配置状态；
- 在中央 Relay 服务端注册租户、保存凭证；
- 自动配置企微回调地址到 Relay；
- 管理 Relay 配置。

> **本地 webhook server 模式已禁用。** 所有回调统一通过中央 Relay 接收。

## 模式说明

### 中央 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`；
   - 调用 `/client/setCallback` 把回调地址设为 `{RELAY_BASE_URL}/api/webhook/ingest/{tenantId}/{guid}`；
   - 返回配置结果，并提示启动 Relay 轮询客户端。
4. 在服务器上执行 `npm run relay` 启动长轮询（或使用 systemd/pm2 持久化运行）。

### 手动注册 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` — 自动配置企微回调到 Relay（本地模式已禁用）
- `qiwei_relay_config` — 读取 Relay 配置
- `qiwei_relay_save_config` — 保存 Relay 公钥/租户配置
- `qiwei_relay_register` — 注册 Relay 租户并保存凭证
- `qiwei_relay_connect` — 配置 Relay 回调地址

> 已移除的本地模式工具：`qiwei_webhook_discover`、`qiwei_webhook_server_start`、`qiwei_webhook_server_stop`、`qiwei_webhook_setup`。