英文 Secrets

• 原始链接：https://docs.openclaw.ai/gateway/secrets
• 来源章节：4. 官方文档：核心概念、模型与安全
• 来源小节：无
• 抓取方式：jina:https://r.jina.ai/http://docs.openclaw.ai/gateway/secrets
• 抓取时间：2026-04-05 13:47:10
• 状态：ok

中文内容

OpenClaw 支持附加 SecretRef，因此支持的凭据不需要在配置中以明文形式存储。明文仍然有效。 SecretRefs 是根据凭证选择加入的。

目标和运行时模型

秘密被解析为内存中的运行时快照。

• 解析在激活期间是急切的，而不是在请求路径上懒惰的。
• 当无法解析有效活动的 SecretRef 时，启动会快速失败。
• 重新加载使用原子交换：完全成功，或保留最后一次已知的良好快照。
• SecretRef 策略违规（例如 OAuth 模式身份验证配置文件与 SecretRef 输入相结合）在运行时交换之前激活失败。
• 运行时请求仅从活动的内存快照中读取。
• 第一次成功的配置激活/加载后，运行时代码路径会继续读取活动的内存快照，直到成功的重新加载将其交换。
• 出站传送路径也从该活动快照中读取（例如 Discord 回复/线程传送和 Telegram 操作发送）；它们不会在每次发送时重新解析 SecretRef。

这可以防止秘密提供者中断热请求路径。

主动表面过滤

SecretRef 仅在有效的活动表面上进行验证。

• 启用的表面：未解析的引用阻止启动/重新加载。
• 非活动表面：未解析的引用不会阻止启动/重新加载。
• 非活动引用发出非致命诊断，代码为“SECRETS_REF_IGNORED_INACTIVE_SURFACE”。

非活动表面的示例：

• 禁用频道/帐户条目。

• 任何启用的帐户都不会继承顶级通道凭据。

• 禁用工具/特征表面。

• “tools.web.search.provider”未选择特定于 Web 搜索提供商的键。在自动模式下（未设置提供程序），将按提供程序自动检测的优先顺序查询密钥，直到解决为止。选择后，未选择的提供者密钥将被视为非活动状态，直到被选择为止。

• 仅当默认代理或已启用代理的有效沙箱后端为“ssh”时，沙箱 SSH 身份验证材料（“agents.defaults.sandbox.ssh.identityData”、“certificateData”、“knownHostsData”以及每个代理覆盖）才处于活动状态。

• gateway.remote.token / gateway.remote.password 如果其中之一为 true，则 SecretRef 处于活动状态：

  • gateway.mode=远程
  • 配置了gateway.remote.url
  • gateway.tailscale.mode 是 serve 或 funnel
  • 在没有这些远程表面的本地模式下：
    • 当令牌身份验证可以获胜且未配置 env/auth 令牌时，gateway.remote.token 处于活动状态。
    • gateway.remote.password 仅当密码验证可以获胜且未配置 env/auth 密码时才有效。

• 设置“OPENCLAW_GATEWAY_TOKEN”时，“gateway.auth.token”SecretRef 对于启动身份验证解析无效，因为 env 令牌输入在该运行时获胜。

网关身份验证表面诊断

当在 gateway.auth.token、gateway.auth.password、gateway.remote.token 或 gateway.remote.password 上配置 SecretRef 时，网关启动/重新加载显式记录表面状态：

• active：SecretRef 是有效身份验证表面的一部分，必须解析。
• inactive：此运行时将忽略 SecretRef，因为另一个身份验证表面获胜，或者因为远程身份验证被禁用/不活动。

这些条目使用“SECRETS_GATEWAY_AUTH_SURFACE”进行记录，并包含活动表面策略使用的原因，因此您可以了解为什么凭证被视为活动或非活动。

入职参考预检

当 onboarding 在交互模式下运行并且您选择 SecretRef 存储时，OpenClaw 在保存之前运行预检验证：

• Env refs：验证环境变量名称并确认在设置过程中非空值可见。
• 提供者引用（file 或 exec）：验证提供者选择，解析id，并检查解析值类型。
• 快速启动重用路径：当 gateway.auth.token 已经是 SecretRef 时，载入会在探针/仪表板引导程序（对于 env、file 和 exec 引用）之前使用相同的快速失败门对其进行解析。

如果验证失败，入门会显示错误并让您重试。

SecretRef 合约

到处使用一种物体形状：

{ 来源：“env”| “文件” | “exec”，提供商：“默认”，id：“...”}

来源：“env”

{ 来源：“env”，提供商：“默认”，id：“OPENAI_API_KEY” }

验证：

• provider 必须匹配 ^[a-z][a-z0-9_-]{0,63}$
• id 必须匹配 ^[A-Z][A-Z0-9_]{0,127}$

来源：“文件”

{ 来源：“文件”，提供商：“filemain”，id：“/providers/openai/apiKey” }

验证：

• provider 必须匹配 ^[a-z][a-z0-9_-]{0,63}$
• id 必须是绝对 JSON 指针 (/...)
• RFC6901 分段转义： ~ =>~0, / =>~1

来源：“执行”

{ 来源：“exec”，提供商：“vault”，id：“providers/openai/apiKey” }

验证：

• provider 必须匹配 ^[a-z][a-z0-9_-]{0,63}$
• id 必须匹配 ^[A-Za-z0-9][A-Za-z0-9._:/-]{0,255}$
• id 不得包含 . 或 .. 作为斜杠分隔的路径段（例如 a/../b 被拒绝）

提供者配置

在“secrets.providers”下定义提供者：

{
  秘密：{
    提供商：{
      默认值：{源：“env”}，
      文件主：{
        来源：“文件”，
        路径：“~/.openclaw/secrets.json”，
        模式：“json”，//或“singleValue”
      },
      保险库：{
        来源：“执行”，
        命令：“/usr/local/bin/openclaw-vault-resolver”，
        参数：[“--profile”，“产品”]，
        passEnv：[“路径”，“VAULT_ADDR”]，
        jsonOnly：正确，
      },
    },
    默认值：{
      环境：“默认”，
      文件：“文件主”，
      执行：“金库”，
    },
    分辨率：{
      最大提供者并发数：4，
      最大引用数：512，
      最大批次字节数：262144，
    },
  },
}

环境提供商

• 通过 allowlist 可选允许名单。
• 缺少/空环境值无法解析。

文件提供者

• 从“path”读取本地文件。
• mode: "json" 需要 JSON 对象负载并将 id 解析为指针。
• mode: "singleValue" 需要 ref id "value" 并返回文件内容。
• 路径必须通过所有权/权限检查。
• Windows 失败关闭注意：如果路径的 ACL 验证不可用，则解析失败。仅对于受信任路径，请在该提供程序上设置“allowInsecurePath: true”以绕过路径安全检查。

执行提供者

• 运行配置的绝对二进制路径，无 shell。
• 默认情况下，command 必须指向常规文件（而不是符号链接）。
• 设置“allowSymlinkCommand: true”以允许符号链接命令路径（例如 Homebrew 垫片）。 OpenClaw 验证解析的目标路径。
• 将 allowSymlinkCommand 与 trustedDirs 配对作为包管理器路径（例如 ["/opt/homebrew"]）。
• 支持超时、无输出超时、输出字节限制、环境允许列表和可信目录。
• Windows 失败关闭注意：如果命令路径的 ACL 验证不可用，则解析失败。仅对于受信任路径，请在该提供程序上设置“allowInsecurePath: true”以绕过路径安全检查。

请求负载（标准输入）：

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

响应负载（标准输出）：

{ "protocolVersion": 1, "values": { "providers/openai/apiKey": "<openai-api-key>" } } // 编译指示：白名单秘密

可选的每个 ID 错误：

{
  “协议版本”：1，
  “值”：{}，
  “错误”：{“providers/openai/apiKey”：{“消息”：“未找到”}}
}

Exec 集成示例

1密码 CLI

{
  秘密：{
    提供商：{
      onepassword_openai：{
        来源：“执行”，
        命令：“/opt/homebrew/bin/op”，
        allowedSymlinkCommand: true, // Homebrew 符号链接二进制文件需要
        trustDirs: ["/opt/homebrew"],
        args: ["read", "op://Personal/OpenClaw QA API 密钥/密码"],
        passEnv: ["HOME"],
        jsonOnly：假，
      },
    },
  },
  型号：{
    提供商：{
      打开：{
        baseUrl: "https://api.openai.com/v1",
        型号：[{ id：“gpt-5”，名称：“gpt-5”}]，
        apiKey: { 来源: "exec", 提供者: "onepassword_openai", id: "值" },
      },
    },
  },
}

HashiCorp Vault CLI

{
  秘密：{
    提供商：{
      保险库开放：{
        来源：“执行”，
        命令：“/opt/homebrew/bin/vault”，
        allowedSymlinkCommand: true, // Homebrew 符号链接二进制文件需要
        trustDirs: ["/opt/homebrew"],
        args: ["kv", "get", "-field=OPENAI_API_KEY", "secret/openclaw"],
        passEnv：[“VAULT_ADDR”，“VAULT_TOKEN”]，
        jsonOnly：假，
      },
    },
  },
  型号：{
    提供商：{
      打开：{
        baseUrl: "https://api.openai.com/v1",
        型号：[{ id：“gpt-5”，名称：“gpt-5”}]，
        apiKey: { 来源: "exec", 提供者: "vault_openai", id: "value" },
      },
    },
  },
}

sop

{
  秘密：{
    提供商：{
      sops_openai：{
        来源：“执行”，
        命令：“/opt/homebrew/bin/sops”，
        allowedSymlinkCommand: true, // Homebrew 符号链接二进制文件需要
        trustDirs: ["/opt/homebrew"],
        args: ["-d", "--extract", '["providers"]["openai"]["apiKey"]', "/path/to/secrets.enc.json"],
        passEnv：[“SOPS_AGE_KEY_FILE”]，
        jsonOnly：假，
      },
    },
  },
  型号：{
    提供商：{
      打开：{
        baseUrl: "https://api.openai.com/v1",
        型号：[{ id：“gpt-5”，名称：“gpt-5”}]，
        apiKey: { 来源: "exec", 提供者: "sops_openai", id: "值" },
      },
    },
  },
}

MCP服务器环境变量

通过“plugins.entries.acpx.config.mcpServers”配置的 MCP 服务器环境变量支持 SecretInput。这使得 API 密钥和令牌远离明文配置：

{
  插件：{
    条目：{
      acpx：{
        启用：真，
        配置：{
          mcp服务器：{
            github: {
              命令：“npx”，
              参数：[“-y”，“@modelcontextprotocol/server-github”]，
              环境：{
                GITHUB_PERSONAL_ACCESS_TOKEN：{
                  来源：“环境”，
                  提供商：“默认”，
                  id：“MCP_GITHUB_PAT”，
                },
              },
            },
          },
        },
      },
    },
  },
}

纯文本字符串值仍然有效。像“${MCP_SERVER_API_KEY}”和 SecretRef 对象这样的环境模板引用会在 MCP 服务器进程生成之前在网关激活期间解析。与其他 SecretRef 表面一样，未解析的引用仅在“acpx”插件有效激活时阻止激活。

沙箱 SSH 身份验证材料

核心“ssh”沙箱后端还支持 SSH 身份验证材料的 SecretRefs：

{
  代理商：{
    默认值：{
      沙箱：{
        模式：“全部”，
        后端：“ssh”，
        SSH：{
          目标：“用户@网关主机：22”，
          IdentityData: { 来源: "env", 提供者: "默认", id: "SSH_IDENTITY" },
          证书数据：{ 来源：“env”，提供商：“默认”，id：“SSH_CERTIFICATE” }，
          knownHostsData：{来源：“env”，提供商：“默认”，id：“SSH_KNOWN_HOSTS”}，
        },
      },
    },
  },
}

运行时行为：

• OpenClaw 在沙箱激活期间解析这些引用，而不是在每次 SSH 调用期间延迟解析。
• 解析值写入具有限制性权限的临时文件，并在生成的 SSH 配置中使用。
• 如果有效的沙箱后端不是“ssh”，这些引用将保持不活动状态并且不会阻止启动。

支持的凭证表面

规范支持和不支持的凭据列于：

• SecretRef 凭证表面

运行时生成或轮换的凭据和 OAuth 刷新材料有意从只读 SecretRef 解析中排除。

所需的行为和优先级

• 没有引用的字段：未更改。
• 带有参考的字段：激活期间活动表面上需要。
• 如果纯文本和 ref 都存在，则 ref 优先于受支持的优先路径。
• 修订标记“OPENCLAW_REDACTED”保留用于内部配置修订/恢复，并作为文字提交的配置数据被拒绝。

警告和审核信号：

• SECRETS_REF_OVERRIDES_PLAINTEXT（运行时警告） *“REF_SHADOWED”（审核发现“auth-profiles.json”凭据何时优先于“openclaw.json”引用）

Google Chat 兼容性行为：

• serviceAccountRef 优先于纯文本 serviceAccount。
• 当设置兄弟引用时，纯文本值将被忽略。

激活触发器

秘密激活运行于：

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

激活合约：

• 成功自动交换快照。
• 启动失败会中止网关启动。
• 运行时重新加载失败会保留最后一次已知的良好快照。
• Write-RPC 预检失败会拒绝提交的配置，并保持磁盘配置和活动运行时快照不变。
• 向出站帮助程序/工具调用提供显式的每次调用通道令牌不会触发 SecretRef 激活；激活点仍然是启动、重新加载和显式的“secrets.reload”。

降级和恢复的信号

当健康状态后重新加载时激活失败时，OpenClaw 会进入降级机密状态。一次性系统事件和日志代码：

• SECRETS_RELOADER_DEGRADED
• SECRETS_RELOADER_RECOVERED

行为：

• 降级：运行时保留最后已知的良好快照。
• 恢复：下次成功激活后发出一次。
• 重复失败，同时已降级日志警告，但不发送垃圾邮件事件。
• 启动快速失败不会发出降级事件，因为运行时从未变为活动状态。

命令路径解析

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

• 严格的命令路径（例如“openclaw memory”远程内存路径和“openclaw qr --remote”，当需要远程共享秘密引用时）从活动快照读取，并在所需的 SecretRef 不可用时快速失败。
• 只读命令路径（例如“openclaw status”、“openclaw status --all”、“openclawchannelsstatus”、“openclawchannelsresolve”、“openclawsecurityaudit”和只读 doctor/config 修复流程）也更喜欢活动快照，但当目标 SecretRef 在该命令路径中不可用时，会降级而不是中止。

只读行为：

• 当网关运行时，这些命令首先从活动快照中读取。
• 如果网关解析不完整或网关不可用，它们会尝试特定命令界面的有针对性的本地回退。
• 如果目标 SecretRef 仍然不可用，该命令将继续执行降级的只读输出和显式诊断，例如“已配置但在此命令路径中不可用”。
• 这种降级行为仅适用于命令本地。它不会削弱运行时启动、重新加载或发送/验证路径。

其他注意事项：

• 后端秘密轮换后的快照刷新由“openclaw 秘密重新加载”处理。
• 这些命令路径使用的网关 RPC 方法：secrets.resolve。

审核和配置工作流程

默认操作流程：

openclaw 秘密审计--检查
openclaw 秘密配置
openclaw 秘密审计--检查

秘密审计

调查结果包括：

• 静态纯文本值（openclaw.json、auth-profiles.json、.env 和生成的 agents/*/agent/models.json）
• 生成的“models.json”条目中残留明文敏感的提供程序标头
• 未解决的参考
• 优先级遮蔽（auth-profiles.json 优先于 openclaw.json 引用） *遗留残留（auth.json，OAuth提醒）

执行注：

• 默认情况下，审核会跳过 exec SecretRef 的可解析性检查，以避免命令副作用。
• 使用 openclaw Secrets Audit --allow-exec 在审核期间执行 exec 提供程序。

标头残留注：

• 敏感提供程序标头检测基于名称启发式（常见身份验证/凭证标头名称和片段，例如“授权”、“x-api-key”、“令牌”、“秘密”、“密码”和“凭证”）。

秘密配置

交互式助手：

• 首先配置 secrets.providers (env/file/exec，添加/编辑/删除)
• 允许您在“openclaw.json”和“auth-profiles.json”中为一个代理范围选择支持的秘密字段
• 可以直接在目标选择器中创建新的auth-profiles.json映射
• 捕获 SecretRef 详细信息（source、provider、id）
• 运行预检分辨率
• 可立即申请

执行注：

• 预检会跳过 exec SecretRef 检查，除非设置了 --allow-exec。
• 如果您直接从“configure --apply”申请并且计划包含 exec refs/providers，请也为应用步骤保留“--allow-exec”设置。

有用的模式：

• openclaw 秘密配置 --providers-only
• openclaw 秘密配置 --skip-provider-setup
• openclaw 秘密配置 --agent <id>

configure 应用默认值：

• 从“auth-profiles.json”中擦除匹配目标提供商的静态凭据
• 从“auth.json”中清除旧的静态“api_key”条目
• 擦除匹配<config-dir>/.env中的已知秘密行

秘密适用

应用保存的计划：

openclaw 秘密适用 --from /tmp/openclaw-secrets-plan.json
openclaw 秘密适用 --from /tmp/openclaw-secrets-plan.json --allow-exec
openclaw 秘密适用 --from /tmp/openclaw-secrets-plan.json --dry-run
openclaw 秘密适用 --from /tmp/openclaw-secrets-plan.json --dry-run --allow-exec

执行注：

• 除非设置了 --allow-exec，否则干运行会跳过执行检查。
• 写入模式拒绝包含 exec SecretRefs/providers 的计划，除非设置了“--allow-exec”。

有关严格的目标/路径合同详细信息和确切的拒绝规则，请参阅：

• 秘密申请计划合约

单向安全政策

OpenClaw 故意不写入包含历史明文秘密值的回滚备份。安全模型：

• 预检必须在写入模式之前成功
• 运行时激活在提交之前进行验证
• 使用原子文件替换和失败时尽力恢复来应用更新文件

旧版身份验证兼容性说明

对于静态凭证，运行时不再依赖于纯文本遗留身份验证存储。

• 运行时凭证源是已解析的内存快照。
• 旧静态“api_key”条目一旦发现就会被清除。
• OAuth 相关的兼容性行为保持独立。

网页用户界面注释

一些 SecretInput 联合在原始编辑器模式下比在表单模式下更容易配置。

• CLI 命令：秘密
• 计划合约详情：【Secrets 应用计划合约】(https://docs.openclaw.ai/gateway/secrets-plan-contract)
• 凭证表面：SecretRef 凭证表面
• 身份验证设置：身份验证
• 安全态势：安全
• 环境优先级：环境变量