【AI 工具】Hermes Agent 配置指南

本文主要介绍博主认为常用的 Hermes Agent 的核心配置项（重要的配置会标注 ⭐️）：

目录结构与配置优先级、上下文文件（SOUL.md 等）

显示与流式传输设置

群聊会话隔离

智能审批机制

终端后端（local / docker / ssh / modal 等）

上下文压缩

快速命令

检查点

本文未介绍但会在其他文章单独介绍的配置：

技能相关： skills

模型相关： model, providers, fallback_providers, custom_providers

本文未介绍的配置（博主认为不重要）：

管理配置、环境变量替换、内存配置、文件读取安全、工具输出截断限制、全局工具集禁用、Git Worktree 隔离、上下文引擎、迭代预算压力、上下文压力警告、凭据池策略、Prompt 缓存、辅助模型、推理努力程度、工具使用强制、TTS 配置、隐私、语音转文字（STT）、语音模式（CLI）、未授权 DM 行为、人类延迟、代码执行、Web 搜索后端、浏览器、时区、Discord、安全、网站黑名单、委托、澄清、工作目录

配置目录结构

所有配置存储在 ~/.hermes/ 目录下：

~/.hermes/
├── config.yaml          # 主配置：模型、终端、TTS、压缩等
├── .env                 # API 密钥和机密
├── auth.json            # OAuth 凭据（Nous Portal 等）
├── SOUL.md              # Agent 人格设定（系统提示词第 1 槽位）
├── memories/            # 持久记忆（MEMORY.md、USER.md）
├── skills/              # 技能（通过 skill_manage 管理）
├── cron/                # 定时任务
├── sessions/            # Gateway 会话记录
└── logs/                # 日志（API 密钥自动脱敏）

配置优先级

设置按以下顺序解析（优先级从高到低）：

CLI 参数 —— 例如 hermes chat --model anthropic/claude-sonnet-4（单次调用覆盖）
~/.hermes/config.yaml —— 所有非机密设置的主配置文件
~/.hermes/.env —— 环境变量的回退；机密（API 密钥、token、密码）必须放这里
内置默认值 —— 未设置任何内容时的硬编码安全默认值

.env：放置机密（API 密钥、bot token、密码）
config.yaml：其他所有内容（模型、终端后端、压缩设置、内存限制、工具集等）

上下文文件

文件	用途	范围
`SOUL.md`	Agent 人格（系统提示词第 1 槽位）	`~/.hermes/SOUL.md`
`.hermes.md` / `HERMES.md`	项目特定指令（最高优先级）	向上走到 git 根目录
`AGENTS.md`	项目编码规范	递归目录遍历

SOUL.md 是 agent 的主要身份。它占据系统提示词的第 #1 槽位，完全替换内置的默认身份。编辑它以完全自定义 agent 是谁。
如果 SOUL.md 缺失、为空或无法加载，Hermes 回退到内置默认身份。
项目上下文文件使用优先级系统 —— 仅加载一种类型（第一个匹配优先）：.hermes.md / HERMES.md → AGENTS.md → CLAUDE.md → .cursorrules。
SOUL.md 始终独立加载。
AGENTS.md 是分层的：如果子目录也有 AGENTS.md，所有都会合并。
如果 SOUL.md 不存在，Hermes 会自动生成默认的 SOUL.md。
所有加载的上下文文件上限为 20,000 字符，并进行智能截断。

`display`: 显示设置

display:
  tool_progress: all      # ⭐️ off | new | all | verbose
  tool_progress_command: true  # ⭐️ 在消息 gateway 中启用 /verbose 斜杠命令
  platforms:              # 每个平台的单独配置（覆盖主配置）
    signal:
      tool_progress: 'off'    # 在 Signal 上静默进度
    telegram:
      tool_progress: verbose  # 在 Telegram 上详细进度
    slack:
      tool_progress: 'off'    # 在共享 Slack 工作区中保持安静
  interim_assistant_messages: true  # Gateway：将自然的轮次中 assistant 更新作为单独消息发送
  skin: default           # 内置或自定义 CLI 皮肤（参阅 user-guide/features/skins）
  personality: "kawaii"   # 旧版外观字段，仍在某些摘要中显示
  compact: false          # 紧凑输出模式（减少空白）
  resume_display: full    # full（恢复时显示之前的消息）| minimal（仅单行）
  bell_on_complete: false # 当 agent 完成时播放终端铃声（适合长任务）
  streaming: true         # ⭐️ 将 token 实时流式传输到终端
  show_reasoning: true    # ⭐️ 在每次响应上方显示模型推理/思考（用 /reasoning show|hide 切换）
  show_cost: false        # 在 CLI 状态栏中显示估计 $ 成本
  timestamps: false       # 为 true 时，在 CLI/TUI 记录中为用户和 assistant 标签添加 [HH:MM] 时间戳前缀
  tool_preview_length: 0  # 工具调用预览的最大字符数（0 = 无限制，显示完整路径/命令）
  runtime_footer:         # ⭐️ 在 gateway 的最终回复中附加运行时上下文页脚（模型、上下文 %、cwd、会话时长、token、成本）
    enabled: true
    fields: ["model", "context_pct", "cwd", "duration", "tokens", "cost"]
  file_mutation_verifier: true    # 当本轮 write_file/patch 调用失败时附加建议性页脚
  language: zh            # 静态消息的 UI 语言（审批提示、部分 gateway 回复）。en | zh | zh-hant | ja | de ...

`streaming`: Gateway 流式传输

CLI 流式传输

通过 display.streaming 设置，见上：

1
2
3

display:
  streaming: true         # 实时将 token 流式传输到终端
  show_reasoning: true    # 同时流式传输推理/思考 token（可选）

Gateway 流式传输

streaming:
  enabled: true           # ⭐️ 启用渐进式消息编辑
  transport: edit         # "edit"（渐进式消息编辑）或 "off"
  edit_interval: 0.2      # ⭐️ 消息编辑之间的秒数
  buffer_threshold: 40    # 强制编辑刷新前的字符数
  cursor: " ▉"            # 流式传输期间显示的光标
  fresh_final_after_seconds: 60   # 当预览超过此时间时发送新的最终消息（Telegram）；0 = 始终就地编辑

不支持消息编辑的平台（Signal、Email）自动禁用流式传输。

`group_sessions_per_user`: 群聊会话隔离

1	group_sessions_per_user: true # ⭐️ 群组中每用户隔离会话

true = 群组中每用户独立对话，false = 每个聊天一个共享会话。

true 是默认和推荐设置。在 Discord 频道、Telegram 群组、Slack 频道和类似共享上下文中，当平台提供用户 ID 时，每个发送者获得自己的会话。
false 恢复到旧的共享房间行为。如果您明确希望 Hermes 将频道视为一个协作对话，这可能有用，但这也意味着用户共享上下文、token 成本和中断状态。
私信不受影响。Hermes 仍然像往常一样通过聊天/DM ID 键入 DM。
线程与其父频道保持隔离；使用 true 时，每个参与者在线程内也获得自己的会话。

`approvals`: 智能审批

1 2	approvals: mode: smart # ⭐️ manual \| smart \| off

模式	行为
`manual`（默认）	在执行任何被标记的命令之前提示用户。在 CLI 中显示交互式审批对话框。在消息中排队待处理的审批请求。
`smart`	使用辅助 LLM 评估被标记的命令是否真正危险。低风险命令以会话级持久性自动批准。真正有风险的命令升级给用户。
`off`

智能模式对于减少审批疲劳特别有用 —— 它让 agent 在安全操作上更自主地工作，同时仍然捕获真正破坏性的命令。

`terminal`: 终端后端

Hermes 支持六种终端后端，每种决定 agent 的 shell 命令实际执行位置：

后端	执行位置	隔离性	适用场景
local	本机	无	开发、个人使用
docker	单个持久 Docker 容器	完全隔离	安全沙箱、CI/CD
ssh	远程服务器（SSH）	网络边界	远程开发、高性能硬件
modal	Modal 云沙箱	完全隔离	临时云计算、评估
daytona	Daytona 工作区	完全隔离	托管云开发环境
singularity	Singularity/Apptainer 容器	命名空间隔离	HPC 集群、共享机器

基础配置：

terminal:
  backend: local    # local | docker | ssh | modal | daytona | singularity
  cwd: "."          # Gateway/cron 工作目录
  timeout: 180      # 每条命令超时（秒）

Docker 后端

Hermes 在首次使用时启动单个长期运行的容器，所有终端、文件和 execute_code 调用通过 docker exec 路由到同一容器中，跨会话、/new、/reset 和子 agent 共享。工作目录更改、已安装的包以及 /workspace 中的文件会延续。

terminal:
  backend: docker
  docker_image: "nikolaik/python-nodejs:python3.11-nodejs20"
  docker_mount_cwd_to_workspace: true
  docker_run_as_host_user: true
  docker_forward_env:
    - "GITHUB_TOKEN"
  docker_volumes:
    - "/home/user/projects:/workspace/projects"
    - "/home/user/data:/data:ro"
  docker_extra_args:
    - "--gpus=all"
    - "--network=host"
  container_cpu: 1
  container_memory: 5120
  container_disk: 51200
  container_persistent: true

参数	说明
`docker_mount_cwd_to_workspace`	将启动目录挂载到 `/workspace`，默认 `false`
`docker_run_as_host_user`	附加 `--user $(id -u):$(id -g)`，使文件归宿主用户所有而非 root，默认 `false`
`docker_forward_env`	转发到容器的环境变量，先从 shell 环境解析，回退到 `.env`
`docker_volumes`	标准 Docker `-v` 语法：`host:container[:options]`
`docker_extra_args`	附加到 `docker run` 的额外标志

容器在 Hermes 关闭时停止并删除。如遇问题，先切回 local 验证命令可正常运行：

1	hermes config set terminal.backend local

SSH 后端

通过 SSH 在远程服务器运行命令，使用 ControlMaster 连接复用（5 分钟空闲保活）。默认启用持久 shell，状态（cwd、环境变量）在命令之间保持。

1
2
3

terminal:
  backend: ssh
  persistent_shell: true

必需环境变量：

1 2	export TERMINAL_SSH_HOST=my-server.example.com export TERMINAL_SSH_USER=ubuntu

可选变量：

变量	默认值	说明
`TERMINAL_SSH_PORT`	`22`	SSH 端口
`TERMINAL_SSH_KEY`	系统默认	SSH 私钥路径
`TERMINAL_SSH_PERSISTENT`	`true`	持久 shell

在 Modal 云沙箱中运行命令，每个任务获得隔离 VM。启用 container_persistent 后，文件系统在清理时快照、下次会话恢复。

terminal:
  backend: modal
  container_cpu: 1
  container_memory: 5120
  container_disk: 51200
  container_persistent: true

需要 MODAL_TOKEN_ID + MODAL_TOKEN_SECRET 环境变量，或 ~/.modal.toml 配置文件。

Singularity 后端

专为 Docker 不可用的 HPC 集群设计。Docker URL（docker://...）自动转换为 SIF 并缓存。

terminal:
  backend: singularity
  singularity_image: "docker://nikolaik/python-nodejs:python3.11-nodejs20"
  container_cpu: 1
  container_memory: 5120
  container_persistent: true

需要 $PATH 中有 apptainer 或 singularity 二进制文件。

`compression`: 上下文压缩

当对话接近模型 token 限制时，Hermes 自动压缩旧消息以保留上下文窗口。

compression:
  enabled: true
  threshold: 0.50           # 达到上下文限制的 50% 时触发压缩
  target_ratio: 0.20        # 保留最近 20% 不压缩
  protect_last_n: 20        # 至少保留最近 20 条消息
  hygiene_hard_message_limit: 400  # 超过 400 条消息强制压缩（安全阀）

压缩摘要由独立 LLM 调用完成，模型配置在 auxiliary.compression 下。编辑 config.yaml 中的 model.context_length 或 compression.* 后无需重启 gateway，下一条消息自动生效。

摘要模型的上下文窗口必须不小于主模型。若小于主模型，中间轮次会在无摘要的情况下被丢弃，导致对话上下文静默丢失。

`quick_commands`: 快速命令

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
  restart:
    type: alias
    target: /gateway restart

用法：在 CLI 或任何消息平台中输入 /status、/disk、/update、/gpu 或 /restart。
exec 命令在宿主本地运行并直接返回输出 —— 无 LLM 调用，不消耗 token。
alias 命令重写为配置的斜杠命令目标。

`checkpoints`: 检查点

破坏性文件操作前的自动快照：

1
2
3

checkpoints:
  enabled: false    # 默认关闭，可选启用
  max_snapshots: 20 # 每目录最大检查点数

参考

Hermes Agent 官方配置文档： https://hermes-agent.nousresearch.com/docs/zh-Hans/user-guide/configuration

配置目录结构

配置优先级

上下文文件

display: 显示设置

streaming: Gateway 流式传输

CLI 流式传输

Gateway 流式传输

group_sessions_per_user: 群聊会话隔离

approvals: 智能审批

terminal: 终端后端