Hermes 配置入门（Codex）

看不懂？让 AI 帮你配

把本页地址发给 Codex 或 OpenClaw，让它参考这篇教程直接帮你生成配置：

请参考 https://docs.codexzh.com/codex/hermes-config 帮我配置 Hermes

如果你是第一次接触 Hermes，可以把它理解成：

Hermes = 一个本地运行的 AI 助手框架
config.yaml = 它的总开关面板
你只要先会改 5 类配置，就能正常用：模型、备用模型、上下文压缩、助手行为、显示效果

先说结论

当前推荐的核心配置如下：

配置项	推荐值
默认模型	`gpt-5.5`
接口服务商	codexzh
接口地址	`https://api.codexzh.com/v1`
上下文窗口	272000
备用模型	`gpt-5.3-codex`
推理强度	medium
压缩触发阈值	0.72（用到 72% 开始压缩）

1. 配置文件在哪里？

Hermes 的主配置文件：

macOS / Linux：~/.hermes/config.yaml

直接打开编辑：

bash

nano ~/.hermes/config.yaml
# 或
vim ~/.hermes/config.yaml

只看内容：

bash

cat ~/.hermes/config.yaml

2. 最重要的几个配置块

不需要一开始把整个文件都看懂，先认识这 5 块。

model — 模型配置（最核心）

决定 Hermes 用哪个模型、走哪个接口：

yaml

model:
  default: gpt-5.5
  provider: custom
  base_url: https://api.codexzh.com/v1
  api_key: ${CODEXZH_API_KEY}
  api_mode: codex_responses
  context_length: 272000

字段说明：

default：默认模型名
provider：custom 表示自定义接口
base_url：接口地址，末尾带 /v1
api_key：API 密钥，建议用环境变量引用，不要明文写死
api_mode：接口协议类型，codexzh 填 codex_responses
context_length：上下文窗口大小（token 数）

零基础记住一句话

模型能不能用，先看这 6 个字段。

fallback_model — 备用模型

主模型临时异常、限流、不可用时，Hermes 自动切备用模型：

yaml

fallback_model:
  provider: custom
  model: gpt-5.3-codex
  base_url: https://api.codexzh.com/v1
  key_env: CODEXZH_API_KEY
  api_key: ${CODEXZH_API_KEY}
  api_mode: codex_responses

建议

零基础用户都保留备用模型，不然主模型一挂就直接中断。

compression — 上下文压缩

很多新手最容易忽略、但实际非常重要的部分：

yaml

compression:
  enabled: true
  threshold: 0.72
  target_ratio: 0.3
  protect_last_n: 32

字段说明：

enabled: true：开启上下文压缩
threshold: 0.72：当上下文用到 72% 时，开始压缩
target_ratio: 0.3：压缩后把核心内容收缩到更安全的比例
protect_last_n: 32：最近 32 条消息尽量不压缩

简单理解：

上下文 = 聊天记忆容量
压缩 = 把旧聊天摘要一下，给新内容腾地方
protect_last_n 越大，最近的对话越不容易被摘掉

这组配置属于比较稳、偏实用型：不会太早压缩，又能保住最近对话，适合 272k 大上下文模型。

agent — 助手行为

yaml

agent:
  max_turns: 60
  gateway_timeout: 1800
  restart_drain_timeout: 20
  verbose: false
  reasoning_effort: medium

重点关注：

max_turns：一轮任务最多允许模型连续工作多少步
gateway_timeout：长时间无活动多久超时（秒）
restart_drain_timeout：重启前给当前任务留多少秒收尾
reasoning_effort：推理强度，可选 low / medium / high

零基础建议

日常使用保留 medium 很稳，不建议一上来改成 high。

display — 显示效果

yaml

display:
  compact: false
  personality: kawaii
  busy_input_mode: interrupt
  show_reasoning: false
  streaming: true
  tool_progress: all

常用的 3 个：

streaming: true：边生成边显示，观感更顺
show_reasoning: false：一般建议关闭，减少干扰
tool_progress: all：能看到 Hermes 在做什么

3. 最小可用配置

如果只保留最核心、最适合新手的部分：

yaml

model:
  default: gpt-5.5
  provider: custom
  base_url: https://api.codexzh.com/v1
  api_key: ${CODEXZH_API_KEY}
  api_mode: codex_responses
  context_length: 272000

fallback_model:
  provider: custom
  model: gpt-5.3-codex
  base_url: https://api.codexzh.com/v1
  key_env: CODEXZH_API_KEY
  api_key: ${CODEXZH_API_KEY}
  api_mode: codex_responses

compression:
  enabled: true
  threshold: 0.72
  target_ratio: 0.3
  protect_last_n: 32

agent:
  reasoning_effort: medium
  max_turns: 60
  gateway_timeout: 1800
  restart_drain_timeout: 20

display:
  streaming: true
  show_reasoning: false
  tool_progress: all

这已经足够支撑大多数日常使用。

4. 零基础怎么改配置？

建议按这个顺序改：

只改模型名
确认 base_url 和 api_key
确认 context_length
保留压缩配置
重启 Hermes

最常见的修改场景：

换默认模型 — 把 default 改成你想用的模型名：

yaml

default: gpt-5.5  # 改成你要的模型

换接口地址 — 把 base_url 改成新服务商地址：

yaml

base_url: https://api.codexzh.com/v1

换密钥 — 通常不是改 config.yaml，而是改 ~/.hermes/.env：

bash

CODEXZH_API_KEY=sk-你的新密钥

这样更安全

把密钥放在 .env 文件里，config.yaml 里用 ${变量名} 引用，不要把密钥明文写进配置文件。

5. 改完后怎么重启？

改完配置后执行：

bash

hermes gateway restart

检查当前状态：

bash

hermes status

检查配置是否有明显问题：

bash

hermes config check

零基础记住这 3 个命令就够用了

hermes status
hermes config check
hermes gateway restart

6. 怎么判断配置已经生效？

看这几个点：

hermes status 里显示的模型是不是你改后的模型
网关状态是不是 running
发送一条消息时，是否能正常回复
长对话时，是否没有很快爆上下文

7. 新手最容易踩的坑

⚠️ 把 API Key 直接发给别人

不要把 ~/.hermes/.env 发出去，不要截图完整密钥。

模型名写错

服务商支持的是 gpt-5.5，你写成别的，就会报错。

接口协议不对

codexzh 使用的是 codex_responses，不要随便改成别的，除非你确认服务商协议不同。

上下文只改大、不配压缩

上下文再大也会用完，所以 compression 很重要。

改完不重启

很多人改完文件，忘了执行 hermes gateway restart。

8. 适合零基础用户的推荐配置思路

日常问答 / 写代码

保持 gpt-5.5
reasoning_effort: medium
streaming: true

长文档 / 长对话

保持 context_length: 272000
保留当前压缩配置

更稳定

保留 fallback_model

更简单

先不要碰 auxiliary、bedrock、smart_model_routing 这些高级项

9. 配置示例参考

关于 JSON 示例

Hermes 实际使用 YAML 格式（~/.hermes/config.yaml），下面的 JSON 示例仅用于教学说明字段结构，不能直接替换 YAML 文件使用。

新手最小配置（JSON 结构说明）

只包含最关键的部分，看懂这几块就能正常用起来：

json

{
  "model": {
    "default": "gpt-5.5",
    "provider": "custom",
    "base_url": "https://api.codexzh.com/v1",
    "api_key": "${CODEXZH_API_KEY}",
    "api_mode": "codex_responses",
    "context_length": 272000
  },
  "fallback_model": {
    "provider": "custom",
    "model": "gpt-5.3-codex",
    "base_url": "https://api.codexzh.com/v1",
    "api_key": "${CODEXZH_API_KEY}",
    "api_mode": "codex_responses"
  },
  "compression": {
    "enabled": true,
    "threshold": 0.72,
    "target_ratio": 0.3,
    "protect_last_n": 32
  },
  "agent": {
    "reasoning_effort": "medium",
    "max_turns": 60
  },
  "display": {
    "streaming": true,
    "show_reasoning": false,
    "tool_progress": "all"
  },
  "stt": {
    "enabled": true,
    "provider": "local",
    "local": {
      "model": "base"
    }
  }
}

完整配置参考（所有可用字段）

下面是包含所有常见字段的完整示例，按需取用，不需要的块可以直接删掉：

json

{
  "model": {
    "default": "gpt-5.5",
    "provider": "custom",
    "base_url": "https://api.codexzh.com/v1",
    "api_key": "${CODEXZH_API_KEY}",
    "api_mode": "codex_responses",
    "context_length": 272000
  },
  "fallback_model": {
    "provider": "custom",
    "model": "gpt-5.3-codex",
    "base_url": "https://api.codexzh.com/v1",
    "key_env": "CODEXZH_API_KEY",
    "api_key": "${CODEXZH_API_KEY}",
    "api_mode": "codex_responses"
  },
  "toolsets": ["hermes-cli"],
  "agent": {
    "max_turns": 60,
    "gateway_timeout": 1800,
    "restart_drain_timeout": 20,
    "tool_use_enforcement": "auto",
    "gateway_timeout_warning": 900,
    "gateway_notify_interval": 600,
    "verbose": false,
    "reasoning_effort": "medium",
    "personalities": {
      "helpful": "You are a helpful, friendly AI assistant.",
      "concise": "You are a concise assistant. Keep responses brief and to the point.",
      "technical": "You are a technical expert. Provide detailed, accurate technical information.",
      "creative": "You are a creative assistant. Think outside the box and offer innovative solutions.",
      "teacher": "You are a patient teacher. Explain concepts clearly with examples.",
      "kawaii": "You are a kawaii assistant! Use cute expressions like (◕‿◕), ★, ♪, and ~!"
    }
  },
  "terminal": {
    "backend": "local",
    "modal_mode": "auto",
    "cwd": ".",
    "timeout": 180,
    "persistent_shell": true,
    "lifetime_seconds": 300
  },
  "browser": {
    "inactivity_timeout": 120,
    "command_timeout": 30,
    "record_sessions": false,
    "allow_private_urls": false
  },
  "checkpoints": {
    "enabled": true,
    "max_snapshots": 50
  },
  "file_read_max_chars": 100000,
  "compression": {
    "enabled": true,
    "threshold": 0.72,
    "target_ratio": 0.3,
    "protect_last_n": 32
  },
  "smart_model_routing": {
    "enabled": false,
    "max_simple_chars": 160,
    "max_simple_words": 28,
    "cheap_model": {}
  },
  "auxiliary": {
    "vision":        { "provider": "auto", "timeout": 120 },
    "web_extract":   { "provider": "auto", "timeout": 360 },
    "compression":   { "provider": "auto", "timeout": 120 },
    "session_search":{ "provider": "auto", "timeout": 30 },
    "skills_hub":    { "provider": "auto", "timeout": 30 },
    "approval":      { "provider": "auto", "timeout": 30 },
    "mcp":           { "provider": "auto", "timeout": 30 },
    "flush_memories":{ "provider": "auto", "timeout": 30 },
    "title_generation": { "provider": "auto", "timeout": 30 }
  },
  "display": {
    "compact": false,
    "personality": "kawaii",
    "resume_display": "full",
    "busy_input_mode": "interrupt",
    "bell_on_complete": false,
    "show_reasoning": false,
    "streaming": true,
    "inline_diffs": true,
    "show_cost": false,
    "tool_progress": "all",
    "background_process_notifications": "all"
  },
  "privacy": {
    "redact_pii": false
  },
  "tts": {
    "provider": "edge",
    "edge": { "voice": "en-US-AriaNeural" },
    "openai": { "model": "gpt-4o-mini-tts", "voice": "alloy" }
  },
  "stt": {
    "enabled": true,
    "provider": "local",
    "local": { "model": "base" },
    "openai": { "model": "whisper-1" }
  },
  "memory": {
    "memory_enabled": true,
    "user_profile_enabled": true,
    "memory_char_limit": 2200,
    "user_char_limit": 1375,
    "nudge_interval": 10,
    "flush_min_turns": 6
  },
  "session_reset": {
    "mode": "both",
    "idle_minutes": 1440,
    "at_hour": 4
  },
  "custom_providers": [
    {
      "name": "codexzh",
      "base_url": "https://api.codexzh.com/v1",
      "key_env": "CODEXZH_API_KEY",
      "api_key": "${CODEXZH_API_KEY}",
      "api_mode": "codex_responses"
    },
    {
      "name": "Ccodezh",
      "base_url": "https://api.ccodezh.com",
      "key_env": "CCODEZH_API_KEY",
      "api_key": "${CCODEZH_API_KEY}",
      "api_mode": "codex_responses"
    }
  ],
  "code_execution": {
    "timeout": 300,
    "max_tool_calls": 50
  },
  "delegation": {
    "max_iterations": 50,
    "default_toolsets": ["terminal", "file", "web"]
  },
  "skills": {
    "creation_nudge_interval": 15
  }
}

完整配置各块说明：

toolsets：启用的工具集，hermes-cli 是基础终端工具
agent.personalities：预设人格，personality 字段引用这里的 key 名
terminal：终端执行环境，本地使用保持默认即可
browser：浏览器工具配置，不用浏览器功能时忽略
checkpoints：对话存档，建议保留，出问题可以回滚
smart_model_routing：智能路由（根据问题复杂度自动切换模型），新手保持 false
auxiliary：各类辅助任务（视觉、压缩、MCP 等）使用的子模型，auto 表示跟主模型走
tts / stt：语音合成 / 语音识别，不需要可以删掉整块
memory：长期记忆功能配置
session_reset：会话自动重置策略
custom_providers：自定义服务商列表，支持同时配置多个

一句话理解这套 Hermes 配置

用 codexzh 作为自定义接口，默认跑 gpt-5.5，备用 gpt-5.3-codex，明确指定 272k 上下文，打开流式输出，用较稳妥的压缩策略保证长对话不容易炸。

对新手来说，这套配置已经是能直接用、也比较稳的方案。

Hermes 配置入门（Codex） ​

先说结论 ​

1. 配置文件在哪里？ ​

2. 最重要的几个配置块 ​

model — 模型配置（最核心） ​

fallback_model — 备用模型 ​

compression — 上下文压缩 ​

agent — 助手行为 ​

display — 显示效果 ​

3. 最小可用配置 ​

4. 零基础怎么改配置？ ​

5. 改完后怎么重启？ ​

6. 怎么判断配置已经生效？ ​

7. 新手最容易踩的坑 ​

8. 适合零基础用户的推荐配置思路 ​

9. 配置示例参考 ​

新手最小配置（JSON 结构说明） ​

完整配置参考（所有可用字段） ​

一句话理解这套 Hermes 配置 ​

Hermes 配置入门（Codex）

先说结论

1. 配置文件在哪里？

2. 最重要的几个配置块

model — 模型配置（最核心）

fallback_model — 备用模型

compression — 上下文压缩

agent — 助手行为

display — 显示效果

3. 最小可用配置

4. 零基础怎么改配置？

5. 改完后怎么重启？

6. 怎么判断配置已经生效？

7. 新手最容易踩的坑

8. 适合零基础用户的推荐配置思路

9. 配置示例参考

新手最小配置（JSON 结构说明）

完整配置参考（所有可用字段）

一句话理解这套 Hermes 配置