---
title: "03 · 配置、Provider 与目录结构"
description: "理解 Hermes 的 ~/.hermes 目录、config.yaml、.env、auth.json、SOUL.md、provider、timeout 和 terminal backend。"
verifiedAt: "2026-05-09"
---

Hermes 的**配置中心**是 `~/.hermes/`。理解这个目录，比记住单个命令更重要——大多数 Hermes 问题不是"命令不会用"，而是密钥、模型、目录、身份、记忆、session 或执行环境**混在一起**：把 API key 放进了 config.yaml、把项目级规则塞进了全局 SOUL.md、把 OAuth 凭据手动复制到了错误位置。

官方资料：[Configuration](https://hermes-agent.nousresearch.com/docs/user-guide/configuration)、[Providers](https://hermes-agent.nousresearch.com/docs/integrations/providers)、[Tools & Toolsets](https://hermes-agent.nousresearch.com/docs/user-guide/features/tools)、[Configuring Models](https://hermes-agent.nousresearch.com/docs/user-guide/configuring-models)、[Profiles](https://hermes-agent.nousresearch.com/docs/user-guide/profiles)。

> [!NOTE]
> **先给结论**：`config.yaml` 管普通设置，`.env` 管 secret（密钥），`auth.json` 管 OAuth 凭据，`SOUL.md` 管**全局**长期身份，`terminal.backend` 管命令执行位置。Provider 先配一个跑稳，再加 fallback（备用切换）和 routing（路由）——多 provider 排障复杂度是单 provider 的好几倍。

## 配置目录

核心结构：

```text
~/.hermes/
├── config.yaml
├── .env
├── auth.json
├── SOUL.md
├── memories/
├── skills/
├── cron/
├── sessions/
└── logs/
```

每个文件解决的是不同的"该把什么放进 system prompt"问题——分工如下：

```mermaid
flowchart LR
    subgraph CFG["配置层 · 决定 Hermes 怎么跑"]
        C1["config.yaml<br/>非密钥设置<br/>(可进 git)"]
        C2[".env<br/>密钥<br/>(.gitignore)"]
        C3["auth.json<br/>OAuth 凭据<br/>(自动写入)"]
    end
    subgraph IDENT["身份层 · 决定 Hermes 是谁"]
        S1["SOUL.md<br/>全局人格"]
        P1["AGENTS.md / CLAUDE.md<br/>.hermes.md<br/>项目级规则"]
    end
    subgraph PERSIST["持久化层 · 决定 Hermes 记得什么"]
        M1["memories/<br/>MEMORY.md + USER.md"]
        SK1["skills/<br/>可复用流程"]
        SE1["sessions/<br/>会话历史"]
    end
    subgraph RUN["运行时 · Hermes 在做什么"]
        CR1["cron/<br/>定时任务"]
        LG1["logs/<br/>排障证据"]
    end
    CFG -->|"启动注入"| SP[("system prompt<br/>每次会话开头")]
    IDENT -->|"启动注入"| SP
    PERSIST -->|"启动注入"| SP
    SP -.->|"运行中产生"| RUN
    style C2 fill:#fde2e2,stroke:#c43d3d
    style SP fill:#fde7c2,stroke:#d4761a
```

红色 `.env` 是必须严守的边界——它**不进 system prompt**，也**不进 git**，只通过环境变量在 backend 进程里被读取。下面 6 张卡是同一份分工的逐项细节：

<Cards>
  <Card title="config.yaml" description="普通配置：model、terminal backend、toolsets、压缩策略、memory 开关、display 等——可进 git 的非密钥设置。" />
  <Card title=".env" description="密钥：API key、bot token、password、webhook secret、backend 凭据——必须在 .gitignore 里。" />
  <Card title="auth.json" description="OAuth 凭据，例如 Nous Portal、OpenAI Codex、Anthropic Claude（Max plan）、GitHub Copilot 等——hermes model 交互登录后自动写入。" />
  <Card title="SOUL.md" description="全局长期身份和行为原则，进入 system prompt（系统提示）的靠前位置；项目级规则放 AGENTS.md / CLAUDE.md / .hermes.md。" />
  <Card title="memories / skills" description="长期事实（MEMORY.md / USER.md）与可复用流程（agent-created skills + 手动 skill）。" />
  <Card title="sessions / logs" description="会话和日志，是排障时最重要的证据——出问题先看 logs，不要直接改配置。" />
</Cards>

## 配置和密钥分工

`config.yaml` 存普通设置，`.env` 存 secrets。

如果某个值既像设置又像密钥，按密钥处理。典型例子：API key（API 密钥）、bot token（机器人凭据）、OAuth secret（开放授权密钥）、webhook secret（事件回调密钥）、SSH 连接凭据、sudo password（管理员密码）。

不要把 `.env` 贴进 issue、PR、分享会话、公开日志或教程正文。也不要让 agent 把 `.env` 作为普通上下文读取。

## 优先用 CLI

常用命令：

```bash
hermes config
hermes config edit
hermes config set KEY VALUE
hermes config check
hermes config migrate
```

`hermes config set` 会判断值类型：API key 进入 `.env`，普通配置进入 `config.yaml`。

示例（具体模型名按官方 [Configuring Models](https://hermes-agent.nousresearch.com/docs/user-guide/configuring-models) 当前推荐为准，不要在教程里写死版本号）：

```bash
hermes config set model openrouter/anthropic/claude-sonnet-4
hermes config set terminal.backend docker
hermes config set OPENROUTER_API_KEY sk-or-...   # 也可改写到 ~/.hermes/.env
```

手动编辑可以做，但**不要**绕过 `hermes config check` 和 `hermes doctor`——前者校验语法和必填字段，后者跑端到端自查。改完 yaml 不验证就启动，很容易把一个 typo 留到上线后才发现。

## Provider 策略

**第一次只配置一个 provider**。等基础闭环稳定后，再考虑多 provider、fallback（备用切换）或 routing（基于条件路由到不同 provider）。

选 provider 时看五个因素：

- **凭据稳定**：API key 长期可用，OAuth 流程能跑通；订阅型（Claude Max / Nous Portal）比 API key 更省事但成本固定。
- **模型上下文 ≥ 64K**：官方 quickstart 强制要求至少 64K tokens，Hermes 启动时直接拒绝低于此值的模型加载。
- **工具调用稳定**：模型对函数调用、长输出、多轮工具循环响应不掉链——这点不同模型差异比想象大，建议跑 quickstart 里的 prompt 实测。
- **成本可控**：注意 rate limit（速率限制）、按 token 计费 vs 订阅、限流后的退避策略。
- **网络可达**：当前网络能稳定连接该 provider；国内开发者没梯子优先选中国区直连（Z.AI / Kimi / DeepSeek / Qwen）。

Hermes 支持的 provider 很多，但这**不**代表应该全部启用。Provider 越多，排障越复杂——同一个"模型不回"症状可能来自主链路、fallback 链路、routing 规则、或某条 credential pool 里某个 key 失效，定位时间会指数级上升。

## Timeout 不等于稳定性

官方配置支持 provider 级和 model 级 timeout、stale timeout。它适合处理长请求或 provider 挂起，但不能修复错误模型、错误 key、错误 base URL 或 context 不足。

调整 timeout 前先确认：

- key 没错。
- model 名没错。
- base URL 没错。
- 网络能连。
- context size 足够。
- backend 没卡在 terminal 命令。

先修根因，再调 timeout。

## SOUL.md 边界

`SOUL.md` 适合写长期稳定的助手身份和工作原则。

适合写：

- 助手角色。
- 长期沟通偏好。
- 稳定安全边界。
- 工具使用原则。

不适合写：

- 本次任务。
- 临时路径。
- 短期计划。
- 会频繁变化的项目细节。

项目细节优先放项目自己的 `AGENTS.md`、`CLAUDE.md`、`.hermes.md` 或 context files，不要塞进全局 SOUL。

## Terminal backend

Terminal backend 决定命令在哪里执行。第一次跑通可以用 `local`，但它没有隔离。

```yaml
terminal:
  backend: local
  cwd: "."
  timeout: 180
```

选择原则：

- `local`：可信个人项目和低风险命令。
- `docker`：未知脚本、临时依赖、隔离执行。
- `ssh`：远程服务器、VPS、隔离主机。
- `modal` / `daytona` / `vercel_sandbox`：云端 sandbox 或 workspace。
- `singularity`：HPC 或共享机器。

命令在哪执行，决定它能读写哪些文件、看到哪些环境变量、影响哪些系统。这个问题必须在启用 terminal toolset 前说清楚。

## 每次变更后的验收

每次升级、迁移机器、切 provider、改 model、改 backend 后，先跑：

```bash
hermes config check    # 配置文件语法 + 必填字段校验
hermes doctor          # Hermes 端到端自查（依赖、PATH、配置、权限）
```

配置健康意味着下面 6 项**都能用一句话回答**——不能回答说明这一项还没真正搞清楚：

- **key 不缺**且**没**进入公开文件——验证：`grep -r "sk-" ~/.hermes/config.yaml` 应为空。
- **provider/model 能回**——验证：`hermes` 跑一次 quickstart 推荐的 prompt 收到正常回复。
- **session 能写入和恢复**——验证：完成对话后 `hermes --continue` 能接回上文。
- **logs 可读**——验证：`ls ~/.hermes/logs/` 看到当天日志，能 tail 看到刚才命令的痕迹。
- **command backend 明确**——验证：`hermes config show` 能看到 `terminal.backend: <值>`，不是默认推断。
- **最小工具调用可控**——验证：让 Hermes 跑一条只读命令，命令实际执行位置（cwd）符合预期。

## 官方资料

- [Configuration](https://hermes-agent.nousresearch.com/docs/user-guide/configuration)
- [Configuring Models](https://hermes-agent.nousresearch.com/docs/user-guide/configuring-models)
- [Providers 完整目录](https://hermes-agent.nousresearch.com/docs/integrations/providers)
- [Profiles](https://hermes-agent.nousresearch.com/docs/user-guide/profiles)（多 profile 切换）
- [Provider Routing](https://hermes-agent.nousresearch.com/docs/user-guide/features/provider-routing) / [Fallback Providers](https://hermes-agent.nousresearch.com/docs/user-guide/features/fallback-providers) / [Credential Pools](https://hermes-agent.nousresearch.com/docs/user-guide/features/credential-pools)

## 下一步

<Cards>
  <Card title="工具系统与终端后端" description="配置清楚后，下一步理解 toolset（调什么）和 terminal backend（在哪跑）的解耦设计。" href="/docs/hermes/understanding/04-tools-terminal-backends" />
  <Card title="配置手册" description="需要操作细节（具体 yaml 字段、命令）查官方教程中文版的配置页。" href="/docs/hermes/official/01-user-guide/configuration" />
</Cards>
