Hermes Agent 配置使用指南
如果你想长期稳定地使用 Hermes Agent，那么理解它的配置方式非常重要。
Hermes 的大多数设置都围绕 ~/.hermes/ 目录展开。你可以把这个目录理解成 Hermes 的“主配置中心”：模型、终端后端、语音、压缩、记忆、技能、日志等内容，基本都从这里读取。
这篇文档会用对新手更友好的方式，带你理解 Hermes 的配置结构、常见配置文件、终端后端、上下文压缩、辅助模型、显示设置以及安全相关功能。
文档概览
| 模块 | 你会学到什么 |
|---|---|
| 配置目录 | ~/.hermes/ 下面都有什么 |
| 管理配置 | 怎么查看、编辑、设置配置 |
| 配置优先级 | CLI 参数、config.yaml、.env 谁优先 |
| 终端后端 | local、docker、ssh、modal、daytona、singularity 的区别 |
| 上下文压缩 | 长会话如何自动摘要和保留上下文 |
| 辅助模型 | 图像分析、网页提取、审批、技能搜索等如何配置 |
| 显示与交互 | 状态显示、流式传输、语音、TTS、STT |
| 安全相关 | 隐私、网站黑名单、工具审批、检查点 |
Hermes 配置目录
Hermes 默认把所有设置都放在 ~/.hermes/ 目录下。
常见目录结构如下：
YAML
hermes_home:
config.yaml: 配置项（模型、终端、TTS、压缩等）
.env: API 密钥与敏感信息
auth.json: OAuth 提供商凭证
SOUL.md: 主 Agent 身份
memories/: 持久记忆
skills/: Agent 创建的技能
cron/: 定时任务
sessions/: 网关会话
logs/: 日志文件
每个文件大概是做什么的
| 文件或目录 | 用途 |
|---|---|
config.yaml |
放大多数普通配置 |
.env |
放 API 密钥、密码、令牌等敏感信息 |
auth.json |
存储 OAuth 登录信息 |
SOUL.md |
定义主 Agent 的人格和系统身份 |
memories/ |
持久记忆相关内容 |
skills/ |
技能目录 |
cron/ |
定时任务 |
sessions/ |
会话记录 |
logs/ |
日志输出 |
管理配置
Hermes 提供了内置命令来管理配置。
常用命令
| 场景 | 命令 |
|---|---|
| 查看当前配置 | hermes config |
打开 config.yaml 编辑 |
hermes config edit |
| 设置某个配置项 | hermes config set KEY VAL |
| 检查升级后缺失的配置项 | hermes config check |
| 交互式补全缺失配置 | hermes config migrate |
示例
| 需求 | 命令 |
|---|---|
| 切换默认模型 | hermes config set model anthropic/claude-opus-4 |
| 切换终端后端为 Docker | hermes config set terminal.backend docker |
| 设置 OpenRouter API 密钥 | hermes config set OPENROUTER_API_KEY sk-or-... |
一个很重要的细节
hermes config set 会自动判断应该把值写到哪里：
- API 密钥这类敏感信息会写到
.env - 普通配置项会写到
config.yaml
这能减少你手动分文件维护的麻烦。
配置优先级
Hermes 读取配置时是有优先级的。优先级从高到低如下：
- CLI 参数
~/.hermes/config.yaml~/.hermes/.env- 内置默认值
这意味着什么
举个简单例子：
如果你在 config.yaml 里把模型设成了 A，但启动命令里又显式写了 --model B，那么本次运行会优先使用 B。
建议怎么放
最稳的做法是：
- 敏感信息放
.env - 普通配置放
config.yaml - 临时测试用 CLI 参数覆盖
环境变量替换
在 config.yaml 里，你可以用 ${VAR_NAME} 的形式引用环境变量。
示例：
YAML
auxiliary:
vision:
api_key: ${GOOGLE_API_KEY}
base_url: ${CUSTOM_VISION_URL}
delegation:
api_key: ${DELEGATION_KEY}
规则
- 支持
${VAR}写法 - 支持一个值里拼多个变量，例如
"${HOST}:${PORT}" - 如果变量没定义，占位符会保留原样
- 不支持不带花括号的
$VAR
终端后端配置
终端后端决定了 Hermes 执行 shell 命令时，命令到底在哪里跑。
Hermes 支持 6 种终端后端：
| 后端 | 命令执行位置 | 隔离级别 | 适用场景 |
|---|---|---|---|
| local | 本地机器 | 无隔离 | 日常开发、个人使用 |
| docker | Docker 容器 | 完全隔离 | 安全沙箱、CI/CD |
| ssh | 远程服务器 | 网络边界隔离 | 远程开发、高性能机器 |
| modal | Modal 云沙箱 | 云虚拟机隔离 | 临时云计算、实验环境 |
| daytona | Daytona 工作区 | 云容器隔离 | 受管理的云开发环境 |
| singularity | Singularity/Apptainer 容器 | 命名空间隔离 | HPC 集群、共享主机 |
基础配置示例
YAML
terminal:
backend: local
cwd: "."
timeout: 180
env_passthrough: []
singularity_image: docker://nikolaik/python-nodejs:python3.11-nodejs20
modal_image: nikolaik/python-nodejs:python3.11-nodejs20
daytona_image: nikolaik/python-nodejs:python3.11-nodejs20
Local 后端
这是默认后端。命令直接在你的机器上执行，没有额外隔离。
YAML
terminal:
backend: local
适合：
- 个人开发环境
- 你完全信任当前会话
- 不需要沙箱隔离
Docker 后端
如果你希望更安全地执行命令，Docker 是最常见选择。
示例：
YAML
terminal:
backend: docker
docker_image: nikolaik/python-nodejs:python3.11-nodejs20
docker_mount_cwd_to_workspace: false
docker_forward_env:
- GITHUB_TOKEN
docker_volumes:
- /home/user/projects:/workspace/projects
- /home/user/data:/data:ro
container_cpu: 1
container_memory: 5120
container_disk: 51200
container_persistent: true
你可以从这个配置里重点理解几件事：
- 用哪个镜像
- 是否把当前目录挂进去
- 是否把某些环境变量传给容器
- 是否挂载主机目录
- CPU、内存、磁盘限制是多少
- 会话结束后文件是否保留
SSH 后端
SSH 后端适合把命令跑到远程服务器上。
YAML
terminal:
backend: ssh
persistent_shell: true
通常至少需要：
TERMINAL_SSH_HOSTTERMINAL_SSH_USER
可选项包括端口、私钥路径和持久化 shell 设置。
Modal、Daytona、Singularity
这几个后端都属于“更隔离或更云端”的执行方式。
共同点基本是：
- 要配置 backend
- 要配置资源限制
- 要决定是否持久化
Docker 卷挂载
如果你使用 Docker 后端，可以通过 docker_volumes 把主机目录共享给容器：
YAML
terminal:
backend: docker
docker_volumes:
- /home/user/projects:/workspace/projects
- /home/user/datasets:/data:ro
- /home/user/outputs:/outputs
适合：
- 把数据集提供给 Agent
- 让 Agent 输出文件到主机目录
- 共享项目工作区
Docker 凭证转发
默认情况下，Docker 容器不会自动继承你主机的所有凭证。
如果你需要某些令牌，可以显式写在 docker_forward_env 里：
YAML
terminal:
backend: docker
docker_forward_env:
- GITHUB_TOKEN
- NPM_TOKEN
注意：这意味着这些变量会对容器中的命令可见，所以只转发你愿意暴露的凭证。
持久化 Shell
持久化 shell 的意义是：
前一条命令里的状态，可以影响下一条命令。
例如：
cd /tmp后，下一条命令还在/tmpexport FOO=bar后，下一条命令还能看到这个变量
示例：
YAML
terminal:
persistent_shell: true
这对 SSH 后端尤其有用。
技能设置
技能可以在 skills.config 命名空间下保存自己的配置。
YAML
skills:
config:
wiki:
path: ~/wiki
这类配置一般适合放路径、偏好、领域设置等非敏感信息。
记忆配置
YAML
memory:
memory_enabled: true
user_profile_enabled: true
memory_char_limit: 2200
user_char_limit: 1375
这部分控制 Hermes 是否启用记忆，以及记忆内容的长度上限。
文件读取安全
为了避免一次读取超大文件导致上下文爆炸，Hermes 可以限制单次 read_file 的最大字符数。
YAML
file_read_max_chars: 100000
如果你经常读取大文件，可以根据模型上下文窗口大小调整这个值。
Git 工作树隔离
如果你想在同一个仓库里并行运行多个 Agent，可以启用 worktree 隔离：
YAML
worktree: true
这样每个会话都会在独立工作树里工作，互不影响。
上下文压缩
当会话很长时，Hermes 会自动压缩中间历史，避免超出模型上下文上限。
完整参考示例：
YAML
compression:
enabled: true
threshold: 0.50
target_ratio: 0.20
protect_last_n: 20
summary_model: google/gemini-3-flash-preview
summary_provider: auto
summary_base_url: null
你只需要先理解这几个重点
| 字段 | 作用 |
|---|---|
enabled |
是否开启压缩 |
threshold |
达到多大上下文占用时开始压缩 |
summary_model |
用哪个模型做摘要 |
summary_provider |
压缩摘要使用哪个提供方 |
上下文引擎
Hermes 用上下文引擎决定接近上下文上限时如何处理对话。
YAML
context:
engine: compressor
如果你安装了其他上下文插件，也可以改成对应插件名，例如 lcm。
迭代预算压力
当 Agent 在复杂任务里频繁调用工具时，可能会逐渐接近最大迭代轮次。Hermes 会在接近上限时自动给出预算警告。
YAML
agent:
max_turns: 90
这能提醒模型尽快收敛，也能帮助你避免任务在不知不觉中跑得太长。
辅助模型
Hermes 会使用辅助模型处理这些任务：
- 图像分析
- 网页提取与摘要
- 危险命令审批分类
- 会话搜索摘要
- Skills Hub 搜索
- MCP 调度
- 记忆刷新
完整参考示例：
YAML
auxiliary:
vision:
provider: auto
model: ""
base_url: ""
api_key: ""
timeout: 30
download_timeout: 30
web_extract:
provider: auto
model: ""
base_url: ""
api_key: ""
timeout: 360
approval:
provider: auto
model: ""
base_url: ""
api_key: ""
timeout: 30
compression:
timeout: 120
session_search:
provider: auto
model: ""
base_url: ""
api_key: ""
timeout: 30
skills_hub:
provider: auto
model: ""
base_url: ""
api_key: ""
timeout: 30
mcp:
provider: auto
model: ""
base_url: ""
api_key: ""
timeout: 30
flush_memories:
provider: auto
model: ""
base_url: ""
api_key: ""
timeout: 30
你可以先记住的原则
provider决定走哪家model决定用哪个模型base_url决定是否直连某个 OpenAI 兼容端点api_key决定认证方式
推理努力
推理努力控制模型在回答前“思考”的强度。
YAML
agent:
reasoning_effort: ""
留空时默认是中等强度。设置为更高值，通常能提升复杂任务表现，但也会增加延迟和 token 消耗。
工具使用强制执行
有些模型会把“应该调用工具”的操作写成文字说明，而不是实际调用工具。
这个配置就是用来纠正这个问题的。
YAML
agent:
tool_use_enforcement: auto
TTS 配置
Hermes 支持多种文字转语音提供方。
YAML
tts:
provider: edge
edge:
voice: en-US-AriaNeural
elevenlabs:
voice_id: pNInz6obpgDQGcFmaJgB
model_id: eleven_multilingual_v2
openai:
model: gpt-4o-mini-tts
voice: alloy
base_url: https://api.openai.com/v1
neutts:
ref_audio: ''
ref_text: ''
model: neuphonic/neutts-air-q4-gguf
device: cpu
显示设置
显示设置控制 CLI 和消息平台里的输出风格。
YAML
display:
tool_progress: all
tool_progress_command: false
tool_progress_overrides: {}
skin: default
personality: kawaii
compact: false
resume_display: full
bell_on_complete: false
show_reasoning: false
streaming: false
show_cost: false
tool_preview_length: 0
tool_progress 的常见模式
| 模式 | 含义 |
|---|---|
off |
只显示最终响应 |
new |
工具变更时显示提示 |
all |
每次工具调用都显示简短预览 |
verbose |
显示完整参数、结果和调试日志 |
隐私
YAML
privacy:
redact_pii: false
开启后，Hermes 会在支持的平台里对部分用户标识做脱敏处理。
STT（语音转文本）
YAML
stt:
provider: local
local:
model: base
openai:
model: whisper-1
支持的提供方包括：
localgroqopenai
语音模式（CLI）
YAML
voice:
record_key: ctrl+b
max_recording_seconds: 120
auto_tts: false
silence_threshold: 200
silence_duration: 3.0
流式传输
CLI 和消息网关都支持流式输出配置。
CLI 侧示例：
YAML
display:
streaming: true
show_reasoning: true
消息网关侧示例：
YAML
streaming:
enabled: true
transport: edit
edit_interval: 0.3
buffer_threshold: 40
cursor: " ▉"
群聊会话隔离
YAML
group_sessions_per_user: true
这个配置决定群聊里是“所有人共享一个会话”，还是“每个用户一个独立会话”。
未授权私信行为
YAML
unauthorized_dm_behavior: pair
whatsapp:
unauthorized_dm_behavior: ignore
快速命令
快速命令适合做零 token 的系统操作。
YAML
quick_commands:
status:
type: exec
command: systemctl status hermes-agent
disk:
type: exec
command: df -h /
update:
type: exec
command: cd ~/.hermes/hermes-agent && git pull && pip install -e .
gpu:
type: exec
command: nvidia-smi --query-gpu=name,utilization.gpu,memory.used,memory.total --format=csv,noheader
人类延迟
YAML
human_delay:
mode: off
min_ms: 800
max_ms: 2500
代码执行
YAML
code_execution:
timeout: 300
max_tool_calls: 50
网络搜索后端
YAML
web:
backend: firecrawl
支持的后端包括：
firecrawlparalleltavilyexa
浏览器
YAML
browser:
inactivity_timeout: 120
command_timeout: 30
record_sessions: false
camofox:
managed_persistence: false
时区
YAML
timezone: America/New_York
Discord
YAML
discord:
require_mention: true
free_response_channels: ""
auto_thread: true
安全
YAML
security:
redact_secrets: true
tirith_enabled: true
tirith_path: tirith
tirith_timeout: 5
tirith_fail_open: true
website_blocklist:
enabled: false
domains: []
shared_files: []
网站黑名单
YAML
security:
website_blocklist:
enabled: false
domains:
- "*.internal.company.com"
- "admin.example.com"
- "*.local"
shared_files:
- /etc/hermes/blocked-sites.txt
智能审批
YAML
approvals:
mode: manual
支持模式：
manualsmartoff
检查点
YAML
checkpoints:
enabled: true
max_snapshots: 50
委派
YAML
delegation:
# model: google/gemini-3-flash-preview
# provider: openrouter
# base_url: http://localhost:1234/v1
# api_key: local-key
明确化
YAML
clarify:
timeout: 120
上下文文件
Hermes 会加载多种上下文文件，用于定义 Agent 身份和项目规则。
| 文件 | 用途 | 作用域 |
|---|---|---|
SOUL.md |
主 Agent 身份 | ~/.hermes/SOUL.md |
.hermes.md / HERMES.md |
项目最高优先级上下文 | 向上遍历到 Git 根目录 |
AGENTS.md |
项目特定编码规范 | 递归目录遍历 |
CLAUDE.md |
Claude Code 上下文文件 | 当前工作目录 |
.cursorrules |
Cursor 规则 | 当前工作目录 |
工作目录
| 上下文 | 默认值 |
|---|---|
| CLI | 启动命令时所在目录 |
| 消息网关 | 用户主目录 ~ |
| Docker / Singularity / Modal / SSH | 容器或远程机器中的用户主目录 |
你也可以通过环境变量覆盖工作目录，例如：
YAML
MESSAGING_CWD: /home/myuser/projects
TERMINAL_CWD: /workspace
需要人工确认的部分
- 原文包含非常多的配置块和后端细节，正式发布时建议按主题拆成多篇文档，否则篇幅会偏长。
- 原文部分示例更适合继续拆分成单独专题，例如“终端后端配置”“辅助模型配置”“安全与审批配置”。
- 本整理稿没有保留网页底部自动目录、SEO JSON、结构化数据，这些已视为噪音清理掉。
本文是原创文章，采用 CC BY-NC-SA 4.0 协议，完整转载请注明来自 吴彦祖
评论
隐私政策
0/500
滚动到此处加载评论...