SecretRef 契约和提供商配置
本页是 SecretRef 参考:接受的 source 及其 id 语法、验证规则,以及支撑它们的提供商配置块。
SecretRef 契约¶
所有位置都使用同一种对象形状:
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 提供商,否则解析将失败。
SecretInput 字段也接受简写字符串:
验证:
provider必须匹配^[a-z][a-z0-9_-]{0,63}$id必须匹配^[A-Z][A-Z0-9_]{0,127}$
验证:
provider必须匹配^[a-z][a-z0-9_-]{0,63}$id必须是绝对 JSON 指针(/...),或者对于singleValue提供商为字面量value- 段中的 RFC 6901 转义:
~变为~0,/变为~1
验证:
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会被拒绝)
提供商配置¶
在 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