Skip to main content

配置

所有设置均存储在 ~/.hermes/ 目录中，便于访问。

目录结构​

~/.hermes/
├── config.yaml     # Settings (model, terminal, TTS, compression, etc.)
├── .env            # API keys and secrets
├── auth.json       # OAuth provider credentials (Nous Portal, etc.)
├── SOUL.md         # Primary agent identity (slot #1 in system prompt)
├── memories/       # Persistent memory (MEMORY.md, USER.md)
├── skills/         # Agent-created skills (managed via skill_manage tool)
├── cron/           # Scheduled jobs
├── sessions/       # Gateway sessions
└── logs/           # Logs (errors.log, gateway.log — secrets auto-redacted)

管理配置​

hermes config              # View current configuration
hermes config edit         # Open config.yaml in your editor
hermes config set KEY VAL  # Set a specific value
hermes config check        # Check for missing options (after updates)
hermes config migrate      # Interactively add missing options

# Examples:
hermes config set model anthropic/claude-opus-4
hermes config set terminal.backend docker
hermes config set OPENROUTER_API_KEY sk-or-...  # Saves to .env
tip

hermes config set 命令会自动将值路由到正确的文件 —— API 密钥保存至 .env，其余所有内容保存至 config.yaml。

配置优先级​

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

  1. CLI 参数 —— 例如 hermes chat --model anthropic/claude-sonnet-4（单次调用覆盖）
  2. ~/.hermes/config.yaml —— 所有非敏感设置的主要配置文件
  3. ~/.hermes/.env —— 环境变量的备用来源；必须用于敏感信息（API 密钥、机器人令牌、密码）
  4. 内置默认值 —— 当其他设置均未指定时使用的硬编码安全默认值
口诀

敏感信息（API 密钥、机器人令牌、密码）请放入 .env。其余内容（模型、终端后端、压缩设置、内存限制、工具集等）请放入 config.yaml。当两者都已设置时，config.yaml 对非敏感设置具有更高优先级。

环境变量替换​

您可以在 config.yaml 中使用 ${VAR_NAME} 语法引用环境变量：

auxiliary:
  vision:
    api_key: ${GOOGLE_API_KEY}
    base_url: ${CUSTOM_VISION_URL}

delegation:
  api_key: ${DELEGATION_KEY}

单个值中可包含多个引用：url: "${HOST}:${PORT}"。如果引用的变量未设置，则占位符将原样保留（${UNDEFINED_VAR} 保持不变）。仅支持 ${VAR} 语法 —— 未经包装的 $VAR 不会被展开。

关于 AI 提供商设置（OpenRouter、Anthropic、Copilot、自定义端点、自托管 LLM、回退模型等），请参阅 AI 提供商。

终端后端配置​

Hermes 支持六种终端后端。每种后端决定了代理的 shell 命令实际执行的位置 —— 您的本地机器、Docker 容器、通过 SSH 连接的远程服务器、Modal 云沙箱、Daytona 工作区，或 Singularity/Apptainer 容器。

terminal:
  backend: local    # local | docker | ssh | modal | daytona | singularity
  cwd: "."          # Working directory ("." = current dir for local, "/root" for containers)
  timeout: 180      # Per-command timeout in seconds
  env_passthrough: []  # Env var names to forward to sandboxed execution (terminal + execute_code)
  singularity_image: "docker://nikolaik/python-nodejs:python3.11-nodejs20"  # Container image for Singularity backend
  modal_image: "nikolaik/python-nodejs:python3.11-nodejs20"                 # Container image for Modal backend
  daytona_image: "nikolaik/python-nodejs:python3.11-nodejs20"               # Container image for Daytona backend

对于 Modal 和 Daytona 等云沙箱，container_persistent: true 表示 Hermes 将尝试在沙箱重建过程中保留文件系统状态。但这并不保证后续仍存在相同的活跃沙箱、PID 空间或后台进程。

后端概览​

后端命令运行位置隔离级别适用场景
local你的机器上直接运行无开发、个人使用
dockerDocker 容器内完全隔离（命名空间、能力降级）安全沙箱、CI/CD
ssh通过 SSH 连接的远程服务器网络边界远程开发、高性能硬件
modalModal 云沙箱完全隔离（云虚拟机）临时云计算、评测
daytonaDaytona 工作区完全隔离（云容器）受管理的云开发环境
singularitySingularity/Apptainer 容器命名空间隔离（--containall）HPC 集群、共享机器

本地后端​

默认选项。命令直接在你的机器上运行，不进行任何隔离。无需额外设置。

terminal:
  backend: local
warning

代理拥有与你用户账户相同的文件系统访问权限。建议使用 hermes tools 禁用不需要的工具，或切换到 Docker 以实现沙箱隔离。

Docker 后端​

在 Docker 容器中运行命令，并采用安全加固措施（移除所有能力、禁止权限提升、限制 PID 数量）。

terminal:
  backend: docker
  docker_image: "nikolaik/python-nodejs:python3.11-nodejs20"
  docker_mount_cwd_to_workspace: false  # Mount launch dir into /workspace
  docker_forward_env:              # Env vars to forward into container
    - "GITHUB_TOKEN"
  docker_volumes:                  # Host directory mounts
    - "/home/user/projects:/workspace/projects"
    - "/home/user/data:/data:ro"   # :ro for read-only

  # Resource limits
  container_cpu: 1                 # CPU cores (0 = unlimited)
  container_memory: 5120           # MB (0 = unlimited)
  container_disk: 51200            # MB (requires overlay2 on XFS+pquota)
  container_persistent: true       # Persist /workspace and /root across sessions

要求： 已安装并运行 Docker Desktop 或 Docker Engine。Hermes 会探测 $PATH 以及常见的 macOS 安装路径（/usr/local/bin/docker、/opt/homebrew/bin/docker、Docker Desktop 应用包）。

容器生命周期： 每个会话启动一个长期运行的容器（docker run -d ... sleep 2h）。命令通过 docker exec 以登录 shell 方式执行。清理时，容器将被停止并删除。

安全加固：

  • --cap-drop ALL，仅重新添加 DAC_OVERRIDE、CHOWN、FOWNER
  • --security-opt no-new-privileges
  • --pids-limit 256
  • 为 /tmp（512MB）、/var/tmp（256MB）、/run（64MB）设置大小受限的 tmpfs

凭证转发： docker_forward_env 列出的环境变量会首先从你的 shell 环境中解析，然后从 ~/.hermes/.env 获取。技能也可以声明 required_environment_variables，这些将自动合并。

SSH 后端​

通过 SSH 在远程服务器上运行命令。使用 ControlMaster 实现连接复用（5 分钟空闲保活）。默认启用持久化 shell —— 状态（当前目录、环境变量）可在命令之间持续保留。

terminal:
  backend: ssh
  persistent_shell: true           # Keep a long-lived bash session (default: true)

必需环境变量：

TERMINAL_SSH_HOST=my-server.example.com
TERMINAL_SSH_USER=ubuntu

可选参数：

变量默认值描述
TERMINAL_SSH_PORT22SSH 端口
TERMINAL_SSH_KEY（系统默认）SSH 私钥路径
TERMINAL_SSH_PERSISTENTtrue启用持久化 shell

工作原理： 初始化时使用 BatchMode=yes 和 StrictHostKeyChecking=accept-new 连接。持久化 shell 会在远程主机上保持一个单独的 bash -l 进程运行，通过临时文件通信。需要 stdin_data 或 sudo 的命令会自动回退到一次性模式。

在 Modal 云沙箱中运行命令。每个任务获得一个隔离的虚拟机，支持配置 CPU、内存和磁盘。文件系统可在会话间快照与恢复。

terminal:
  backend: modal
  container_cpu: 1                 # CPU cores
  container_memory: 5120           # MB (5GB)
  container_disk: 51200            # MB (50GB)
  container_persistent: true       # Snapshot/restore filesystem

必需条件： 必须设置 MODAL_TOKEN_ID + MODAL_TOKEN_SECRET 环境变量，或提供一个 ~/.modal.toml 配置文件。

持久化： 启用后，沙箱文件系统将在清理时进行快照，并在下次会话中恢复。快照记录在 ~/.hermes/modal_snapshots.json 中。这可以保留文件系统状态，但无法保留运行中的进程、PID 空间或后台作业。

凭证文件： 自动从 ~/.hermes/ 挂载（OAuth 令牌等），并在每次命令前同步。

Daytona 后端​

在 Daytona 管理的工作区中运行命令。支持暂停/恢复以实现持久化。

terminal:
  backend: daytona
  container_cpu: 1                 # CPU cores
  container_memory: 5120           # MB → converted to GiB
  container_disk: 10240            # MB → converted to GiB (max 10 GiB)
  container_persistent: true       # Stop/resume instead of delete

必需条件： 设置 DAYTONA_API_KEY 环境变量。

持久化： 启用后，沙箱在清理时会被停止（而非删除），并在下次会话中恢复。沙箱名称遵循模式 hermes-{task_id}。

磁盘限制： Daytona 强制最大 10 GiB。超过此限制的请求将被警告并截断。

Singularity/Apptainer 后端​

在 Singularity/Apptainer 容器中运行命令。专为 Docker 不可用的 HPC 集群和共享机器设计。

terminal:
  backend: singularity
  singularity_image: "docker://nikolaik/python-nodejs:python3.11-nodejs20"
  container_cpu: 1                 # CPU cores
  container_memory: 5120           # MB
  container_persistent: true       # Writable overlay persists across sessions

要求： apptainer 或 singularity 二进制文件位于 $PATH。

镜像处理： Docker URL（docker://...）会自动转换为 SIF 文件并缓存。现有的 .sif 文件将直接使用。

临时目录： 按顺序解析：TERMINAL_SCRATCH_DIR → TERMINAL_SANDBOX_DIR/singularity → /scratch/$USER/hermes-agent（HPC 常规做法）→ ~/.hermes/sandboxes/singularity。

隔离： 使用 --containall --no-home 实现完整的命名空间隔离，且不挂载主机家目录。

常见终端后端问题​

若终端命令立即失败，或报告终端工具已禁用：

  • 本地 —— 无特殊要求。开始使用时最安全的默认选项。
  • Docker —— 运行 docker version 以验证 Docker 是否正常工作。若失败，请修复 Docker 或 hermes config set terminal.backend local。
  • SSH —— 必须同时设置 TERMINAL_SSH_HOST 和 TERMINAL_SSH_USER。Hermes 会在任一缺失时输出清晰错误。
  • Modal —— 需要 MODAL_TOKEN_ID 环境变量或 ~/.modal.toml。运行 hermes doctor 检查。
  • Daytona —— 需要 DAYTONA_API_KEY。Daytona SDK 会处理服务器 URL 配置。
  • Singularity —— 需要在 $PATH 中设置 apptainer 或 singularity。在 HPC 集群上常见。

如有疑问，将 terminal.backend 重置为 local，并先确认命令在此环境下能否正常运行。

Docker 卷挂载​

使用 Docker 后端时，docker_volumes 允许你将主机目录与容器共享。每个条目使用标准 Docker -v 语法：host_path:container_path[:options]。

terminal:
  backend: docker
  docker_volumes:
    - "/home/user/projects:/workspace/projects"   # Read-write (default)
    - "/home/user/datasets:/data:ro"              # Read-only
    - "/home/user/outputs:/outputs"               # Agent writes, you read

这很有用，具体包括：

  • 向代理提供文件（数据集、配置文件、参考代码）
  • 从代理接收文件（生成的代码、报告、导出内容）
  • 共享工作区，让你和代理都能访问相同的文件

也可以通过环境变量设置：TERMINAL_DOCKER_VOLUMES='["/host:/container"]'（JSON 数组格式）。

Docker 凭证转发​

默认情况下，Docker 终端会话不会继承主机上的任意凭证。如果你需要在容器内使用特定令牌，请将其添加到 terminal.docker_forward_env 中。

terminal:
  backend: docker
  docker_forward_env:
    - "GITHUB_TOKEN"
    - "NPM_TOKEN"

Hermes 会优先从当前 shell 环境中解析每个列出的变量，若未找到则回退至已保存的 ~/.hermes/.env。

warning

列在 docker_forward_env 中的任何内容都会暴露给容器内运行的命令。请仅转发你愿意在终端会话中公开的凭证。

可选：将启动目录挂载到 /workspace​

默认情况下，Docker沙箱是隔离的。Hermes 不会 自动将你的主机工作目录传递给容器，除非你明确启用该功能。

在 config.yaml 中启用：

terminal:
  backend: docker
  docker_mount_cwd_to_workspace: true

启用后：

  • 如果你从 ~/projects/my-app 启动 Hermes，该主机目录将被绑定挂载到 /workspace
  • Docker 后端将在 /workspace 启动
  • 文件工具和终端命令都将看到相同的挂载项目

禁用时，/workspace 保持沙箱独占，除非你通过 docker_volumes 显式挂载其他内容。

安全权衡：

  • false 保留沙箱边界
  • true 允许沙箱直接访问你启动 Hermes 时所在的目录

仅当你有意让容器操作主机上的实时文件时才启用此选项。

持久化 Shell​

默认情况下，每次终端命令都在独立的子进程中运行——工作目录、环境变量和 shell 变量在命令之间都会重置。当启用 持久化 Shell 时，一个长期存活的 bash 进程将跨 execute() 调用保持运行，使状态在命令间持续存在。

这对 SSH 后端 最为有用，因为它还能消除每次命令的连接开销。持久化 Shell 在 SSH 后端中 默认启用，而在本地后端中默认禁用。

terminal:
  persistent_shell: true   # default — enables persistent shell for SSH

如需禁用：

hermes config set terminal.persistent_shell false

在命令间持续存在的内容：

  • 工作目录（cd /tmp 对下一条命令保持有效）
  • 导出的环境变量（export FOO=bar）
  • Shell 变量（MY_VAR=hello）

优先级顺序：

层级变量默认值
配置terminal.persistent_shelltrue
SSH 覆盖TERMINAL_SSH_PERSISTENT继承配置
本地覆盖TERMINAL_LOCAL_PERSISTENTfalse

各后端的环境变量具有最高优先级。若你也希望在本地后端启用持久化 Shell：

export TERMINAL_LOCAL_PERSISTENT=true
note

需要使用 stdin_data 或 sudo 的命令会自动降级为一次性模式，因为持久化 Shell 的 stdin 已被 IPC 协议占用。

有关各后端的详细信息，请参阅 代码执行 和 README 中的 终端部分。

技能设置​

技能可通过其 SKILL.md 前言声明自己的配置项。这些是非敏感值（路径、偏好、领域设置），存储在 skills.config 命名空间下的 config.yaml 中。

skills:
  config:
    wiki:
      path: ~/wiki          # Used by the llm-wiki skill

技能设置的工作方式：

  • hermes config migrate 扫描所有启用的技能，发现未配置的设置，并提示你输入
  • hermes config show 在“技能设置”中显示所有技能的设置及其所属技能
  • 当技能加载时，其解析后的配置值会自动注入到技能上下文中

手动设置值：

hermes config set skills.config.wiki.path ~/my-research-wiki

关于如何在自定义技能中声明配置项的详细说明，请参见 创建技能 — 配置设置。

内存配置​

memory:
  memory_enabled: true
  user_profile_enabled: true
  memory_char_limit: 2200   # ~800 tokens
  user_char_limit: 1375     # ~500 tokens

文件读取安全​

控制单次 read_file 调用可返回的内容量。超过限制的读取将被拒绝，并提示代理改用 offset 和 limit 来读取更小范围的内容。这可防止对压缩 JS 包或大文件的单次读取导致上下文窗口溢出。

file_read_max_chars: 100000  # default — ~25-35K tokens

如果你使用的是具有大上下文窗口的模型且频繁读取大文件，可适当提高此值；对于小上下文模型，则应降低以保持读取效率：

# Large context model (200K+)
file_read_max_chars: 200000

# Small local model (16K context)
file_read_max_chars: 30000

代理还会自动去重文件读取——如果同一文件区域被重复读取且文件未更改，将返回轻量级占位符而非重新发送内容。此机制在上下文压缩后重置，因此代理可在内容被摘要后重新读取文件。

Git 工作树隔离​

为在同一仓库中并行运行多个代理，启用隔离的 Git 工作树：

worktree: true    # Always create a worktree (same as hermes -w)
# worktree: false # Default — only when -w flag is passed

启用后，每个 CLI 会话会在 .worktrees/ 下创建一个全新的工作树，并拥有独立分支。代理可以编辑文件、提交、推送和创建 PR，互不干扰。退出时干净的工作树会被自动清理；脏的工作树将保留以便手动恢复。

你还可以通过在仓库根目录设置 .worktreeinclude 来指定要复制进工作树的 gitignored 文件：

# .worktreeinclude
.env
.venv/
node_modules/

上下文压缩​

Hermes 会自动压缩长时间对话，以确保不超过模型的上下文窗口限制。压缩总结器是一个独立的 LLM 调用，你可以将其指向任意提供商或端点。

所有压缩设置均位于 config.yaml（无环境变量）。

完整参考​

compression:
  enabled: true                                     # Toggle compression on/off
  threshold: 0.50                                   # Compress at this % of context limit
  target_ratio: 0.20                                # Fraction of threshold to preserve as recent tail
  protect_last_n: 20                                # Min recent messages to keep uncompressed
  summary_model: "google/gemini-3-flash-preview"    # Model for summarization
  summary_provider: "auto"                          # Provider: "auto", "openrouter", "nous", "codex", "main", etc.
  summary_base_url: null                            # Custom OpenAI-compatible endpoint (overrides provider)

常见配置​

默认（自动检测）——无需配置：

compression:
  enabled: true
  threshold: 0.50

使用首个可用的提供商（OpenRouter → Nous → Codex），采用 Gemini Flash。

强制指定特定提供商（基于 OAuth 或 API Key）：

compression:
  summary_provider: nous
  summary_model: gemini-3-flash

适用于任意提供商：nous、openrouter、codex、anthropic、main 等。

自定义端点（自托管、Ollama、zai、DeepSeek 等）：

compression:
  summary_model: glm-4.7
  summary_base_url: https://api.z.ai/api/coding/paas/v4

指向自定义的 OpenAI 兼容端点。使用 OPENAI_API_KEY 进行认证。

三个配置项的交互逻辑​

summary_providersummary_base_url结果
auto（默认）未设置自动检测最佳可用提供商
nous / openrouter / 等未设置强制使用该提供商，使用其认证方式
任意值已设置直接使用自定义端点（忽略提供商）

summary_model 必须支持至少与主模型相同长度的上下文，因为它需要接收整个对话中间部分用于压缩。

上下文引擎​

上下文引擎控制当接近模型令牌限制时对话的管理方式。内置的 compressor 引擎使用有损摘要（详见 上下文压缩）。插件引擎可替换它，采用替代策略。

context:
  engine: "compressor"    # default — built-in lossy summarization

若要使用插件引擎（例如 LCM 实现无损上下文管理）：

context:
  engine: "lcm"          # must match the plugin's name

插件引擎 从不自动激活 —— 你必须显式设置 context.engine 为插件名称。可用引擎可通过 hermes plugins → 提供商插件 → 上下文引擎 浏览和选择。

有关内存插件的类似单选系统，请参见 内存提供者。

迭代预算压力​

当代理处理复杂任务并进行大量工具调用时，可能不知不觉耗尽迭代预算（默认：90 轮）。预算压力机制会在接近上限时自动向模型发出警告：

阈值等级模型所见内容
70%警告[BUDGET: 63/90. 27 iterations left. Start consolidating.]
90%严重警告[BUDGET WARNING: 81/90. Only 9 left. Respond NOW.]
agent:
  max_turns: 90                # Max iterations per conversation turn (default: 90)

预算压力默认启用。代理会自然地将警告视为工具结果的一部分，从而鼓励其整合工作，在耗尽迭代次数前完成响应。

流式传输超时​

LLM 流式连接包含两层超时机制。对于本地提供方（localhost、局域网 IP）会自动调整——大多数设置无需额外配置。

超时类型默认值本地提供方环境变量
套接字读取超时120秒自动提升至 1800秒HERMES_STREAM_READ_TIMEOUT
静默流检测180秒自动禁用HERMES_STREAM_STALE_TIMEOUT
API 调用（非流式）1800秒保持不变HERMES_API_TIMEOUT

套接字读取超时 控制 httpx 等待提供方发送下一个数据块的时间。本地 LLM 在处理大上下文时可能需要数分钟进行预填充（prefill）才能生成第一个 token，因此当 Hermes 检测到本地端点时，会将其提升至 30 分钟。如果你显式设置了 HERMES_STREAM_READ_TIMEOUT，则无论是否检测到本地端点，都将始终使用该值。

静默流检测 会终止那些仅接收 SSE 心跳包但无实际内容的连接。此功能在本地提供方上完全禁用，因为它们在预填充阶段不会发送心跳包。

上下文压力警告​

与迭代预算压力分开，上下文压力用于跟踪对话距离 压缩阈值 的接近程度——即触发上下文压缩以总结旧消息的临界点。这有助于你和代理了解对话是否过长。

进度等级发生什么
≥ 60% 至阈值信息CLI 显示青色进度条；网关发送信息通知
≥ 85% 至阈值警告CLI 显示粗体黄色条；网关警告压缩即将发生

在 CLI 中，上下文压力以工具输出流中的进度条形式呈现：

  ◐ context ████████████░░░░░░░░ 62% to compaction  48k threshold (50%) · approaching compaction

在即时通讯平台中，会发送纯文本通知：

◐ Context: ████████████░░░░░░░░ 62% to compaction (threshold: 50% of window).

如果禁用了自动压缩，警告将提示上下文可能会被截断。

上下文压力为自动机制——无需配置。它仅作为面向用户的提醒，不会修改消息流或向模型上下文中注入任何内容。

凭证池策略​

当你为同一提供方拥有多个 API 密钥或 OAuth 令牌时，可配置轮换策略：

credential_pool_strategies:
  openrouter: round_robin    # cycle through keys evenly
  anthropic: least_used      # always pick the least-used key

选项：fill_first（默认）、round_robin、least_used、random。详见 凭证池 完整文档。

辅助模型​

Hermes 使用轻量级“辅助”模型来执行图像分析、网页摘要、浏览器截图分析等附加任务。默认情况下，这些任务通过自动检测使用 Gemini Flash——无需额外配置。

通用配置模式​

Hermes 中所有模型槽位——包括辅助任务、压缩、回退模型——均采用相同的三个控制参数：

键名作用默认值
provider用于认证和路由的提供方"auto"
model请求的具体模型提供方默认模型
base_url自定义 OpenAI 兼容端点（覆盖提供方）未设置

当 base_url 被设置时，Hermes 会忽略提供方，直接调用该端点（使用 api_key 或 OPENAI_API_KEY 进行认证）。当仅设置 provider 时，Hermes 将使用该提供方内置的认证方式和基础 URL。

可用于辅助任务的提供方：auto、openrouter、nous、codex、copilot、anthropic、main、zai、kimi-coding、minimax、提供方注册表 中注册的任意提供方，或你 custom_providers 列表中的任意命名自定义提供方（例如 provider: "beans"）。

"main" 仅适用于辅助任务

"main" 提供方选项表示“使用我主代理所用的提供方”——它仅在 auxiliary:、compression: 和 fallback_model: 配置中有效。它不是顶层 model.provider 设置的有效值。若使用自定义 OpenAI 兼容端点，请在 provider: custom 的 model: 部分设置。详见 AI 提供方 获取所有主模型提供方选项。

完整辅助配置参考​

auxiliary:
  # Image analysis (vision_analyze tool + browser screenshots)
  vision:
    provider: "auto"           # "auto", "openrouter", "nous", "codex", "main", etc.
    model: ""                  # e.g. "openai/gpt-4o", "google/gemini-2.5-flash"
    base_url: ""               # Custom OpenAI-compatible endpoint (overrides provider)
    api_key: ""                # API key for base_url (falls back to OPENAI_API_KEY)
    timeout: 30                # seconds — LLM API call; increase for slow local vision models
    download_timeout: 30       # seconds — image HTTP download; increase for slow connections

  # Web page summarization + browser page text extraction
  web_extract:
    provider: "auto"
    model: ""                  # e.g. "google/gemini-2.5-flash"
    base_url: ""
    api_key: ""
    timeout: 360               # seconds (6min) — per-attempt LLM summarization

  # Dangerous command approval classifier
  approval:
    provider: "auto"
    model: ""
    base_url: ""
    api_key: ""
    timeout: 30                # seconds

  # Context compression timeout (separate from compression.* config)
  compression:
    timeout: 120               # seconds — compression summarizes long conversations, needs more time

  # Session search — summarizes past session matches
  session_search:
    provider: "auto"
    model: ""
    base_url: ""
    api_key: ""
    timeout: 30

  # Skills hub — skill matching and search
  skills_hub:
    provider: "auto"
    model: ""
    base_url: ""
    api_key: ""
    timeout: 30

  # MCP tool dispatch
  mcp:
    provider: "auto"
    model: ""
    base_url: ""
    api_key: ""
    timeout: 30

  # Memory flush — summarizes conversation for persistent memory
  flush_memories:
    provider: "auto"
    model: ""
    base_url: ""
    api_key: ""
    timeout: 30
tip

每个辅助任务都有可配置的 timeout（单位：秒）。默认值：视觉任务 30 秒，网页提取 360 秒，审批任务 30 秒，压缩任务 120 秒。若使用较慢的本地模型执行辅助任务，可适当增加该值。视觉任务还有一项独立的 download_timeout（默认 30 秒），用于 HTTP 图像下载——在连接缓慢或自托管图像服务器时可增加该值。

info

上下文压缩拥有独立的顶层 compression: 块，包含 summary_provider、summary_model 和 summary_base_url —— 参见上方 上下文压缩。回退模型使用 fallback_model: 块——参见 回退模型。三者均遵循相同的提供方/模型/基础 URL 模式。

更改视觉模型​

要使用 GPT-4o 而非 Gemini Flash 进行图像分析：

auxiliary:
  vision:
    model: "openai/gpt-4o"

或通过环境变量（在 ~/.hermes/.env 中）：

AUXILIARY_VISION_MODEL=openai/gpt-4o

提供方选项​

这些选项适用于 辅助任务配置（auxiliary:、compression:、fallback_model:），而非你的主 model.provider 设置。

提供方描述要求
"auto"最佳可用（默认）。视觉任务尝试顺序：OpenRouter → Nous → Codex。—
"openrouter"强制使用 OpenRouter —— 可路由至任意模型（Gemini、GPT-4o、Claude 等）OPENROUTER_API_KEY
"nous"强制使用 Nous Portalhermes auth
"codex"强制使用 Codex OAuth（ChatGPT 账户）。支持视觉功能（gpt-5.3-codex）。hermes model → Codex
"main"使用你当前激活的自定义/主端点。该端点可来自 OPENAI_BASE_URL` + `OPENAI_API_KEY，或通过 hermes model` / `config.yaml 保存的自定义端点。支持 OpenAI、本地模型或任何 OpenAI 兼容 API。仅限辅助任务使用——不适用于 model.provider。自定义端点凭据 + 基础 URL

常见配置场景​

直接使用自定义端点（比 provider: "main" 更清晰，适用于本地/自托管 API）：

auxiliary:
  vision:
    base_url: "http://localhost:1234/v1"
    api_key: "local-key"
    model: "qwen2.5-vl"

base_url 优先于 provider，因此这是将辅助任务路由至特定端点最明确的方式。对于直接端点覆盖，Hermes 使用配置的 api_key 或回退至 OPENAI_API_KEY；它不会复用 OPENROUTER_API_KEY 来访问该自定义端点。

使用 OpenAI API 密钥进行视觉分析：

# In ~/.hermes/.env:
# OPENAI_BASE_URL=https://api.openai.com/v1
# OPENAI_API_KEY=sk-...

auxiliary:
  vision:
    provider: "main"
    model: "gpt-4o"       # or "gpt-4o-mini" for cheaper

使用 OpenRouter 进行视觉分析（可路由至任意模型）：

auxiliary:
  vision:
    provider: "openrouter"
    model: "openai/gpt-4o"      # or "google/gemini-2.5-flash", etc.

使用 Codex OAuth（ChatGPT Pro/Plus 账户——无需 API 密钥）：

auxiliary:
  vision:
    provider: "codex"     # uses your ChatGPT OAuth token
    # model defaults to gpt-5.3-codex (supports vision)

使用本地/自托管模型：

auxiliary:
  vision:
    provider: "main"      # uses your active custom endpoint
    model: "my-local-model"

provider: "main" 使用 Hermes 用于正常聊天的提供方——无论是命名的自定义提供方（如 beans）、内置提供方（如 openrouter），还是传统的 OPENAI_BASE_URL 端点。

tip

如果你将 Codex OAuth 作为主模型提供方，视觉分析可自动生效——无需额外配置。Codex 已包含在视觉任务的自动检测链中。

warning

视觉分析需要多模态模型。 若设置了 provider: "main"，请确保你的端点支持多模态/视觉功能——否则图像分析将失败。

环境变量（旧版）辅助模型也可以通过环境变量进行配置。然而，config.yaml 是推荐的方法——它更易于管理，并支持所有选项，包括 base_url 和 api_key。​

设置环境变量
视觉模型提供商AUXILIARY_VISION_PROVIDER
视觉模型AUXILIARY_VISION_MODEL
视觉端点AUXILIARY_VISION_BASE_URL
视觉 API 密钥AUXILIARY_VISION_API_KEY
网页提取提供商AUXILIARY_WEB_EXTRACT_PROVIDER
网页提取模型AUXILIARY_WEB_EXTRACT_MODEL
网页提取端点AUXILIARY_WEB_EXTRACT_BASE_URL
网页提取 API 密钥AUXILIARY_WEB_EXTRACT_API_KEY

压缩和回退模型设置仅限于 config.yaml 文件。

tip

运行 hermes config 可查看当前的辅助模型设置。只有当设置与默认值不同时，才会显示覆盖项。

推理努力程度​

控制模型在响应前“思考”的程度：

agent:
  reasoning_effort: ""   # empty = medium (default). Options: none, minimal, low, medium, high, xhigh (max)

未设置时（默认值），推理努力程度为“中等”——适用于大多数任务的平衡水平。设置该值将覆盖默认值：更高的推理努力程度可在复杂任务上获得更好结果，但会增加 token 消耗和延迟。

你也可以通过 /reasoning 命令在运行时更改推理努力程度：

/reasoning           # Show current effort level and display state
/reasoning high      # Set reasoning effort to high
/reasoning none      # Disable reasoning
/reasoning show      # Show model thinking above each response
/reasoning hide      # Hide model thinking

工具调用强制执行​

某些模型（尤其是 GPT 系列）偶尔会以文本形式描述预期操作，而非实际调用工具。工具调用强制执行会注入引导信息，促使模型真正调用工具。

agent:
  tool_use_enforcement: "auto"   # "auto" | true | false | ["model-substring", ...]
值行为
"auto"（默认）对 GPT 模型（gpt-、openai/gpt-）启用，对其他模型禁用。
true对所有模型始终启用。
false对所有模型始终禁用。
["gpt-", "o1-", "custom-model"]仅对名称包含指定子字符串的模型启用。

启用后，系统提示中会包含提醒模型实际调用工具而非仅描述行为的引导语。这对用户是透明的，且对已可靠使用工具的模型无影响。

TTS 配置​

tts:
  provider: "edge"              # "edge" | "elevenlabs" | "openai" | "neutts"
  edge:
    voice: "en-US-AriaNeural"   # 322 voices, 74 languages
  elevenlabs:
    voice_id: "pNInz6obpgDQGcFmaJgB"
    model_id: "eleven_multilingual_v2"
  openai:
    model: "gpt-4o-mini-tts"
    voice: "alloy"              # alloy, echo, fable, onyx, nova, shimmer
    base_url: "https://api.openai.com/v1"  # Override for OpenAI-compatible TTS endpoints
  neutts:
    ref_audio: ''
    ref_text: ''
    model: neuphonic/neutts-air-q4-gguf
    device: cpu

此设置同时控制 text_to_speech 工具以及语音模式下的语音回复（CLI 或消息网关中的 /voice tts）。

显示设置​

display:
  tool_progress: all      # off | new | all | verbose
  tool_progress_command: false  # Enable /verbose slash command in messaging gateway
  tool_progress_overrides: {}  # Per-platform overrides (see below)
  skin: default           # Built-in or custom CLI skin (see user-guide/features/skins)
  personality: "kawaii"  # Legacy cosmetic field still surfaced in some summaries
  compact: false          # Compact output mode (less whitespace)
  resume_display: full    # full (show previous messages on resume) | minimal (one-liner only)
  bell_on_complete: false # Play terminal bell when agent finishes (great for long tasks)
  show_reasoning: false   # Show model reasoning/thinking above each response (toggle with /reasoning show|hide)
  streaming: false        # Stream tokens to terminal as they arrive (real-time output)
  show_cost: false        # Show estimated $ cost in the CLI status bar
  tool_preview_length: 0  # Max chars for tool call previews (0 = no limit, show full paths/commands)
模式你看到的内容
off静默模式——仅显示最终响应
new仅在工具变更时显示工具指示器
all每次工具调用均显示简短预览（默认）
verbose显示完整参数、结果和调试日志

在 CLI 中，使用 /verbose 在这些模式间循环切换。要在消息平台（Telegram、Discord、Slack 等）中使用 /verbose，请在上述的 display 部分设置 tool_progress_command: true。该命令将循环切换模式并保存至配置文件。

各平台进度显示覆盖​

不同平台对输出详细程度的需求不同。例如，Signal 不支持编辑消息，因此每次进度更新都会变成一条独立消息——容易造成干扰。使用 tool_progress_overrides 可为各平台设置独立的显示模式：

display:
  tool_progress: all          # global default
  tool_progress_overrides:
    signal: 'off'             # silence progress on Signal
    telegram: verbose         # detailed progress on Telegram
    slack: 'off'              # quiet in shared Slack workspace

未设置覆盖的平台将回退到全局的 tool_progress 值。有效的平台键名：telegram、discord、slack、signal、whatsapp、matrix、mattermost、email、sms、homeassistant、dingtalk、feishu、wecom、weixin、bluebubbles。

隐私​

privacy:
  redact_pii: false  # Strip PII from LLM context (gateway only)

当 redact_pii 设置为 true 时，网关会在支持的平台上从系统提示中删除个人身份信息后再发送给 LLM：

字段处理方式
电话号码（WhatsApp/Signal 上的用户 ID）哈希为 user_<12-char-sha256>
用户 ID哈希为 user_<12-char-sha256>
聊天 ID数字部分哈希，平台前缀保留（telegram:<hash>）
主频道 ID数字部分哈希
用户名 / 用户别名不受影响（由用户自定义，公开可见）

平台支持情况： 哈希处理适用于 WhatsApp、Signal 和 Telegram。Discord 和 Slack 不适用，因为其提及系统（<@user_id>）需要在 LLM 上下文中使用真实 ID。

哈希是确定性的——同一用户始终映射到相同的哈希值，因此模型仍能在群聊中区分不同用户。路由和投递仍使用原始值内部处理。

语音转文字（STT）​

stt:
  provider: "local"            # "local" | "groq" | "openai"
  local:
    model: "base"              # tiny, base, small, medium, large-v3
  openai:
    model: "whisper-1"         # whisper-1 | gpt-4o-mini-transcribe | gpt-4o-transcribe
  # model: "whisper-1"         # Legacy fallback key still respected

提供方行为：

  • local 使用运行在你本地机器上的 faster-whisper。需单独安装，使用 pip install faster-whisper。
  • groq 使用 Groq 的 Whisper 兼容端点，并读取 GROQ_API_KEY。
  • openai 使用 OpenAI 的语音 API，并读取 VOICE_TOOLS_OPENAI_KEY。

如果请求的提供方不可用，Hermes 将按以下顺序自动降级：local → groq → openai。

Groq 和 OpenAI 模型的覆盖由环境变量驱动：

STT_GROQ_MODEL=whisper-large-v3-turbo
STT_OPENAI_MODEL=whisper-1
GROQ_BASE_URL=https://api.groq.com/openai/v1
STT_OPENAI_BASE_URL=https://api.openai.com/v1

语音模式（CLI）​

voice:
  record_key: "ctrl+b"         # Push-to-talk key inside the CLI
  max_recording_seconds: 120    # Hard stop for long recordings
  auto_tts: false               # Enable spoken replies automatically when /voice on
  silence_threshold: 200        # RMS threshold for speech detection
  silence_duration: 3.0         # Seconds of silence before auto-stop

在 CLI 中使用 /voice on 启用麦克风模式，record_key 开始/停止录音，/voice tts 切换语音回复。详见 语音模式 了解端到端设置及各平台的具体行为。

流式传输​

在完整响应生成前，逐个流式传输 token 到终端或消息平台。

CLI 流式传输​

display:
  streaming: true         # Stream tokens to terminal in real-time
  show_reasoning: true    # Also stream reasoning/thinking tokens (optional)

启用后，响应将以逐 token 方式在流式框内显示。工具调用仍会静默捕获。若提供方不支持流式传输，则自动回退到正常显示。

网关流式传输（Telegram、Discord、Slack）​

streaming:
  enabled: true           # Enable progressive message editing
  transport: edit         # "edit" (progressive message editing) or "off"
  edit_interval: 0.3      # Seconds between message edits
  buffer_threshold: 40    # Characters before forcing an edit flush
  cursor: " ▉"            # Cursor shown during streaming

启用后，机器人会在首个 token 到达时发送一条消息，随后随着更多 token 到达逐步编辑该消息。对于不支持消息编辑的平台（如 Signal、Email、Home Assistant），将在首次尝试时自动检测——该会话将优雅地禁用流式传输，避免消息泛滥。

溢出处理： 若流式文本超过平台的消息长度限制（约 4096 字符），当前消息将被固定，新消息将自动开启。

note

流式传输默认关闭。请在 ~/.hermes/config.yaml 中启用以体验流式交互。

群聊会话隔离​

控制共享聊天是否保持每房间一个对话，还是每参与者一个对话：

group_sessions_per_user: true  # true = per-user isolation in groups/channels, false = one shared session per chat
  • true 是默认且推荐设置。在 Discord 频道、Telegram 群组、Slack 频道等共享上下文中，只要平台提供用户 ID，每位发送者都将拥有自己的会话。
  • false 回退到旧的共享房间行为。这在你明确希望 Hermes 将频道视为单一协作对话时可能有用，但也意味着用户之间共享上下文、token 成本和中断状态。
  • 直接消息不受影响。Hermes 仍按聊天/私信 ID 键控 DM。
  • 无论设置如何，线程始终与其父频道隔离；使用 true 时，线程内的每位参与者也会拥有自己的会话。

有关行为细节和示例，请参阅 会话 和 Discord 指南。

未经授权的私信行为​

控制 Hermes 在未知用户发送私信时的行为：

unauthorized_dm_behavior: pair

whatsapp:
  unauthorized_dm_behavior: ignore
  • pair 是默认设置。Hermes 拒绝访问，但在私信中回复一次性配对码。
  • ignore 无声丢弃未经授权的私信。
  • 平台部分可覆盖全局默认值，因此你可以在整体保持配对功能的同时，让某个平台更安静。

快速命令​

定义自定义命令，直接执行 shell 命令而不调用 LLM——零 token 消耗，即时执行。特别适合在消息平台（Telegram、Discord 等）中用于快速服务器检查或实用脚本。

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

使用方法：在 CLI 或任意消息平台中输入 /status、/disk、/update 或 /gpu。该命令将在主机本地运行并直接返回输出——无需调用 LLM，也不会消耗 token。

  • 30 秒超时 —— 长时间运行的命令将被终止并返回错误信息
  • 优先级 —— 快捷命令会在技能命令之前被检查，因此你可以覆盖技能名称
  • 自动补全 —— 快捷命令在分派时即被解析，不会显示在内置斜杠命令自动补全列表中
  • 类型限制 —— 仅支持 exec（执行 shell 命令）；其他类型会报错
  • 全域可用 —— 支持 CLI、Telegram、Discord、Slack、WhatsApp、Signal、Email、Home Assistant

人类延迟模拟​

在消息平台中模拟类人响应节奏：

human_delay:
  mode: "off"                  # off | natural | custom
  min_ms: 800                  # Minimum delay (custom mode)
  max_ms: 2500                 # Maximum delay (custom mode)

代码执行​

配置沙盒化的 Python 代码执行工具：

code_execution:
  timeout: 300                 # Max execution time in seconds
  max_tool_calls: 50           # Max tool calls within code execution

网络搜索后端​

web_search、web_extract 和 web_crawl 工具支持四种后端提供商。可通过 config.yaml 或通过 hermes tools 配置后端：

web:
  backend: firecrawl    # firecrawl | parallel | tavily | exa
后端环境变量搜索提取爬取
Firecrawl（默认）FIRECRAWL_API_KEY✔✔✔
ParallelPARALLEL_API_KEY✔✔—
TavilyTAVILY_API_KEY✔✔✔
ExaEXA_API_KEY✔✔—

后端选择规则：
若未设置 web.backend，系统将根据可用 API 密钥自动检测后端。
若仅设置了 EXA_API_KEY，则使用 Exa。
若仅设置了 TAVILY_API_KEY，则使用 Tavily。
若仅设置了 PARALLEL_API_KEY，则使用 Parallel。
否则默认使用 Firecrawl。

自托管 Firecrawl：
设置 FIRECRAWL_API_URL 指向你自己的实例。当指定自定义 URL 时，API 密钥变为可选（可在服务器上设置 USE_DB_AUTHENTICATION=false 来禁用认证）。

Parallel 搜索模式：
设置 PARALLEL_SEARCH_MODE 以控制搜索行为 —— 可选值为 fast、one-shot 或 agentic（默认：agentic）。

浏览器​

配置浏览器自动化行为：

browser:
  inactivity_timeout: 120        # Seconds before auto-closing idle sessions
  command_timeout: 30             # Timeout in seconds for browser commands (screenshot, navigate, etc.)
  record_sessions: false         # Auto-record browser sessions as WebM videos to ~/.hermes/browser_recordings/
  camofox:
    managed_persistence: false   # When true, Camofox sessions persist cookies/logins across restarts

浏览器工具集支持多个提供商。有关 Browserbase、Browser Use 及本地 Chrome CDP 设置的详细信息，请参阅 浏览器功能页面。

时区​

使用 IANA 时区字符串覆盖服务器本地时区。影响日志中的时间戳、定时任务调度以及系统提示中的时间注入。

timezone: "America/New_York"   # IANA timezone (default: "" = server-local time)

支持的值：任意 IANA 时区标识符（例如 America/New_York、Europe/London、Asia/Kolkata、UTC）。留空或省略则使用服务器本地时间。

Discord​

为消息网关配置 Discord 特定行为：

discord:
  require_mention: true          # Require @mention to respond in server channels
  free_response_channels: ""     # Comma-separated channel IDs where bot responds without @mention
  auto_thread: true              # Auto-create threads on @mention in channels
  • require_mention — 当 true（默认）时，机器人仅在被提及（含 @BotName）时回复服务器频道中的消息。私信始终无需提及即可响应。
  • free_response_channels — 逗号分隔的频道 ID 列表，机器人在此类频道中对所有消息自动响应，无需提及。
  • auto_thread — 当 true（默认）时，频道中的提及会自动创建线程进行对话，保持频道整洁（类似 Slack 的线程功能）。

安全性​

执行前的安全扫描与敏感信息脱敏：

security:
  redact_secrets: true           # Redact API key patterns in tool output and logs
  tirith_enabled: true           # Enable Tirith security scanning for terminal commands
  tirith_path: "tirith"          # Path to tirith binary (default: "tirith" in $PATH)
  tirith_timeout: 5              # Seconds to wait for tirith scan before timing out
  tirith_fail_open: true         # Allow command execution if tirith is unavailable
  website_blocklist:             # See Website Blocklist section below
    enabled: false
    domains: []
    shared_files: []
  • redact_secrets — 自动检测并脱敏工具输出中看起来像 API 密钥、令牌和密码的模式，防止其进入对话上下文和日志。
  • tirith_enabled — 当 true 时，终端命令在执行前会由 Tirith 扫描，以检测潜在危险操作。
  • tirith_path — Tirith 可执行文件路径。如果 Tirith 安装在非标准位置，请设置此项。
  • tirith_timeout — Tirith 扫描的最大等待时间（秒）。若扫描超时，命令仍将继续执行。
  • tirith_fail_open — 当 true（默认）时，若 Tirith 不可用或失败，命令仍允许执行。设为 false 可在 Tirith 无法验证时阻止命令执行。

网站黑名单​

阻止特定域名被代理的网页和浏览器工具访问：

security:
  website_blocklist:
    enabled: false               # Enable URL blocking (default: false)
    domains:                     # List of blocked domain patterns
      - "*.internal.company.com"
      - "admin.example.com"
      - "*.local"
    shared_files:                # Load additional rules from external files
      - "/etc/hermes/blocked-sites.txt"

启用后，任何匹配黑名单域名规则的 URL 都会在网页或浏览器工具执行前被拒绝。此规则适用于 web_search、web_extract、browser_navigate 以及所有访问 URL 的工具。

域名规则支持：

  • 精确域名：admin.example.com
  • 通配符子域名：*.internal.company.com（阻断所有子域名）
  • 通配符顶级域：*.local

共享文件中每行一个域名规则（空行和 # 注释会被忽略）。文件缺失或不可读时会记录警告，但不会禁用其他网页工具。

策略缓存时间为 30 秒，因此配置更改可快速生效，无需重启。

智能审批​

控制 Hermes 如何处理潜在危险命令：

approvals:
  mode: manual   # manual | smart | off
模式行为
manual（默认）在执行任何标记命令前向用户发起确认请求。在 CLI 中显示交互式审批对话框；在消息平台中将审批请求排队等待。
smart使用辅助 LLM 评估标记命令是否真正危险。低风险命令将自动批准，并在会话级别持久化。高风险命令将升级至用户确认。
off跳过所有审批检查。等同于 HERMES_YOLO_MODE=true。请谨慎使用。

智能模式特别有助于减少审批疲劳——让代理在安全操作上更自主地工作，同时仍能捕捉真正具有破坏性的命令。

warning

设置 approvals.mode: off 将禁用所有终端命令的安全检查。仅在受信任的沙箱环境中使用。

检查点​

在破坏性文件操作前自动创建文件系统快照。详情请参见 检查点与回滚。

checkpoints:
  enabled: true                  # Enable automatic checkpoints (also: hermes --checkpoints)
  max_snapshots: 50              # Max checkpoints to keep per directory

委托​

配置 delegate 工具的子代理行为：

delegation:
  # model: "google/gemini-3-flash-preview"  # Override model (empty = inherit parent)
  # provider: "openrouter"                  # Override provider (empty = inherit parent)
  # base_url: "http://localhost:1234/v1"    # Direct OpenAI-compatible endpoint (takes precedence over provider)
  # api_key: "local-key"                    # API key for base_url (falls back to OPENAI_API_KEY)

子代理提供方/模型覆盖：
默认情况下，子代理继承父代理的提供方和模型。可通过设置 delegation.provider 和 delegation.model 将子代理路由到不同的提供方/模型组合——例如，对范围狭窄的子任务使用廉价快速的模型，而主代理则运行昂贵的推理模型。

直接端点覆盖：
若需使用明确的自定义端点路径，请设置 delegation.base_url、delegation.api_key 和 delegation.model。这将使子代理直接发送至该 OpenAI 兼容端点，并优先于 delegation.provider。若 delegation.api_key 被省略，Hermes 将仅回退至 OPENAI_API_KEY。

委托提供方使用与 CLI/gateway 启动时相同的凭证解析机制。所有已配置的提供方均受支持：openrouter、nous、copilot、zai、kimi-coding、minimax、minimax-cn。当提供方设置后，系统会自动解析正确的基础 URL、API 密钥和 API 模式——无需手动配置凭证。

优先级顺序：
delegation.base_url（配置中）→ delegation.provider（配置中）→ 父提供方（继承）。
delegation.model（配置中）→ 父模型（继承）。
仅设置 model 而不设置 provider 仅更改模型名称，保留父代理的凭证（适用于在同一提供方内切换模型，如 OpenRouter）。

明确化​

配置明确化提示行为：

clarify:
  timeout: 120                 # Seconds to wait for user clarification response

上下文文件（SOUL.md、AGENTS.md）​

Hermes 使用两种不同的上下文作用域：| 文件 | 用途 | 作用范围 | |------|------|--------| | SOUL.md | 主代理身份 — 定义代理的身份（系统提示中的第 #1 位置） | ~/.hermes/SOUL.md 或 $HERMES_HOME/SOUL.md | | .hermes.md / HERMES.md | 项目特定指令（最高优先级） | 从 Git 仓库根目录开始遍历 | | AGENTS.md | 项目特定指令，编码规范 | 递归目录遍历 | | CLAUDE.md | Claude Code 上下文文件（也支持检测） | 仅限工作目录 | | .cursorrules | Cursor IDE 规则（也支持检测） | 仅限工作目录 | | .cursor/rules/*.mdc | Cursor 规则文件（也支持检测） | 仅限工作目录 |

  • SOUL.md 是代理的核心身份标识。它占据系统提示中的第 #1 位置，完全取代内置的默认身份。通过编辑该文件可彻底自定义代理的身份。
  • 若 SOUL.md 缺失、为空或无法加载，Hermes 将回退至内置的默认身份。
  • 项目上下文文件采用优先级机制 —— 只加载其中一种类型（首个匹配项胜出）：.hermes.md → AGENTS.md → CLAUDE.md → .cursorrules。SOUL.md 始终独立加载。
  • AGENTS.md 具有层级结构：若子目录中也存在 AGENTS.md，则所有文件将合并处理。
  • Hermes 会自动创建一个默认的 SOUL.md，前提是该文件不存在。
  • 所有加载的上下文文件均限制在 20,000 字符以内，并采用智能截断策略。

另请参阅：

工作目录​

上下文默认值
CLI (hermes)您运行命令时所在的当前目录
消息网关用户主目录 ~（可通过 MESSAGING_CWD 覆盖）
Docker / Singularity / Modal / SSH容器或远程机器内的用户主目录

覆盖工作目录的方法：

# In ~/.hermes/.env or ~/.hermes/config.yaml:
MESSAGING_CWD=/home/myuser/projects    # Gateway sessions
TERMINAL_CWD=/workspace                # All terminal sessions