接入 Telegram

将 Telegram 机器人连接到 Ghast，即可通过手机私聊或群聊发送任务，并在 Telegram 收到回复。连接运行在你的电脑上：使用时需要保持 Ghast Desktop 运行、登录和联网。

打开 设置 → 渠道 → Telegram。页面包含机器人 token、三种不同的准备/测试操作、用户列表、默认模型和工作区绑定。群聊参与及 Telegram 隐私模式在 Telegram 配置，Ghast 没有另一个独立的“群组”开关。

开始前准备

使用专供这次 Ghast 安装使用的机器人、一个可用的 Provider 和模型，以及不含敏感资料的小范围工作区。先测试私聊，再考虑加入群聊。

用户列表不限制群成员

允许的用户 ID 检查普通私聊消息。列表为空时，允许能够联系机器人的所有私聊发送者。它不是群成员白名单：群消息使用另一套处理流程，而且当前页面没有群 ID 白名单。

因此，只填写你自己的用户 ID，并不能让共享群里的机器人变成“仅限你本人使用”。群成员、机器人可见范围、模型用量和工作区访问需要单独核对。

1. 创建机器人并填写 token

1. 在 Telegram 打开官方 @BotFather。
2. 发送 /newbot，按提示设置显示名称和用户名。
3. 将获得的机器人 token 粘贴到 Ghast 的 机器人 token。它不是你的 Telegram 登录验证码、手机号、用户 ID，也不是模型 API Key。
4. 使用眼睛按钮保持 token 遮蔽，不要将其放入求助消息或截图。
5. 点击 验证凭证，确认返回的用户名属于你准备连接的机器人。

取得 token 的步骤见 Telegram 的 机器人创建教程。你不需要另外实现教程中的示例程序，Ghast 已提供运行程序。

不要让其他服务和 Ghast 同时轮询同一个 token。Ghast 使用长轮询接收消息，不需要公开回调地址。已有 webhook 会与轮询冲突；迁移已有机器人时，需要有意识地停用此前的连接。参见 Telegram 消息接收说明。

2. 区分三个按钮

操作	实际做什么	成功不代表什么
验证凭证	使用输入框中的当前 token，向 Telegram 请求机器人身份	不保存设置、不启用桥接、不发送聊天消息，也不测试模型或工作区
检测	读取当前 Ghast 本地账号中已经记录的人物与 Telegram 历史，列出已知用户 ID	不查询所有 Telegram 用户、不验证输入的 token，也不会自动把任何人加入白名单
发送测试消息	验证当前 token，然后向明确填写的聊天 ID 发送固定的 Ghast 测试文字	不验证入站消息、用户白名单、模型生成、工具权限或工作区路由

验证和测试发送都使用输入框中的当前 token，包括尚未保存的修改；不要求机器人已经启用。之前的成功结果只对应当时测试的 token，改完输入框不等于重新验证过。

发送测试消息会真正向外发送消息。 它不调用模型生成回复，也不把入站用户白名单当成出站收件人限制。点击前核对收件人；页面不会替你自动选择一个聊天。

真实设置界面。token 保持遮蔽，测试收件人为空，因此无法点击发送测试消息。“已连接”描述当前桥接状态，不代表模型收发闭环已通过。

3. 添加允许的用户

使用对方的数字 Telegram 用户 ID，不要填写 @用户名、显示名称或负数的群聊天 ID。

已经知道用户 ID

1. 在 允许的用户 ID 中输入一个 ID。
2. 点击 添加，或按 Enter。
3. 确认下方出现该 ID 标签，访问范围摘要随之改变。
4. 逐个添加其他允许私聊的用户。
5. 其他配置准备好后，点击 保存。

只输入而没有添加，不会改变列表。每次添加一个 ID；输入框不会核验该人的身份，也不会拆分逗号分隔的多个值。重复 ID 不会再次加入。移除时点击标签旁的 ×。

摘要显示的是当前草稿。“当前仅允许 1 位用户”旁边如果仍有 未保存的修改，不表示正在运行的机器人已经采用这一限制。

用检测查找以前出现过的用户

1. 如果 Ghast 已经处理过目标用户的一条非敏感消息，点击 检测。
2. 核对返回的名称和数字 ID。
3. 点击该用户结果，将其加入草稿；加入后的结果会显示勾选标记。
4. 保存配置。

检测读取本地记录，包括以前见过的群成员。因此，某个结果不一定属于输入框中这个 token 对应的机器人，也可能是旧记录；必须重新确认身份。被检测到也不证明此人现在仍能联系该机器人。

没有结果时，可能是 Ghast 尚无此人的本地记录；可以手动填写已知 ID。不要为了填充检测结果，临时把生产机器人开放给所有人。

移除最后一个允许用户会让列表变为空，也就是私聊允许所有人，不是拒绝所有人。需要停止访问时，请关闭机器人并保存。

4. 选择模型与工作区

默认模型

选择可用的 默认模型 并保存。Telegram 任务的模型优先级是：

1. 明确选定的 Telegram 默认模型；
2. 映射会话中已经保存的模型；
3. 没有会话模型时使用 Chat 默认模型。

因此，明确设置 Telegram 默认模型后，已有 Telegram 会话的下一条任务也会优先使用它；并不像界面的简短提示那样只影响新会话。

没有可用配置时，Ghast 会返回未配置模型的错误，不会把机器人 token 当作推理服务。请检查 模型启用与可用性；Provider 计费和余额与 Telegram 连接是两回事。

工作区绑定

1. 在 工作区绑定 中选择已识别聊天，或手动填写聊天 ID；选择器也提供手动输入入口。
2. 选择一个非临时工作区。
3. 点击 添加，确认出现 聊天 → 工作区 的对应行。
4. 保存。

这里的 ID 识别聊天会话，不是人物。私聊 ID 为正数，群/超级群 ID 为负数；保留群 ID 的负号和完整数值。

有效的聊天绑定优先于 通用 → 默认工作区。两者都不可用时，使用 Ghast 内置默认工作区。“自动”不是当前桌面上正打开的项目。下一条 Telegram 任务也会把已有映射会话重新绑定到当前解析出的工作区。

要替换已有绑定，移除原行，再添加同一聊天和新的工作区，最后保存。移除绑定会恢复回退工作区，不会阻止该聊天，也不会删除文件。

ID 为未保存草稿中的示例值。用户列表决定普通私聊的允许发送者；下面独立的聊天 ID 则决定任务在哪个工作区执行。

5. 保存并验证私聊

1. 核对机器人 token、允许用户、模型和工作区。
2. 打开 启用 Telegram 机器人，点击 保存；token 为空时无法打开启用开关。
3. 等待 Telegram 标签状态刷新。已连接表示轮询成功且当前没有轮询错误，不代表模型已成功回复。
4. 在 Telegram 打开你的机器人，点击 Start 或发送 /start。
5. 发送：“只回复 telegram-ready-47，不要使用工具。”
6. 确认 Telegram 收到相应回复。

机器人不能主动开启与从未联系过它的用户的私聊。参见 Telegram 机器人介绍。如需额外测试单向发送，在 接收测试消息的聊天 ID 中填写已知 Chat ID，再点击 发送测试消息。输入框接受数字，可带开头的负号；用户名或 t.me 链接不能启用发送按钮。

测试结果可能同时出现正确机器人身份和发送失败。这说明 token 验证成功，但向该收件人送达失败；检查聊天 ID、用户是否已开始会话/屏蔽机器人，以及机器人在群里的发送权限。

群聊：可见范围、触发和历史

只把 Ghast 加入允许由你的本地 Ghast 及其所配置服务处理成员信息和消息内容的群。

有意识地配置 Telegram 侧

需要允许机器人入群时，在 BotFather 使用 /setjoingroups。Group Privacy 决定 Telegram 会向机器人交付哪些普通群消息；没有明确需要扩大参与范围时保持开启。用 /setprivacy 关闭后，更多群内容会变得可见；Telegram 说明需要把机器人重新加入群聊才能应用该变更。将机器人设为群管理员也会带来更广的消息可见范围。参见 Telegram 隐私模式。

如果明确需要与其他机器人通信，参阅 Telegram 的 Bot-to-Bot Communication Mode。与人聊天不要求启用它，不要仅为排查人类消息而打开。

Ghast 如何处理已经收到的群消息

当前 Ghast 的 Telegram 页面没有 仅提及时响应 开关。

• @ 机器人用户名、回复机器人，或文字中包含 ghast，都可能触发任务。
• 支持的斜杠命令可以进入命令处理。
• 其他已交付消息可能进入后台回复判断。Ghast 刚回复过时，也可能把后续发言当成延续讨论，不要求每次重新 @。
• 将机器人加入群聊本身就可能启动问候任务；不要假设它一定等到第一条明确指令才行动。
• 媒体、历史、链接和参与者信息可能在判断是否回复前已被处理。“没有回复”不等于“没有收集”。

后台判断可能消耗模型用量，并包含最近群聊文字和图片，也可能在没有明确请求时选择参与。参与判断不是严格的允许/拒绝策略。应该控制平台可见范围及机器人所在群聊，而不是依赖它保持沉默。

话题不是隔离工作区

Telegram 话题可以携带回复位置，但当前 Ghast 的会话及工作区映射使用群聊天 ID，没有按话题分别映射。同一个群的不同成员和话题可以共用 Ghast 会话及群聊历史。不要把话题当成私密任务边界；还需单独验证回复确实进入了目标话题。

命令和会话范围

个人会话管理请在私聊中使用以下命令：

命令	用途
/start 或 /help	显示可用命令说明
/new Project notes	创建另一会话，可附带标题
/conversations 或 /list	列出映射到当前 Telegram 用户的会话
/conversation 2 或 /switch 2	切换到最新列表中的指定编号
/stop	请求停止当前 Telegram 聊天中的一个运行任务
/model	打开 Provider/模型按钮，并修改 Telegram 共享默认模型

会话编号是列表位置，不是永久会话 ID。切换前重新获取列表。列表按用户查询，并非只包含当前群的历史；如果标题不应公开，不要在共享群里请求列表。

**当前群聊限制：**普通群消息使用群共享映射，/new 和 /conversation 却更新发令者映射。因此，群里的成功确认不证明后续普通消息已经切换到新会话；这两个命令也不会清除群聊历史。

已有任务仍在运行时，新消息可能分支到另一会话，而不是等待。/stop 按聊天寻找运行任务，不保证只停止发令者本人或某个话题的任务，也不会撤销已经完成的工具操作。

在 Telegram 中切换模型

/model 先显示已启用 Provider，再显示所选 Provider 最多 50 个已启用模型。选择后修改的是 Telegram 渠道整体的默认模型，不是仅修改个人会话。找不到目标模型时可在桌面选择器中设置；提示 Session expired 时，重新发送 /model。

这些按钮不是仅供所有者使用的管理界面。模型按钮回调不会重新检查私聊用户白名单，群成员也可能操作它。不要把模型菜单放到不适合改变共享默认值的群中。继续在桌面修改前重新打开设置，避免旧草稿覆盖远端已完成的模型切换。

保存、关闭和断开连接

token、启用开关、用户列表、模型和工作区绑定都属于草稿，需要 保存。切换平台标签不会保存。需要放弃时，关闭设置并确认不保存。

保存 Telegram 变更会重启桥接，包括只改模型或绑定的情况。请在任务之间调整；运行中的回复或外部送达不保证能跨越重启继续。验证、检测和测试发送则是立即执行的操作，不是关闭设置就能撤销的待保存修改。

要断开连接，关闭 启用 Telegram 机器人并保存。这不会撤销 token、将机器人移出 Telegram 群、清除已有会话/媒体或删除已发送消息。不再使用时，需要分别处理这些内容。

常见问题

现象	检查方式
无法启用	先填写机器人 token。
凭证验证成功，但没有入站回复	保存并启用；检查轮询状态、私聊用户 ID、可用模型，以及是否有其他轮询/webhook 消费者。
检测结果为空	它使用本地记录，不是实时 Telegram 用户目录；必要时手动填写已知用户 ID。
检测到不认识的人	结果可能来自之前的本地私聊/群聊记录，不限于当前机器人；添加前核对身份。
无法发送测试消息	填写数字 Chat ID，不是用户名或链接；有测试进行中时等待结束。
显示机器人身份，但测试发送失败	检查收件人 ID、是否已开始会话/屏蔽机器人、群成员身份和发送权限。
添加 ID 好像没有生效	点击添加，确认出现标签，再保存；只填写输入框不算列表条目。
群成员不受用户列表限制	该列表限制私聊消息，不限制群成员。
收不到普通群文字	Telegram 隐私模式可能阻止交付，Ghast 无法处理未收到的事件。先决定所需范围，不要直接授予管理员来排查。
不同话题混用会话或工作区	话题共享群级路由；检查完整群聊天 ID 和回退工作区。
其他 Telegram 会话的模型也变了	远端模型按钮修改共享默认值。
文本正常，语音或附件不正常	按 语音输入与回复 分别测试；文字送达不证明附件处理或转录成功。
反复轮询/网络错误	保持 Ghast 联网，检查 网络设置、token 有效性和重复运行的机器人连接。不要分享含 token 的 Telegram API URL 日志。