高级配置

所有设置存储在 ~/.hermes/ 目录下，方便随时访问。

目录结构

~/.hermes/
├── config.yaml      # 设置（模型、终端、TTS、压缩等）
├── .env             # API Key 和密钥
├── auth.json        # OAuth 提供商凭据（Nous Portal 等）
├── SOUL.md          # 主 Agent 身份（系统提示词插槽 #1）
├── memories/        # 持久化记忆（MEMORY.md, USER.md）
├── skills/          # Agent 创建的技能（通过 skill_manage 工具管理）
├── cron/            # 定时任务
├── sessions/        # 网关会话
└── logs/            # 日志（errors.log, gateway.log — 密钥自动脱敏）

配置管理命令

hermes config               # 查看当前配置
hermes config edit          # 在编辑器中打开 config.yaml
hermes config set KEY VAL   # 设置特定值
hermes config check         # 检查缺失的选项（更新后运行）
hermes config migrate       # 交互式添加缺失选项

# 示例：
hermes config set model anthropic/claude-opus-4
hermes config set terminal.backend docker
hermes config set OPENROUTER_API_KEY sk-or-...    # 保存到 .env

提示

hermes config set 命令会自动将值路由到正确的文件 — API Key 保存到 .env，其他保存到 config.yaml。

配置优先级

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

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

环境变量替换

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

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

delegation:
  api_key: ${DELEGATION_KEY}

• 支持单值中的多个引用：url: "${HOST}:${PORT}"
• 如果引用的变量未设置，占位符保持原样
• 仅支持 ${VAR} 语法，不支持裸 $VAR

终端后端配置

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

terminal:
  backend: local              # local | docker | ssh | modal | daytona | singularity
  cwd: "."                    # 网关/定时任务工作目录（CLI 始终使用启动目录）
  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	本机直接执行	无	开发、个人使用
docker	单个持久化 Docker 容器	完全（命名空间、cap-drop）	安全沙盒、CI/CD
ssh	通过 SSH 远程服务器	网络边界	远程开发、强力硬件
modal	Modal 云沙盒	完全（云 VM）	临时云计算、评测
daytona	Daytona 工作区	完全（云容器）	托管云开发环境
singularity	Singularity/Apptainer 容器	命名空间（—containall）	HPC 集群、共享机器

Local 后端

默认后端。命令直接在本机执行，无隔离。无需特殊设置。

terminal:
  backend: local

警告

Agent 拥有与你的用户账户相同的文件系统访问权限。使用 hermes tools 禁用不需要的工具，或切换到 Docker 进行沙盒隔离。

Docker 后端

在 Docker 容器内运行命令，具有安全加固（所有能力丢弃、禁止特权升级、PID 限制）。

Hermes 在首次使用时启动一个长生命周期容器，所有终端、文件和 execute_code 调用都通过 docker exec 路由到同一个容器 — 跨会话、/new、/reset 和 delegate_task 子代理。工作目录变更、已安装包和 /workspace 中的文件在工具调用之间保持不变。

terminal:
  backend: docker
  docker_image: "nikolaik/python-nodejs:python3.11-nodejs20"
  docker_mount_cwd_to_workspace: false       # 将启动目录挂载到 /workspace
  docker_run_as_host_user: false             # 以宿主用户身份运行容器
  docker_forward_env:                        # 转发到容器的环境变量
    - "GITHUB_TOKEN"
  docker_volumes:                            # 宿主目录挂载
    - "/home/user/projects:/workspace/projects"
    - "/home/user/data:/data:ro"             # :ro 表示只读
  docker_extra_args:                         # 附加到 docker run 的额外参数
    - "--gpus=all"
    - "--network=host"

  # 资源限制
  container_cpu: 1              # CPU 核心数（0 = 无限制）
  container_memory: 5120        # MB（0 = 无限制）
  container_disk: 51200         # MB（需要 overlay2 on XFS+pquota）
  container_persistent: true    # 跨会话持久化 /workspace 和 /root

安全加固措施：

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

提示

使用 docker_volumes 与容器共享宿主目录。每个条目使用标准 Docker -v 语法：host_path:container_path[:options]。

SSH 后端

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

terminal:
  backend: ssh
  persistent_shell: true        # 保持长生命周期 bash 会话（默认: true）

必需的环境变量：

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

可选：

变量	默认值	说明
TERMINAL_SSH_PORT	22	SSH 端口
TERMINAL_SSH_KEY	系统默认	SSH 私钥路径
TERMINAL_SSH_PERSISTENT	true	启用持久化 Shell

Modal 后端

在 Modal 云沙盒中运行命令。每个任务获得一个隔离 VM，可配置 CPU、内存和磁盘。

terminal:
  backend: modal
  container_cpu: 1
  container_memory: 5120        # 5GB
  container_disk: 51200         # 50GB
  container_persistent: true    # 快照/恢复文件系统

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

Daytona 后端

在 Daytona 托管工作区中运行命令。支持停止/恢复持久化。

terminal:
  backend: daytona
  container_cpu: 1
  container_memory: 5120        # MB → 转换为 GiB
  container_disk: 10240         # MB → 转换为 GiB（最大 10 GiB）
  container_persistent: true    # 停止/恢复而非删除

需要 DAYTONA_API_KEY 环境变量。Daytona 强制 10 GiB 磁盘上限。

Singularity/Apptainer 后端

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

terminal:
  backend: singularity
  singularity_image: "docker://nikolaik/python-nodejs:python3.11-nodejs20"
  container_cpu: 1
  container_memory: 5120
  container_persistent: true    # 可写 overlay 跨会话持久化

需要 apptainer 或 singularity 在 $PATH 中。

常见终端后端问题

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

• Local — 无特殊要求，最安全的默认选择
• Docker — 运行 docker version 验证 Docker 是否正常工作
• SSH — 必须设置 TERMINAL_SSH_HOST 和 TERMINAL_SSH_USER
• Modal — 需要 MODAL_TOKEN_ID 或 ~/.modal.toml。运行 hermes doctor 检查
• Daytona — 需要 DAYTONA_API_KEY
• Singularity — 需要 apptainer 或 singularity 在 $PATH 中

拿不准时，先设回 terminal.backend: local 验证命令能否正常运行。

资源限制

terminal:
  timeout: 180                   # 每条命令超时（秒）
  container_cpu: 1               # CPU 核心数（0 = 无限制）
  container_memory: 5120         # 内存限制 MB（0 = 无限制）
  container_disk: 51200          # 磁盘限制 MB（0 = 无限制）

model:
  max_context_tokens: 128000     # 上下文窗口上限
  max_output_tokens: 16384       # 单次输出上限

memory:
  max_entries: 1000              # 记忆条目上限
  max_file_size_kb: 500          # 单个记忆文件大小上限

compression:
  enabled: true                  # 启用上下文压缩
  threshold: 0.8                 # 上下文使用率阈值（触发压缩）

远程文件同步

对于 SSH、Modal 和 Daytona 后端，Hermes 会追踪 Agent 在远程沙盒中触碰的文件，并在会话拆卸/沙盒清理时将修改的文件同步回宿主机的 ~/.hermes/cache/remote-syncs/<session-id>/。

terminal:
  file_sync_max_mb: 100          # 默认 — 同步最大 100 MB 的文件
  file_sync_enabled: true        # 默认 — 设 false 可完全跳过同步

触发时机：会话关闭、/new、/reset、网关消息超时、使用远程后端的子代理完成。