Hermes-Agent 是 Nous Research 开源的个人 AI 助手，本地跑一个 Gateway 服务，通过 channel 接入 Telegram / Discord / WhatsApp / Slack / Signal 等 20+ IM 平台，搭配 LiteLLM 自动支持 OpenAI / Anthropic / MiniMax 等几十家模型 provider。CLI、Telegram、Web UI 都能用同一套 memory / skills / sessions。

相比 Claude Code --channels 的官方方案（详见踩坑记录：第三方 base URL 直接拒接），Hermes-Agent 在国内第三方代理 + Telegram bot 的场景下能直接 work。

安装

一、前置依赖

• Python 3.11+ （Hermes 自带 venv）
• Node.js 22.19+ （可选，chat UI / Canvas 用）
• brew install uv （macOS）

二、一键安装

# 推荐：交互式，向导会带过 provider / channel / skills 全套配置
curl -fsSL https://hermes-agent.nousresearch.com/install.sh | bash

# 静默安装：跳过 setup 向导，不下载内置 skills（自定义更轻量）
curl -fsSL https://hermes-agent.nousresearch.com/install.sh | bash -s -- --non-interactive --skip-setup --no-skills

装完之后：

• 配置：~/.hermes/config.yaml
• 密钥：~/.hermes/.env
• 代码：~/.hermes/hermes-agent/
• skills 仓库：~/.hermes/skills/

三、查看版本与状态

hermes --version
hermes doctor        # 自检：Python / SSL / 配置 / 鉴权
hermes gateway status

配置 model provider

Hermes 通过 LiteLLM provider 注册表覆盖 MiniMax / 智谱 / OpenRouter / 本地 Ollama 等几十家。下面以国内常用的 MiniMax（minimaxi） 为例。

1. 编辑 ~/.hermes/config.yaml

model:
  default: "MiniMax-M3"
  provider: "minimax-cn"

model_providers:
  - name: minimax-cn
    base_url: "https://api.minimaxi.com/v1"
    api_key_env: "MINIMAX_CN_API_KEY"
    models:
      - id: MiniMax-M3
        context_window: 200000
        max_tokens: 8192
        cost_per_million_input: 0
        cost_per_million_output: 0

minimax-cn provider 是 Hermes-Agent 内置的一等公民，写法与 minimax（海外）等价。如果你用 OpenRouter / 本地 vLLM，按 LiteLLM 文档 把 base_url 和 model id 改了即可。

2. 填 ~/.hermes/.env

MINIMAX_CN_API_KEY=sk-cp-xxxxxxxxxxxxxxxxxxxxxxxx
MINIMAX_CN_BASE_URL=https://api.minimaxi.com/v1

3. 验证 LLM 通路

hermes model chat "1+1=?"

正常会收到模型回的 “1+1=2。” 类回复。如果提示 401/403，多半是 base URL 缺前缀 /v1 或 key 没 export 出来。

Telegram 渠道

1. 申请 bot token

1. Telegram 搜索 @BotFather，发 /newbot 拿 token
2. 拿自己的 Telegram 数字 ID：私聊 @userinfobot，回显的那一串就是 TELEGRAM_ALLOWED_USERS

2. 写 ~/.hermes/.env

TELEGRAM_BOT_TOKEN=1234567890:AAxxxxxxxxxxxxxxxxxxxxxxxx
TELEGRAM_ALLOWED_USERS=646304977     # 你的 Telegram id，多用户用逗号分隔
TELEGRAM_DM_POLICY=open
TELEGRAM_GROUP_POLICY=allowlist

3. 国内代理（GFW 这关）

api.telegram.org 在国内不通。Clash Verge / ClashX Pro 一般 mixed-port 在 7897：

curl -x "http://127.0.0.1:7897" "https://api.telegram.org/bot<TOKEN>/getMe"
# → {"ok":true,"result":{"username":"yourbot",...}}

通了之后在 ~/.hermes/.env 加：

TELEGRAM_PROXY=http://127.0.0.1:7897
TELEGRAM_FALLBACK_IPS=149.154.166.110,149.154.167.220

TELEGRAM_FALLBACK_IPS 是 Telegram 官方稳定的 Bot API 解析 IP 段（OpenClaw 时代就 seed 在 config 里），绕开 dns.google / cloudflare-dns.com 的 DoH 在国内不通的问题。

4. 启动 Gateway

hermes gateway run
# 或前台 + 日志
hermes gateway run --foreground

正常输出 Gateway listening on http://127.0.0.1:8765，然后去 Telegram 给 bot 发消息就能收到回复。

权限：YOLO 模式

bypassPermissions / yolo / --yes 模式：跳过所有危险操作确认，等价于 Claude Code 的 bypassPermissions。

# 单次
hermes gateway run --yolo

# 持久化：写进 config
vim ~/.hermes/config.yaml

approvals:
  mode: 'off'        # off = yolo; on = 每次问; auto = 危险操作问，其余自动
permissions:
  defaultMode: bypassPermissions
  bypassAll: true

⚠️ 风险：等同于 rm -rf 类命令无确认。线上环境别开，本机开发随便开。

Skills & 插件

Hermes 把”技能”拆成 SKILL.md 文件，~/.hermes/skills/ 一份一份放。安装时 --no-skills 跳过的话想找回：

hermes skills install --bundled
hermes skills search telegram

启用插件（在 ~/.hermes/config.yaml）：

plugins:
  enabled:
    - github
    - telegram
    - apple-notes
    - himalaya

常用命令速查

调试

# 看 Gateway 日志
tail -f ~/.hermes/logs/gateway.log

# Telegram 渠道单独 verbose
hermes gateway run --debug telegram

# Python 环境坏掉的话
cd ~/.hermes/hermes-agent
python -m venv .venv --clear
source .venv/bin/activate
pip install -e .

碰到 app.initialize() hang / __pycache__ 覆盖源码类坑，先 find ~/.hermes/hermes-agent -name __pycache__ -type d -exec rm -rf {} + 把缓存清掉，再重启。

参考

• NousResearch/hermes-agent
• 官方安装脚本
• LiteLLM provider 列表
• Telegram Bot API
• anthropics/claude-plugins-official#783 — 为什么不用 Claude Code –channels