Hermes Agent 配置指南：从模型接入到多平台部署

Hermes Agent 是 Nous Research 开源的 AI Agent 框架，支持 CLI、桌面端、Web Dashboard 以及 20+ 消息平台（Telegram、Discord、QQ、微信等）。本文整理了日常使用中最常碰到的配置指令，涵盖模型接入、图像生成、OAuth 登录、QQ/微信机器人部署等场景。

目录

1. 安装与快速开始

# 一键安装（自动配置 uv、Python、venv 和启动器）
curl -fsSL https://hermes-agent.nousresearch.com/install.sh | bash

# 交互式聊天（默认 CLI 模式）
hermes

# 单次查询
hermes chat -q "什么是量子计算？"

# 设置向导（交互式引导配置模型、TTS、终端等）
hermes setup

# 健康检查
hermes doctor

关键路径

路径 说明
~/.hermes/config.yaml 主配置文件（只放设置，不放密钥）
~/.hermes/.env API 密钥和秘密
~/.hermes/skills/ 已安装的 skills
~/.hermes/auth.json OAuth 令牌和凭证池
~/.hermes/logs/ 网关和错误日志
~/.hermes/state.db 会话存储（SQLite）

⚠️ 重要原则：密钥放 .env，配置放 config.yaml。永远不要在 config.yaml 里写 API key。

2. 第三方模型配置

Hermes 支持 35+ 模型提供商，包括 OpenRouter、Anthropic、OpenAI、Google、DeepSeek、xAI、小米等。

2.1 交互式选择模型

# 打开模型选择器（推荐新手使用）
hermes model

# 或通过设置向导
hermes setup model

2.2 手动配置模型

# 设置默认模型和提供商
hermes config set model.default deepseek-chat
hermes config set model.provider deepseek

# 设置自定义 base_url（用于私有部署或兼容 API）
hermes config set model.base_url https://your-api.com/v1

# 设置 API Key（密钥放 `.env`，不要放 `config.yaml`）
echo 'DEEPSEEK_API_KEY=sk-xxxxxxxx' >> ~/.hermes/.env

2.3 常用提供商一览

提供商 环境变量 说明
OpenRouter OPENROUTER_API_KEY 聚合 200+ 模型
Anthropic ANTHROPIC_API_KEY Claude 系列
Google Gemini GOOGLE_API_KEY Gemini 系列
DeepSeek DEEPSEEK_API_KEY DeepSeek V3/R1
xAI XAI_API_KEY Grok 系列
小米 XIAOMI_API_KEY MiMo 系列
通义千问 DASHSCOPE_API_KEY Qwen 系列
智谱 GLM GLM_API_KEY GLM/CogView
HuggingFace HF_TOKEN 开源模型推理
Ollama（本地） 无需 Key 需设置 base_url

2.4 模型别名

在 config.yaml 中定义快捷别名，之后用 /model fav 即可切换：

model:
  aliases:
    fav: openrouter/anthropic/claude-sonnet-4.6
    deep: deepseek/deepseek-chat
    qwen: dashscope/qwen-max

CLI 方式添加：

hermes config set model.aliases.fav openrouter/anthropic/claude-sonnet-4.6

内置别名：sonnet、opus、gpt、gemini、deepseek、grok、qwen、mimo 等。

2.5 Fallback 链

主模型不可用时自动切换到备用模型：

hermes fallback add anthropic/claude-sonnet-4.6
hermes fallback add openrouter/deepseek/deepseek-chat
hermes fallback list    # 查看当前链
hermes fallback remove  # 移除

2.6 凭证池（多 Key 轮换）

同一提供商可以配置多个 API Key，系统自动轮换、跳过耗尽的 Key：

hermes auth              # 交互式凭证管理器
hermes auth add          # 添加凭证
hermes auth list         # 查看所有凭证
hermes auth status       # 查看凭证状态

3. Codex OAuth 登录

openai-codex 提供商使用 OAuth 设备码流程登录，不需要 API Key。登录后可用于聊天模型和图像生成。

3.1 登录流程

# 触发 Codex OAuth 登录
hermes auth add openai-codex

系统会显示一个设备码和 URL，在浏览器中打开 URL 并输入设备码完成授权。登录成功后令牌自动保存到 ~/.hermes/auth.json。

3.2 设为默认模型

hermes config set model.provider openai-codex
hermes config set model.default gpt-5    # Codex 支持的模型名

3.3 Nous Portal 登录

Nous Portal 提供订阅制的工具网关（图像生成、网页搜索等）：

hermes auth add nous
# 或使用 Portal 快速设置
hermes portal

3.4 常见问题

Codex OAuth 轮询失败（SSL / 代理问题）

如果你在代理环境下遇到 SSL handshake failed，需要确保代理使用 CONNECT 隧道而非 MITM：

# 检查代理配置
echo $HTTPS_PROXY

# 临时绕过代理
unset HTTPS_PROXY
hermes auth add openai-codex

4. 图像生成 (ImageGen) 配置

Hermes 内置图像生成工具，支持多个后端提供商。

4.1 可用提供商

提供商 认证方式 可用模型
openai-codex Codex OAuth GPT-Image-2 (Low/Medium/High)
openai OPENAI_API_KEY GPT-Image-1
fal FAL_KEY 所有 fal-ai/* 模型
nous (网关) Nous 订阅 所有 FAL 托管模型
xai XAI OAuth / API Key Grok Imagine
krea KREA_API_KEY Krea 2
deepinfra DEEPINFRA_API_KEY 多模型

4.2 交互式配置

# 打开工具配置界面，选择 image_gen → 选择提供商 → 选择模型
hermes tools

# 如果已经配置过但想重新选择，需要先禁用再启用
hermes tools disable image_gen
hermes tools enable image_gen

4.3 手动配置

# 使用 Codex OAuth（不需要额外 API Key）
hermes config set image_gen.provider openai-codex
hermes config set image_gen.model gpt-image-2-medium
hermes config set image_gen.use_gateway false

# 使用 FAL 直连
hermes config set image_gen.provider fal
hermes config set image_gen.model fal-ai/fast-sdxl
echo 'FAL_KEY=your-fal-key' >> ~/.hermes/.env

# 使用 Nous 订阅网关（FAL 托管，通过 Nous 计费）
hermes config set image_gen.provider nous
hermes config set image_gen.model fal-ai/gpt-image-2
hermes config set image_gen.use_gateway true

4.4 FAL 托管的 GPT Image 模型

模型 速度 特点 价格
fal-ai/gpt-image-1.5 ~15s 提示词遵循度高 $0.034/张
fal-ai/gpt-image-2 ~20s SOTA 文字渲染、中文支持、照片级真实感 $0.04–0.06/张

4.5 调试

export IMAGE_TOOLS_DEBUG=true
# 日志保存到 ./logs/image_tools_debug_<session_id>.json

4.6 验证当前配置

hermes config get image_gen
# 输出示例：
# use_gateway: false
# provider: openai-codex
# model: gpt-image-2-medium

5. QQ 机器人配置

Hermes 通过 QQ 官方 Bot API（v2） 连接 QQ 平台，支持私聊、群聊、语音转文字等。

5.1 前置准备

  1. 前往 QQ 开放平台 创建机器人应用
  2. 获取 AppID 和 ClientSecret
  3. 在机器人管理后台开启所需的权限（消息内容意图等）

5.2 配置方式

方式一：环境变量

echo 'QQ_APP_ID=your-app-id' >> ~/.hermes/.env
echo 'QQ_CLIENT_SECRET=your-secret' >> ~/.hermes/.env

方式二：config.yaml

channels:
  qqbot:
    enabled: true
    extra:
      app_id: "your-app-id"
      client_secret: "your-secret"
      markdown_support: true        # 启用 QQ Markdown（msg_type 2）
      dm_policy: "pairing"          # 私聊策略：open | allowlist | disabled | pairing
      allow_from: ["openid_1"]      # 私聊白名单
      group_policy: "pairing"      # 群聊策略
      group_allow_from: ["group_openid_1"]  # 群聊白名单

方式三：扫码配置（推荐）

Hermes 支持扫码一键配置 QQ 机器人：

hermes gateway setup
# 选择 QQ Bot → 扫码 → 自动完成配置

5.3 启动网关

# 启动所有已配置的消息平台
hermes gateway run

# 安装为系统服务（开机自启）
hermes gateway install
hermes gateway start

# 查看状态
hermes gateway status

# 查看日志
hermes logs -f

5.4 QQ 语音转文字

QQ 机器人支持三级语音转写优先级：

  1. QQ 内置 ASR（腾讯，免费，自动优先）
  2. 配置的 STT 提供商（config.yaml 中的 stt 配置）
  3. 跳过（不转写）
channels:
  qqbot:
    extra:
      stt:
        provider: "zai"           # zai (GLM-ASR), openai (Whisper)
        baseUrl: "https://open.bigmodel.cn/api/coding/paas/v4"
        apiKey: "your-key"
        model: "glm-asr"

5.5 QQ 平台工具集配置

可以为 QQ 平台单独配置可用的工具集：

hermes tools
# 交互式界面中选择 qqbot 平台，勾选/取消工具

在 config.yaml 中也可以直接指定：

toolsets:
  qqbot:
    - terminal
    - file
    - web
    - image_gen
    - vision
    - memory
    - skills
    - tts

6. 微信 (WeChat) 配置

Hermes 通过腾讯 iLink Bot API 连接微信个人账号。

6.1 配置流程

# 启动网关设置向导，选择 WeChat
hermes gateway setup
# 选择 WeChat → 扫码登录 → 自动完成配置

6.2 手动配置

channels:
  weixin:
    enabled: true
    extra:
      # iLink Bot Token（扫码后自动获取）
      token: "your-ilink-token"

6.3 查看微信连接状态

hermes status | grep -i weixin
# 输出示例：Weixin:o9cq80_HJ1gUXEHrFE6JmJfV4mk4@im.wechat

6.4 注意事项

  • 微信通过 iLink 长轮询接收消息，需要保持网关进程运行
  • 出站消息必须回传最新的 context_token（Hermes 自动处理）
  • 媒体文件通过 AES-128-ECB 加密 CDN 协议传输
  • iLink 有 30 秒速率限制，批量操作时需注意间隔

7. 其他消息平台

Hermes 支持 20+ 消息平台，配置方式大同小异：

7.1 Telegram

# 1. 通过 @BotFather 创建 Bot，获取 Token
# 2. 配置
echo 'TELEGRAM_BOT_TOKEN=your-token' >> ~/.hermes/.env
hermes gateway setup    # 选择 Telegram

7.2 Discord

# 1. 在 Discord Developer Portal 创建 Bot
# 2. 开启 Message Content Intent（必须！）
echo 'DISCORD_BOT_TOKEN=your-token' >> ~/.hermes/.env
hermes gateway setup    # 选择 Discord

7.3 Slack

echo 'SLACK_BOT_TOKEN=xoxb-xxx' >> ~/.hermes/.env
echo 'SLACK_APP_TOKEN=xapp-xxx' >> ~/.hermes/.env
# 需要订阅 message.channels 事件才能在公开频道响应

7.4 钉钉/飞书/企业微信

hermes gateway setup    # 选择对应平台，按向导操作

7.5 平台总览

平台 协议 备注
Telegram Bot API 最成熟
Discord Bot API 需开启 Message Content Intent
Slack Socket Mode 需订阅 message.channels
QQ 官方 Bot API v2 支持扫码配置
微信 iLink Bot API 扫码登录
WhatsApp Baileys / Business Cloud API 两种模式
Signal signal-cli 需要额外安装
Teams Microsoft Graph 企业版
钉钉 企业内部应用 Webhook
飞书 企业自建应用 Webhook
Matrix Matrix Client-SDK 开源协议
Email IMAP/SMTP 邮件集成

8. 工具集 (Toolsets) 管理

8.1 交互式管理

hermes tools    # 打开交互式工具配置界面（curses UI）

8.2 命令行管理

hermes tools list                       # 查看所有工具及状态
hermes tools enable image_gen           # 启用图像生成
hermes tools disable computer_use       # 禁用桌面控制
hermes tools enable browser --force     # 强制启用

8.3 常用工具集

工具集 功能
web 网页搜索 + 内容提取
browser 浏览器自动化
terminal Shell 命令执行
file 文件读写/搜索/补丁
image_gen 图像生成
video_gen 视频生成
vision 图像分析
tts 文字转语音
computer_use 桌面 GUI 控制
memory 跨会话记忆
delegation 子 Agent 任务委派
cronjob 定时任务管理
skills Skill 管理

⚠️ 工具变更在 /reset（新会话）后生效，不会在当前对话中生效（保护 prompt cache）。

8.4 为特定平台配置工具集

hermes tools
# 在交互式界面中选择平台（cli/telegram/qqbot/discord...），为每个平台独立配置工具

9. MCP 服务器接入

Hermes 内置 MCP 客户端，可以连接任何 MCP 服务器并将其工具作为一等公民使用。

9.1 安装 MCP SDK

pip install mcp

9.2 配置 MCP 服务器

在 ~/.hermes/config.yaml 中添加：

mcp_servers:
  # stdio 传输（本地命令）
  filesystem:
    command: "npx"
    args: ["-y", "@modelcontextprotocol/server-filesystem", "/home/user/documents"]
    timeout: 30

  github:
    command: "npx"
    args: ["-y", "@modelcontextprotocol/server-github"]
    env:
      GITHUB_PERSONAL_ACCESS_TOKEN: "ghp_xxxxxxxxxxxx"

  # HTTP 传输（远程服务器）
  company_api:
    url: "https://mcp.mycompany.com/v1/mcp"
    headers:
      Authorization: "Bearer sk-xxxxxxxx"
    timeout: 180

9.3 管理 MCP 服务器

hermes mcp list             # 列出已配置的 MCP 服务器
hermes mcp add NAME --url URL           # 添加 HTTP 服务器
hermes mcp add NAME --command "npx ..." # 添加 stdio 服务器
hermes mcp test NAME        # 测试连接
hermes mcp remove NAME     # 移除
hermes mcp catalog          # 浏览官方目录
hermes mcp install NAME    # 从目录安装

工具命名规则：mcp_{server_name}_{tool_name}，例如 mcp_github_list_issues。

10. 语音配置 (STT/TTS)

10.1 STT（语音转文字）

stt:
  enabled: true
  provider: local    # local | groq | openai | mistral | elevenlabs | deepinfra
  local:
    model: base      # tiny, base, small, medium, large-v3

自动检测优先级：local faster-whisper → Groq → OpenAI → Mistral。

# 安装本地 Whisper（免费）
pip install faster-whisper

10.2 TTS（文字转语音）

tts:
  provider: edge     # edge | elevenlabs | openai | minimax | mistral | gemini | piper | kittentts
提供商 环境变量 免费？
Edge TTS（默认） 无需 ✅ 免费
ElevenLabs ELEVENLABS_API_KEY 免费额度
OpenAI VOICE_TOOLS_OPENAI_KEY 付费
MiniMax MINIMAX_API_KEY 付费
Gemini GOOGLE_API_KEY 免费额度
Piper / KittenTTS 无需 ✅ 本地免费

10.3 语音聊天模式

在聊天中使用斜杠命令：

/voice on       # 语音对话模式（语音输入 + 语音回复）
/voice tts      # 始终语音回复
/voice off      # 关闭语音

11. 配置文件速查

11.1 config.yaml 常用配置段

# 模型配置
model:
  default: deepseek-chat
  provider: deepseek
  base_url: https://api.deepseek.com/v1   # 自定义端点

# Agent 行为
agent:
  max_turns: 90              # 最大工具调用轮次
  tool_use_enforcement: auto # 工具使用策略
  reasoning_effort: medium   # 推理深度

# 终端
terminal:
  backend: local             # local | docker | ssh
  timeout: 180               # 命令超时（秒）

# 显示
display:
  skin: default              # 主题皮肤
  interface: cli             # cli | tui
  language: zh               # 界面语言
  show_cost: true            # 显示费用

# 安全
approvals:
  mode: smart                # smart | manual | off

# 记忆
memory:
  memory_enabled: true
  user_profile_enabled: true

# 压缩（长对话自动压缩）
compression:
  enabled: true
  threshold: 0.50            # 上下文使用率触发压缩
  target_ratio: 0.20         # 压缩目标比率

# 子 Agent 委派
delegation:
  max_concurrent_children: 3
  max_iterations: 50
  max_spawn_depth: 1

# 定时任务
# 通过 hermes cron 或 cronjob 工具管理，不在 config.yaml 中配置

11.2 完整配置参考

hermes config show          # 查看当前完整配置
hermes config edit          # 用编辑器打开配置文件
hermes config get section   # 查看某个配置段
hermes config set KEY VAL   # 设置配置项
hermes config unset KEY     # 删除配置项
hermes config check         # 检查缺失的配置段
hermes config path          # 显示配置文件路径
hermes config env-path      # 显示 .env 文件路径

12. 常用运维指令

12.1 会话管理

hermes sessions list            # 列出所有会话
hermes sessions browse          # 浏览会话
hermes sessions rename ID NAME  # 重命名会话
hermes sessions export OUT      # 导出会话
hermes sessions stats           # 统计信息
hermes --continue               # 恢复最近的会话
hermes --resume SESSION_ID      # 恢复指定会话

12.2 定时任务

hermes cron list                # 列出定时任务
hermes cron create "0 9 * * *"  # 创建（每天 9:00）
hermes cron pause ID            # 暂停
hermes cron resume ID           # 恢复
hermes cron run ID              # 立即执行一次
hermes cron remove ID           # 删除

12.3 网关管理

hermes gateway run              # 前台运行网关
hermes gateway install          # 安装为 systemd 服务
hermes gateway start            # 启动服务
hermes gateway stop             # 停止服务
hermes gateway restart          # 重启
hermes gateway status           # 查看状态
hermes gateway setup            # 设置向导（添加新平台）

12.4 Profile（多配置隔离）

hermes profile list             # 列出所有 profile
hermes profile create work      # 创建新 profile
hermes profile use work         # 切换到 work profile
hermes profile delete work      # 删除

每个 Profile 独立拥有 skills、plugins、cron、memories 和 config。

12.5 日志与调试

hermes logs                     # 查看日志
hermes logs -f                  # 实时跟踪
hermes logs errors              # 只看错误日志
hermes doctor                   # 全面健康检查
hermes doctor --fix             # 自动修复
hermes status                   # 组件状态
hermes status --all             # 详细状态

12.6 其他实用工具

# 桌面应用
hermes desktop                  # 启动原生桌面应用（Electron）

# Web 管理面板
hermes dashboard                # 启动 Web Dashboard

# 本地 OpenAI 兼容代理
hermes proxy                    # 将 OAuth 提供商暴露为 OpenAI API

# Skills 管理
hermes skills list              # 列出已安装的 Skills
hermes skills browse            # 浏览 Skill 目录
hermes skills install NAME      # 安装 Skill

# 主题切换
hermes skin list                # 列出可用皮肤
hermes skin use synthwave       # 切换皮肤

# 更新
hermes update                   # 更新到最新版本

附录：环境变量速查

变量 用途
OPENROUTER_API_KEY OpenRouter 聚合平台
ANTHROPIC_API_KEY Claude 模型
OPENAI_API_KEY OpenAI 模型
GOOGLE_API_KEY Gemini 模型
DEEPSEEK_API_KEY DeepSeek 模型
XAI_API_KEY xAI Grok 模型
XIAOMI_API_KEY 小米 MiMo 模型
DASHSCOPE_API_KEY 通义千问
GLM_API_KEY 智谱 GLM
HF_TOKEN HuggingFace
FAL_KEY FAL.ai 图像/视频
KREA_API_KEY Krea 图像
TELEGRAM_BOT_TOKEN Telegram Bot
DISCORD_BOT_TOKEN Discord Bot
SLACK_BOT_TOKEN Slack Bot
QQ_APP_ID QQ 机器人 App ID
QQ_CLIENT_SECRET QQ 机器人密钥
ELEVENLABS_API_KEY ElevenLabs TTS
VOICE_TOOLS_OPENAI_KEY OpenAI 语音
GROQ_API_KEY Groq（STT/模型）
FIRECRAWL_API_KEY Firecrawl 网页抓取

更多信息

  • 官方文档：https://hermes-agent.nousresearch.com/docs/
  • GitHub：https://github.com/NousResearch/hermes-agent
  • 在终端中运行 hermes --help 查看所有命令
  • 运行 hermes setup 启动交互式设置向导
# 人工智能 # 运维
Logo
智能体开发者社区

中国智能体开发者社区，聚焦智能体与大模型开发，提供前沿资讯、实用工具链、开源项目及行业案例。通过技术沙龙、开发者大赛等活动，促进经验交流与协作，助力开发者快速构建创新智能应用。

更多推荐

cover

2026年AI Agent开发完整学习路线 | 后端工程师转型指南 | 从零到手搓生产级多Agent系统

avatar 智能体开发者社区

AI Agent 大模型开发技术框架选型指南

LangChain 是目前认知度最高的大模型应用开发生态之一，提供统一的模型接口、Prompt、工具调用、文档加载、文本切分、向量存储、检索器、中间件和 Agent 抽象。当前官方将 LangChain 定位为快速构建 Agent 的高层框架，并将复杂、可控的底层编排交给 LangGraph。

avatar 智能体开发者社区
cover

你的 AI Agent 正在被攻陷，而大多数团队还蒙在鼓里

avatar 智能体开发者社区