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

企鹅的蚂蚁

216人浏览 · 2026-07-31 14:53:02

企鹅的蚂蚁 · 2026-07-31 14:53:02 发布

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 前置准备

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

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 机器人支持三级语音转写优先级：

QQ 内置 ASR（腾讯，免费，自动优先）
配置的 STT 提供商（config.yaml 中的 stt 配置）
跳过（不转写）

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 启动交互式设置向导

AI Agent技术社区

Agent 垂直技术社区，欢迎活跃、内容共建。

更多推荐

AI Agent 对比和选型

AI Agent技术社区

2026企业微信AI Agent实测：7款技术方案对比

会话审计、敏感词管理、聊天质检、敏感行为识别、舆情、属性、词频及竞品分析覆盖服务风险；线索公海、客户、产品、商机、订单、回款、发票和业绩目标则连接销售全过程。快创助手负责快速建运营任务，策略生成把目标拆成方案，智能客服回答系统使用咨询，数据报表处理自然语言查数，AI洞察联合标签、订单和会话分析客户。我们设计了客户筛选、订单关联、销售交接、会话质检和异常恢复任务，配合技术访谈与行业公开资料复核。准备

AI Agent技术社区

如何构建 AI Agent Harness 2.0，让 AI Agent 比 99% 的开发者更工程化

AI Agent技术社区

所有评论(0)

查看更多评论

企鹅的蚂蚁

@weixin_41533008

已为社区贡献2条内容

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

企鹅的蚂蚁

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

目录

1. 安装与快速开始

关键路径

2. 第三方模型配置

2.1 交互式选择模型

2.2 手动配置模型

2.3 常用提供商一览

2.4 模型别名

2.5 Fallback 链

2.6 凭证池（多 Key 轮换）

3. Codex OAuth 登录

3.1 登录流程

3.2 设为默认模型

3.3 Nous Portal 登录

3.4 常见问题

4. 图像生成 (ImageGen) 配置

4.1 可用提供商

4.2 交互式配置

4.3 手动配置

4.4 FAL 托管的 GPT Image 模型

4.5 调试

4.6 验证当前配置

5. QQ 机器人配置

5.1 前置准备

5.2 配置方式

5.3 启动网关

5.4 QQ 语音转文字

5.5 QQ 平台工具集配置

6. 微信 (WeChat) 配置

6.1 配置流程

6.2 手动配置

6.3 查看微信连接状态

6.4 注意事项

7. 其他消息平台

7.1 Telegram

7.2 Discord

7.3 Slack

7.4 钉钉/飞书/企业微信

7.5 平台总览

8. 工具集 (Toolsets) 管理

8.1 交互式管理

8.2 命令行管理

8.3 常用工具集

8.4 为特定平台配置工具集

9. MCP 服务器接入

9.1 安装 MCP SDK

9.2 配置 MCP 服务器

9.3 管理 MCP 服务器

10. 语音配置 (STT/TTS)

10.1 STT（语音转文字）

10.2 TTS（文字转语音）

10.3 语音聊天模式

11. 配置文件速查

11.1 config.yaml 常用配置段

11.2 完整配置参考

12. 常用运维指令

12.1 会话管理

12.2 定时任务

12.3 网关管理

12.4 Profile（多配置隔离）

12.5 日志与调试

12.6 其他实用工具

附录：环境变量速查

所有评论(0)

温馨提示：您尚未绑定手机号

企鹅的蚂蚁