跳到主要內容

託管作用域

**託管作用域（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）交付。
  • 更嚴格的（組範圍）託管密鑰權限。