跳到主要内容

配置

所有设置均存储在 ~/.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
提示

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
注意

代理具有与您的用户账户相同的文件系统访问权限。请使用 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

要求： $PATH 中需存在 apptainer 或 singularity 二进制文件。

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

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

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

常见终端后端问题​

如果终端命令立即失败，或终端工具被报告为禁用：

  • 本地（Local） — 无特殊要求。开始时最安全的默认选项。
  • 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 — 需要 apptainer 或 singularity 在 $PATH 中。这在 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（如果曾通过 hermes config set 保存过）。

注意

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
备注

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

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

技能设置​

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

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 文件列出要复制到工作树中的被忽略文件：

# .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 密钥）：

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 → Provider Plugins → Context Engine 浏览并选择可用的引擎。

有关内存插件的类似单选系统，请参阅 Memory Providers。

迭代预算压力​

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

阈值等级模型所见内容
70%警告[BUDGET: 63/90. 27 次迭代剩余。开始整合工作。]
90%警告[BUDGET WARNING: 81/90. 仅剩 9 次。立即响应。]

警告会注入到最后一个工具结果的 JSON 中（作为 _budget_warning 字段），而非作为独立消息——这保留了提示缓存机制，且不会破坏对话结构。

agent:
  max_turns: 90                # Max iterations per conversation turn (default: 90)

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

流式传输超时​

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

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

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

静默流检测会终止接收 SSE 心跳 ping 但无实际内容的连接。此机制对本地提供者完全禁用，因为它们在预填充期间不会发送心跳 ping。

上下文压力警告​

与迭代预算压力不同，上下文压力跟踪对话距离压缩阈值的接近程度——即上下文压缩触发以总结较早消息的临界点。这有助于您和代理了解对话是否正在变长。

进度等级发生什么
≥ 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。完整文档请参见 Credential Pools。

辅助模型​

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 兼容端点，请在 model: 部分设置 provider: custom。有关所有主模型提供者选项，请参阅 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
提示

每个辅助任务都有一个可配置的 timeout（以秒为单位）。默认值：vision 30 秒，web_extract 360 秒，approval 30 秒，compression 120 秒。如果你为辅助任务使用较慢的本地模型，请增加这些值。vision 还有一个独立的 download_timeout（默认 30 秒），用于 HTTP 图像下载——对于慢速连接或自托管图像服务器，请增加此值。

信息

上下文压缩有其自身的顶层 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 端点。

提示

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

注意

视觉功能需要多模态模型。 如果你设置 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。

提示

运行 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 时，网关会在支持的平台上将系统提示中的个人身份信息（PII）进行脱敏处理后再发送给 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 切换语音回复。详见 语音模式 以获取端到端设置及各平台的具体行为说明。

流式传输​

在完整响应生成前，逐个令牌地将内容流式传输到终端或消息平台，而非等待全部响应完成。

CLI 流式传输​

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

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

网关流式传输（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

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

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

备注

流式传输默认禁用。请在 ~/.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 键控私信，如常操作。
  • 无论设置为何，线程始终与父频道隔离；当设置为 true 时，线程内的每位参与者也会拥有自己的会话。

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

未授权私信行为​

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

unauthorized_dm_behavior: pair

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

快速命令​

定义自定义命令，运行 shell 命令而不调用大语言模型 —— 零 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。请谨慎使用。

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

注意

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

检查点​

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

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

委派​

配置委派工具的子代理行为：

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/网关启动时相同的凭证解析机制。所有已配置的提供者均受支持：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.mdClaude Code 上下文文件（也支持检测）当前工作目录
.cursorrulesCursor IDE 规则（也支持检测）当前工作目录
.cursor/rules/*.mdcCursor 规则文件（也支持检测）当前工作目录
  • SOUL.md 是代理的主要身份标识。它占据系统提示中的第 #1 位置，完全取代内置的默认身份。通过编辑此文件，可完全自定义代理的身份。
  • 如果缺少 SOUL.md 文件、文件为空或无法加载，Hermes 将回退到内置的默认身份。
  • 项目上下文文件使用优先级系统 —— 仅加载一种类型（首个匹配项胜出）：.hermes.md → AGENTS.md → CLAUDE.md → .cursorrules。SOUL.md 始终独立加载。
  • AGENTS.md 具有层级结构：如果子目录中也包含 AGENTS.md，所有文件将被合并。
  • 如果不存在 SOUL.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