openagent 集成 1Password CLI(op)实战:安装、桌面应用集成与密钥安全读写指南

原创2026-10-11 21:03:341,867 阅读
文章标签:人工智能大模型AI AgentRAG本地部署交互助手知识库工具调用后端前端语音

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)

两个容易踩坑的前提需要特别说明:

  1. 订阅与桌面应用缺一不可:op 的「桌面应用集成」能力依赖 1Password 订阅账户,且必须安装并解锁桌面应用。纯命令行、完全脱离桌面应用的认证方式则走 op account add 流程(详见下文第四节)。
  2. 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 的工作流中,将登录编排为三步:

  1. 验证 CLI 存在:op --version;
  2. 确认桌面应用集成已启用且应用处于解锁状态;
  3. 执行登录并在应用内授权:op signin(预期会弹出应用授权提示);
  4. 验证访问可用: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。

登录后查看全文
openagent