托管作用域

托管作用域让管理员可以推送一套配置与机密基线，而普通（非 root）用户无法覆盖。它面向机群/组织部署：IT 需要在一台机器上为所有用户锁定例如模型提供商、共享的 API base URL 或 security.redact_secrets: true。

当托管作用域存在时，它指定的值会在其所锁定的确切键上，优先于用户的 ~/.hermes/config.yaml、~/.hermes/.env，甚至 shell 环境。其余一切仍完全由用户掌控。

不同于包管理器锁定的安装

包管理器托管的安装（声明式发行版/formula）会阻止所有配置改动，并让你用包管理器去改。托管作用域是另一套机制：它按键注入特定的不可变值，而不是锁定整个配置。两者相互独立，可以共存。

它在哪里

托管作用域从一个系统级目录读取，默认 /etc/hermes：

/etc/hermes/
├── config.yaml     # 托管配置层（优先于 ~/.hermes/config.yaml）
└── .env            # 托管环境层（优先于 ~/.hermes/.env + shell）

该目录和文件归 root 所有（目录模式 0755，文件 0644）：所有人可读，只有管理员可写。文件系统权限就是强制执行机制——普通用户可以读取托管文件，但不能编辑。

两个文件都是可选的。托管目录缺失或文件缺失，就意味着"没有托管作用域"，配置的解析与没有该功能时完全一样。

搬迁目录位置

位置可通过 HERMES_MANAGED_DIR 环境变量搬迁（用于容器或非 /etc 部署）。这是一个部署/启动引导旋钮——类似 HERMES_HOME——由拥有托管文件的同一个管理员设置。Hermes 绝不会把它持久化到任何 .env。

# 把托管作用域指向自定义目录（由 IT/部署方设置，而非用户）
export HERMES_MANAGED_DIR=/opt/org/hermes-policy
WARNING

一个能设置 HERMES_MANAGED_DIR 的用户，可以把托管作用域重指向他自己控制的目录，从而绕过它。在真实部署中，这个变量应由管理员固定（例如烧进服务单元/容器镜像），不能留给用户自设。hermes doctor 会报告解析后的托管目录，因此重定向会被看到。

优先级

对于托管层指定的键，顺序如下（最高者胜出）：

层级config.yaml.env
1/etc/hermes/config.yaml（托管）/etc/hermes/.env（托管）
2~/.hermes/config.yaml（用户）~/.hermes/.env（用户）
3内置默认值已存在的 shell 环境

合并是叶子级的：锁定 model.default 不会冻结 model.* 的其余部分。一份托管 config.yaml：

model:
  default: org/standard-model

会为每个用户强制 model.default，同时把 model.fallback（以及其他每个键）留给用户控制。

优先级说明

对于它锁定的键，托管作用域刻意也优先于 shell 环境——否则就不是"托管"了。这是唯一反转"环境变量覆盖 config.yaml"常规规则的地方，且仅适用于托管层指定的具体键。

查看哪些被托管了

hermes config        # 显示一个标题，说明托管来源 + 被锁定的键
hermes doctor        # 报告解析后的托管目录 + 被锁定的键数量

如果你尝试改一个托管值，Hermes 会拒绝并指明来源：

$ hermes config set model.default my/model
无法设置 'model.default'：它由你的管理员托管
(/etc/hermes/config.yaml)，无法更改。

托管机密同理——对于被托管 .env 锁定的环境变量键，hermes config set/setup 不会写入用户值。

设置托管作用域（管理员）

sudo mkdir -p /etc/hermes

# 为这台机器上的每个用户锁定一些配置值
sudo tee /etc/hermes/config.yaml >/dev/null <<'YAML'
model:
  provider: nous
security:
  redact_secrets: true
YAML

# 可选：锁定一个共享的、非敏感的环境值
sudo tee /etc/hermes/.env >/dev/null <<'ENV'
OPENAI_API_BASE=https://inference.example.com/v1
ENV

sudo chmod 0755 /etc/hermes
sudo chmod 0644 /etc/hermes/config.yaml /etc/hermes/.env

改动在下次 Hermes 启动时生效（畸形的托管文件会被大声记录并忽略——它绝不阻塞启动，但管理员应检查 hermes doctor 以确认策略已被应用）。

安全模型与限制（v1）

  • 强制执行仅靠文件系统权限。 如果一个用户对托管目录有写权限（或以 root 运行 Hermes），托管作用域只是建议性的。
  • 托管 .env 是全局可读的（0644），因此任何本地用户都能读到经它推送的机密。把它用于共享的、非敏感的值（组织 API base URL、功能默认值），而不是高敏感度机密。
  • agent 自己的工具不会被硬阻挡于托管 env 值之外。 托管环境变量在启动时应用，但没有什么能阻止 agent 在自己的子进程 shell 里设置另一个值。v1 是面向普通用户的管理便利边界，而非无法逃脱的沙箱。

以下内容在 v1 中有意排除，可能后续加入：

  • agent 自身无法逃脱的硬边界。
  • macOS 和 Windows 上的原生托管位置（v1 以 Linux/POSIX 优先）。
  • 用于分层策略的 drop-in 片段目录（managed.d/）。
  • 已签名/完整性校验的托管文件。
  • 远程/设备管理（MDM）下发。
  • 更严格的（按组划分的）托管机密权限。