openclaw 集成 1Password CLI：三种认证模式的选型、执行与密钥注入实战指南

openclaw 集成 1Password CLI：三种认证模式的选型、执行与密钥注入实战指南

【免费下载链接】openclawThe AI that really does things. Any OS. Any Platform. The lobster way. 🦞项目地址: https://gitcode.com/GitHub_Trending/cl/openclaw

导读

本文以 openclaw 仓库中的 1Password Skill 及其配套参考文档为主体，系统讲解 Agent/Gateway 场景下如何使用 1Password CLI（op）完成登录、桌面应用集成与密钥读取注入。你将掌握 Service Account、桌面应用集成、独立交互式登录三种认证模式的适用场景与执行方式，理解为什么桌面集成模式下不能在 tmux 中执行op、而独立登录模式反而必须依赖 tmux 保持会话，并了解 openclaw 仓库中 onepassword 扩展 的服务账号实现如何与这套流程衔接。

前置条件与安装

平台与 Shell 支持

根据 get-started 参考文档，1Password CLI 支持以下环境：

• 操作系统：macOS、Windows、Linux 全平台可用。
• Shell：macOS/Linux 支持 bash、zsh、sh、fish；Windows 上为 PowerShell。
• macOS 版本要求：Big Sur 11.0.0 或更高。
• 订阅要求：使用桌面应用集成需要 1Password 订阅以及已安装的 1Password 桌面应用。
• Linux 特别要求：桌面应用集成需要 PolKit 与认证代理（auth agent）配合。

安装方式

SKILL.md 的元数据中声明了该技能对op二进制的依赖，并提供推荐的安装途径：

{ "requires": { "bins": ["op"] }, "install": [ { "id": "brew", "kind": "brew", "formula": "1password-cli", "bins": ["op"], "label": "Install 1Password CLI (brew)" } ] }

即通过 Homebrew 安装1password-cli公式（macOS/Linux），Windows 用户则按官方文档对应方式安装。SKILL.md 同时强调："Follow the official CLI get-started steps. Don't guess install commands."——不要猜测安装命令，应遵循官方安装指引。

启用桌面应用集成

若使用桌面应用集成认证，需要先在 1Password 应用中打开对应开关：

• macOS：设置（Settings）> Developer > "Integrate with 1Password CLI"（Touch ID 可选开启）。
• Windows：先开启 Windows Hello，再进入 Settings > Developer > Integrate。
• Linux：Settings > Security > "Unlock using system authentication"，然后进入 Settings > Developer > Integrate。

集成完成后，执行任意op命令（如op vault list）即可触发登录。

认证模式判定：先探测，再执行

SKILL.md 给出的核心工作流是"先判断用户已配置的认证模式，再按对应方式执行"，共 5 步：

1. 检查操作系统与 Shell。
2. 验证 CLI 存在：op --version。
3. 检测用户已配置的认证模式（三选一，见下文）。
4. 按认证模式执行op命令。
5. 在任何密钥读取之前，先用op whoami验证访问是否成功。
6. 若存在多个账号，使用--account参数或OP_ACCOUNT环境变量指定。

三种认证模式的特征判别如下：

按认证模式执行op

Service Account：无头环境的首选

Service Account 认证无需登录步骤、无需 tmux，直接执行即可：

export OP_SERVICE_ACCOUNT_TOKEN="ops_..." op vault list op read op://app-prod/db/password

这是 Gateway 与 CI 场景的推荐方式。值得说明的是，openclaw 仓库自带的 onepassword 扩展 正是以 Service Account 为主的服务端实现：其 op-client.ts 在每次item get调用时从令牌文件读取OP_SERVICE_ACCOUNT_TOKEN，并额外注入OP_LOAD_DESKTOP_APP_SETTINGS=false与OP_BIOMETRIC_UNLOCK_ENABLED=false，注释明确指出：若不覆盖这两个环境变量，op 2.35 在 macOS 上仍会读取桌面应用设置，可能弹出 per-PID 的 App Data Protection 对话框阻塞 broker。这从源码层面印证了"Service Account 走纯无头路径"的正确做法。

此外，该扩展对op输出的错误做了细粒度分类（见 op-client.ts 的 classifyOpError），包括OP_NOT_FOUND（找不到二进制）、ITEM_NOT_FOUND/FIELD_NOT_FOUND（条目或字段不存在）、AUTH_FAILED（未登录/无效 Service Account/权限拒绝）、RATE_LIMITED（429 限流）与TIMEOUT，便于 Agent 根据错误码给出精准的补救建议。

桌面应用集成：直接执行，切勿套 tmux

桌面集成模式同样直接执行，但有一条关键纪律：不要在 tmux 中执行op。原因在于桌面集成依赖 per-user 的 IPC 通道，该通道建立在 Gateway 的 exec 环境中，而 tmux 子 shell 运行在不同的环境上下文里，往往无法可靠到达这条 IPC 通道。

IPC 通道的底层传输因平台而异（这一点在 get-started 参考文档 中有同样说明）：

• macOS：通过 1Password Browser Helper 的 XPC；
• Linux：Unix domain socket；
• Windows：命名管道（named pipe）。

对 Agent 而言，三条平台的实践规则一致：直接运行op。在 macOS 上，一个有用的故障判据是 1Password 集成组容器路径~/Library/Group Containers/2BUA8C4S2C.com.1password/t/（注意：它用于识别故障模式，而非可达性测试）。

op vault list # 首次调用可能触发 Touch ID / Windows Hello / 系统认证 op whoami

若调用返回1Password CLI couldn't connect to the 1Password desktop app，不要转向 tmux，而应确认桌面应用正在运行且已解锁，然后重试直接执行。

独立交互式登录：唯一需要 tmux 的模式

这是唯一一种 tmux 有帮助的模式。原理如下：op signin会输出一段eval风格的导出语句，用于在 POSIX shell 中设置OP_SESSION_*令牌；后续同 shell 中的命令依靠该环境变量完成认证。而 Gateway 的 per-command shell 会在调用之间丢失这些状态，因此需要一个持久的 tmux pane 保活会话令牌——前提是确实在 POSIX shell 中用eval应用了导出。若把op signin作为普通命令直接发送，stdout 只会打印在 pane 里，随后op whoami必然失败。

SKILL.md 给出的完整 tmux 流程如下：

SOCKET_DIR="${OPENCLAW_TMUX_SOCKET_DIR:-${TMPDIR:-/tmp}/openclaw-tmux-sockets}" mkdir -p "$SOCKET_DIR" chmod 700 "$SOCKET_DIR" SOCKET="$SOCKET_DIR/openclaw-op.sock" SESSION="op-auth-$(date +%Y%m%d-%H%M%S)" tmux -S "$SOCKET" new -d -s "$SESSION" -n shell /bin/sh tmux -S "$SOCKET" send-keys -t "$SESSION":0.0 -- 'eval "$(op signin --account my.1password.com)"' Enter tmux -S "$SOCKET" capture-pane -t "$SESSION":0.0 -p -S - | tail -40

要点拆解：

• 示例特意打开/bin/sh，确保 POSIX 风格的eval "$(op signin ...)"输出在用户默认 shell 为 fish 时同样有效；不要把该 POSIX eval 形式发送进 fish 或 PowerShell。
• -S "$SOCKET"指定 tmux server socket，socket 应放在用户拥有的0700权限目录中（如上面chmod 700所示），不要跨用户共享，且每次新的登录尝试都要选用新的 session 名。
• 登录提示期间不要排队后续命令：用capture-pane轮询 pane，直到登录完成、shell 提示符回归，或明确看到它在等待人工输入。
• 若提示需要密码、MFA 或账号选择，暂停并把 socket 与 session 值交给用户，让其在本机终端完成登录；Agent 不应通过 exec 运行tmux attach，因为 attach 会占用当前 TTY，阻碍脚本化的send-keys/capture-pane控制。

提示符回归后，在同一个 pane 内发送校验命令：

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 tmux -S "$SOCKET" capture-pane -t "$SESSION":0.0 -p -S - | tail -80

保持该 tmux session 持续运行，后续的op read/op run即可复用同一个已认证 shell。之后所有跟进命令都必须复用相同的SOCKET与SESSION值。

平台限制：tmux 流程仅在 macOS/Linux 主机且tmux技能可用时可行；Windows 上优先使用桌面集成或 Service Account 认证，若用户仅有独立交互式登录，应停下询问，请其提供持久的 PowerShell 会话机制，或改用桌面集成/Service Account，切勿直接照搬 tmux 命令。

浏览器登录场景（1Password for Claude）

当会话在 Chrome 凭证工具中暴露了request_credentials、autofill_credential、enter_verification_code等能力时，网站登录应优先走这些浏览器凭证工具而非op：1Password 直接填充页面，密钥永远不会进入上下文。规则如下：

• 在导航之前，用一次request_credentials调用请求任务所需的全部凭证。
• 批准是一个在 Gateway 主机上弹出的 1Password 提示；若它一直处于 pending，应明确告知用户在哪台主机解锁（如 "1Password is waiting for approval on this Mac"），而不是重试。
• 绝不要求用户通过聊天发送密码或一次性验证码；验证码只能通过enter_verification_code传入。
• 不要因为浏览器流程需要批准就回退到op read读取网站密码——那会破坏"密钥不暴露"的设计。op只应用于命令与配置消费的密钥，当浏览器流程存在时，不应用于 Web 登录。

op命令速查（来自 op help）

cli-examples 参考文档 整理了op的核心用法，按功能分组如下。

登录（Sign in）

op signin op signin --account <shorthand|signin-address|account-id|user-id>

多账号场景用--account或OP_ACCOUNT指定账号。

读取密钥（Read）

op read op://app-prod/db/password op read "op://app-prod/db/one-time password?attribute=otp" op read "op://app-prod/ssh key/private key?ssh-format=openssh" op read --out-file ./key.pem op://app-prod/server/ssh/key.pem

op://URI 结构为op://vault/item/field，可附加查询参数：?attribute=otp读取一次性密码字段，?ssh-format=openssh指定 SSH 私钥导出格式，--out-file可将结果写入文件（注意 SKILL.md 的护栏：优先op run/op inject而非把密钥写盘）。

运行注入（Run）

export DB_PASSWORD="op://app-prod/db/password" op run --no-masking -- printenv DB_PASSWORD op run --env-file="./.env" -- printenv DB_PASSWORD

op run会把环境变量中的op://引用解析为真实值再启动子命令，--no-masking关闭输出打码，--env-file支持从.env文件加载引用。

模板注入（Inject）

echo "db_password: {{ op://app-prod/db/password }}" | op inject op inject -i config.yml.tpl -o config.yml

op inject用于把{{ op://... }}占位符替换为真实密钥，-i/-o指定模板输入与输出文件。

身份验证（Whoami / Accounts）

op whoami op account list

op whoami是每次密钥读取前的标准前置校验命令；非集成认证场景先用op account add添加账号。

护栏与故障排查

SKILL.md 明确了以下安全护栏：

• 绝不把密钥写入日志、聊天或代码。
• 优先op run/op inject，而不是把密钥写到磁盘。
• 无应用集成的登录，先op account add再登录。
• 出现 "account is not signed in" 时按模式处理：
  • Service Account：重新导出OP_SERVICE_ACCOUNT_TOKEN；
  • 桌面应用：确认应用在运行且集成已开启；
  • 独立登录：在同一 tmux session 内重跑op signin并完成授权。

这一"按模式对症下药"的排障思路，与 onepassword 扩展中AUTH_FAILED等错误码的设计（见 errors.ts 配套逻辑与 classifyOpError）相互印证：服务端扩展把认证失败归类为可恢复错误并给出模式化提示，技能层则在交互终端中引导用户完成相同模式的恢复。

与 openclaw 仓库的衔接

除 Skill 外，openclaw 还内置了完整的 onepassword 扩展，其模块划分可以看作本 Skill 流程的服务端落地：

• op-client.ts：OpClient封装op item get，负责 Service Account 令牌读取、--cache=false强制走服务账号路径、错误分类；
• broker.ts 与 pending-authorization.ts：处理授权与待批准状态，与 SKILL.md 中"浏览器凭证流程需要用户在 Gateway 主机批准"的设计呼应；
• secret-ref-cli.ts 与 secret-ref-resolver.ts：解析op://形式的密钥引用，对应上文op read/op run/op inject的引用语法；
• tool.ts：将能力暴露为 Agent 可调用的工具；
• cli.test.ts、op-client.test.ts 等测试覆盖了令牌缺失、错误分类、字段解析等关键路径。

简而言之：在无头 Gateway/CI 上，Service Account +op直接执行是标准答案；在桌面环境，直接执行op并善用浏览器凭证工具；只有独立交互式登录才需要 tmux 保活。将本 Skill 的三种模式判断与 onepassword 扩展的服务端实现对照阅读，可以完整理解 openclaw 从交互终端到无头服务的密钥管理全链路。

【免费下载链接】openclawThe AI that really does things. Any OS. Any Platform. The lobster way. 🦞项目地址: https://gitcode.com/GitHub_Trending/cl/openclaw