【Hermes：多平台接入】15、Telegram Bot 接入：手机随时叫 AI 助手（最推荐） —— 把 Honcho 智能体装进口袋

无心水2026-04-30 13:46

Telegram Bot 接入：手机随时叫 AI 助手（最推荐） ------ 把 Honcho 智能体装进口袋

电脑上的智能体再强大，也不如手机里随时能聊的机器人方便。Telegram Bot + Honcho，让你在等车、做饭、开会时都能随手召唤 AI 助手。本文手把手教你从零搭建。

前言：为什么 Telegram Bot 是最佳移动入口？

在众多即时通讯平台中，Telegram 凭借以下优势成为 AI 助手接入的首选：

  • 原生 Bot API：官方提供完整的机器人接口，无需破解或中间件。
  • 多端同步：手机、电脑、网页版消息全同步，不会漏掉对话。
  • 语音消息支持：可以直接发语音，Bot 能转文字或返回语音回复。
  • 隐私可控：可以设置 Bot 仅对你自己可用，或限制群组使用。
  • 全球免费：无广告、无收费墙，消息推送稳定。

将 Honcho 智能体（Hermes 画像引擎）接入 Telegram Bot，你就拥有了一个随身携带、长期记忆、支持工具调用的 AI 助手。无论在地铁上问天气，还是在深夜写代码时调试，只需打开 Telegram，发一条消息即可。

本文将从创建 Bot 开始，逐步完成配置、部署、测试，并涵盖语音支持、隐私设置、手机使用技巧和常见问题修复。全文包含 4 张 mermaid 流程图，确保你即使第一次接触 Telegram Bot 也能顺利完成。

1. @BotFather 创建机器人获取 Token

1.1 什么是 BotFather？

BotFather 是 Telegram 官方的"机器人管理员"，负责创建和管理所有 Bot。你需要通过它来获得一个专属的 Bot Token。

1.2 创建步骤

  1. 打开 Telegram （手机或桌面版），搜索 @BotFather。

  2. 点击 Start 或发送 /start。

  3. 发送 /newbot 命令。

  4. 按照提示输入：

    • Bot 显示名称 ：例如 My Honcho Assistant（用户看到的名称）
    • Bot 用户名 ：必须以 bot 结尾，例如 my_honcho_bot（唯一标识）

  5. 成功后，BotFather 会返回一条消息，包含：

    复制代码 
    Done! Congratulations on your new bot. You will find it at t.me/my_honcho_bot.
Use this token to access the HTTP API:
1234567890:ABCdefGHIjklmNOPqrstUVwxyz

⚠️ 重要 ：Token 是 Bot 的"密码"，任何人拿到都可以控制你的 Bot。不要上传到公开代码仓库。

1.3 设置 Bot 信息（可选）

  • /setdescription：设置简短描述
  • /setabouttext：设置"关于"信息
  • /setuserpic：上传头像
  • /setcommands：设置命令菜单（如 /start, /help）

建议至少设置 /setcommands，让用户知道 Bot 支持哪些功能：

复制代码 
start - 开始对话并初始化用户画像
help - 查看帮助
reset - 重置当前会话记忆

Telegram API @BotFather 用户 Telegram API @BotFather 用户 保存 Token，后续配置使用 /newbot 询问 Bot 名称 输入名称 询问 Bot 用户名 (xxx_bot) 输入用户名 创建 Bot 生成 Token 返回 Token

2. config.yaml 配置 telegram gateway

2.1 Honcho 的 Telegram 集成方式

Honcho 提供了两种与 Telegram 集成的方式：

  • Webhook 模式：Honcho 服务提供一个公网 URL，Telegram 将消息 POST 到该 URL。适合 Serverless 或 VPS 部署。
  • Polling 模式：Honcho 主动轮询 Telegram API 获取新消息。适合内网或没有公网 IP 的环境。

本文采用 Webhook 模式（推荐），因为响应更快、资源消耗更小。

2.2 配置 config.yaml

在 Honcho 的配置文件（通常位于 ~/.hermes/config/config.yaml）中添加 Telegram 网关配置：

yaml 复制代码 
# Telegram Bot 配置
telegram:
  enabled: true
  bot_token: "1234567890:ABCdefGHIjklmNOPqrstUVwxyz"  # 替换为你的 Token
  webhook:
    enabled: true
    url: "https://your-honcho-domain.com/telegram/webhook"  # 公网可达的地址
    secret_token: "your_secret_optional"  # 可选，用于验证请求来自 Telegram
  allowed_users:
    - "123456789"   # 你的 Telegram 用户 ID（数字）
    - "987654321"   # 可添加多个，留空则允许所有人
  commands:
    start: "初始化助手，开始对话"
    help: "显示帮助信息"
    reset: "重置当前会话历史"

获取自己的 Telegram User ID ：向 @userinfobot 发送任意消息，它会返回你的 ID。

2.3 设置 Webhook

启动 Honcho 服务后，你需要告诉 Telegram 将消息发送到你的 Webhook 地址。有两种方式：

方式一：Honcho 自动设置（推荐）

Honcho 启动时会自动调用 Telegram API 设置 Webhook（如果配置了 webhook.url）。检查日志是否有：

复制代码 
INFO: Telegram webhook set successfully: https://xxx/telegram/webhook
方式二：手动设置

使用 curl 或浏览器访问：

复制代码 
https://api.telegram.org/bot<YOUR_TOKEN>/setWebhook?url=<YOUR_WEBHOOK_URL>

例如：

bash 复制代码 
curl -X POST "https://api.telegram.org/bot1234567890:ABCdef/setWebhook" \
  -d "url=https://your-domain.com/telegram/webhook" \
  -d "secret_token=your_secret_optional"

成功返回：

json 复制代码 
{"ok":true,"result":true,"description":"Webhook was set"}

2.4 验证 Webhook 状态

bash 复制代码 
curl "https://api.telegram.org/bot<YOUR_TOKEN>/getWebhookInfo"

返回中 url 字段应为你的地址，pending_update_count 应为 0 或很小。
渲染错误: Mermaid 渲染失败: Lexical error on line 7. Unrecognized text. .../telegram/webhook 端点] end subgra -----------------------^

3. 启动与连接测试

3.1 启动 Honcho 服务

确保 Honcho 已经配置好 Telegram 网关。使用 Docker 或直接运行：

bash 复制代码 
# Docker 方式
docker run -d \
  --name honcho \
  -v ~/.hermes/data:/app/data \
  -v ~/.hermes/config:/app/config:ro \
  -p 8080:8080 \
  -e TELEGRAM_BOT_TOKEN="你的Token" \
  honcho/hermes:latest

# 直接运行方式
python -m honcho.server --config ~/.hermes/config/config.yaml

查看日志确认 Telegram 网关已加载：

复制代码 
INFO: Telegram bot started, polling mode disabled (webhook mode)
INFO: Webhook endpoint registered: /telegram/webhook

3.2 测试连接

  1. 打开 Telegram，搜索你的 Bot 用户名（如 @my_honcho_bot）。
  2. 点击 Start 或发送 /start。
  3. 发送一条普通消息，例如："你好，我是谁？"

如果一切正常，Bot 应该会回复（可能根据你的 Honcho 后端配置给出个性化回复）。

3.3 调试技巧

如果 Bot 没有响应，按以下顺序排查：

问题现象 可能原因 解决方法
Bot 不回复任何消息 Webhook 未设置或 URL 不可达 检查 getWebhookInfo，确保 URL 公网可访问
回复"未授权"或"无权限" allowed_users 未包含你的 ID 在配置中添加你的 Telegram ID，或删除该字段
回复内容为 Honcho 内部错误 Honcho 后端异常或 API Key 无效 查看 Honcho 日志，检查 LLM 配置
回复延迟极高（>5秒） 冷启动（Serverless）或网络问题 预热实例或检查服务器地域

4. 语音消息支持

Telegram Bot 的一大亮点是原生支持语音消息。Honcho 可以：

  • 接收用户发送的语音，转文字后处理
  • 以语音形式回复用户（TTS）

4.1 接收语音消息

当用户发送语音时，Telegram Webhook 会收到一个 voice 字段，包含 file_id。Honcho 需要：

  1. 通过 getFile API 获取文件路径
  2. 下载语音文件（通常是 .ogg 格式）
  3. 使用语音识别（如 OpenAI Whisper）转文字
  4. 将文字传入对话流程

配置示例（在 config.yaml 中）：

yaml 复制代码 
telegram:
  voice:
    enabled: true
    stt_provider: whisper  # 或 openai_whisper, local_whisper
    stt_model: base        # tiny, base, small, medium, large

4.2 发送语音回复

Honcho 生成文本回复后，可以选择将其转为语音发送（需要配置 TTS）。

yaml 复制代码 
telegram:
  voice_reply:
    enabled: true
    tts_provider: openai   # 或 elevenlabs, edge
    tts_voice: "alloy"     # 不同 provider 的 voice 名称
    max_length: 1000       # 超过此长度仍发送文本

4.3 用户体验优化

  • 自动切换：用户发语音，Bot 也尽量回语音；用户发文字，回文字。
  • 语言匹配：检测语音语言，使用相同语言回复（若 TTS 支持）。
  • 成本控制：语音识别和合成需要调用外部 API（如 OpenAI），注意设置每日配额。

是
否
用户发送语音
Telegram
Honcho Webhook
下载 .ogg 文件
Whisper 转文字
用户消息文本
Honcho 智能体
回复文本
语音回复启用?
文本转语音
发送文字回复
生成音频
发送语音消息
User

5. 隐私与权限设置

5.1 限制用户范围

默认情况下，任何人找到你的 Bot 都可以对话。如果你只想自己使用，配置 allowed_users：

yaml 复制代码 
telegram:
  allowed_users:
    - 123456789   # 你的 Telegram 数字 ID

如果 allowed_users 为空或不存在，则允许所有人。

5.2 限制群组使用

如果你不希望 Bot 被添加到群组（避免打扰），可以在 BotFather 中设置：

  • 发送 /setjoingroups 给 BotFather，选择 Disable。

或者在代码中检测消息的 chat.type，如果是 group 或 supergroup 则忽略。

5.3 用户数据隐私

Honcho 默认会存储用户画像和对话记忆（用于个性化）。对于 Telegram Bot，你可以：

  • 允许用户删除自己的数据 ：实现 /forgetme 命令，调用 Honcho 的删除接口。
  • 设置数据保留期限 ：在 config.yaml 中配置 memory_ttl_days。
  • 告知用户隐私政策 ：在 /start 回复中包含说明。

5.4 敏感命令保护

某些命令（如 /reset 重置记忆）可能导致数据丢失。建议添加确认机制：

python 复制代码 
# 伪代码
if command == "/reset":
    reply = "⚠️ 确认重置所有记忆？回复 '确认' 继续。"
    # 保存一个待确认状态

5.5 Telegram 隐私设置最佳实践

设置项 推荐值 理由
允许群组添加 Bot 禁用 避免被滥用
允许通过链接邀请 Bot 禁用（个人用） 只有你知道用户名才能找到
显示最后上线时间 不适用 Bot 无此概念
收集用户隐私数据 最小化 只存储对话中必要的画像信息

6. 手机使用最佳姿势

6.1 置顶对话

在 Telegram 主界面，长按 Bot 对话 → 置顶。这样 Bot 始终在聊天列表顶部，随时可达。

6.2 使用语音输入

手机键盘上的麦克风图标可以直接语音转文字发送给 Bot。但更好的体验是直接发语音消息，让 Bot 的 STT 处理（准确性可能更高，取决于模型）。

6.3 快捷回复

Telegram 支持将常用短语保存为快捷回复（iOS/Android 都有）。例如设置 #weather 为"北京天气"，发送给 Bot。

6.4 跨设备同步

Telegram 网页版和桌面版与手机完全同步。你在电脑上向 Bot 发消息，手机也能看到历史，反之亦然。

6.5 离线消息

即使你的 Bot 服务暂时不可用，Telegram 会缓存用户消息，服务恢复后重新发送 Webhook（最多重试一定次数）。Honcho 需要实现幂等处理。

6.6 通知管理

  • 如果 Bot 回复频繁，可以关闭该对话的通知（长按 → 静音）。
  • 设置 Bot 回复的消息不触发通知（Telegram 支持静默发送，需要 Bot API 设置 disable_notification）。

6.7 典型使用流程

可随时切走
收到回复后
打开Telegram
点击置顶Bot
输入消息
发送
等待回复
收到回复
继续对话
后台挂起
通知提醒

7. 常见问题与修复

7.1 Bot 不响应新消息

现象 ：发送消息后 Bot 无任何反应，getWebhookInfo 显示 pending_update_count 不断增长。

原因：Webhook URL 不可达或返回非 200 状态码。

解决：

  • 确保 Honcho 服务正常运行，/telegram/webhook 路径可访问。
  • 检查防火墙和安全组，开放必要端口（通常是 443 或 8080）。
  • 如果使用自签名证书，Telegram 不接受。必须使用有效的 HTTPS（Let's Encrypt 免费）。

7.2 Webhook 设置失败："error":"Bad webhook: SSL error"

原因：Telegram 要求 Webhook URL 必须使用 HTTPS 且证书有效。

解决：

  • 使用 Nginx/Caddy 反向代理并配置 Let's Encrypt 证书。
  • 或使用 Cloudflare Tunnel（免费）暴露本地服务。

7.3 用户 ID 获取不到

原因 ：allowed_users 配置了数字 ID，但 Telegram 发送的用户 ID 是整数，YAML 解析可能有问题。

解决：用引号包裹，或确保 YAML 中数字格式正确。

7.4 语音识别失败

原因：Whisper API Key 无效或网络问题。

解决：

  • 检查 OpenAI API Key 是否正确。
  • 确认 Honcho 服务器能访问 api.openai.com（可能需要代理）。

7.5 Bot 被限流

现象：发送大量消息后 Bot 返回 429 错误。

解决：

  • 实现发送队列和退避重试。
  • 避免在短时间内对同一用户发送多条消息。

7.6 消息重复处理

原因：Telegram 重试机制导致同一消息多次发送到 Webhook。

解决 ：在 Honcho 中实现消息去重（基于 update_id 或 message_id 缓存）。

7.7 命令菜单不显示

原因 ：未设置 /setcommands 或设置后未生效。

解决 ：在 BotFather 中执行 /setcommands，按格式发送：

复制代码 
start - 开始对话
help - 显示帮助
reset - 重置记忆

8. 总结：最流畅移动端入口

8.1 核心优势回顾

  • 零门槛：Telegram 用户量大，Bot 创建免费且简单。
  • 多媒体支持：语音、图片、文件皆可收发。
  • 多端同步：手机、电脑、网页无缝切换。
  • 隐私可控：限制用户、群组，数据自托管。
  • 与 Honcho 深度集成：利用用户建模、长期记忆、工具调用。

8.2 部署检查清单

  • 通过 @BotFather 创建 Bot，保存 Token
  • 获取自己的 Telegram User ID
  • 在 Honcho 配置文件中添加 telegram 节
  • 设置 Webhook URL（确保 HTTPS 公网可达）
  • 启动 Honcho 服务，验证 Webhook 状态
  • 发送 /start 测试基本功能
  • （可选）配置语音识别和合成
  • 设置 allowed_users 限制访问
  • 在手机上置顶 Bot，开始使用

8.3 最佳实践建议

  1. 使用环境变量存储 Token ：不要在配置文件中明文写入，用 ${TELEGRAM_BOT_TOKEN} 引用。
  2. 实现日志记录：记录用户消息和 Bot 回复，方便调试。
  3. 设置超时：Honcho 处理消息可能耗时较长（调用 LLM），Telegram 默认超时 30 秒。复杂任务应异步处理（先回复"处理中..."）。
  4. 定期更新 Webhook：如果域名或证书变更，重新设置 Webhook。
  5. 监控成本：语音识别和 TTS 可能产生额外费用，设置每日限额。

8.4 与其他平台的简单对比

平台 优点 缺点
Telegram 免费、多端、语音原生、Bot API 完善 国内需代理
微信 国内用户多 个人号有封号风险，公众号复杂
Discord 社区活跃，支持 Slash Command 移动端较重
Slack 企业集成好 免费版限制
网页/APP 完全可控 需要自己开发前端

8.5 最终流程图：完整消息处理链路

你的服务器
Telegram 服务
用户端
发送文字/语音
POST Webhook
有语音
文本
用户ID
画像
Prompt
回复
需要语音
音频
响应
HTTP 200
发送消息
手机 Telegram
Telegram Bot API
Nginx/Caddy HTTPS
Honcho 服务

/telegram/webhook
Hermes 画像引擎
LLM API
Whisper STT
TTS 服务

8.6 一句话总结

把 Honcho 智能体接入 Telegram Bot，你就拥有了一个随身携带、能听懂语音、记住你习惯的 AI 助手------这是目前最流畅、最私密的移动端入口。

下一步：完成本文的配置后，试试让你的 Bot 帮你查天气、记笔记、写代码片段。如果遇到问题，查阅 Honcho 官方文档或 Telegram Bot API 文档。

附录：扩展阅读与资源

版权声明：本文为原创技术博客，采用 CC BY-NC-SA 4.0 许可。欢迎转载，请保留出处。有任何 Telegram Bot 接入问题，欢迎评论区交流。

相关推荐
乐迪信息1 小时前
乐迪信息：实时预警，秒级响应：船舶AI异常行为检测算法
大数据·人工智能·算法·安全·目标跟踪
用AI赚一点1 小时前
AI落地不是造大模型：从概念到落地的核心差异
人工智能·深度学习·机器学习
littleM1 小时前
深度拆解 HermesAgent（五）：记忆系统与用户建模
jvm·人工智能·架构·ai编程
红色星际1 小时前
进军具身机器人和Robotaxi的智驾公司
大数据·人工智能·机器人
Bruce_Liuxiaowei1 小时前
《轻量化制播系统技术应用指南（2026版）》解读：县级融媒体的“减负增效“新路径
大数据·人工智能·媒体
IT届小白1 小时前
Medical-Qwen3-14B基于Ollama内网私有化部署方案
人工智能·大模型
2601_956139421 小时前
文旅行业品牌全案公司哪家强
大数据·人工智能·python
生活观察站1 小时前
中文在线亮相横琴—澳门国际数字艺术博览会国际数字创意论坛：AI漫剧打开内容创作新想象
大数据·人工智能
@PHARAOH1 小时前
WHAT - 大语言模型 Memory 系统设计入门
人工智能·语言模型·自然语言处理
热门推荐
01GitHub 镜像站点022026年4月AI大事件深度解读：大模型竞争进入“深水区“03Codex 接入 DeepSeek API 完整配置文档04近期有什么ai的新消息，新动态？ 2026.4月05【AI】2026 年具身智能模型和世界模型总结062026年AI编程工具终极横评：Cursor vs Claude Code vs Copilot07实测可用｜小米 MiMo 百万亿 Token 免费领，开发者速冲08在Windows 11上安装Docker的踩坑记录09裂开！ChatGPT 居然开始要手机号验证，附详细解决方法10零基础教你claude code 接入 deepseek V4