5.3 KiB
| title | nav_title | description | order |
|---|---|---|---|
| Telegram 接入 | Telegram | 找 BotFather 要一个 Bot Token 填进桌面端，在 Telegram 私聊里点按钮批权限。 | 2 |
Telegram 接入
五个平台里接入最快的一个：找 @BotFather 要一个 Token，粘进桌面端就完事，权限审批是原生按钮。适合能连上 Telegram 的个人用户。限制是只处理私聊，不处理群组；国内网络下的连通性要你自己解决。
创建机器人
在 Telegram 里搜索官方账号 @BotFather。
给它发送 /newbot。
按提示走完两步：
- 取一个机器人名称，例如
ClaudeCodeHaha机器人。 - 取一个用户名，全英文且必须以
_bot结尾，例如jiang_cc_hah_bot。
创建成功后复制 BotFather 返回的Bot Token。这枚 Token 等同于机器人的密码，别贴到公开的地方。
在桌面端填 Token
- 打开「设置」→「IM 接入」，切到「Telegram」Tab。
- 把 Bot Token 粘进「Bot Token」。
- 点「保存」。
「允许的用户」可以留空。留空时只有完成配对的人能用。要直接放行已知账号，就填 Telegram 数字用户 ID，多个用逗号分隔。
配对
回到页面顶部的「配对管理」，点「生成配对码」，拿到一枚 6 位码。这一步立即生效，不需要再点保存。
在 Telegram 里私聊刚创建的机器人，随便发一条消息，按提示把这枚码发过去。看到配对成功提示就可以开始对话。
配对码 60 分钟内有效、只能用一次，重新生成后旧码立刻作废。连续输错会被限流，等几分钟再试。
支持的命令
/start— 显示帮助和可用命令/help— 显示当前可用命令/projects— 列出最近项目并切换/resume— 选择并恢复历史会话/status— 当前项目、模型、运行状态和任务摘要/new— 清空当前绑定并重新选择项目/clear— 清空上下文，保留项目绑定/stop— 停止本轮生成/provider— 查看或切换 Provider/model [model]— 查看或切换模型/skills— 查看当前项目可用的 Skills，点选后直接调用
Agent 能力与边界
Telegram 不是一套独立的问答模型。普通消息和从 /skills 点选的 Skill 都会进入当前项目的同一条 Claude Code Agent 会话，因此会延续多轮上下文，并能使用该会话已经加载的文件、终端、Git、Skills 和 MCP 工具。点选 Skill 后，adapter 会把对应的 /<skill-name> 作为用户消息送入 Agent，由现有 Skill 系统加载 SKILL.md 并继续执行。
这些能力只适合单一可信用户远程控制自己的机器。配对账号获得的是当前项目中的完整 Agent 能力，权限确认只是操作闸门，并不是操作系统沙箱；不要把 Bot 暴露给公开群聊或不可信账号，也不要从聊天中安装未经本机审核的 Skill、Plugin 或 MCP。
Adapter 只接受已配对或在允许列表中的私聊账号。项目列表、名称匹配和历史会话恢复都会限制在配置的项目根目录内；新建远程会话固定使用 default 权限模式，bypassPermissions 历史会话不会在远程恢复。Agent 输出中的本地图片只能从当前会话工作目录读取，远程图片 URL 不会由 Adapter 自动请求。
权限审批与消息表现
Claude 请求敏感权限时，Telegram 里会收到一条带按钮的消息，三个选项分别是允许一次、本次会话内永久允许同类操作、拒绝。只有当前待处理的请求才能被确认，点完结果直接回传给同一条桌面端会话。
回复走一层流式缓冲：思考阶段先发占位消息，正文逐步累积更新，完成后按 Telegram 的长度上限分片发送。
本地开发启动
发布版桌面端会自动把 adapter 作为 sidecar 拉起。只有从源码运行或单独调试时才需要手动启动：
cd adapters
bun install
bun run telegram
可选的环境变量覆盖：
export TELEGRAM_BOT_TOKEN="123456:ABC-DEF..."
export ADAPTER_SERVER_URL="ws://127.0.0.1:3456"
常见问题
adapter 启动时报缺少 Token：TELEGRAM_BOT_TOKEN 和 ~/.claude/adapters.json 里的 telegram.botToken 都没生效，回设置页把 Token 填好并保存。
设置页能打开但机器人没反应：源码运行时 webapp 只负责写配置，不会自动拉起 bun run telegram；发布版桌面端才会通过 sidecar 自动启动。
发消息提示未授权：检查是否已生成配对码、码是否还在 60 分钟有效期内、是否发到了正确的机器人私聊里。
重启后会话没接回来：检查 ~/.claude/adapter-sessions.json 能否正常写入，以及桌面端里那条会话是否还在。
源码入口
adapters/telegram/index.ts，以及 adapters/common/ 下的 pairing.ts、session-store.ts、ws-bridge.ts、message-buffer.ts、format.ts。