跳转至

SecretRef 参考

本页是 SecretRef 参考：受支持的来源及其 id 语法、验证规则，以及支撑它们的提供者配置块。

SecretRef 契约

所有场景下都使用同一种对象结构：

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

env 和 store 引用在其来源的有效默认别名处拥有隐式提供者：secrets.defaults.env 或 secrets.defaults.store，未设置时回退到 default。匹配的同来源 secrets.providers 条目优先；否则，该引用使用内置读取器，无需提供者条目。

其他别名以及所有 file/exec 引用要求注册具有相同 source 的 secrets.providers 条目。更改某个来源的默认值不会重写显式引用：在覆盖后仍命名为 default 的引用必须匹配已注册的同来源提供者，否则解析失败。

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

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

只读检查无需打开数据库即可识别有效的 store 绑定。这是配置证据，而非值存在的证明：凭据的可用性在运行时解析之前始终是未知的。

Env 提供者
  • 可通过 allowlist 设置可选的精确名称允许列表。匹配的显式 env 提供者即使是被选中的默认提供者，也会强制执行此列表。省略该列表则允许任何名称；使用 [] 则拒绝所有名称。
  • 缺失或为空的 env 值会导致解析失败。显式的 env SecretRef 始终具有权威性，不会回退到其他凭据或认证配置文件。
File 提供者
  • 读取 path 处的本地文件。
  • mode: "json"（默认）期望 JSON 对象负载，并将 id 解析为 JSON 指针。
  • mode: "singleValue" 期望 ref id 为 "value" 并返回原始文件内容（去除末尾换行符）。
  • 路径必须是具有单个硬链接的私有常规文件，并通过所有权/权限检查。符号链接和硬链接文件会被拒绝；timeoutMs（默认 5000）和 maxBytes（默认 1 MiB）限制读取。
  • Windows 故障关闭（fail-closed）：如果该路径的 ACL 验证不可用，则解析失败。请将机密移动到 OpenClaw 可以验证其 ACL 的路径；不存在提供者级别的绕过方式。

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

(
  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。参见激活行为。1Password 集成保留了对 broker-token 硬链接的独立、显式许可。

Exec 提供者
  • 直接运行配置的绝对二进制路径，不使用 shell。
  • command 不得是符号链接，不得是组可写或全局可写，并且在 POSIX 上必须由当前用户所有。对于包管理器垫片（shim），请解析真实的二进制路径（例如使用 realpath "$(command -v vault)"）并配置该绝对路径。使用 trustedDirs 将可执行文件限制在经过批准的目录中。
  • config validate 会检查每个手动 exec 命令路径，而不执行提供者。配置写入和试运行（dry run）只检查已更改或新引用的提供者，因此无关的未激活提供者不会阻止修复。这些是路径信任检查，而非提供者能够执行或返回机密的证明。
  • 支持 timeoutMs（默认 5000）、noOutputTimeoutMs（默认等于 timeoutMs）、maxOutputBytes（默认 1 MiB）、env/passEnv 允许列表以及 trustedDirs。
  • jsonOnly 默认为 true。当 jsonOnly: false 且只请求单个 id 时，纯非 JSON 的 stdout 会被接受为该 id 的值。
  • Windows 故障关闭（fail-closed）：如果命令路径的 ACL 验证不可用，则解析失败。请使用 OpenClaw 可以验证其 ACL 的命令路径；不存在提供者级别的绕过方式。
  • 插件管理的 exec 提供者可以使用 pluginIntegration，而无需复制 command/args。OpenClaw 在启动/重新加载期间从已安装的插件清单中解析当前命令详细信息；如果插件被禁用、移除、不受信任或不再声明该集成，则该提供者上的活动 SecretRef 将故障关闭（fail closed）。

请求负载（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 会显示已识别的代码
`NOT_FOUND` 和 `AMBIGUOUS_DUPLICATE_KEY`，并附带提供方和 ref id。其他
代码以及 `message` 等自由格式字段会被接受以保持 protocol-v1 兼容性，
但不会显示，因为解析器输出可能包含凭据材料。
Store 提供方
  • 从 OpenClaw 的共享状态 SQLite 数据库中读取值。
  • 该提供方没有连接设置。secrets.defaults.store 选择其默认别名。
  • 仅解析团队范围。身份范围尚不支持。

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