跳到主要内容

1Password

在进程启动时从 1Password 解析 provider API key,而不是以明文形式存储在 ~/.kopi/.env 中。你将密钥保存为 1Password 条目,并通过 op://vault/item/field 引用它们;轮换凭据时只需在 1Password 中修改一处。

工作原理​

  1. 安装官方 1Password CLI(op)并完成身份验证——可以使用服务账号 token(无头服务器),也可以使用交互式/桌面会话(你的笔记本电脑)。
  2. 在 ~/.kopi/config.yaml 中将环境变量名映射到 op:// 引用。
  3. 每次 kopi(或网关,或定时任务)启动时,在 ~/.kopi/.env 加载完毕后,Kopi Agent 会为每个引用运行 op read,并将解析出的值设置到 os.environ 中。
  4. 默认情况下,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 容器——而不仅仅是交互式网关。有三种方式可以使其可用,按优先级顺序排列:

  1. 放在 ~/.kopi/.env 中(推荐)。 kopi secrets onepassword setup --token <token> 会将 token 写入 ~/.kopi/.env,与 Bitwarden 的 BWS_ACCESS_TOKEN 完全一致。由于 load_kopi_dotenv() 总是会加载 .env,因此该 token 无需任何额外配置即可在各处使用。这是最简单可靠的方式。

  2. 放在 ~/.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.env

    Kopi Agent 会在启动时自动加载 .op.env,顺序在 .env 之后,且绝不会覆盖环境中已存在的 token。.op.env 已被 gitignore,因此 token 绝不会进入任何已提交的文件。

  3. 通过 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
键默认值作用
enabledfalse总开关。为 false 时,op 永远不会被调用。
env{}环境变量名 → op://vault/item/field 引用的映射。名称不是合法环境变量名、或值不是 op:// 引用的条目会被跳过并给出警告。
account""作为 op read --account 传入的账户简称 / 登录地址。留空则使用 op 的默认账户。
service_account_token_envOP_SERVICE_ACCOUNT_TOKENKopi Agent 从中读取服务账户 token 的环境变量。其值会以 OP_SERVICE_ACCOUNT_TOKEN(即 op 所期望的名称)导出给 op 子进程。不设置该变量则使用桌面/交互式会话。
binary_path""op 的绝对路径。设置后将按原样使用,不会查询 PATH —— 固定此路径可避免信任 PATH 上最先出现的任何 op。
cache_ttl_seconds300已解析值的复用时长(进程内和磁盘上)。设为 0 可禁用两层缓存 —— 完全不向磁盘写入任何值。
override_existingtrue为 true 时,解析出的值会覆盖环境中已有的同名变量(从而让轮换生效)。改为 false 则让 .env / shell 导出优先;此时这些引用会在调用 op 之前就被跳过。

故障模式​

1Password 永远不会阻塞 Kopi Agent 的启动。如果出现问题,你会在 stderr 中看到一行警告,Kopi Agent 继续运行:

症状原因解决方法
the op CLI was not found on PATHop 未安装 / 不在 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 安装实例之间进行集中轮换与吊销的地方。