跳转至

SecretRef 契约和提供商配置

本页是 SecretRef 参考:接受的 source 及其 id 语法、验证规则,以及支撑它们的提供商配置块。

SecretRef 契约

所有位置都使用同一种对象形状:

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

env 和 store 引用在其 source 的有效默认别名处具有隐式 provider:secrets.defaults.env 或 secrets.defaults.store,未设置时回退到 default。匹配的同 source secrets.providers 条目优先;否则,该引用使用没有 provider 条目的内置读取器。

结构化引用始终包含 provider。对于仅包含 source 和 id 的旧对象,请运行 openclaw doctor --fix。Doctor 会将该 source 配置的默认提供商添加到已注册的配置凭据中。已存储的 auth-profile 引用保留其历史 default 提供商,独立于配置默认值。Doctor 在重写配置和 auth 数据库之前会备份它们;更新会运行相同的修复。Plugin SDK 的输入强制转换保持兼容,并且 SDK auth 写入会持久化规范引用。

SecretRefs 恰好包含这三个字段。如果已注册的配置凭据或 auth profile 中的旧无提供商引用包含其他字段,Doctor 会报告这些字段的移除,并在写入规范引用之前,在备份或源存档中保留原始配置行或 auth 行。注册凭据路径之外的不透明值保持不变。新的 SDK auth 写入会在更改已存储或已发布状态之前拒绝扩展输入。 请单独保留该元数据,并在保存前显式调用 coerceSecretRef 以选择规范引用。

其他别名以及所有 file/exec 引用都需要一个已注册的 secrets.providers 条目,且 source 相同。更改某个 source 的默认值不会重写显式引用:在覆盖之后仍命名为 default 的引用必须匹配一个已注册的同 source 提供商,否则解析将失败。

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

SecretInput 字段也接受简写字符串:

"${OPENAI_API_KEY}"
"$OPENAI_API_KEY"

验证:

  • provider 必须匹配 ^[a-z][a-z0-9_-]{0,63}$
  • id 必须匹配 ^[A-Z][A-Z0-9_]{0,127}$
{ source: "file", provider: "filemain", id: "/providers/openai/apiKey" }

验证:

  • provider 必须匹配 ^[a-z][a-z0-9_-]{0,63}$
  • id 必须是绝对 JSON 指针(/...),或者对于 singleValue 提供商为字面量 value
  • 段中的 RFC 6901 转义:~ 变为 ~0,/ 变为 ~1
{ source: "exec", provider: "vault", id: "providers/openai/apiKey#value" }

验证:

  • provider 必须匹配 ^[a-z][a-z0-9_-]{0,63}$
  • id 必须匹配 ^[A-Za-z0-9][A-Za-z0-9._:/#-]{0,255}$(支持诸如 secret#json_key 的选择器)
  • id 不得包含以斜杠分隔的路径段 . 或 ..(例如 a/../b 会被拒绝)
{ source: "store", provider: "default", id: "OPENAI_API_KEY" }

验证:

  • provider 必须匹配 ^[a-z][a-z0-9_-]{0,63}$
  • id 使用环境变量名称语法 ^[A-Z][A-Z0-9_]{0,127}$
  • 仅解析 Gateway 范围的团队作用域

提供商配置

在 secrets.providers 下定义提供商:

{
  secrets: {
    providers: {
      default: { source: "env" },
      teamstore: { source: "store" },
      filemain: {
        source: "file",
        path: "~/.openclaw/secrets.json",
        mode: "json", // or "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",
      store: "teamstore",
    },
  },
}

提供商别名是特定于 source 的。匹配的显式提供商条目优先;如果 env 或 store 默认别名也被另一个 source 的条目使用,则该 source 的内置提供商优先。非默认别名以及 file 或 exec 提供商必须解析为具有匹配 source 的显式条目。

只读检查会在不打开数据库的情况下识别有效的 store 绑定。这是配置证据,而不是值存在的证明:凭据可用性在运行时解析之前保持未知。

Env 提供商
  • 通过 allowlist 提供可选的精确名称允许列表。匹配的显式 env 提供商即使作为选定的默认值也会强制使用此列表。省略列表以允许任意名称;使用 [] 拒绝所有名称。
  • 缺失或空的 env 值会导致解析失败。显式 env SecretRef 仍然具有权威性,并且不会回退到另一个凭据或 auth profile。
File 提供商
  • 读取 path 处的本地文件。
  • mode: "json"(默认)期望 JSON 对象负载,并将 id 解析为 JSON 指针。
  • mode: "singleValue" 期望引用 id 为 "value",并返回原始文件内容(去除末尾换行符)。
  • 路径必须是一个具有一个硬链接的私有常规文件,并通过所有权/权限检查。符号链接和硬链接文件会被拒绝;timeoutMs(默认 5000)和 maxBytes(默认 1 MiB)限制读取。
  • Windows 失败关闭:如果无法对该路径进行 ACL 验证,则解析失败。将密钥移动到 OpenClaw 可以验证其 ACL 的路径;没有提供商级别的绕过。

如果升级报告 must not be hardlinked,请将内容复制到新的私有文件中,并替换已配置的路径。仅更改权限不会断开硬链接。在 Linux 或 macOS 上,请以 Gateway 用户身份运行此操作,并使用现有私有目录中的实际凭据路径:

bash ( set -eu umask 077 credential_path="$HOME/.openclaw/secrets.json" replacement="$(mktemp "${credential_path}.XXXXXX")" trap 'rm -f "$replacement"' EXIT cat "$credential_path" > "$replacement" chmod 600 "$replacement" mv -f "$replacement" "$credential_path" )

这会保留已配置的路径和内容,同时创建一个单链接、`0600` 文件。旧 inode 的其他名称保持不变。对于正在运行的 Gateway,请运行 `openclaw secrets reload`;如果启动失败,请在再次启动 Gateway 之前修复该文件。参见[激活行为](operations.md#activation-triggers)。[1Password 集成](integration-examples.md#1password)保留其对 broker-token 硬链接的单独且明确的许可。
Exec 提供商
  • 直接运行已配置的绝对二进制路径,不使用 shell。
  • command 不能是符号链接,不能对组或所有用户可写,并且在 POSIX 上必须由当前用户拥有。对于包管理器 shim,请解析真实二进制路径(例如使用 realpath "$(command -v vault)")并配置该绝对路径。使用 trustedDirs 将可执行文件限制在已批准的目录中。
  • config validate 会检查每个手动 exec 命令路径,而不会执行提供商。配置写入和试运行只检查已更改或新引用的提供商,因此无关的非活动提供商不会阻止修复。这些是路径信任检查,并非证明提供商可以执行或返回密钥。
  • 支持 timeoutMs(默认 5000)、noOutputTimeoutMs(默认等于 timeoutMs)、maxOutputBytes(默认 1 MiB)、env/passEnv 允许列表以及 trustedDirs。
  • jsonOnly 默认为 true。当 jsonOnly: false 且只请求单个 id 时,纯非 JSON stdout 会被接受为该 id 的值。
  • Windows 失败关闭:如果无法对命令路径进行 ACL 验证,则解析失败。请使用 OpenClaw 可以验证其 ACL 的命令路径;没有提供商级别的绕过。
  • 插件管理的 exec 提供商可以使用 pluginIntegration,而不是复制的 command/args。OpenClaw 会在启动/重新加载期间从已安装的插件清单中解析当前命令详情;如果插件被禁用、移除、不受信任,或不再声明该集成,则该提供商上活动的 SecretRefs 会失败关闭。

请求负载(stdin):

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

响应负载(stdout):

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

可选的按 id 错误:

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

code 是可选的机器可读诊断信息。OpenClaw 会连同提供商和 ref id 一起显示已识别的代码 NOT_FOUND 和 AMBIGUOUS_DUPLICATE_KEY。其他代码以及 message 等自由格式字段会被接受以保持 protocol-v1 兼容性,但不会显示,因为解析器输出可能包含凭据材料。

Store 提供商
  • 从 OpenClaw 的共享状态 SQLite 数据库中读取值。
  • 该提供商没有连接设置。secrets.defaults.store 选择其默认别名。
  • 仅解析 team 范围。Identity 范围尚不支持。

本页原文 Markdown:在 AtomGit 查看·内容源自开源项目 cl/openclaw