op-session

用途

op-session 是面向 Claude Code 的 1Password CLI 会话初始化技能。它解决的问题是：Claude Code 每次执行 Bash 工具调用都会在无 TTY 的新子进程中运行，而 1Password CLI 的应用集成将认证绑定到终端会话，因此每次 op 调用都会触发生物识别提示。该技能通过自动检测认证模式并做相应配置来消除重复认证。

主要能力

自动检测并配置两种认证模式：

• Token 模式：当 op signin --raw 返回非空令牌时，将令牌缓存到 ~/.op-claude-session，后续调用由包装脚本传递 --session 标志。
• App Integration 模式：当 op signin --raw 返回为空且 op whoami 成功时，在会话文件中记录模式，包装脚本直接调用 op（通过桌面应用 IPC 认证）。

工作流程：/op-session [--account <name>] → op signin --raw → 若令牌非空则进入 Token 模式（验证 → 写入会话文件 → 完成）；若令牌为空则检查 op whoami 是否成功，成功则进入 App Integration 模式（写入会话文件，不含令牌 → 完成），失败则报错 signin failed。

使用方式

初始化会话：

bash skills/op-session/scripts/op-session-init.sh
# 或指定账户
bash skills/op-session/scripts/op-session-init.sh --account my-team

列出可用账户：

bash skills/op-session/scripts/op-session-init.sh --list

检查会话状态：

bash skills/op-session/scripts/op-session-init.sh --check

清除会话：

bash skills/op-session/scripts/op-session-init.sh --clear

后续 op 调用（推荐使用安全辅助脚本，它处理模式检测、令牌加载、校验与过期）：

bash skills/op-session/scripts/op-with-session.sh read "op://vault/item/field"
bash skills/op-session/scripts/op-with-session.sh item list --vault Production
bash skills/op-session/scripts/op-with-session.sh whoami

辅助脚本的行为：从会话文件（OP_AUTH_MODE）自动检测认证模式；Token 模式传递 --session 和 --account 标志；App 模式仅传递 --account 标志（通过桌面应用 IPC 认证）；每次调用前校验会话；若会话缺失、过期或应用被锁定则返回明确错误。

会话生命周期

事件	Token 模式	App Integration 模式
空闲超时	30 分钟 → 过期	10 分钟 → 过期（使用时自动刷新）
每次 op 调用	重置空闲计时器	重置空闲计时器
硬性上限	12 小时	12 小时
1Password 应用锁定	不撤销令牌	下次 op 调用失败，直到解锁
/op-session --clear	移除会话文件	移除会话文件

会话文件格式

# Token 模式
export OP_AUTH_MODE='token'
export OP_SESSION='<session-token>'
export OP_ACCOUNT='<account-id>'

# App Integration 模式
export OP_AUTH_MODE='app'
export OP_SESSION=''
export OP_ACCOUNT='<account-id>'

旧版会话文件（不含 OP_AUTH_MODE）在 OP_SESSION 非空时会被自动识别为 Token 模式。

安全

方面	Token 模式	App Integration 模式
静态令牌	~/.op-claude-session（通过 umask 077 仅所有者可访问）	不存储令牌
进程参数	--session $TOKEN 对同用户进程可见	无 --session 标志
认证控制	持有令牌即访问	桌面应用生物识别
范围	你可访问的所有保险库	你可访问的所有保险库
风险等级	中等（令牌落盘）	较低（无令牌落盘）
缓解措施	短生命周期令牌，完成后 --clear	应用自动管理会话

已知限制

限制	原因	变通方法
在 ! 上下文检查中，对主目录路径执行 ls 被阻止	Claude Code 沙箱可能在命令模板展开时限制 ls/find 到工作目录	通过 bash -c 包装使用 test -f；参见 skills/op-session/SKILL.md
allowed-tools 无法收窄到特定脚本路径	命令 markdown 中 ${CLAUDE_PLUGIN_ROOT} 不可用（#9354）	在上游修复前保留 Bash(bash:*)
上下文检查是尽力而为的 UI	沙箱策略可能收紧	权威状态通过 bash skills/op-session/scripts/op-session-init.sh --check 获取
桌面应用锁定时 App 模式失败	CLI 无法与锁定的应用进行 IPC	解锁 1Password 应用，或运行 /op-session 重新初始化

前置条件

• 已安装并配置 1Password CLI（op）
• 1Password 桌面应用正在运行（用于初始生物识别认证）
• 账户已登录 1Password 应用

适用场景

适用于在 Claude Code 中需要访问 1Password 密钥的会话、op CLI 反复提示生物识别认证、以及需要为 Claude Code 配置 1Password 会话的场景。