1Password

1Password CLI

遵循官方 CLI 入门步骤。不要猜测安装命令。

参考

• references/get-started.md（安装 + 应用集成 + 登录流程）
• references/cli-examples.md（真实的 op 示例）

工作流程

1. 检查操作系统和 Shell。
2. 验证 CLI 是否安装：op --version。
3. 检测用户已设置的认证模式：
   • 服务账号： 已设置 OP_SERVICE_ACCOUNT_TOKEN 环境变量（通常用于无头设置、CI、网关）。
   • 桌面应用集成： 1Password 桌面应用正在运行且已启用 CLI 集成（通常出现在 macOS / Windows / Linux 桌面）。
   • 独立登录： 既不是上述任何一种情况——op signin 每次会话都会提示输入账户密码。
4. 根据认证模式运行 op（见下文）。
5. 验证访问：在读取任何密钥之前，应确保 op whoami 执行成功。
6. 如果有多个账户：使用 --account 或 OP_ACCOUNT。

按认证模式运行 op

服务账号（推荐用于无头/网关使用）

直接执行。无需 tmux，无需登录步骤。

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

桌面应用集成

直接执行。不要包装在 tmux 中——桌面应用集成使用每个用户的 IPC 通道，该通道为网关的执行环境建立，但在 tmux 子 Shell 中并不总是可靠可达，因为它们使用不同的环境上下文。传输方式因平台而异（macOS 上通过 1Password Browser Helper 的 XPC，Linux 上通过 Unix 域套接字，Windows 上通过命名管道）；对于代理程序来说，在所有三个平台上的实用规则是相同的：直接运行 op。在 macOS 上，一个有用的症状指示器是位于 ~/Library/Group Containers/2BUA8C4S2C.com.1password/t/ 的 1Password 集成组容器。

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

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

独立登录（无应用，交互式密码）

这是唯一适合使用 tmux 的模式。op signin 会输出一个 eval 风格的导出语句，用于在 POSIX Shell 中设置 OP_SESSION_* 令牌；同一 Shell 中的后续命令通过该环境变量进行认证。网关的每个命令之间会丢失该状态，因此持久的 tmux 窗格可以保持会话令牌——但前提是导出语句在 POSIX Shell 中通过 eval 实际应用。将 op signin 作为普通命令发送只会将 stdout 打印到窗格中，而 op whoami 将会失败。

tmux 流程仅在 macOS/Linux 主机上可行，且需要 tmux 技能可用。该示例有意打开 /bin/sh，以便 eval "$(op signin ...)" 的输出即使在用户的正常 Shell 是 fish 时也有效。在 Windows 上，建议使用桌面应用集成或服务账号认证。如果用户仅在 Windows 上使用独立的交互式登录，请停止操作并要求用户提供持久的 PowerShell 会话机制，或切换到桌面集成/服务账号认证；不要直接翻译 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

在登录提示期间不要排队执行后续命令。使用 capture-pane 轮询窗格，直到登录完成并且 Shell 提示符已返回，或者明显在等待用户输入。如果提示需要密码、MFA 或账户选择，请暂停并要求用户在自己的终端中完成登录；提供套接字和会话值，以便用户可以本地附加。代理程序不应从 exec 运行 tmux attach，因为附加会占用当前 TTY 并阻止脚本化的 send-keys / capture-pane 控制。

Shell 提示符返回后，通过将检查命令发送到同一窗格来验证：

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 会话运行，以便后续的 op read / op run 命令重用相同的已认证 Shell。

在此独立登录流程中，每个后续命令都使用相同的 SOCKET 和 SESSION 值。-S "$SOCKET" 标志选择 tmux 服务器套接字；将其保存在用户拥有的 0700 权限目录中，不要在用户之间共享，并为每次新的登录尝试选择新的会话名称。

浏览器登录（1Password for Claude）

如果会话在 Chrome 凭据工具中暴露了 Claude（request_credentials、autofill_credential、enter_verification_code），则优先使用它们而非 op 来登录网站：1Password 直接填充页面，密钥永远不会进入上下文。规则：

• 在一次 request_credentials 调用中请求任务所需的所有凭据，然后再导航。
• 批准是网关主机上的 1Password 提示。如果它一直挂起，请告知用户需要解锁的主机（“1Password 正在等待此 Mac 的批准”），而不是重试。
• 绝不要要求用户通过聊天发送密码或一次性代码；代码只能通过 enter_verification_code 发送。
• 不要仅仅因为浏览器流程需要批准就退回到 op read 获取网站密码；那将破坏无暴露设计。当有浏览器流程时，op 仅用于命令和配置所消费的密钥，而不是用于 Web 登录。

防护措施

• 切勿将密钥粘贴到日志、聊天或代码中。
• 优先使用 op run / op inject 而非将密钥写入磁盘。
• 如果需要不带应用集成的登录，请先使用 op account add。
• 如果命令返回“account is not signed in”：
  • 服务账号：重新导出 OP_SERVICE_ACCOUNT_TOKEN
  • 桌面应用：确认应用正在运行且集成已启用
  • 独立登录：在同一 tmux 会话中重新运行 op signin 并授权