OpenClawDocs
View as MarkdownView this page as plain textOpen in ChatGPTAsk questions about this pageOpen in ClaudeAsk questions about this page

快速开始

1Password

OpenClaw 以两种相互独立的方式与 1Password 配合使用：

  • 配置密钥： openclaw.json 中的任何 SecretRef 字段都可以在运行时通过 op CLI 解析，因此 API 密钥绝不会存放在配置文件中。
  • **智能体工作流：**内置的 1password 技能会指导智能体使用 op 登录、读取密钥或注入密钥，以完成各自的任务。

要求

  • Gateway 网关主机上已安装 1Password CLI（op；在 macOS 上为 brew install 1password-cli）。
  • 为 op 配置一种身份验证模式：
    • 服务账户（建议用于无头 Gateway 网关）：在 Gateway 网关服务环境中导出 OP_SERVICE_ACCOUNT_TOKEN。不需要桌面应用，也不需要交互式登录。
    • 桌面应用集成：1Password 应用与 Gateway 网关运行在同一台计算机上，并已启用 CLI 集成。首次调用可能会触发 Touch ID 或系统身份验证。
    • 独立登录：op signin 会在每个会话中提示登录。智能体可以通过该技能使用这种方式，但它不适合在无头 Gateway 网关上解析配置密钥。

使用 op 解析配置密钥

声明一个运行 op read 并使用 op://vault/item/field 引用的 exec 密钥提供商，然后将任何支持 SecretRef 的字段指向它：

json5
{  secrets: {    providers: {      onepassword_openai: {        source: "exec",        command: "/opt/homebrew/bin/op",        allowSymlinkCommand: true, // Homebrew 符号链接二进制文件需要此项        trustedDirs: ["/opt/homebrew"],        args: ["read", "op://Personal/OpenClaw QA API Key/password"],        passEnv: ["HOME"],        jsonOnly: false,      },    },  },  models: {    providers: {      openai: {        baseUrl: "https://api.openai.com/v1",        models: [{ id: "gpt-5", name: "gpt-5" }],        apiKey: { source: "exec", provider: "onepassword_openai", id: "value" },      },    },  },}

各部分的协作方式如下：

  • command 必须是绝对路径；trustedDirs 将其目录标记为受信任目录；由于 Homebrew 将 op 安装为符号链接，因此还需要 allowSymlinkCommand。
  • args 会原样传递 op://vault/item/field 引用。OpenClaw 本身不会解析 op:// 方案；它由 op 二进制文件解析。
  • passEnv 会从 Gateway 网关环境中转发列出的变量。桌面应用集成需要 HOME；服务账户还要求 Gateway 网关服务环境中存在 OP_SERVICE_ACCOUNT_TOKEN（将其添加到 passEnv；仅当你接受令牌可从配置文件中读取时，才通过 env 设置）。
  • 对于单值输出，请保留 id: "value"。使用 jsonOnly: true 和 JSON 载荷时，应改用 JSON 指针 ID 访问字段。
  • 每个密钥使用一个提供商条目可确保引用便于审计；请根据使用方命名提供商（onepassword_openai、onepassword_telegram）。

有关解析顺序、缓存和失败语义，请参阅 Gateway 网关密钥；有关所有接受 SecretRef 的字段，请参阅 SecretRef 凭据范围。

无头 Gateway 网关的服务账户设置

  1. 在你的 1Password 账户中创建服务账户，并仅授予其对 Gateway 网关所需保险库项目的读取权限。
  2. 向 Gateway 网关服务提供 OP_SERVICE_ACCOUNT_TOKEN（通过 launchd plist、systemd 单元或容器环境变量）。
  3. 将 "OP_SERVICE_ACCOUNT_TOKEN" 添加到提供商的 passEnv 列表中。
  4. 在 Gateway 网关主机环境中验证：op whoami 应直接输出服务账户，不应显示提示。

服务账户读取要求在 op:// 引用中明确指定保险库名称。请严格限制账户权限范围；它是一项持有者凭据。

面向智能体的 1password 技能

OpenClaw 内置了 1password 技能，使智能体能够熟练操作 op：它会检测可用的身份验证模式（服务账户、桌面应用集成或独立登录），在读取任何内容前使用 op whoami 验证访问权限，并优先使用 op run / op inject，而不是将密钥值写入磁盘。该技能需要 op 二进制文件；如果缺失，则会提供 Homebrew 安装方式。

智能体会将其用于自身的工作流，例如在任务执行期间读取部署令牌，或向命令中注入环境变量。它与配置密钥解析相互独立；Gateway 网关无需任何技能参与即可解析 SecretRef。

安全说明

  • 通过 exec 提供商解析的密钥值会保留在 Gateway 网关内存中；配置快照和 config.get 响应会遮盖 SecretRef 字段。
  • 绝不要将密钥值放入 openclaw.json、日志或聊天中。配置中仅保留项目名称，值应存放在 1Password 中。
  • 1Password 审计跟踪会显示服务账户的每次读取操作，使密钥轮换和事件审查切实可行。

故障排查

  • command not found 或生成进程错误：使用 op 的绝对路径，并将其目录加入 trustedDirs。
  • op 可以解析，但读取因符号链接错误而失败：对于 Homebrew 安装，请设置 allowSymlinkCommand: true。
  • account is not signed in：对于服务账户，请确认 OP_SERVICE_ACCOUNT_TOKEN 已传入 Gateway 网关服务，并列在 passEnv 中；对于桌面集成，请确认应用正在运行且已解锁。
  • 首次读取缓慢：提高提供商的 timeoutMs；在繁忙主机上，op 冷启动可能会超过严格的超时时间。
Was this useful?
On this page

On this page