openagent 集成 1Password CLI(op)实战:安装、桌面应用集成与密钥安全读写指南
openagent 集成 1Password CLI(op)实战:安装、桌面应用集成与密钥安全读写指南
导读
1Password CLI(命令 op)是 1Password 提供的官方命令行工具,用于在脚本、自动化流程和 AI Agent 中安全地读取、注入和运行密钥(密码、TOTP、SSH 私钥等)。openagent 项目在 skills/1password 技能包中以「SKILL.md + references 参考文档」的形式封装了完整的 1Password CLI 使用规范(skills/1password/references/get-started.md),从环境要求、桌面应用集成、登录流程到真实 op 命令示例一应俱全。读完本文,你将掌握:如何在 macOS / Windows / Linux 上安装 op 并启用桌面应用集成、如何完成单账户与多账户登录、如何用 op read / op run / op inject 安全读取与注入密钥,以及 openagent 中 Agent 如何借助 tmux 会话和技能加载机制安全地操作 op。
一、支持环境与前置要求
按照技能参考文档(get-started.md)的说明,op CLI 的官方支持范围如下:
| 维度 | 要求 |
|---|---|
| 操作系统 | macOS、Windows、Linux |
| macOS / Linux Shell | bash、zsh、sh、fish |
| Windows Shell | PowerShell |
| 账户前提 | 需要 1Password 订阅,并且桌面应用参与应用集成(app integration) |
| macOS 版本 | Big Sur 11.0.0 或更高 |
| Linux 应用集成 | 需要 PolKit 以及一个认证代理(auth agent) |
两个容易踩坑的前提需要特别说明:
- 订阅与桌面应用缺一不可:
op的「桌面应用集成」能力依赖 1Password 订阅账户,且必须安装并解锁桌面应用。纯命令行、完全脱离桌面应用的认证方式则走op account add流程(详见下文第四节)。 - Linux 的额外依赖:Linux 上要让
op借用系统认证解锁保险库,需要 PolKit(系统权限服务)与认证代理配合,例如常见的polkit-agent-helper-1或图形会话中的认证代理。若系统缺少这些组件,桌面应用集成将无法正常工作。
二、安装 1Password CLI(op)
参考文档明确建议:按官方文档针对你所在操作系统执行安装,不要凭记忆猜测安装命令。openagent 的 1Password 技能包在元数据中记录了可用的安装方式之一——Homebrew 安装(见 skills/1password/SKILL.md 的 metadata.openclaw.install):
brew install 1password-cli
安装完成后,用版本号验证 CLI 是否就绪(这也是技能工作流的第一步检查):
op --version
三、在 1Password 桌面应用中启用 CLI 集成
启用桌面应用集成是让 op 免密访问保险库的关键一步。参考文档给出的三个平台操作路径如下:
- macOS:打开并解锁 1Password 应用,选中你的账户/保险库集合后,进入 设置(Settings)> Developer > Integrate with 1Password CLI(可选用 Touch ID 解锁 CLI)。
- Windows:先开启 Windows Hello,然后进入 设置(Settings)> Developer > Integrate。
- Linux:进入 设置(Settings)> Security > Unlock using system authentication(使用系统认证解锁),再进入 设置(Settings)> Developer > Integrate。
集成完成后,第一次使用任意 op 命令(例如 op vault list)即可触发系统认证流程,在桌面应用的授权提示中确认后完成登录。
四、登录流程:单账户、多账户与无集成认证
4.1 集成后的登录
完成桌面应用集成后,运行任意 op 命令(文档示例用 op vault list)即可触发登录。openagent 技能包在 SKILL.md 的工作流中,将登录编排为三步:
- 验证 CLI 存在:
op --version; - 确认桌面应用集成已启用且应用处于解锁状态;
- 执行登录并在应用内授权:
op signin(预期会弹出应用授权提示); - 验证访问可用:
op whoami(在任何密钥读取之前必须成功)。
op whoami 是健康检查命令,只有它能返回当前登录身份,后续的密钥读取才有保障。
4.2 多账户选择
如果本机存在多个 1Password 账户,登录时需要显式指定目标账户:
- 交互式选择:运行
op signin后从提示中挑选一个账户; - 命令行指定:
op signin --account <shorthand | signin-address | account-id | user-id>; - 环境变量指定:设置
OP_ACCOUNT环境变量来固定账户,后续命令无需反复传入--account。
多账户场景下,建议将 OP_ACCOUNT 写入会话环境,避免每次命令都携带参数、也避免 Agent 自动执行时选错账户。
4.3 无桌面应用集成的认证
若无法或不想使用桌面应用集成,参考文档给出的替代方案是 op account add,即手动添加账户信息完成登录。此路径不依赖桌面应用,适合纯命令行环境或受限容器,但每次使用前需要额外的解锁步骤。
五、核心命令实战:读取、运行与注入密钥
技能包的另一份参考文档 cli-examples.md 汇总了来自 op help 的真实命令示例,以下按功能分类展开。
5.1 登录与账户管理
# 登录(集成场景)
op signin
# 指定账户登录
op signin --account <shorthand|signin-address|account-id|user-id>
# 查看当前身份
op whoami
# 列出本机已配置的账户
op account list
5.2 读取密钥(op read)
op read 使用 Secret Reference URI(op:// 协议)定位密钥,格式为 op://<vault>/<item>/[<field>]:
# 读取保险库 app-prod 中条目 db 的 password 字段
op read op://app-prod/db/password
# 读取一次性密码(OTP)字段,注意字段名含空格时需用 ?attribute= 指定
op read "op://app-prod/db/one-time password?attribute=otp"
# 读取 SSH 私钥,并用 ssh-format 指定输出格式
op read "op://app-prod/ssh key/private key?ssh-format=openssh"
# 将密钥写入文件(例如 PEM 私钥)
op read --out-file ./key.pem op://app-prod/server/ssh/key.pem
需要说明两点:
- 字段名带空格(如
one-time password)时,整个 URI 要用引号包裹,并用?attribute=显式声明字段,否则解析器可能截断; --out-file会把密钥内容落盘,属于敏感操作,应只在确实需要文件形式密钥(如 SSH key.pem)时使用,用后及时清理。
5.3 注入环境变量运行程序(op run)
op run 会解析 Secret Reference URI 并注入环境变量后启动目标程序,是「密钥不入库、不留盘」的首选方式:
# 定义环境变量映射(URI 语法)
export DB_PASSWORD="op://app-prod/db/password"
# 运行 printenv 验证注入效果,--no-masking 表示不做掩码
op run --no-masking -- printenv DB_PASSWORD
# 从 .env 模板文件读取映射并注入
op run --env-file="./.env" -- printenv DB_PASSWORD
--env-file 模式下,.env 文件中形如 DB_PASSWORD=op://app-prod/db/password 的条目会被解析并注入到子进程环境。默认情况下 op run 会对输出中的密钥做掩码处理,调试注入结果时可配合 --no-masking 观察真实值,但在生产日志与对话记录中应避免输出明文密钥。
5.4 模板渲染注入(op inject)
op inject 将模板文件中的 {{ op://... }} 占位符替换为真实密钥:
# 从标准输入读取模板,替换后输出到标准输出
echo "db_password: {{ op://app-prod/db/password }}" | op inject
# 从配置文件模板生成最终配置
op inject -i config.yml.tpl -o config.yml
这条命令非常适合「配置模板入库、密钥运行时注入」的场景:仓库中只保存 config.yml.tpl 模板,最终的 config.yml 通过 op inject 在部署时生成,避免真实凭据进入版本库。
六、openagent 中的集成实践:技能加载与 tmux 会话
6.1 技能如何被加载
openagent 将 skills/1password/ 目录中的内容建模为标准技能结构:SKILL.md 提供整体工作流与护栏,references/get-started.md 与 references/cli-examples.md 提供可选的深度参考。其解析与加载链路清晰可见:
- skillmd/skillmd.go 的
LoadFolder读取SKILL.md的 front matter 与正文,并收集references/目录下所有文件; - object/skill.go 的
LoadSkill将其转换为可入库的Skill对象(含References数组),并在 object/init.go 的initSkillsFromFolder中随服务启动自动同步; - 运行时,Agent 通过内置的
load_skill工具加载技能——该工具定义在 tool/skill.go,支持skill与可选的reference两个参数; - 当指定
reference时,object/skill.go 的LoadSkillPromptContent会把参考文档全文拼接到技能正文之后注入提示词,这就是 Agent 在需要处理 1Password 任务时拿到本篇参考文档内容的方式。
从技能目录结构(skills/1password/)看,SKILL.md 与 references/ 的「主文档 + 参考库」设计,正是为了让主提示词保持精简、把大段操作细节按需按名加载。
6.2 为什么必须在 tmux 会话中运行 op
openagent 的 shell 工具为每次命令调用创建全新的进程环境——tool/shell.go 的 shellBuildCommand 每次执行都新建 exec.Cmd,前台命令执行完即销毁。因此 op signin 建立的认证状态不会在多次命令调用之间保留,直接逐条执行 op 命令会导致反复弹出授权、频繁失败。
技能包 SKILL.md 给出的解决方案是:为所有 op 命令创建专用 tmux 会话,将登录与后续读取放在同一个持久会话中完成,参考 tmux 技能 的 socket 约定,并使用全新的会话名(禁止复用旧会话名)。完整示例流程如下:
SOCKET_DIR="${OPENCLAW_TMUX_SOCKET_DIR:-${TMPDIR:-/tmp}/openclaw-tmux-sockets}"
mkdir -p "$SOCKET_DIR"
SOCKET="$SOCKET_DIR/openclaw-op.sock"
SESSION="op-auth-$(date +%Y%m%d-%H%M%S)"
# 新建会话并执行登录(--account 指定账户)
tmux -S "$SOCKET" new -d -s "$SESSION" -n shell
tmux -S "$SOCKET" send-keys -t "$SESSION":0.0 -- "op signin --account my.1password.com" Enter
tmux -S "$SOCKET" send-keys -t "$SESSION":0.0 -- "op whoami" Enter
tmux -S "$SOCKET" send-keys -t "$SESSION":0.0 -- "op vault list" Enter
# 抓取面板输出(-S -200 表示抓取最近 200 行滚动区)
tmux -S "$SOCKET" capture-pane -p -J -t "$SESSION":0.0 -S -200
# 完成后清理会话
tmux -S "$SOCKET" kill-session -t "$SESSION"
这套流程的关键点在于:登录(op signin)、校验(op whoami)、读取(op vault list)必须在同一个 tmux 会话内串行完成,会话名每次唯一,socket 通过 OPENCLAW_TMUX_SOCKET_DIR 控制(默认 $TMPDIR/openclaw-tmux-sockets),与 tmux 技能 中 capture-pane -p、send-keys 的用法一一对应。
6.3 安全护栏(Guardrails)
技能包为 op 的使用划定了强制边界(SKILL.md):
- 绝不将密钥粘贴进日志、聊天记录或代码;
- 优先使用
op run/op inject,避免把密钥写入磁盘; - 如需无桌面应用集成登录,使用
op account add; - 若命令返回
account is not signed in,在 tmux 会话内重新执行op signin并在桌面应用中授权; - 禁止在 tmux 之外运行
op;若 tmux 不可用,应停止操作并向用户询问。
这些护栏与参考文档(get-started.md)中「多账户用 op signin / --account / OP_ACCOUNT、无集成用 op account add」的指引相互呼应,共同构成 Agent 侧安全使用密钥的完整约定。
七、常见问题排查
| 现象 | 处理方式 |
|---|---|
account is not signed in |
在专用 tmux 会话内重新执行 op signin,并在桌面应用中完成授权 |
| 每次命令都弹出授权/反复失败 | 确认所有 op 命令都在同一个 tmux 会话内执行,会话名不复用 |
| 多账户环境读错保险库 | 用 op signin --account ... 或设置 OP_ACCOUNT 显式固定账户 |
| Linux 集成不生效 | 检查 PolKit 与认证代理是否就绪,并确认桌面应用已解锁、已选中账户 |
| 需要无桌面应用的认证 | 改用 op account add 流程登录 |
结语
1Password CLI 为自动化与 AI Agent 提供了不落盘的密钥访问能力,而 openagent 通过 skills/1password 技能包将安装、桌面应用集成、登录与 op read / op run / op inject 的实操规范沉淀为可加载、可校验的技能文档:主文档(SKILL.md)约束工作流与安全护栏,参考文档(get-started.md、cli-examples.md)提供环境要求与真实命令示例。在实际使用时,务必遵循「tmux 会话隔离 + op whoami 先行校验 + 优先注入而非落盘」三条原则,即可在 Agent 场景中安全、稳定地驾驭 1Password CLI。