> For AI agents: the complete documentation index is available at /llms.txt, the full documentation bundle is available at /llms-full.txt.

# 通道 API：在 Octop 中将专家连接到消息平台

将专家连接到即时通信平台，以便它们可以发送和接收消息。

## 路由

```text
/api/agents/{agent_id}/channels
```

## 端点

| 方法     | 路径                                                | 描述                                          |
| ------ | ------------------------------------------------- | ------------------------------------------- |
| GET    | `/agents/{aid}/channels`                          | 列出专家的渠道                                     |
| POST   | `/agents/{aid}/channels`                          | 添加新渠道                                       |
| GET    | `/agents/{aid}/channels/{cid}`                    | 获取渠道详情                                      |
| PATCH  | `/agents/{aid}/channels/{cid}`                    | 更新渠道配置                                      |
| DELETE | `/agents/{aid}/channels/{cid}`                    | 删除渠道                                        |
| POST   | `/agents/{aid}/channels/{cid}/test`               | 测试渠道连接                                      |
| POST   | `/agents/{aid}/channels/qq/qrcode/generate`       | 发起 QQ 扫码绑定，返回 `qrcode_url` / `qrcode_token` |
| POST   | `/agents/{aid}/channels/qq/qrcode/poll`           | 轮询 QQ 扫码结果；请求体 `{qrcode_token}`             |
| POST   | `/agents/{aid}/channels/dingtalk/qrcode/generate` | 发起钉钉扫码应用授权                                  |
| POST   | `/agents/{aid}/channels/dingtalk/qrcode/poll`     | 轮询钉钉授权结果；成功时创建并启用通道                         |

## 创建通道

### 飞书

```bash
curl -X POST http://127.0.0.1:8088/api/agents/1/channels \
  -H 'Authorization: Bearer <token>' \
  -H 'Content-Type: application/json' \
  -d '{
    "kind": "feishu",
    "name": "团队飞书机器人",
    "config": {"app_id": "cli_xxx", "app_secret": "yyy"}
  }'
```

### Telegram

```bash
curl -X POST http://127.0.0.1:8088/api/agents/1/channels \
  -H 'Authorization: Bearer <token>' \
  -H 'Content-Type: application/json' \
  -d '{
    "kind": "telegram",
    "name": "Telegram 机器人",
    "config": {
      "token": "your-bot-token",
      "allowed_user_ids": ["123456789"]
    }
  }'
```

可选的 `allowed_user_ids` 用于限制谁可以给 Telegram 机器人发消息；省略或留空表示不限制。

两种情况成功后都返回 `201 Created`。

在 `config` 中设置展示选项：

| 字段                | 取值                | 默认                          | 含义                                                                                                      |
| ----------------- | ----------------- | --------------------------- | ------------------------------------------------------------------------------------------------------- |
| `response_mode`   | `invoke`、`stream` | 页面：`stream`；API 兜底：`invoke` | `invoke` 对应页面中的**仅终稿**，聊天应用只收到完成回复；`stream` 对应**实时进度**。QQ 私聊忽略此键。                                       |
| `c2c_streaming`   | bool              | 保存时为 `true`                 | 仅 QQ 私聊。`true` 走官方 `stream_messages`；`false` 只发一条静态 markdown。旧键 `streaming` / `response_mode` 对 C2C 无效。 |
| `show_thinking`   | bool              | `false`                     | 显示思考过程。仅终稿模式下不可用。                                                                                       |
| `show_tool_hints` | bool              | `false`                     | 显示工具提示。仅终稿模式下不可用。QQ 私聊中额外工具气泡会占用被动回复配额。                                                                 |

### 支持的类型

| `kind`     | 平台       |
| ---------- | -------- |
| `weixin`   | 微信       |
| `qq`       | QQ       |
| `wecom`    | 企业微信     |
| `feishu`   | 飞书       |
| `yuanbao`  | 腾讯元宝     |
| `dingtalk` | 钉钉       |
| `telegram` | Telegram |
| `discord`  | Discord  |
| `xiaoyi`   | 华为小艺     |
| `mqtt`     | MQTT     |

对于 `kind: "qq"`，`config` 通常包含 `app_id`、`secret`（或 `client_secret`），可选的 `c2c_streaming`（页面保存时默认为 `true`），以及可选的 `group_context`（`visibility`、`activation`、`history`、`history_limit`）。


> **注意**
> 
> 若 `kind` 不是支持的值，请求将以 `400 CHANNEL_KIND_UNSUPPORTED` 失败。
> 


## QQ 扫码绑定

先生成二维码会话，再轮询直到手机 QQ 扫码成功：

```bash
curl -X POST http://127.0.0.1:8088/api/agents/1/channels/qq/qrcode/generate \
  -H 'Authorization: Bearer <token>'
```

```bash
curl -X POST http://127.0.0.1:8088/api/agents/1/channels/qq/qrcode/poll \
  -H 'Authorization: Bearer <token>' \
  -H 'Content-Type: application/json' \
  -d '{"qrcode_token": "..."}'
```

成功时 poll 响应包含 `app_id` 与 `secret`，可用 `POST` / `PATCH` 写入渠道。

## 钉钉扫码注册

钉钉支持通过二维码授权直接创建并启用通道。先生成注册会话，把 `qrcode_url` 展示给用户，再用 `registration_id` 轮询，直到返回 `success`、`waiting`、`expired` 或 `failed`。

```bash
curl -X POST http://127.0.0.1:8088/api/agents/1/channels/dingtalk/qrcode/generate \
  -H 'Authorization: Bearer <token>'
```

响应：

```json
{
  "registration_id": "...",
  "qrcode_url": "https://...",
  "user_code": "ABCD-EFGH",
  "expires_in": 600,
  "interval": 5
}
```

```bash
curl -X POST http://127.0.0.1:8088/api/agents/1/channels/dingtalk/qrcode/poll \
  -H 'Authorization: Bearer <token>' \
  -H 'Content-Type: application/json' \
  -d '{"registration_id": "..."}'
```

成功时，Octop 返回 `{"status":"success","channel_id":"..."}`，并保存一个已启用的钉钉通道，默认使用实时进度模式且不显示思考过程或工具提示。

## 测试渠道

验证已保存的渠道是否可以成功连接：

```bash
curl -X POST http://127.0.0.1:8088/api/agents/1/channels/5/test \
  -H 'Authorization: Bearer <token>'
```

响应：

```json
{"ok": true}
```

或失败时：

```json
{"ok": false, "error": "无法连接到 Telegram Bot API"}
```

## 更新渠道

```bash
curl -X PATCH http://127.0.0.1:8088/api/agents/1/channels/5 \
  -H 'Authorization: Bearer <token>' \
  -H 'Content-Type: application/json' \
  -d '{"name": "已重命名的渠道"}'
```

可以只传递 `name` 或 `config` 中需要修改的字段子集。

## 删除渠道

```bash
curl -X DELETE http://127.0.0.1:8088/api/agents/1/channels/5 \
  -H 'Authorization: Bearer <token>'
```

成功时返回 `204 No Content`。

## 探测配置（不保存）

在正式持久化之前验证渠道配置：

```bash
curl -X POST http://127.0.0.1:8088/api/agents/1/channels/probe \
  -H 'Authorization: Bearer <token>' \
  -H 'Content-Type: application/json' \
  -d '{"kind": "telegram", "config": {"token": "your-bot-token"}}'
```

响应：

```json
{"ok": true}
```

或失败时：

```json
{"ok": false, "reason": "invalid_token", "detail": "Telegram 拒绝了提交的令牌"}
```
