1Password 密钥代理

内置的 onepassword 插件为智能体提供一个受策略控制的工具，用于 读取一组精选的 1Password 字段。该插件默认禁用，并且在 plugins.entries.onepassword.config 存在之前不会执行任何操作。

这是一个智能体工具，而不是 SecretRef 提供商。它不会注入环境变量， 也不会解析 OpenClaw 配置密钥。

安全模型

• 仅支持服务账户身份验证。令牌保留在本地凭据 文件中，且绝不会在 openclaw.json 中被接受。
• 仅限精选注册表。智能体可以列出已配置的 slug，但该插件绝不会 枚举 1Password 保险库。
• 每个 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 权限对话框。

仅向服务账户授予对插件配置中所注册保险库和项目的读取权限。

开始之前

你需要：

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

启用内置插件：

openclaw plugins enable onepassword

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

mkdir -p ~/.openclaw/credentials/onepasswordchmod 700 ~/.openclaw/credentials/onepasswordprintf '%s' "$OP_SERVICE_ACCOUNT_TOKEN" > \  ~/.openclaw/credentials/onepassword/service-account-tokenchmod 600 ~/.openclaw/credentials/onepassword/service-account-tokenunset OP_SERVICE_ACCOUNT_TOKEN

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

配置已注册的密钥

将插件配置添加到 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 会覆盖默认保险库。opBin 可设置 op 可执行文件的绝对路径；否则插件会从 PATH 解析 op。 项目标题不得以连字符开头。

使用智能体工具

工具名称为 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：使用未过期的长期授权，或请求人工选择仅允许一次、 始终允许或拒绝。

仅允许一次只授权当前工具调用。始终允许会将该智能体和 slug 的长期 授权写入 SQLite；其他智能体必须单独获得 批准。仅当调用方具有具体智能体身份时，OpenClaw 才会提供始终允许 选项。授权将在 grantTtlHours 后过期，默认值为 720 小时。 未解决或超时的批准会拒绝请求；批准等待时间最长为 600 秒。插件最多保留 1,024 个长期授权；达到该 上限时，最早的授权会被逐出，其智能体必须为下一次访问重新获得批准。

每个经过评估的授权只能使用一次，并通过共享 SQLite 状态传递给正在执行的工具 调用，因此当 Gateway 网关进程中有多个 插件实例处于活动状态时，该交接机制仍然有效。未使用的授权会在 600 秒批准窗口结束后过期。

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

检查状态和审计历史记录

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

openclaw onepassword status

此命令会报告令牌文件是否存在、op 是否已解析及其路径、 已注册项目数，以及按策略划分的数量。它绝不会读取或输出 令牌或密钥值。

显示最近的 50 条审计行：

openclaw onepassword auditopenclaw onepassword audit --limit 100

审计行按从新到旧的顺序排列，并显示时间戳、智能体、slug、结果、尝试失败时的 errorCode，以及截断后的原因。原因会按 原样存储；代理绝不会将获取的值添加到审计日志中。

1Password CLI 行为

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

插件只尝试一次。对于 RATE_LIMITED 错误，应先等待， 再由智能体发起后续请求；插件不会创建自动重试 循环。

错误代码

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

1Password 访问错误：

策略和验证错误：