Crabtalk 是一个常驻后台的嵌入式 AI Agent（Agent daemon），而它的 Telegram 网关crabtalk-telegram可以让你3 步把 Agent 接入 Telegram 聊天窗口：无需自己写一行机器人代码，直接获得流式打字回复、Markdown 格式、权限白名单和交互式按钮问答能力。本文带你快速搭好这个 AI 聊天机器人大门。

为什么选择 Crabtalk 的 Telegram 网关

大多数 Telegram 机器人框架需要你手动处理消息轮询、流式输出、Markdown 转义等琐事。Crabtalk 把这一切封装进了一个独立网关组件里：

• 流式回复（Streaming）：Agent 每生成一段内容就实时更新聊天消息，而不是干等一整条长回复（实现见 apps/telegram/src/serve.rs）
• MarkdownV2 格式化：自动转义特殊字符，解析失败时优雅降级为纯文本（apps/telegram/src/markdown.rs）
• 按用户白名单：通过allowed_users精确控制谁可以和机器人对话
• 交互按钮问答：当 Agent 发起ask_user提问时，机器人自动渲染 Telegram 内联键盘按钮，点选即答
• 免公网 IP：基于长轮询（long polling）实现，家用网络即可运行

💡 Crabtalk 的架构是"一个守护进程 + 多个客户端"：crabtalkd守护进程负责运行 Agent、调度工具和 MCP 服务，Telegram 网关只是挂在它身上的一个"大门"，通过本机 Unix socket 通信。更多设计可参考 docs/src/SUMMARY.md。

准备：一条命令安装环境

整个生态的安装由crabup包管理器统一负责（它同时管理 systemd/launchd 服务生命周期），只需一次cargo install：

cargo install crabup

安装说明详见 apps/crabup/README.md。

第 1 步：安装并启动 Crabtalk 守护进程

crabup install daemon cli # 安装 daemon 与 CLI 客户端 crabup daemon start # 安装系统服务并启动

启动后，daemon 会在首次运行时自动创建配置目录~/.crabtalk/config.toml。

第 2 步：配置 LLM 端点

编辑~/.crabtalk/config.toml，填入任意 OpenAI 兼容端点（配置参考：crates/storage/config.toml）：

[llm] base_url = "http://localhost:4000/v1" api_key = "${OPENAI_API_KEY}"

配置完成后在 Telegram 中直接发消息测试——daemon 会在启动时自动发现该端点下的可用模型。

第 3 步：安装 Telegram 网关并填写 Token

crabup install telegram # 安装 crabtalk-telegram 网关 crabup telegram start # 启动服务

首次执行start时，程序会交互式地提示你输入@BotFather创建的 Bot Token（输入时打星号掩码），并自动保存到~/.crabtalk/config/telegram.toml，无需手写配置文件。

配置结构非常简单（apps/telegram/src/config.rs）：

token = "123456:ABC-your-bot-token" # 可选：只允许这些 Telegram 用户 ID 对话，留空则响应所有人 allowed_users = []

启动成功后，去 Telegram 里给你的机器人发条消息，你会看到：

1. 机器人持续显示"正在输入…"状态（打字指示器）
2. 回复以同一条消息滚动更新的形式流式呈现
3. Agent 提问时出现可点击的内联按钮

进阶玩法：白名单与群聊

• 隐私控制：在telegram.toml的allowed_users中填入你的用户 ID，其他人发消息会被静默忽略——把机器人丢进公开群聊也不怕
• 群聊支持：机器人在群组中会自动引用回复触发它的那条消息，避免答非所问
• 多轮交互：流式回复进行中再发消息，会被识别为对ask_user问题的回答并直接传回 Agent
• 附件感知：发来的图片和文档会被摘要后并入对话内容
• 服务管理：crabup telegram stop/crabup telegram logs随时停止与查看日志

常见问题

Q：机器人没反应？先确认crabup daemon logs中 daemon 正常、llm.base_url已配置，再看crabup telegram logs是否有 token 相关报错。

Q：需要公网服务器吗？不需要。网关采用长轮询方式拉取 Telegram 消息，任何能访问外网的机器都可以运行。

Q：如何升级？crabup update会批量对齐所有已安装二进制到最新版本，保证线协议一致。

小结

3 条命令、零代码，你就拥有了一个支持流式回复的 AI 聊天机器人大门。想深入了解网关的消息循环、流式状态机（ChatStream）与交互键盘的实现，可以阅读源码 apps/telegram/；daemon 侧的运行机制参见 docs/src/spec/runtime.md。