密钥管理

OpenClaw 支持增量采用 SecretRef，因此受支持的凭据无需以明文形式存储在配置中。

运行时模型

• 密钥会在激活期间预先解析到内存中的运行时快照，而不是在请求路径上延迟解析。
• Gateway 网关冷启动时，如果已知的非 Gateway 网关所有者支持隔离，则可将可重试的 SecretRef 故障隔离到该所有者。已映射的所有者类别包括模型提供商和 Skills、媒体/TTS/定时任务提供商、符合条件的身份验证配置文件、按智能体配置的记忆、沙箱 SSH、渠道账号，以及清单中声明的插件路由。Gateway 网关会启动，将该所有者记录为“已配置但不可用”，并发出经过脱敏的降级警告。Gateway 网关入口身份验证、结构无效的引用或解析值、故障时关闭的所有者，以及运行时所有者未映射的引用仍会导致启动失败。
• 重新加载会独立验证每个已映射的所有者，然后以原子方式发布单个快照。健康的所有者会刷新。只有当引用标识、提供商定义和完整的非密钥所有者契约均未改变时，符合条件但验证失败的所有者才会保留其最后一个已知良好值并变为陈旧状态；发生变化或新增但验证失败的所有者会进入冷状态。严格故障会拒绝重新加载，并保留活动快照。
• 策略违规（例如，将 OAuth 模式的身份验证配置文件与 SecretRef 输入结合使用）会在运行时切换前导致激活失败。
• 运行时请求只读取活动的内存快照。模型提供商的 SecretRef 凭据会以进程本地哨兵值的形式经过身份验证存储和流选项，直到出站时才注入。出站传递路径（Discord 回复/线程传递、Telegram 操作发送）也会读取该快照，不会在每次发送时重新解析引用。

这样可以避免密钥提供商中断影响高频请求路径。

Gateway 网关入口保护、结构无效的配置或解析值、策略违规以及未知所有权仍会按故障时关闭方式处理。被隔离的所有者绝不会回退到优先级更低的凭据来源。

出站时注入（哨兵值）

对于由 SecretRef 支持的模型提供商凭据，OpenClaw 会在解析模型身份验证时生成一个不透明的进程本地哨兵值。因此，身份验证存储、流选项、SDK 配置、日志、错误对象和大多数运行时内省所看到的是类似 oc-sent-v1-... 的值，而不是提供商凭据。受保护的模型 fetch 和托管本地提供商健康探测会在每个请求离开进程之前，立即替换 URL 和标头值中的已知哨兵值。

未知的哨兵格式值会在发生网络活动前按故障时关闭方式处理。OpenClaw 会拒绝发送请求，而不是将未解析的哨兵值转发给提供商。作为纵深防御措施，解析后的密钥值也会注册用于精确值日志脱敏。

提供商适配器使用其 SDK 所支持的最靠后的注入点：

• 支持自定义 fetch 选项的 SDK 会接收 OpenClaw 的受保护 fetch，因此 SDK 会保留哨兵值。
• 不支持自定义 fetch 选项的 SDK 会在构造客户端之前立即解包哨兵值。插件所有的提供商流和 agent harness 会在核心所有的最终交接点解包，因为这些传输机制不共享 OpenClaw 的受保护 fetch。

哨兵值可以减少模型调用链中的明文暴露，但并不提供进程隔离。真实值仍存在于同一进程的内存中，并会出现在最终适配器边界。未通过 SecretRef 配置的明文环境凭据仍是明文，不属于此机制的保护范围。

设置 OPENCLAW_SECRET_SENTINELS=off（也接受 0 或 false，不区分大小写）可在事件响应或兼容性故障排除期间禁用哨兵值生成。此终止开关不会禁用精确值脱敏注册。

智能体访问边界

SecretRef 可防止凭据持久化到配置和生成的模型文件中，但它并不是进程隔离边界。如果明文凭据仍存储在智能体可读取的磁盘路径中，则仍可通过文件或 shell 工具读取，从而绕过 API 层脱敏。

对于将智能体可访问文件纳入保护范围的生产部署，只有满足以下所有条件时，才应视为迁移完成：

• 受支持的凭据使用 SecretRef，而不是明文值。
• 已从 openclaw.json、auth-profiles.json、.env 和生成的 models.json 文件中清除旧版明文残留。
• 迁移后，openclaw secrets audit --check 的检查结果无异常。
• 任何剩余的不受支持或轮换凭据均受操作系统隔离、容器隔离或外部凭据代理保护。

因此，审计/配置/应用工作流是安全迁移的门槛，而不只是一个便捷辅助工具。

活动表面筛选

仅对实际处于活动状态的表面验证 SecretRef：

• 已启用的表面：对于已映射且可隔离的所有者，可重试故障会进入冷降级或陈旧降级状态。严格、故障时关闭、Gateway 网关必需或未映射的故障会阻止启动/重新加载。
• 非活动表面：未解析的引用不会阻止启动/重新加载；它们会发出非致命的 SECRETS_REF_IGNORED_INACTIVE_SURFACE 诊断。

Gateway 网关身份验证表面诊断

在 gateway.auth.token、gateway.auth.password、gateway.remote.token 或 gateway.remote.password 上设置 SecretRef 后，Gateway 网关启动/重新加载会使用代码 SECRETS_GATEWAY_AUTH_SURFACE 记录表面状态：

• active：SecretRef 是有效身份验证表面的一部分，必须成功解析。
• inactive：另一个身份验证表面胜出，或者远程身份验证已禁用/未处于活动状态。

日志条目包含活动表面策略所采用的原因。

新手引导引用预检

在交互式新手引导中，选择 SecretRef 存储后，会在保存前运行预检验证：

• 环境引用：验证环境变量名称，并确认设置期间可见的值非空。
• 提供商引用（file 或 exec）：验证提供商选择、解析 id，并检查解析值的类型。
• 快速开始流程：当 gateway.auth.token 已是 SecretRef 时，新手引导会在探测/仪表板引导启动前，使用相同的快速失败门槛解析该引用（适用于 env、file 和 exec 引用）。

验证失败时会显示错误，并允许你重试。

SecretRef 契约

所有位置均使用同一种对象结构：

{ source: "env" | "file" | "exec", provider: "default", id: "..." }

{ source: "env", provider: "default", id: "OPENAI_API_KEY" }

"${OPENAI_API_KEY}""$OPENAI_API_KEY"

{ source: "file", provider: "filemain", id: "/providers/openai/apiKey" }

{ source: "exec", provider: "vault", id: "providers/openai/apiKey#value" }

提供商配置

在 secrets.providers 下定义提供商：

{  secrets: {    providers: {      default: { source: "env" },      filemain: {        source: "file",        path: "~/.openclaw/secrets.json",        mode: "json", // 或 "singleValue"      },      vault: {        source: "exec",        command: "/usr/local/bin/openclaw-vault-resolver",        args: ["--profile", "prod"],        passEnv: ["PATH", "VAULT_ADDR"],        jsonOnly: true,      },      "team-secrets": {        source: "exec",        pluginIntegration: {          pluginId: "acme-secrets",          integrationId: "secret-store",        },      },    },    defaults: {      env: "default",      file: "filemain",      exec: "vault",    },  },}

{ "protocolVersion": 1, "provider": "vault", "ids": ["providers/openai/apiKey"] }

{ "protocolVersion": 1, "values": { "providers/openai/apiKey": "<openai-api-key>" } } // pragma: allowlist secret

{"protocolVersion": 1,"values": {},"errors": { "providers/openai/apiKey": { "code": "NOT_FOUND" } }}

基于文件的 API 密钥

不要在配置的 env 块中放置 file:... 字符串。该块按字面值处理且不可覆盖，因此永远不会在其中解析 file:...。

请改为在受支持的凭据字段上使用文件 SecretRef：

{  secrets: {    providers: {      xai_key_file: {        source: "file",        path: "~/.openclaw/secrets/xai-api-key.txt",        mode: "singleValue",      },    },  },  models: {    providers: {      xai: {        apiKey: { source: "file", provider: "xai_key_file", id: "value" },      },    },  },}

对于 mode: "singleValue"，SecretRef id 为 "value"。对于 mode: "json"，请使用绝对 JSON 指针，例如 "/providers/xai/apiKey"。

有关接受 SecretRef 的字段，请参阅 SecretRef 凭据适用范围。

Exec 集成示例

有关服务账户、内置 Agent Skills 和故障排除的 1Password 专用指南，请参阅 1Password。

{  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" },      },    },  },}

{  secrets: {    providers: {      bws: {        source: "exec",        command: "/usr/local/bin/openclaw-bws-resolver.mjs",        passEnv: ["BWS_ACCESS_TOKEN", "BWS_SERVER_URL", "PATH", "BWS_BIN"],        jsonOnly: true,      },    },  },  models: {    providers: {      openai: {        baseUrl: "https://api.openai.com/v1",        models: [{ id: "gpt-5", name: "gpt-5" }],        apiKey: {          source: "exec",          provider: "bws",          id: "openclaw/providers/openai/apiKey",        },      },    },  },}

openclaw secrets audit --allow-exec

{  secrets: {    providers: {      vault_openai: {        source: "exec",        command: "/opt/homebrew/bin/vault",        allowSymlinkCommand: true, // Homebrew 符号链接二进制文件需要此项        trustedDirs: ["/opt/homebrew"],        args: ["kv", "get", "-field=OPENAI_API_KEY", "secret/openclaw"],        passEnv: ["VAULT_ADDR", "VAULT_TOKEN"],        jsonOnly: false,      },    },  },  models: {    providers: {      openai: {        baseUrl: "https://api.openai.com/v1",        models: [{ id: "gpt-5", name: "gpt-5" }],        apiKey: { source: "exec", provider: "vault_openai", id: "value" },      },    },  },}

#!/usr/bin/env nodeconst { spawnSync } = require("node:child_process"); let stdin = "";process.stdin.setEncoding("utf8");process.stdin.on("data", (chunk) => {  stdin += chunk;});process.stdin.on("error", (err) => {  process.stderr.write(`${err.message}\n`);  process.exit(1);});process.stdin.on("end", () => {  let request;  try {    request = JSON.parse(stdin || "{}");  } catch (err) {    process.stderr.write(`Failed to parse request: ${err.message}\n`);    process.exit(1);  }   const passBin = process.env.PASS_BIN || "pass";  const values = {};  const errors = {};   for (const id of request.ids ?? []) {    const result = spawnSync(passBin, ["show", id], { encoding: "utf8" });    if (result.status === 0) {      values[id] = result.stdout.split(/\r?\n/, 1)[0] ?? "";    } else {      errors[id] = { message: (result.stderr || `pass exited ${result.status}`).trim() };    }  }   process.stdout.write(JSON.stringify({ protocolVersion: 1, values, errors }));});

{  secrets: {    providers: {      pass_store: {        source: "exec",        command: "/usr/local/bin/openclaw-pass-resolver",        passEnv: ["PATH", "HOME", "GNUPGHOME", "GPG_TTY", "PASSWORD_STORE_DIR", "PASS_BIN"],        jsonOnly: true,      },    },  },  models: {    providers: {      openai: {        baseUrl: "https://api.openai.com/v1",        models: [{ id: "gpt-5", name: "gpt-5" }],        apiKey: {          source: "exec",          provider: "pass_store",          id: "openclaw/providers/openai/apiKey",        },      },    },  },}

openclaw secrets audit --checkopenclaw secrets audit --allow-exec

{  secrets: {    providers: {      sops_openai: {        source: "exec",        command: "/opt/homebrew/bin/sops",        allowSymlinkCommand: true, // Homebrew 符号链接二进制文件需要此项        trustedDirs: ["/opt/homebrew"],        args: ["-d", "--extract", '["providers"]["openai"]["apiKey"]', "/path/to/secrets.enc.json"],        passEnv: ["SOPS_AGE_KEY_FILE"],        jsonOnly: false,      },    },  },  models: {    providers: {      openai: {        baseUrl: "https://api.openai.com/v1",        models: [{ id: "gpt-5", name: "gpt-5" }],        apiKey: { source: "exec", provider: "sops_openai", id: "value" },      },    },  },}

MCP 服务器环境变量

通过 plugins.entries.acpx.config.mcpServers 配置的 MCP 服务器环境变量接受 SecretInput，从而避免在明文配置中存放 API 密钥和令牌：

{  plugins: {    entries: {      acpx: {        enabled: true,        config: {          mcpServers: {            github: {              command: "npx",              args: ["-y", "@modelcontextprotocol/server-github"],              env: {                GITHUB_PERSONAL_ACCESS_TOKEN: {                  source: "env",                  provider: "default",                  id: "MCP_GITHUB_PAT",                },              },            },          },        },      },    },  },}

明文字符串值仍然有效。类似 ${MCP_SERVER_API_KEY} 的环境变量模板引用和 SecretRef 对象会在 Gateway 网关激活期间、MCP 服务器进程生成之前解析。与其他 SecretRef 适用范围一样，仅当 acpx 插件实际处于活动状态时，未解析的引用才会阻止激活。

沙箱 SSH 身份验证材料

核心 ssh 沙箱后端还支持将 SecretRef 用于 SSH 身份验证材料：

{  agents: {    defaults: {      sandbox: {        mode: "all",        backend: "ssh",        ssh: {          target: "user@gateway-host:22",          identityData: { source: "env", provider: "default", id: "SSH_IDENTITY" },          certificateData: { source: "env", provider: "default", id: "SSH_CERTIFICATE" },          knownHostsData: { source: "env", provider: "default", id: "SSH_KNOWN_HOSTS" },        },      },    },  },}

运行时行为：

• OpenClaw 在沙箱激活期间解析这些引用，而不是在每次 SSH 调用时延迟解析。
• 解析后的值会以严格的文件权限（0o600）写入临时目录，并用于生成的 SSH 配置。
• 如果生效的沙箱后端不是 ssh（或沙箱模式为 off），这些引用将保持非活动状态，并且不会阻止启动。

支持的凭据范围

SecretRef 凭据范围中列出了规范支持和不支持的凭据。

必需行为和优先级

• 没有引用的字段：保持不变。
• 带有引用的字段：激活期间在活动范围上为必需项。
• 如果明文和引用同时存在，在支持优先级的路径上引用优先。
• 脱敏哨兵值 __OPENCLAW_REDACTED__ 保留用于内部配置脱敏/还原；如果将其作为字面配置数据提交，则会被拒绝。

警告和审计信号：

• SECRETS_REF_OVERRIDES_PLAINTEXT（运行时警告）
• REF_SHADOWED（当 auth-profiles.json 凭据的优先级高于 openclaw.json 引用时产生的审计发现）

Google Chat serviceAccount 接受内联 JSON 或 SecretRef。如果此规范字段未设置，Doctor 会将已弃用的同级字段 serviceAccountRef 移入其中。

激活触发条件

Secret 激活会在以下情况运行：

• 启动（预检加最终激活）
• 配置重载热应用路径
• 配置重载重启检查路径
• 通过 secrets.reload 手动重载
• Gateway 配置写入 RPC 预检（config.set / config.apply / config.patch），在持久化编辑内容之前，验证所提交配置载荷中活动范围的 SecretRef

激活契约：

• 成功时会以原子方式替换快照。
• 严格启动失败会中止 Gateway 网关启动。
• 在冷启动期间，如果某个已映射、可隔离的非 Gateway 网关所有者发生可重试的解析失败，可以发布快照，并将该确切所有者配置为不可用。对该所有者的请求会以 SECRET_SURFACE_UNAVAILABLE 失败；显式引用失败后，模型提供商所有者不会回退到环境或身份验证配置文件凭据。
• 重载和重启检查会隔离符合条件的已映射所有者。引用标识未变、提供商定义未变且完整的非 Secret 所有者契约未变时，会将其最后一次已知正常的确切值保留为陈旧状态；发生变更或新配置但无法解析的引用仅会使对应所有者以冷状态发布。严格重载失败会保留先前的活动快照。
• config.set、config.apply 和 config.patch 接受可隔离所有者中语法有效但尚未解析的引用，并返回脱敏的 degradedSecretOwners 报告。Gateway 网关入口身份验证、结构无效的配置或解析值、策略违规以及未知所有者仍会在修改磁盘之前被拒绝。
• 即使另一个所有者处于冷状态或陈旧状态，正常的同级所有者仍会正常解析并发布。
• 为出站辅助函数/工具调用提供显式的单次调用渠道令牌不会触发 SecretRef 激活；激活点仍为启动、重载和显式 secrets.reload。

降级和恢复信号

在正常状态之后，如果重载时激活失败，OpenClaw 会进入 Secret 降级状态，并发出一次性系统事件和日志代码：

• SECRETS_RELOADER_DEGRADED
• SECRETS_RELOADER_RECOVERED

行为：

• 降级：正常的所有者会刷新，陈旧的所有者保留最后一次已知正常值，冷状态所有者仍不可用。
• 已恢复：下一次激活成功后发出一次。
• 已经处于降级状态时，重复失败会记录警告，但不会再次发出事件。
• 严格启动失败绝不会发出降级事件，因为运行时从未进入活动状态。存在冷状态所有者但启动成功时，会记录所有者降级情况，但不会发出重载器事件。
• 引用范围的启动和重载失败会为每个受影响的所有者发出结构化的 SECRETS_DEGRADED 警告。提供商范围的故障会发出一条 SECRETS_PROVIDER_DEGRADED 警告，其中包含提供商及完整的受影响所有者列表，而不是针对每个所有者重复提供商故障。警告包含脱敏原因、cold 或 stale 所有者状态，以及 openclaw secrets reload 重试提示。警告绝不包含解析值或 SecretRef ID。
• openclaw doctor 会列出冷状态和陈旧状态所有者及其受影响的配置路径、脱敏原因和重试指导。

命令路径解析

命令路径可以通过 Gateway 网关快照 RPC 选择使用受支持的 SecretRef 解析。适用两类基本行为：

其他说明：

• 后端 Secret 轮换后的快照刷新由 openclaw secrets reload 处理。
• 这些命令路径使用的 Gateway 网关 RPC 方法：secrets.resolve。

审计和配置工作流

默认操作员流程：

openclaw secrets audit --check

openclaw secrets configure --apply

openclaw secrets audit --check

重新审计结果未清除所有问题之前，不要认为迁移已完成。如果审计仍报告静态存储中存在明文值，即使运行时 API 返回脱敏值，智能体访问风险仍然存在。

如果在 configure 期间保存计划而不是应用，请在重新审计之前使用 openclaw secrets apply --from <plan-path> 应用该已保存计划。

openclaw secrets apply --from /tmp/openclaw-secrets-plan.jsonopenclaw secrets apply --from /tmp/openclaw-secrets-plan.json --allow-execopenclaw secrets apply --from /tmp/openclaw-secrets-plan.json --dry-runopenclaw secrets apply --from /tmp/openclaw-secrets-plan.json --dry-run --allow-exec

单向安全策略

安全模型：

• 进入写入模式之前，预检必须成功。
• 提交之前会验证运行时激活。
• 应用时通过原子文件替换更新文件，并在失败时尽力还原。

旧版身份验证兼容性说明

对于静态凭据，运行时不再依赖明文旧版身份验证存储。

• 运行时凭据来源是解析后的内存快照。
• 发现旧版静态 api_key 条目时会将其清除。
• OAuth 相关兼容行为保持独立。

Web UI 说明

某些 SecretInput 联合类型在原始编辑器模式中比在表单模式中更容易配置。

相关内容

• 身份验证 - 身份验证设置
• CLI：密钥 - CLI 命令
• Vault SecretRefs - HashiCorp Vault 提供商设置
• 环境变量 - 环境变量优先级
• SecretRef 凭据界面 - 凭据界面
• 密钥应用计划契约 - 计划契约详情
• 安全性 - 安全态势