托管作用域
托管作用域(Managed scope)允许管理员下发一套配置和 secrets 的基线,标准(非 root)用户无法覆盖这些内容。它面向大规模/组织级部署场景,IT 需要在一台机器上的所有用户之间固定某些配置,例如模型 provider、共享的 API base URL,或 security.redact_secrets: true。
当存在托管作用域时,对于它所固定的键,其指定的值会优先于用户的 ~/.kopi/config.yaml、~/.kopi/.env,甚至 shell 环境。其余所有内容仍完全由用户控制。
由包管理器管理的安装(declarative-distro / formula)会阻止所有配置修改,并提示你使用包管理器进行操作。托管作用域是另一套独立机制:它按单个键注入特定的不可变值,而不是锁定整个配置。两者相互独立,可以共存。
存放位置
托管作用域从系统级目录读取,默认为 /etc/kopi:
/etc/kopi/
├── config.yaml # managed config layer (wins over ~/.kopi/config.yaml)
└── .env # managed env layer (wins over ~/.kopi/.env + shell)
该目录和文件归 root 所有(目录权限为 0755,文件为 0644):所有人可读,仅管理员可写。文件系统权限就是强制机制——标准用户可以读取托管文件,但无法编辑它们。
两个文件都是可选的。托管目录或文件缺失仅表示"没有托管作用域",配置的解析结果与未启用该功能时完全一致。
迁移该目录
可以通过 KOPI_MANAGED_DIR 环境变量迁移该位置(用于容器或非 /etc 部署)。这是一个部署/引导阶段的旋钮——类似于 KOPI_HOME——由拥有托管文件的同一位管理员设置。Kopi Agent 绝不会将其持久化到任何 .env 中。
# Point managed scope at a custom directory (set by IT / the deployment, not the user)
export KOPI_MANAGED_DIR=/opt/org/kopi-policy
能够设置 KOPI_MANAGED_DIR 的用户可以把托管作用域指向自己控制的目录,从而绕过它。在实际部署中,该变量应由管理员固定(例如固化到服务单元 / 容器镜像中),而不应允许用户自行设置。kopi doctor 会报告最终解析出的托管目录,以便发现此类重定向。
优先级
对于托管层指定的键,优先级顺序如下(越靠前优先级越高):
| 层级 | config.yaml | .env |
|---|---|---|
| 1 | /etc/kopi/config.yaml(托管) | /etc/kopi/.env(托管) |
| 2 | ~/.kopi/config.yaml(用户) | ~/.kopi/.env(用户) |
| 3 | 内置默认值 | 已有的 shell 环境变量 |
合并是**叶级(leaf-level)**的:固定 model.default 并不会冻结 model.* 的其余部分。例如,托管的 config.yaml 设置为:
model:
default: org/standard-model
会为每个用户强制 model.default,同时让 model.fallback(以及所有其他键)仍由用户控制。
对于它所固定的键,托管作用域会有意优先于 shell 环境——否则它就算不上"托管"了。这是唯一一处会颠倒通常"环境变量覆盖 config.yaml"规则的地方,并且仅适用于托管层指定的具体键。
查看哪些内容被托管
kopi config # shows a header naming the managed source + the pinned keys
kopi doctor # reports the resolved managed dir + pinned key counts
如果你尝试修改一个被托管的值,Kopi Agent 会拒绝并指明来源:
$ kopi config set model.default my/model
Cannot set 'model.default': it is managed by your administrator
(/etc/kopi/config.yaml) and cannot be changed.
同样的规则也适用于托管的 secrets——对于被托管的 .env 所固定的环境变量键,kopi config set / setup 不会写入用户值。
设置托管作用域(管理员)
sudo mkdir -p /etc/kopi
# Pin some config values for every user on this machine
sudo tee /etc/kopi/config.yaml >/dev/null <<'YAML'
model:
provider: nous
security:
redact_secrets: true
YAML
# Optionally pin a shared, non-sensitive env value
sudo tee /etc/kopi/.env >/dev/null <<'ENV'
OPENAI_API_BASE=https://inference.example.com/v1
ENV
sudo chmod 0755 /etc/kopi
sudo chmod 0644 /etc/kopi/config.yaml /etc/kopi/.env
更改会在下次启动 Kopi Agent 时生效(格式错误的托管文件会记录详细的告警日志并被忽略——它绝不会阻塞启动,但管理员应检查 kopi doctor 以确认策略已生效)。
安全模型与限制(v1)
- 强制手段仅依赖文件系统权限。 如果用户对托管目录拥有写权限(或以
root身份运行 Kopi Agent),托管作用域就仅是建议性的。 - 托管的
.env对所有用户可读(0644),因此任何本地用户都能读取通过它下发的 secrets。它应仅用于共享的、非敏感的值(例如组织的 API base URL、功能默认值),而非高敏感度的 secrets。 - agent 自身的工具不会被硬性阻止使用托管的 env 值。 托管的环境变量会在启动时应用,但无法阻止 agent 在其自身的子进程 shell 中设置不同的值。v1 是针对普通用户的管理便利性边界,而非不可逃逸的沙箱。
以下内容明确不在 v1 范围内,未来可能会加入:
- agent 自身无法逃逸的硬性边界。
- macOS 和 Windows 上的原生托管位置(v1 以 Linux/POSIX 为优先)。
- 用于分层策略的 drop-in 片段目录(
managed.d/)。 - 签名 / 完整性校验的托管文件。
- 远程 / 设备管理(MDM)下发。
- 针对托管 secrets 的更严格(按组限定)权限。