跳到主要内容

托管作用域

**托管作用域（Managed scope）**允许管理员推送一组配置和密钥的基线，标准用户（非 root 用户）无法覆盖这些设置。它适用于车队或组织部署场景，其中 IT 部门需要在机器上的每个用户之间固定某些设置，例如模型提供商、共享 API 基础 URL，或 security.redact_secrets: true。

当存在托管作用域时，对于其指定的键，其值优先于用户的 ~/.hermes/config.yaml、~/.hermes/.env 甚至 Shell 环境变量——但仅限于它所固定的那些键。其他所有配置仍完全由用户控制。

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

由包管理器管理的安装（声明式发行版 / formula）会阻止所有配置变更，并提示你使用包管理器。托管作用域是一种独立的机制：它基于每个键注入特定的不可变值，而不是锁定整个配置。两者相互独立，可以共存。

存储位置​

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

/etc/hermes/
├── config.yaml     # managed config layer (wins over ~/.hermes/config.yaml)
└── .env            # managed env layer (wins over ~/.hermes/.env + shell)

该目录和文件归 root 所有（目录权限为 0755，文件权限为 0644）：所有人可读，仅管理员可写。文件系统权限即为强制执行机制——标准用户可以读取托管文件，但无法编辑它们。

这两个文件都是可选的。如果缺少托管目录或缺少文件，则意味着“无托管作用域”，配置解析方式将与未启用此功能时完全相同。

重定位目录​

可以通过 HERMES_MANAGED_DIR 环境变量重定位该目录的位置（适用于容器或非 /etc 部署）。这是一个部署/引导路径调节项——类似于 HERMES_HOME——由拥有托管文件的同一位管理员设置。Hermes 绝不会将其持久化到任何 .env 文件中。

# Point managed scope at a custom directory (set by IT / the deployment, not the user)
export HERMES_MANAGED_DIR=/opt/org/hermes-policy
注意

能够设置 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        # shows a header naming the managed source + the pinned keys
hermes doctor        # reports the resolved managed dir + pinned key counts

如果你尝试更改托管值，Hermes 将拒绝该操作并指明来源：

$ hermes config set model.default my/model
Cannot set 'model.default': it is managed by your administrator
(/etc/hermes/config.yaml) and cannot be changed.

这同样适用于托管密钥——hermes config set 或 setup 命令不会为被托管 .env 固定的环境键写入用户值。

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

sudo mkdir -p /etc/hermes

# Pin some config values for every user on this machine
sudo tee /etc/hermes/config.yaml >/dev/null <<'YAML'
model:
  provider: nous
security:
  redact_secrets: true
YAML

# Optionally pin a shared, non-sensitive env value
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 基础 URL、功能默认值），而不是高敏感性的密钥。
  • 代理自身的工具不会被硬性地阻止使用托管的 env 值。 托管环境变量在启动时应用，但没有任何机制阻止代理在其自身的子进程 Shell 中设置不同的值。v1 是针对普通用户的管理便利边界，而非不可逃逸的沙箱。

以下内容在 v1 中故意不在范围内，可能会在后续版本中加入：

  • 代理本身无法逃逸的硬性边界。
  • macOS 和 Windows 上的原生托管位置（v1 优先支持 Linux/POSIX）。
  • 用于分层策略的drop-in片段目录（managed.d/）。
  • 签名/完整性检查的托管文件。
  • 远程/设备管理（MDM）交付。
  • 更严格的（组范围）托管密钥权限。