2password

2password

2password 封装了 1Password CLI（op），让你无需查看机密值即可使用它们，并尽可能减少 1Password 提示。所有输出均为 JSON。

规则

• 绝不打印、记录、概述或重复机密值。只传递 op:// 引用。
• 任何 1Password 调用都可能显示审批提示，而且每个新打开的 shell 都可能需要重新审批。尽可能将任务所需操作合并到少量命令中：在一次 find 中查询多个内容，在一次 env run 中通过一个 env 文件使用多个引用。
• 绝不运行 op whoami 或任何其他预检。直接运行命令；桌面应用会在需要时授权。
• 写入失败或报告“未验证”时，绝不重试。先运行 find，检查写入是否已完成。

查找凭据

2password find openai anthropic "github actions"   # many queries, one prompt
2password find stripe --vault Work --account my.1password.com

每个匹配项只显示一次，格式为 { ref, title, kind }；如果你查询了多个内容，还会包含 queries。如果某个查询没有匹配项，则会返回 suggestions，其中包含来自同一次查找的相近标题（包括拼写错误）。使用这些建议，不要重新搜索或列出整个保险库。它绝不会返回值。

使用凭据

2password run --env "OPENAI_API_KEY=op://Personal/OpenAI API Key/credential" -- bun run dev
2password env write .env.tpl "OPENAI_API_KEY=op://Personal/OpenAI API Key/credential" "STRIPE_KEY=op://Work/Stripe API Key/credential"
2password env run .env.tpl -- bun run dev       # preferred: no plaintext on disk
2password env resolve .env.tpl --output .env    # only when a real file is required (mode 0600)
2password read "op://Personal/OpenAI API Key/credential"   # last resort: prints the value

模板中的所有引用都会通过一次提示完成解析。绝不要循环调用 read。只包含 op:// 引用的 .env.tpl 可以安全查看；解析后的 .env 是明文。

run 和 env run 会避免机密出现在 argv、模板和 2password 自身的输出中，但所选子进程会在其环境中接收到明文。将该子进程视为可信的机密使用者：不要将凭据注入环境转储／调试命令，或用于泄露值的辅助程序。

保存新的 API 密钥

2password create api-credential --title "OpenAI API Key" --vault Personal --clipboard
some-command-that-prints-a-key | 2password create api-credential --title "OpenAI API Key" --vault Personal --stdin

• 必须提供 --vault。使用用户指定的保险库，或其有文档记录的默认保险库；两者都没有时请询问。
• 绝不要将该值放入参数、命令替换或临时文件中，也绝不要先将剪贴板内容读入对话。
• 可选的 --url、--notes 和 --account 只能包含非机密元数据。
• 成功意味着退出码为 0，且 "verified": true。复用返回的 ref；不要通过 read 再次确认。
• 如果保险库中存在重复标题，则会拒绝写入，且绝不会覆盖任何内容。

检查或更新登录密码

2password password "Example Airline" --vault Personal --clipboard           # compare only
2password password "Example Airline" --vault Personal --clipboard --apply   # update, then verify

如果登录项包含通行密钥或未命名的导入字段，该命令会拒绝处理。只有在用户批准后，才能使用 --repair-imported-fields。

审计保险库

2password inventory --vault Work   # item and field metadata, never values or URL query strings
2password audit --vault Personal   # duplicate titles, untagged machine credentials, old logins, transient URLs

将发现的问题视为待审查项。提出重命名或修改建议，只有在用户批准后才执行。

无提示：服务账户（macOS、Windows）

如果用户厌倦了审批提示，可以建议使用服务账户。只有用户提出要求时才进行设置。

2password service-account setup --vault Automation --create-vault --write --save-vault Personal

设置完成后，每条命令都会通过存储在 macOS Keychain 中的令牌静默验证身份（在 Windows 上，则使用 %LOCALAPPDATA% 下的 DPAPI 加密文件），但只能访问 Automation 保险库。在 Windows 上，任何以该用户身份运行的进程都可以解密该文件，因此，保险库的有限访问范围才是真正的安全边界。将 Agent 使用的凭据保存在该保险库中。

• 2password --desktop <command> 使用常规桌面登录，例如访问其他保险库时。
• service-account status | connect --clipboard | recover | forget。forget 只会删除这台 Mac 上的副本；不会撤销该账户。
• 如果设置中途失败，不要重新运行。请运行 2password service-account status。
• 环境中的 OP_SERVICE_ACCOUNT_TOKEN 会覆盖已保存的账户（Linux、CI）。
• run 和 env run 会从子进程的环境中移除服务账户令牌。

条目约定

• API 密钥使用 API Credential 类别、内置的 credential 字段，以及类似 <Provider> API Key 或 <Provider> <Purpose> API Key 的标题。
• 登录项使用内置的 password 字段，以及类似 <Provider> 或 <Provider> <Account> 的标题。
• 保险库会显示条目的所有者，因此不要在标题中重复保险库名称。每个条目只保留一个当前有效的机密值。

报告任何不顺利的情况

2password 专为 Agent 打造，因此你的体验决定了它如何改进。如果某个命令意外失败，或你不得不绕过问题，请及时反馈。如果审批提示比预期更多、输出不够友好或过于冗长，或者此技能中的任何内容不清楚或有误，也请告知用户，并提出创建 issue。该操作会使用用户的 GitHub 帐户公开发布，因此请先征得用户同意。

gh issue list --repo kitlangton/2password --state all --search "<keywords>"   # add to an existing issue instead of duplicating it
gh issue create --repo kitlangton/2password --title "<what went wrong>" --body "<details>"

请附上 2password doctor 的输出（版本和设置；该命令不会提示输入信息，可以安全分享）、你运行的命令，以及预期结果和实际情况。绝不要包含机密值、条目标题、保险库或帐户名称，或 op:// 引用。请用占位符替换这些内容。

其他所有操作

对于其他类别的条目，以及编辑、移动、共享、删除和管理保险库，请使用原始的 op。通过 stdin 传递 JSON 模板中的明文，不要将其放在参数中。完成发现后，请通过 ID 引用条目和保险库。