📱 Hermes Agent Telegram Bot 配置指南 (Docker + 阿里云百炼)

✅ 本文亮点

Docker 容器化部署 Hermes Agent
Telegram Bot 完整配置流程
阿里云百炼 (Bailian) API 集成
解决 401 认证错误的终极方案
代理配置（国内访问 Telegram）

📋 前置条件

Docker + Docker Compose 已安装
Telegram 账号
阿里云百炼 API Key（原 DashScope/Coding Plan）
可用的 HTTP/HTTPS 代理（用于访问 Telegram API）

🚀 步骤 1：创建 Telegram Bot

在 Telegram 搜索 @BotFather
发送 /newbot
设置 Bot 名称（如 "Johnny Assistant"）
设置 Bot 用户名（必须以 bot 结尾，如 johnny_helper_bot）
BotFather 会返回 API Token，格式类似：
```
123456789:ABCdefGHIjklMNOpqrSTUvwxYZ
```

⚠️ 安全提醒

Bot Token 相当于密码！不要泄露给他人，不要提交到 Git。如果泄露，立即在 BotFather 中使用 /revoke 重新生成。

📝 步骤 2：获取你的 Telegram User ID

Hermes 使用 User ID 限制访问权限，防止陌生人使用你的 Bot。

在 Telegram 搜索 @userinfobot 或 @get_id_bot
发送任意消息，它会回复你的 User ID（数字，如 8128834338）
保存这个数字

🐳 步骤 3：创建 Hermes 数据目录

mkdir -p ~/hermes-agent/data
cd ~/hermes-agent

⚙️ 步骤 4：创建配置文件

4.1 创建 config.yaml

cat > data/config.yaml << 'EOF'
llm:
  provider: openrouter
  model: qwen/qwen3.5-plus
  base_url: https://coding.dashscope.aliyuncs.com/v1
agent:
  name: Johnny
memory:
  enabled: true
channels:
  cli:
    enabled: true
gateway:
  enabled: true
model: qwen3.5-plus
EOF

4.2 创建 .env 文件

⚠️ 替换下面的占位符

YOUR_BOT_TOKEN → 你的 Telegram Bot Token
YOUR_USER_ID → 你的 Telegram User ID
YOUR_BAILIAN_API_KEY → 你的阿里云百炼 API Key
YOUR_PROXY_URL → 你的代理地址（如 192.168.1.100:7890）

cat > data/.env << 'EOF'
# API Keys (所有可能的变量名，确保兼容性)
OPENAI_API_KEY=YOUR_BAILIAN_API_KEY
OPENAI_BASE_URL=https://coding.dashscope.aliyuncs.com/v1
OPENROUTER_API_KEY=YOUR_BAILIAN_API_KEY
DASHSCOPE_API_KEY=YOUR_BAILIAN_API_KEY
DASHSCOPE_BASE_URL=https://coding.dashscope.aliyuncs.com/v1

# Telegram Bot Configuration
TELEGRAM_BOT_TOKEN=YOUR_BOT_TOKEN
TELEGRAM_ALLOWED_USERS=YOUR_USER_ID

# Proxy Configuration (中国大陆必需)
HTTP_PROXY=http://YOUR_PROXY_URL
HTTPS_PROXY=http://YOUR_PROXY_URL
NO_PROXY=localhost,127.0.0.1,192.168.0.0/16
EOF

🔧 步骤 5：修改 Hermes 源码（关键修复）

❗ 重要：解决 401 错误

Hermes 默认硬编码了 OpenRouter 的 URL，即使配置了 base_url 也会被忽略。需要修改源码。

启动临时容器修改源码：

docker run --rm -v ~/hermes-agent/data:/opt/data nousresearch/hermes-agent:latest \
  sed -i 's|https://openrouter.ai/api/v1|https://coding.dashscope.aliyuncs.com/v1|g' \
  /opt/hermes/hermes_constants.py

验证修改：

docker run --rm -v ~/hermes-agent/data:/opt/data nousresearch/hermes-agent:latest \
  grep "OPENROUTER_BASE_URL" /opt/hermes/hermes_constants.py

应该输出：

OPENROUTER_BASE_URL = "https://coding.dashscope.aliyuncs.com/v1"

🎯 步骤 6：启动 Johnny

docker run -d \
  --name johnny \
  --restart unless-stopped \
  -v ~/hermes-agent/data:/opt/data \
  -e OPENROUTER_API_KEY=YOUR_BAILIAN_API_KEY \
  -e OPENAI_BASE_URL=https://coding.dashscope.aliyuncs.com/v1 \
  -e HTTP_PROXY=http://YOUR_PROXY_URL \
  -e HTTPS_PROXY=http://YOUR_PROXY_URL \
  -e TELEGRAM_BOT_TOKEN=YOUR_BOT_TOKEN \
  -e TELEGRAM_ALLOWED_USERS=YOUR_USER_ID \
  nousresearch/hermes-agent:latest \
  gateway run

✅ 步骤 7：验证配置

查看日志：

docker logs johnny --tail 30

检查配置：

docker exec johnny hermes config show

应该看到：

◆ API Keys
  OpenRouter     sk-s...xxxx  ✓
  ...
◆ Model
  Model:        qwen3.5-plus
  Base URL:     https://coding.dashscope.aliyuncs.com/v1

📱 步骤 8：测试 Telegram Bot

在 Telegram 搜索你的 Bot 用户名（如 @johnny_helper_bot）
点击 Start 或发送 /start
发送 "你好" 或 "hello" 测试
应该收到 AI 回复！

💡 可选配置

群聊支持：在 BotFather 中关闭隐私模式（Bot Settings → Group Privacy → Turn off）
自定义命令：在 BotFather 中使用 /setcommands 设置命令菜单
Bot 头像：在 BotFather 中使用 /setuserpic 上传头像

🔍 故障排查

问题 1：401 认证错误

⚠️  API call failed (attempt 1/3): AuthenticationError [HTTP 401]
   🔌 Provider: openrouter  Model: qwen3.5-plus
   🌐 Endpoint: https://openrouter.ai/api/v1

原因：Hermes 使用了默认的 OpenRouter URL，而不是配置的 DashScope URL。

解决：按照步骤 5 修改 hermes_constants.py。

问题 2：Telegram 无法连接

WARNING gateway.platforms.telegram_network: [Telegram] Primary api.telegram.org connection failed

原因：代理配置错误或代理不可用。

解决：

检查代理是否可用：curl -x http://YOUR_PROXY_URL https://api.telegram.org
确保容器环境变量正确：docker exec johnny env | grep PROXY
重启容器：docker restart johnny

问题 3：API Key 未识别

◆ API Keys
  OpenRouter     (not set)

原因：.env 文件权限问题或容器未正确加载环境变量。

解决：

检查 .env 文件权限：chmod 600 data/.env
在 docker run 时直接传入环境变量（见步骤 6）
重启容器

📊 配置总结

组件	配置值
Provider	`openrouter`（但使用 DashScope URL）
Model	`qwen/qwen3.5-plus`
Base URL	`https://coding.dashscope.aliyuncs.com/v1`
API Key 变量	`OPENROUTER_API_KEY`（Hermes 要求）
Telegram Token	`TELEGRAM_BOT_TOKEN`
允许的用户	`TELEGRAM_ALLOWED_USERS`（逗号分隔多个 ID）

🎉 完成！

现在你可以在 Telegram 上随时随地和 Johnny 聊天了！🚀