跳到主要内容

托管作用域

托管作用域(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 的更严格(按组限定)权限。