1Password¶

内置的 onepassword 插件提供两个相互独立、需显式启用的功能面：

• 一个受管的 exec 提供器，用于在 Gateway 启动、重新加载、审计和应用预检期间解析配置的 SecretRefs
• 一个受策略控制的代理工具，用于读取一组精选的 1Password 字段

两者都使用官方的 op CLI 和同一个服务账户令牌文件。单独启用插件并不会暴露代理工具：该功能面还需要一个已配置的条目注册表。

安全模型¶

• 仅限服务账户认证。令牌保存在本地凭据文件中，绝不会在 openclaw.json 中接受。
• 仅限精选代理注册表。代理可以列出已配置的 slug，但插件绝不会枚举 1Password 保管库。SecretRef 读取仅限于显式存储在已注册 OpenClaw 凭据目标上的引用。
• 每个 slug 可设置 auto、approve 或 deny 策略。
• 审批授权会过期。缓存值绝不会绕过当前策略。
• 每次访问尝试都会记录在 OpenClaw 的共享 SQLite 状态中。审计行包含提供的理由；请保持理由不敏感。代理层绝不会将获取到的值或服务令牌复制到审计行中。
• 当前工具执行结束后，OpenClaw 自己的转录持久化会用脱敏元数据替换成功的 get 值。
• 该值在该次执行中对模型可见。如果模型将其复制到后续的工具调用或回复中，该独立记录不在本插件的持久化钩子范围内。请保持策略范围狭窄，且不要要求模型回显值。
• 插件在每次缓存未命中时调用一次 op。它不会重试速率限制或其他失败。
• 每次 op 调用都在最小化环境中运行，该环境禁用 1Password 桌面应用集成（OP_LOAD_DESKTOP_APP_SETTINGS=false、OP_BIOMETRIC_UNLOCK_ENABLED=false），因此安装在 Gateway 主机上的 1Password 应用绝不会触发生物识别或 macOS 权限对话框。

仅向服务账户授予已注册 SecretRef 和代理工具 slug 所使用的保管库和条目的读取权限。

开始之前¶

你需要：

• 在 Gateway 主机上安装 1Password CLI（op）
• 一个有权访问所选条目的 1Password 服务账户
• 一个专用的服务账户令牌文件

启用内置插件：

openclaw plugins enable onepassword

在 OpenClaw 状态目录下创建令牌目录和文件：

mkdir -p ~/.openclaw/credentials/onepassword
chmod 700 ~/.openclaw/credentials/onepassword
printf '%s' "$OP_SERVICE_ACCOUNT_TOKEN" > \
  ~/.openclaw/credentials/onepassword/service-account-token
chmod 600 ~/.openclaw/credentials/onepassword/service-account-token
unset OP_SERVICE_ACCOUNT_TOKEN

当设置了 OPENCLAW_STATE_DIR 时，请用该目录替换 ~/.openclaw。如果令牌文件可被组用户或其他用户读取或写入，插件会警告一次。

配置 SecretRefs¶

为常见模型提供器密钥创建 secrets apply 计划：

openclaw onepassword secretref setup \
  --anthropic-id op://Automation/Anthropic/credential \
  --openrouter-id op://Automation/OpenRouter/credential \
  --plan-out ./openclaw-1password-secrets-plan.json

对于其他模型提供器，使用 --provider-key <provider=id>；对于任何已注册的 SecretRef 凭据目标，使用 --target <path=id>。该命令至少需要一个目标，并且会写入一个计划。检查该计划，确认本地 op 和令牌文件前提条件，然后应用并重新加载：

openclaw onepassword secretref status
openclaw secrets apply --from ./openclaw-1password-secrets-plan.json --dry-run --allow-exec
openclaw secrets apply --from ./openclaw-1password-secrets-plan.json --allow-exec
openclaw secrets audit --check --allow-exec
openclaw secrets reload

在 apply 之前，status 可能会报告提供器本身尚未配置；prerequisites ready: yes 确认受信任的 op 可执行文件和可接受的非空令牌文件已就绪。apply 之后，ready: yes 确认提供器连接和前提条件都已就绪。缺失或不安全的前提条件会给出可操作的下一个步骤，而不会打印令牌或原始解析器错误。

手动提供器配置使用现有插件 ID：

{
  plugins: {
    entries: {
      onepassword: { enabled: true },
    },
  },
  secrets: {
    providers: {
      onepassword: {
        source: "exec",
        pluginIntegration: {
          pluginId: "onepassword",
          integrationId: "onepassword",
        },
      },
    },
  },
  models: {
    providers: {
      openai: {
        apiKey: {
          source: "exec",
          provider: "onepassword",
          id: "op://Automation/OpenAI/credential",
        },
      },
    },
  },
}

引用使用 op://<vault>/<item>/<field> 或 op://<vault>/<item>/<section>/<field> 形式。保管库、条目、分区和字段名称可以包含空格。setup 命令会将不符合 OpenClaw 共享 exec-id 语法的引用，以插件本地的不透明形式存储，并且仅在解析器内部解码它们。非常长的引用应使用稳定的 1Password ID；这些 ID 更短，并能减少 1Password API 请求次数。

SecretRef 解析器最多并发运行四个 op read 进程；它禁用 1Password CLI 缓存，以便重新加载时能观察到轮换后的值；它绝不使用桌面应用集成，也不会为任意读取暴露代理工具。在传递服务账户令牌之前，两个插件功能面都会解析可执行文件，并拒绝其他本地账户可替换的路径；Windows ACL 验证也必须成功。使用以下命令检查提供器连接和本地就绪状态：

openclaw onepassword secretref status --json

配置已注册的 secrets¶

向 openclaw.json 添加插件配置：

{
  "plugins": {
    "entries": {
      "onepassword": {
        "enabled": true,
        "config": {
          "vault": "Automation",
          "defaultPolicy": "approve",
          "cacheTtlSeconds": 300,
          "grantTtlHours": 720,
          "opTimeoutMs": 15000,
          "items": {
            "repository-token": {
              "item": "Repository automation token",
              "field": "credential",
              "policy": "approve",
              "description": "Token for repository automation",
            },
            "model-key": {
              "item": "Model provider key",
              "vault": "Agent credentials",
              "policy": "auto",
            },
          },
        },
      },
    },
  },
}

Slug 只能使用小写字母、数字和连字符，必须以字母或数字开头，且最多包含 64 个字符。注册表最多可包含 32 个 slug；描述最多可包含 200 个字符。field 接受一个字段标签或 ID，不能包含逗号，默认值为 credential。 条目级别的 vault 会覆盖默认 vault。opBin 可以设置 op 可执行文件的绝对路径；否则插件会从 PATH 中解析 op。 条目标题不能以连字符开头。

使用 agent 工具¶

工具名称为 onepassword。

列出已注册的 slug：

{ "action": "list" }

结果仅包含 slug、描述、策略，以及是否存在有效的长期授权。它从不包含机密值，也不会查询 1Password。

请求一个机密：

{
  "action": "get",
  "slug": "repository-token",
  "reason": "Authenticate the requested repository operation"
}

reason 为必填项，必须非空，且限制为 300 个字符。成功的 get 会返回该值，以及已配置的 slug、条目标题和字段标签。

工具模式还声明了一个内部参数 authorizationNonce。策略层在评估请求后注入该参数，以便将授权传递给正在执行的工具调用。切勿手动设置它：策略钩子会覆盖任何提供的值，未知值会导致请求失败。

策略层级与审批¶

• auto：立即获取并审计该请求。
• deny：阻止并审计该请求。
• approve：使用未过期的长期授权，或请求人工选择允许一次、始终允许或拒绝。

“允许一次”仅授权当前工具调用。“始终允许”会为相应 agent 和 slug 在 SQLite 中写入一条长期授权；其他 agent 必须获得各自的审批。仅当调用方具有明确的 agent 身份时，OpenClaw 才会提供“始终允许”。授权在 grantTtlHours 后过期，默认值为 720 小时。 未解决或超时的审批会拒绝请求；最大审批等待时间为 600 秒。插件最多保留 1,024 条长期授权；达到该上限时，最早的授权会被移除，其 agent 必须为下一次访问重新审批。

每个已评估的授权均为一次性使用，并通过共享 SQLite 状态传递给正在执行的工具调用，因此当网关进程中存在多个插件实例时，该传递机制仍然有效。未使用的授权会在 600 秒审批窗口后过期。

待处理授权的读取和写入在 SQLite 工作线程上运行。工具执行会等待某次审批的待处理写入完成后再消费它；写入失败会使请求失败，而不会获取机密。现有待处理行及其过期时间在更新之间保持兼容。

内存缓存默认值为 300 秒，并受已配置的 slug 注册表限制。将 cacheTtlSeconds 设置为 0 可禁用它。每次缓存查找前都会评估策略，并且缓存命中会被审计。运行时配置重新加载会在每个策略和执行边界生效；禁用插件，或移除、拒绝或重新指向某个 slug，会使待处理授权和缓存值失效。

检查状态和审计历史¶

显示就绪状态和注册表计数：

openclaw onepassword status

这会报告 token 文件是否存在、op 是否已解析及其路径、已注册条目数量，以及按策略统计的数量。它从不读取或打印 token 或机密值。

显示最近 50 条审计记录：

openclaw onepassword audit
openclaw onepassword audit --limit 100

记录按最新优先排序，并显示时间戳、agent、slug、结果、尝试失败时的 errorCode，以及截断后的原因。原因按提供的内容存储；broker 从不将获取到的值添加到审计日志中。

1Password CLI 行为¶

每次缓存未命中都会运行 op item get，使用已配置的条目、vault 和精确字段选择器、JSON 输出、有限超时以及 --cache=false。子进程仅接收该字段，而不是完整条目。子进程环境中仅存在 OP_SERVICE_ACCOUNT_TOKEN 和 HOME。

插件只尝试一次。RATE_LIMITED 错误应通过等待来处理，以便在后续 agent 请求前重试；插件不会创建自动重试循环。

错误代码¶

失败尝试会在工具结果和审计行中携带一个固定错误代码。

1Password 访问错误：

策略和验证错误：

相关¶

• 密钥管理
• 1Password — 内置的 op:// 密钥源，以及插件、技能和 MCP 选项的对比
• openclaw secrets — 从 CLI 存储、重新加载、审计、配置并应用 SecretRefs