# Telegram 接入

配置 Bot Token，排除轮询冲突，检查私聊、群和话题。

## 先让机器人接收一条私聊

本页完成 Telegram 机器人接入、私聊配对与群聊检查。开始前，先在 Nexus 内验证目标 Agent 能回答普通消息。Telegram 只提供消息入口，模型和工具需要在 Nexus 中分别配置。

在 Telegram 的 BotFather 创建或选择自己的机器人，取得 Bot Token。令牌用于让 Nexus 代表该机器人连接服务，保存在通道表单中，不要粘贴进聊天或公开截图。

## 保存连接配置

打开 **能力 → 频道 → Telegram**，填写以下字段。

| 字段 | 填写方式 |
| --- | --- |
| Bot Token | BotFather 为该机器人签发的令牌 |
| Bot API Base URL | 通常保留 `https://api.telegram.org` |

使用自建 Bot API 服务时再填写对应地址。访问 Telegram 的网络能力取决于运行 Nexus 的机器；电脑上能打开 Telegram，不能证明 Web 服务器能访问 Bot API。

保存后检查连接结果。若令牌刚轮换，应在 Nexus 同步更新，再用新消息验证，不以旧聊天中的回复判断是否成功。

## 排除其他消息接收程序

Nexus 使用 `getUpdates` 长轮询收取消息。同一机器人若仍设置 Webhook，需先由管理者核对并解除旧接入；Telegram 不允许两种方式同时取更新。也应停止其他使用同一令牌轮询的程序，避免消息被另一端消费。[Telegram 接收更新说明](https://core.telegram.org/bots/faq#getting-updates)

迁移前记录旧服务的用途，确认哪个实例负责后续收发。不要为了测试新环境而让两套后台同时接管同一个机器人。

## 配对自己的私聊

1. 在 Telegram 打开目标机器人的私聊，启动对话并发送测试文字。
2. 在 Nexus **能力 → 配对** 中找到该外部用户，绑定到测试 Agent 与会话。
3. 返回 Telegram 再发下面的请求。

```text
这是 Telegram 私聊测试。请只回复“已收到私聊测试”。
```

检查 Nexus 对应会话出现该请求，Telegram 原聊天收到回复。两端都核对后，再交给机器人真实材料。

## 从私聊扩展到群和话题

将机器人加入测试群，检查它在群内的消息可见范围。Telegram 的隐私模式会限制机器人收到哪些群消息；普通文字没有传入时，先按平台允许的命令或回复方式测试，再决定是否需要调整隐私设置。[Telegram 消息可见范围](https://core.telegram.org/bots/faq#what-messages-will-my-bot-get)

群聊需要核对群本身的配对。使用话题时还要检查对应话题，不能把私聊成功等同于所有群和话题都已授权。

先使用真人账号发普通文本，Nexus 收到后检查绑定的 Agent，再测试回复位置。首次测试不同时加入附件、定时投递和多群转发，便于区分失败阶段。

## 按现象排查

| 现象 | 检查 | 复测 |
| --- | --- | --- |
| 通道无法连接 | Token、服务器出站网络、API 地址 | 保存后发送新私聊 |
| 长轮询冲突或收不到更新 | 旧 Webhook、其他轮询进程 | 只保留目标接收实例 |
| 私聊正常，群里无消息 | 群消息可见范围和群配对 | 在测试群发送允许接收的消息 |
| 群正常，某话题异常 | 话题配对与回复目标 | 在同一话题测试 |
| Nexus 有请求但未完成 | 模型、审批或待答问题 | 在绑定会话处理阻塞 |
| 已完成但未送达 | 平台发送错误与目标聊天 | 先看原聊天，再决定重试 |

设备退出或服务器停止会影响在线收发。需要长期运行时保持宿主在线；变更配对后，用新消息确认进入了新的目标会话。配对管理见[外部消息配对](/docs/pairing)。