1Password
在进程启动时从 1Password 解析 provider API key,而不是以明文形式存储在 ~/.kopi/.env 中。你将密钥保存为 1Password 条目,并通过 op://vault/item/field 引用它们;轮换凭据时只需在 1Password 中修改一处。
工作原理
- 安装官方 1Password CLI(
op)并完成身份验证——可以使用服务账号 token(无头服务器),也可以使用交互式/桌面会话(你的笔记本电脑)。 - 在
~/.kopi/config.yaml中将环境变量名映射到op://引用。 - 每次
kopi(或网关,或定时任务)启动时,在~/.kopi/.env加载完毕后,Kopi Agent 会为每个引用运行op read,并将解析出的值设置到os.environ中。 - 默认情况下,Kopi Agent 会覆盖环境中已有的值,因此 1Password 是唯一的可信来源——凭据只需轮换一次,所有 Kopi Agent 进程都会在下次启动时获取到新值。如果你希望
.env优先生效,则切换override_existing: false。
Kopi Agent 绝不会代你进行身份验证,也绝不会下载 op:它会调用你已安装、已信任的 CLI。如果 op 缺失、会话被锁定,或引用有误,Kopi Agent 会打印一行警告,并继续使用 .env 中已有的凭据——绝不会阻塞启动过程。
身份验证
op 支持两种对非交互式环境友好的模式;Kopi Agent 对两者均可兼容:
- 服务账号(推荐用于服务器/CI):在 1Password 中创建一个服务账号,授予其对相应 vault 的读取权限,并将其 token 以
OP_SERVICE_ACCOUNT_TOKEN的形式导出到~/.kopi/.env中。该 token 本身就是凭据——请像对待任何其他 bearer token 一样妥善保管。 - 桌面/交互式会话(笔记本电脑):运行
op signin(或在 1Password 应用中启用 CLI 集成)。Kopi Agent 会将你的OP_SESSION_*变量传递给op子进程。1Password 的缓存键包含这些会话变量,因此切换到不同账号登录后,绝不会返回之前身份下缓存的值。
引导 token
当你使用服务账号 token 进行身份验证时,该 token 本身就是 Kopi Agent 在解析任何 op:// 引用之前所需的引导凭据。它必须存在于每个解析密钥的进程的 os.environ 中——包括定时任务(kanban.dispatch_in_gateway: false)、子进程调用、CLI 运行、macOS launchd 代理和 Docker 容器——而不仅仅是交互式网关。有三种方式可以使其可用,按优先级顺序排列:
-
放在
~/.kopi/.env中(推荐)。kopi secrets onepassword setup --token <token>会将 token 写入~/.kopi/.env,与 Bitwarden 的BWS_ACCESS_TOKEN完全一致。由于load_kopi_dotenv()总是会加载.env,因此该 token 无需任何额外配置即可在各处使用。这是最简单可靠的方式。 -
放在
~/.kopi/.op.env中(已被 gitignore)。 如果你更希望将服务账号 token 排除在.env之外——例如让.env可以提交到私有 dotfiles 仓库,而 token 保持在版本控制之外——请将其放入~/.kopi/.op.env:echo 'OP_SERVICE_ACCOUNT_TOKEN=ops_...' > ~/.kopi/.op.env
chmod 600 ~/.kopi/.op.envKopi Agent 会在启动时自动加载
.op.env,顺序在.env之后,且绝不会覆盖环境中已存在的 token。.op.env已被 gitignore,因此 token 绝不会进入任何已提交的文件。 -
通过 systemd
EnvironmentFile(Linux 网关)。 如果你在 systemd 下运行网关,可以直接将 token 注入服务环境:[Service]
EnvironmentFile=-/home/youruser/.kopi/.op.env以这种方式注入的 token 具有最高优先级——Kopi Agent 检测到
OP_SERVICE_ACCOUNT_TOKEN已设置后,会完全跳过加载.op.env。
如果 token 只能通过交互式 shell 获取(例如 op signin、.bashrc 中的 OP_SESSION_* 导出等),它不会被定时任务或新生成的子进程继承,这些上下文会记录一条警告,并回退到 .env 中已有的凭据。对于任何非交互式工作负载,请使用上述三种方式之一。
设置
1. 安装 op 并登录
按照 1Password CLI 入门指南 操作。验证其是否正常工作:
op whoami
2. 启用集成
kopi secrets onepassword setup
此命令会验证 op 位于 PATH(或使用 --binary-path),记录你的账号/token 设置,检查是否存在活动会话,并切换 secrets.onepassword.enabled: true。非交互式参数:
kopi secrets onepassword setup \
--account my.1password.com \
--token-env OP_SERVICE_ACCOUNT_TOKEN \
--token "$OP_SERVICE_ACCOUNT_TOKEN"
3. 映射你的凭据
引用格式为 op://<vault>/<item>/<field>:
kopi secrets onepassword set OPENAI_API_KEY "op://Private/OpenAI/api key"
kopi secrets onepassword set ANTHROPIC_API_KEY "op://Private/Anthropic/credential"
4. 预览并确认
kopi secrets onepassword sync # dry-run: resolve now, show what would apply
kopi secrets onepassword status # config + binary + references + auth
从现在开始,每次 kopi 调用都会在启动时解析这些引用。首次在某个进程中应用密钥时,你会在 stderr 中看到一行摘要。
CLI
| 命令 | 作用 |
|---|---|
kopi secrets onepassword setup | 验证 op,设置账号/token 环境变量,启用 |
kopi secrets onepassword status | 显示配置、二进制文件、身份验证状态和已配置的引用 |
kopi secrets onepassword set ENV_VAR "op://…" | 将一个环境变量映射到引用(存储时去除多余内容并校验) |
kopi secrets onepassword remove ENV_VAR | 删除一条映射 |
kopi secrets onepassword sync | 试运行:立即解析引用并显示将要应用的内容 |
kopi secrets onepassword sync --apply | 解析并导出到当前 shell 的环境中 |
kopi secrets onepassword disable | 切换 enabled: false;保留现有映射 |
op 和 1password 可作为 onepassword 的别名使用。
配置
~/.kopi/config.yaml 中的默认值:
secrets:
onepassword:
enabled: false
env:
OPENAI_API_KEY: "op://Private/OpenAI/api key"
ANTHROPIC_API_KEY: "op://Private/Anthropic/credential"
account: ""
service_account_token_env: OP_SERVICE_ACCOUNT_TOKEN
binary_path: ""
cache_ttl_seconds: 300
override_existing: true
| 键 | 默认值 | 作用 |
|---|---|---|
enabled | false | 总开关。为 false 时,op 永远不会被调用。 |
env | {} | 环境变量名 → op://vault/item/field 引用的映射。名称不是合法环境变量名、或值不是 op:// 引用的条目会被跳过并给出警告。 |
account | "" | 作为 op read --account 传入的账户简称 / 登录地址。留空则使用 op 的默认账户。 |
service_account_token_env | OP_SERVICE_ACCOUNT_TOKEN | Kopi Agent 从中读取服务账户 token 的环境变量。其值会以 OP_SERVICE_ACCOUNT_TOKEN(即 op 所期望的名称)导出给 op 子进程。不设置该变量则使用桌面/交互式会话。 |
binary_path | "" | op 的绝对路径。设置后将按原样使用,不会查询 PATH —— 固定此路径可避免信任 PATH 上最先出现的任何 op。 |
cache_ttl_seconds | 300 | 已解析值的复用时长(进程内和磁盘上)。设为 0 可禁用两层缓存 —— 完全不向磁盘写入任何值。 |
override_existing | true | 为 true 时,解析出的值会覆盖环境中已有的同名变量(从而让轮换生效)。改为 false 则让 .env / shell 导出优先;此时这些引用会在调用 op 之前就被跳过。 |
故障模式
1Password 永远不会阻塞 Kopi Agent 的启动。如果出现问题,你会在 stderr 中看到一行警告,Kopi Agent 继续运行:
| 症状 | 原因 | 解决方法 |
|---|---|---|
the op CLI was not found on PATH | op 未安装 / 不在 PATH 中 | 安装该 CLI,或设置 secrets.onepassword.binary_path |
op read failed for 'op://…': … | 会话已锁定、token 已过期,或无保险库访问权限 | op signin、刷新 token,或授予该服务账户访问权限 |
op read returned an empty value for 'op://…' | 引用的字段存在但为空 | 在 1Password 中修正该条目/字段(空值永远不会被应用 —— 你现有的环境变量保持不变) |
… is not an op:// secret reference | 某个映射值不是 op:// 引用 | 使用正确的 op://vault/item/field 形式重新设置 |
op read timed out | 网络被阻断或 1Password 响应缓慢 | 检查网络连通性 / 桌面应用集成 |
缓存
成功且完整的拉取结果会被缓存在进程内和 <kopi_home>/cache/op_cache.json 下的磁盘上(原子写入,权限模式 0600),因此连续的短生命周期 kopi 调用不必为每个引用都重新调起 op 子进程。该缓存:
- 仅存储已解析的密钥值 —— 永远不存储服务账户 token 或任何原始认证材料(认证信息会以指纹形式并入缓存键);
- 当 token、账户、
OP_SESSION_*变量或引用集合发生变化时失效; - 当某次拉取存在任何按引用计的错误时不写入,从而不会让一次瞬时认证失败在 TTL 期间被固化;
- 当
cache_ttl_seconds: 0时完全禁用 —— 读取和写入都会停止。
安全说明
- 1Password 服务账户 token 可以读取该账户有权访问的每一个密钥。请将其存储在
~/.kopi/.env(而非config.yaml)中;如果泄露,请在 1Password 中吊销并重新生成。 - 即使启用了
override_existing: true,Kopi Agent 也拒绝让解析出的值覆盖 token 环境变量本身。 op子进程只会获得一个最小化的白名单环境(认证/会话变量 +PATH/HOME),而不是完整os.environ的副本,因此 dotenv 之后的 provider(服务提供商)凭证不会全部被子进程继承。- 引用会被校验必须以
op://开头,并且引用会放在--选项终结符之后传入,从而防止精心构造的值被解析为op标志。
何时不应使用此功能
- 单机个人配置 —— 直接使用
~/.kopi/.env即可。 - 无法访问 1Password 的隔离(air-gapped)环境。
- CI/CD 中已经接入了现成的密钥注入机制 —— 选择一条路径即可,不要两套并用。
此功能的适用场景是多机器集群、共享开发机、网关 VPS,或任何你需要在多个 Kopi Agent 安装实例之间进行集中轮换与吊销的地方。