配置文件——让 Hermes 按你的喜好工作

好的，没问题！这是为您重写的博客文章，完全符合您的要求：

配置文件——让 Hermes 按你的喜好工作

嘿，朋友们！上次我们聊了怎么把 Hermes 请进家门，今天咱们来聊聊怎么给它“装修”一下，让它完全按你的喜好来工作。别担心，这事儿比你想的简单多了，咱们的目标是轻松上手，拒绝头秃。

你的私人控制台：`~/.hermes/` 文件夹

所有魔法都发生在一个叫 ~/.hermes/ 的文件夹里。你可以把它想象成 Hermes 的大脑和储物间，里面整整齐齐地放着各种重要文件：

config.yaml：这是主控台！模型、终端、语音、压缩……所有非秘密的设置都在这里。
.env：保险箱！专门存放 API 密钥、令牌、密码这类敏感信息。
SOUL.md：Hermes 的“人设”，定义它的身份和行为。
memories/：它的长期记忆库。
skills/：它学会的技能都存这儿。

偷懒大法：一条命令搞定一切

手动编辑 YAML 文件听起来有点麻烦？没问题，官方给了一条捷径：

hermes setup --portal

运行这条命令，通过一次 OAuth 授权，就能帮你搞定模型提供商和四个 Tool Gateway 工具，完全不用碰配置文件。而且，Portal 订阅用户还能享受 10% 的折扣，简直美滋滋。

配置命令：你的魔法棒

不想用 setup？那就用下面这些命令来管理配置，它们就像魔法棒一样好用：

hermes config              # 查看当前配置
hermes config edit         # 用编辑器打开 config.yaml
hermes config get model    # 查看当前模型
hermes config set model anthropic/claude-opus-4  # 切换模型
hermes config set terminal.backend docker        # 设置终端后端
hermes config unset terminal.backend             # 取消设置
hermes config check        # 检查是否有遗漏的配置项
hermes config migrate      # 交互式添加缺失的配置项

划重点：hermes config set 命令非常聪明，它会自动判断该把值写到哪个文件里。凡是全大写下划线格式的名字（比如 OPENROUTER_API_KEY、DISCORD_HOME_CHANNEL、HERMES_TIMEZONE）都当成环境变量，一律存进 .env，绝不写进 config.yaml；带点号的设置才进 config.yaml。其他全大写名字也会原样存进 .env（会导出给插件和技能用），但像 HERMES_YOLO_MODE、PATH 这种在黑名单上的名字会被拒绝。要是你把一个已知的键写错了前缀（比如 gateway.discord.foo，而 discord.foo 本身是个已知键），它会直接拒绝并提示你是不是想写别的，除非加 --force 硬写。其他未知路径（比如手滑打成 agent.max_turnz）会照写，但附带一条“你是不是想写……”的提醒。用 hermes config get 读这类路径时，它会把文件里的值打出来，同时在 stderr 提醒你 Hermes 可能根本不读它——所以残留的键不会悄悄冒充生效的设置。

配置的“江湖规矩”：优先级

当多个地方都有同一个设置时，听谁的？记住这个顺序（从高到低）：

命令行参数：比如 hermes chat --model xxx，只在本次对话中生效，权力最大。
config.yaml：你的主配置文件。
.env：环境变量的后备军。
内置默认值：Hermes 自带的“保底”设置。

一句话总结：秘密放 .env，其他放 config.yaml。如果两边都设了，非秘密设置以 config.yaml 为准。

进阶玩法：环境变量和数据库调优

你还可以在 config.yaml 里引用环境变量，比如 ${GOOGLE_API_KEY}，这样就能把密钥藏在环境里，更安全。如果引用的变量没设置，占位符会原样保留（${UNDEFINED_VAR} 还是 ${UNDEFINED_VAR}），并记录一条警告；裸写的 $VAR 不会被展开。Cursor 风格的 ${env:VAR_NAME} 写法也支持，效果和 ${VAR_NAME} 一样；而 ${file:...}、${vault:...}、${bitwarden:...} 这类外部密钥后端不会内联解析，需要在 secrets: 块里注入环境后以 ${env:NAME} 引用。另外，在多 profile 网关下，某个 profile 的 config.yaml 里的引用只在该 profile 自己的 .env 里查找，不会去读共享的进程环境。

另外，database: 部分可以微调 SQLite 数据库的性能，比如日志模式（journal_mode）和同步级别（synchronous），不过这些对新手来说可以先放一放，等玩熟了再研究也不迟。顺带一提，在 Docker Desktop、macOS 上的 Podman、OrbStack 这类 virtiofs/9p 挂载上，Hermes 会自动检测并把新建的数据库设成 delete 模式；但已经存在的 WAL 数据库不会被在线降级——你设了 journal_mode: delete 它也不会自动改，hermes doctor 会一直提醒你，直到你停掉所有 Hermes 进程、手动跑一次离线的 PRAGMA journal_mode=DELETE。这个提醒还会告诉你当前是哪些进程占着数据库（<db> is held by PID <n> (<command>)），方便你知道该关谁。

更新这件事，也值得说两句

Hermes 的后台更新检查（CLI 横幅、TUI 徽章、仪表盘、桌面应用）是直接问 GitHub REST API 要 main 分支的最新提交，不会跑 git fetch，而且每 24 小时最多查一次（失败后一小时重试）。想立刻查，可以用 hermes update --check，或者桌面端的“Check for Updates…”菜单、Settings → About → “Check now”，这些都会绕过缓存。

更新相关的设置都在 config.yaml 的 updates 下面：

updates:
  pre_update_backup: quick       # quick（状态快照，默认）| full（快照 + HERMES_HOME 打包）| off
  backup_keep: 5                 # 保留多少个完整更新前备份 zip
  non_interactive_local_changes: stash  # stash | discard
  auto_switch_parked_branch: true       # 干净且已完全合并的 parked 分支自动切回 main

pre_update_backup 是更新前唯一的安全开关：quick（默认）会把关键状态文件（配对数据、cron 任务、配置、认证；超过 1 GiB 的文件会跳过）快照到 state-snapshots/；full 还会把整个 HERMES_HOME 打包进 backups/，目录大的话可能要多等几分钟；off 则两者都关掉。旧的布尔写法也认（true → full，false → off）。

另外，config.yaml 本身也会留下时间点副本（在 hermes setup 重写前、hermes migrate 修改前、每次解析成功时、以及解析失败时），放在 backups/config/config.yaml.<原因>.<时间戳>。重复内容会跳过，每种原因只保留最新的五份。如果 config.yaml 坏了，Hermes 会用最新的 good 副本而不是内置默认值，并在每次启动时提醒你，直到 YAML 修好为止；坏掉的文件本身不会被改动。

对了，git 安装版在更新前会自动把改动的和未跟踪的文件 stash 起来，交互式更新会问你要不要恢复；非交互式更新（桌面/聊天应用、网关或 --yes）则看 updates.non_interactive_local_changes 这个设置：stash 会在拉取成功后恢复你本地的源码改动，discard 则直接丢掉更新时创建的 stash——后者只建议用在“本地源码改动本来就不该保留”的托管安装上。

好了，现在你已经掌握了配置 Hermes 的基本功。快去试试看，把它调教成你最趁手的AI助手吧！