Hermes Agent 配置文件

安装完成后，所有配置和数据都保存在 ~/.hermes/ 下：

~/.hermes/
├── config.yaml      # 主配置文件（模型、工具、终端后端等）
├── .env             # API 密钥和 Secret（不提交到版本库）
├── auth.json        # OAuth 凭据（Nous Portal 等）
├── SOUL.md          # Agent 人格设定文件
├── memories/        # 持久记忆（MEMORY.md、USER.md）
├── skills/          # 技能文件（Agent 自动创建和管理）
├── cron/            # 定时任务配置
├── sessions/        # 网关会话记录
└── logs/            # 日志（API 密钥自动脱敏）

重要原则：

• Secrets（API 密钥、Token、密码） → 存入 .env
• 普通配置（模型、工具、终端后端等） → 存入 config.yaml
• 使用 hermes config set KEY VALUE 命令会自动路由到正确的文件

---

选择模型提供商

运行以下命令进入交互式选择：

hermes model

推荐路径：Nous Portal（最省事）

一个订阅覆盖 300+ 模型 + Tool Gateway（网页搜索、图片生成、TTS、云端浏览器），无需分别申请多个 API Key：

hermes setup

执行后通过 OAuth 登录，自动完成提供商配置和工具网关的开启。

常用提供商一览

提供商	特点	配置方式
Nous Portal	订阅制，300+ 模型，Tool Gateway	hermes setup --portal OAuth 登录
Anthropic	Claude 系列，Max 订阅可 OAuth	ANTHROPIC_API_KEY 或 OAuth
OpenAI Codex	ChatGPT OAuth，Codex 模型	hermes model → OAuth 设备码
OpenRouter	多提供商路由，200+ 模型	OPENROUTER_API_KEY
xAI Grok OAuth	SuperGrok / Premium+ 订阅，无需 API Key	hermes model → xAI Grok OAuth
GitHub Copilot	Copilot 订阅（GPT、Claude、Gemini）	hermes model → OAuth
Google AI Studio	Gemini 系列	GOOGLE_API_KEY
DeepSeek	DeepSeek 系列	DEEPSEEK_API_KEY
本地模型（Ollama）	完全本地，无费用	设置自定义 Base URL

模型上下文窗口要求：Hermes 要求模型至少支持 64,000 tokens 的上下文。使用本地模型时，确保启动参数中设置了足够的上下文大小（如 --ctx-size 65536）。

切换提供商

随时可以切换，无需修改任何代码：

hermes model

---

三种 Setup 模式

首次运行 hermes setup 时，会提示选择初始化模式：

模式一：Quick Setup（Nous Portal）

免费 OAuth 登录，自动配置模型 + Tool Gateway（网页搜索、图片生成、TTS、浏览器）。推荐新用户使用。

模式二：Full Setup

手动逐项配置提供商、工具集、消息平台等。适合有明确需求、自带 API Key 的用户。

模式三：Blank Slate（空白起点）

只保留最小运行集（提供商、文件工具、终端工具），其余一切关闭。适合需要精确控制 Agent 能力边界的高级用户。空白模式会显式写入配置，防止 hermes update 后自动开启新功能。

---

开启第一次对话

配置完成后，启动 Hermes：

hermes          # 经典 CLI 模式
hermes --tui    # 现代 TUI 模式（推荐，支持鼠标、弹窗等）

启动后会显示欢迎横幅，包含当前模型、可用工具和已加载技能的信息。

验证一切正常

用一个简单但具体的提示词测试：

检查我当前目录，告诉我里面有哪些文件，并识别主要的项目入口文件。

成功标志：

• 横幅正确显示你选择的模型/提供商
• Agent 正常响应，无报错信息
• 需要时能调用工具（终端、文件读取等）
• 对话可以持续超过一轮

验证会话恢复

确认跨会话连续性正常工作：

检查我当前目录，告诉我里面有哪些文件，并识别主要的项目入口文件。

---

TUI 界面基本操作

运行 hermes --tui 进入现代 TUI 模式后，常用操作：

操作	快捷键
发送消息	Enter
多行输入换行	Alt+Enter 或 Ctrl+J
打断 Agent 当前任务	直接输入新消息后 Enter
强制中断	Ctrl+C
查看所有命令	输入 / 触发自动补全

核心斜杠命令

命令	作用
/help	显示所有可用命令
/tools	列出当前启用的工具
/model	运行时切换模型
/memory	查看和管理 Agent 记忆
/skills	查看和管理技能
/save	保存当前对话
/new	开启新会话（保留当前设置）
/verbose	切换工具调用详细输出级别
/voice on	开启语音输入模式

---

终端执行后端配置

Hermes 支持六种终端执行环境，决定 Agent 的 Shell 命令在哪里运行：

后端	命令在哪里执行	隔离程度	适用场景
local（默认）	本机直接执行	无	开发、个人使用
docker	Docker 容器内	完全隔离	安全沙箱、CI/CD
ssh	远程服务器	网络边界	远程开发、高性能机器
modal	Modal 云沙箱	完全（云 VM）	临时云计算、评测
daytona	Daytona 工作区	完全（云容器）	托管云开发环境
singularity	Singularity 容器	命名空间隔离	HPC 集群、共享机器

切换到 Docker 后端（推荐用于生产）

hermes config set terminal.backend docker

或直接编辑 ~/.hermes/config.yaml：

terminal:
  backend: docker
  docker_image: "nikolaik/python-nodejs:python3.11-nodejs20"

安全说明：默认的 local 后端让 Agent 拥有和你相同的文件系统权限。如果你希望限制 Agent 的操作范围，切换到 docker 后端是最简单有效的方式。

---

工具集管理

Hermes 将 70+ 内置工具分组为 28 个工具集，可以按需启用或关闭：

hermes tools    # 打开可视化工具集管理界面（curses UI）

主要工具集

工具集	包含能力
filesystem	文件读写、目录操作
terminal	Shell 命令执行
web	网页搜索、内容提取
browser	完整浏览器自动化（需 Playwright）
code	代码执行（execute_code 工具）
vision	图片分析
audio	语音转文字、TTS
memory	记忆管理工具
skills	技能管理工具
mcp	MCP 服务器工具集（动态）

关闭某个工具集：该工具集从系统提示词中完全消失，不只是禁用——这样可以节省 Token，并防止 Agent 误用不该用的工具。

---

配置管理常用命令

# 查看当前完整配置
hermes config

# 用编辑器打开 config.yaml
hermes config edit

# 设置单个配置值（自动路由到正确文件）
hermes config set model anthropic/claude-sonnet-4-6
hermes config set terminal.backend docker
hermes config set OPENROUTER_API_KEY sk-or-...   # 自动存入 .env

# 检查是否有新版本引入的配置项未填写
hermes config check

# 交互式补全缺失配置
hermes config migrate

# 诊断所有配置问题
hermes doctor

# 更新到最新版本
hermes update

---

常见问题排查

问题一：hermes: command not found

# 刷新 Shell 配置
source ~/.bashrc   # 或 source ~/.zshrc

# 如果仍然找不到，检查 PATH
echo $PATH
# 确保 ~/.local/bin 在其中
export PATH="$HOME/.local/bin:$PATH"

问题二：API key not set / 模型无响应

# 重新配置提供商
hermes model

# 或直接设置 API Key
hermes config set OPENROUTER_API_KEY sk-or-...

问题三：回复为空或乱码

可能是提供商鉴权或模型选择有误：

# 重新选择模型
hermes model

# 全面诊断
hermes doctor

问题四：上下文窗口不足报错

Hermes 要求模型至少支持 64K Token 上下文。切换到支持更大上下文的模型，或在使用本地模型时增大上下文参数（如 Ollama：OLLAMA_NUM_CTX=65536）。

问题五：hermes --continue 找不到旧会话

# 查看所有会话
hermes sessions list

# 确认当前 Profile
hermes profile list

万能恢复工具包

遇到任何奇怪问题，按以下顺序执行：

hermes doctor           # 1. 诊断
hermes model            # 2. 检查模型配置
hermes setup            # 3. 重新向导配置
hermes sessions list    # 4. 查看会话状态
hermes --continue       # 5. 尝试恢复会话
hermes gateway status   # 6. 检查网关状态（如已启用）

---

进阶配置预览

完成基础安装后，以下功能可以按需开启（后续章节详细介绍）：

接入消息平台

hermes gateway setup    # 交互式配置 Telegram、Discord、Slack 等
hermes gateway          # 启动消息网关

启用语音模式

# 安装语音依赖
cd ~/.hermes/hermes-agent
uv pip install -e ".[voice]"

# 在 CLI 中启用
/voice on
# 按 Ctrl+B 开始录音

接入 MCP 服务器

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

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

hermes mcp    # 交互式管理 MCP 服务器

编辑器集成（ACP）

hermes acp    # 启动编辑器 Agent 模式（VS Code / Zed / JetBrains）

---

快速命令参考

命令	说明
hermes	启动 CLI 对话
hermes --tui	启动 TUI 对话（推荐）
hermes desktop	启动桌面应用
hermes model	选择/切换 LLM 提供商和模型
hermes setup	完整 Setup 向导
hermes setup --portal	快速配置 Nous Portal
hermes tools	配置工具集
hermes doctor	诊断配置问题
hermes update	更新到最新版本
hermes gateway	启动消息网关
hermes gateway setup	配置消息平台
hermes --continue	恢复最近会话
hermes config set KEY VAL	设置配置项
hermes sessions list	查看历史会话
hermes profile list	查看 Agent Profile