密钥管理

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

运行时模型

• Secret 会在激活期间预先解析到内存中的运行时快照中，而不是在请求路径上延迟解析。
• 当实际处于活动状态的 SecretRef 无法解析时，启动会快速失败。
• 重载采用原子交换：要么完全成功，要么保留最后一个已知良好的快照。
• 策略违规（例如，将 OAuth 模式的身份验证配置文件与 SecretRef 输入组合使用）会在运行时交换之前导致激活失败。
• 运行时请求仅从活动的内存快照中读取。模型提供商的 SecretRef 凭据会以进程本地哨兵值的形式穿过身份验证存储和流式选项，直至出站。出站交付路径（Discord 回复/话题串交付、Telegram 操作发送）也会读取该快照，不会在每次发送时重新解析引用。

这样可以避免 Secret 提供商故障影响高频请求路径。

出站时注入（哨兵值）

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

形似哨兵值的未知值会在发生网络活动前以失败关闭方式处理。OpenClaw 会拒绝发送请求，而不是将未解析的哨兵值转发给提供商。作为纵深防御措施，已解析的 Secret 值还会注册用于精确值日志脱敏。

提供商适配器使用其 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：

• 已启用表面：未解析的引用会阻止启动/重载。
• 非活动表面：未解析的引用不会阻止启动/重载；它们会发出非致命的 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",    },    resolution: {      maxProviderConcurrency: 4,      maxRefsPerProvider: 512,      maxBatchBytes: 262144,    },  },}

{ "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 集成示例

{  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 兼容性：serviceAccountRef 的优先级高于明文 serviceAccount；设置同级引用后，明文值会被忽略。

激活触发条件

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

• 启动（预检加最终激活）
• 配置重新加载的热应用路径
• 配置重新加载的重启检查路径
• 通过 secrets.reload 手动重新加载
• Gateway 网关配置写入 RPC 预检（config.set / config.apply / config.patch），在持久化编辑前，检查所提交配置载荷中的活动表面 SecretRef 是否可解析

激活契约：

• 成功时以原子方式替换快照。
• 启动失败会中止 Gateway 网关启动。
• 运行时重新加载失败会保留最后一个已知正常的快照。
• 写入 RPC 预检失败会拒绝提交的配置；磁盘配置和活动运行时快照均保持不变。
• 为出站辅助函数/工具调用提供显式的单次渠道令牌不会触发 SecretRef 激活；激活点仍为启动、重新加载和显式的 secrets.reload。

降级和恢复信号

当系统处于正常状态后，重新加载时的激活失败，OpenClaw 会进入密钥降级状态，并发出一次性系统事件和日志代码：

• SECRETS_RELOADER_DEGRADED
• SECRETS_RELOADER_RECOVERED

行为：

• 降级：运行时保留最后一个已知正常的快照。
• 恢复：在下一次成功激活后发送一次。
• 已处于降级状态时，重复失败会记录警告，但不会再次发送该事件。
• 启动快速失败绝不会发送降级事件，因为运行时从未进入活动状态。

命令路径解析

命令路径可以通过 Gateway 网关快照 RPC 选择启用受支持的 SecretRef 解析。主要有两类行为：

其他说明：

• 后端密钥轮换后的快照刷新由 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：secrets - CLI 命令
• Vault SecretRef - HashiCorp Vault 提供商设置
• 环境变量 - 环境变量优先级
• SecretRef 凭据功能面 - 凭据功能面
• 密钥应用计划契约 - 计划契约详情
• 安全性 - 安全态势