本页内容
本页内容
插件指南
避难所 SecretRefs
Vault SecretRefs
捆绑的 Vault 插件允许 OpenClaw 在网关启动和重新加载时从 HashiCorp Vault 解析 exec SecretRefs。 OpenClaw 将 Vault 引用存储在配置中,将解析的值保留在内存中的机密快照中,并且不会将解析的 API 密钥写回 openclaw.json。
当你已经在运行 Vault,或者希望模型提供方密钥存放在 OpenClaw 配置文件之外时,可以使用此功能。有关 SecretRef 运行时模型,请参阅 密钥管理。
开始之前
你需要:
- 已启用内置的
vault插件的 OpenClaw - 一个可访问的 Vault 服务器
- Vault 认证方式,能够生成具有对 OpenClaw 应解析的密钥路径的读取权限的客户端令牌
- 启动 Gateway 的环境必须包含
VAULT_ADDR,并且还要包含以下其中之一:VAULT_TOKEN,OPENCLAW_VAULT_AUTH_METHOD=token_file搭配VAULT_TOKEN_FILE, 或者已配置的 JWT/Kubernetes 登录
解析器通过 HTTP 从 Node 与 Vault 进行通信。网关不需要 Vault CLI 来解析 SecretRefs。
在运行 openclaw vault 命令之前,先启用内置插件:
在 Vault 中存储提供方密钥
OpenClaw 默认为安装在 secret 的 KV v2,与 Vault 开发服务器示例相匹配。对于生产 Vault,请在创建 SecretRef id 之前将 OPENCLAW_VAULT_KV_MOUNT 设置为实际的 KV 挂载路径。使用 OpenClaw 默认值,此 SecretRef id:
会读取这个 Vault 字段:
使用 Vault CLI 创建它的一种方式是:
请为 OpenClaw 使用具有限定范围的客户端令牌,不要使用根令牌。对于默认的 KV v2 结构,模型提供方密钥的最小策略如下:
使 Vault 对 Gateway 可见
对于未容器化的本地 Gateway,请在启动 OpenClaw 的同一个 shell 中导出 Vault 设置。默认认证方式会从 VAULT_TOKEN 读取 Vault 客户端令牌:
如果 Vault Agent 写入了一个 token sink 文件,请使用 token-file 认证:
对于由私有 CA 签名的 Vault 服务器,可以将该 CA 安装到主机信任存储中,并启用 Node 系统信任:
或者直接提供一个 PEM 捆绑包:
这些变量必须在 OpenClaw 启动时就已存在。Vault 插件会将它们转发给其 resolver 进程。
对于非交互式 JWT 认证,请使用 workload JWT 文件以及类型为 jwt 的 Vault 角色:
JWT 文件应为投影的 workload token,例如具有 Vault 角色可接受 audience 的 Kubernetes service account token。 交互式 OIDC 浏览器登录适合人工使用,但 Gateway 运行时需要非交互式 JWT 登录或 token 文件。
对于 Vault 的 Kubernetes 认证方式,请使用 kubernetes。这适用于作为 Pod 运行的 Gateway;默认挂载点为 kubernetes,默认 JWT 文件为标准 service account token 路径:
仅当 Vault 在 auth/kubernetes 以外的位置安装 Kubernetes 身份验证时,才设置 OPENCLAW_VAULT_AUTH_MOUNT。仅当服务帐户令牌投影到自定义路径时,才设置 OPENCLAW_VAULT_JWT_FILE。
可选设置:
检查当前 shell 能看到什么:
当配置了多个基于 Vault 的 secret provider 时,可通过别名选择其中一个:
openclaw vault status 从不打印 VAULT_TOKEN;它只报告 token、token 文件和 JWT 文件是否已设置。
生成并应用 SecretRef 方案
创建一个将 OpenRouter 的模型提供方 API 密钥映射到 Vault 的方案:
应用并验证该方案:
使用 --allow-exec 因为 Vault 插件通过 OpenClaw- 托管执行 SecretRef 提供程序进行解析。
如果 Gateway 还没有运行,请在应用方案后正常启动它, 而不是运行 openclaw secrets reload。
配置更多提供方密钥
内置快捷方式:
在一个计划中配置多个提供方密钥:
没有快捷方式的捆绑提供程序,或已配置的 OpenAI- 兼容和自定义模型提供程序,请使用 --provider-key:
每个 --provider-key <provider=id> 会将一个 SecretRef 写入 models.providers.<provider>.apiKey。对于自定义提供方,它不会创建该提供方的 baseUrl、api 或 models 设置;请先配置这些项。
对任何已知的 SecretRef 目标路径,使用 --target <path=id>:
裸目标路径适用于 openclaw.json。将 auth-profiles:<agentId>:<path> 用于现有 SQLite 身份验证配置文件目标。目标路径必须是已注册的 OpenClaw SecretRef 目标。 setup命令不会在OpenClaw中创建任意命名的秘密; Vault 仍然是秘密存储,OpenClaw 仅在支持的配置字段上存储 SecretRefs。
SecretRef id 格式
Vault SecretRef id 使用以下约定:
示例:
| SecretRef id | 默认 KV v2 Vault 读取 | 返回字段 |
|---|---|---|
providers/openrouter/apiKey |
secret/data/providers/openrouter |
apiKey |
providers/openai/apiKey |
secret/data/providers/openai |
apiKey |
teams/agent-prod/openrouter |
secret/data/teams/agent-prod |
openrouter |
返回的 Vault 字段必须是字符串。
对于 KV v1,设置:
然后 providers/openrouter/apiKey 读取:
OpenClaw 存储的内容
应用 Vault 设置方案会存储一个由插件管理的 provider:
凭据字段会指向该 provider:
解析后的值只存在于当前活动运行时的 secrets 快照中。
容器和托管部署
容器化的 Gateway 仍然使用相同的插件和 SecretRef 配置。容器必须接收:
VAULT_ADDR- 以下某一种认证来源:
VAULT_TOKENOPENCLAW_VAULT_AUTH_METHOD=token_file以及VAULT_TOKEN_FILEOPENCLAW_VAULT_AUTH_METHOD=jwt以及OPENCLAW_VAULT_AUTH_MOUNT、OPENCLAW_VAULT_AUTH_ROLE和OPENCLAW_VAULT_JWT_FILEOPENCLAW_VAULT_AUTH_METHOD=kubernetes以及OPENCLAW_VAULT_AUTH_ROLE;也可以选择覆盖OPENCLAW_VAULT_AUTH_MOUNT或OPENCLAW_VAULT_JWT_FILE
- 可选的
VAULT_NAMESPACE、OPENCLAW_VAULT_KV_MOUNT和OPENCLAW_VAULT_KV_VERSION
在使用 Kubernetes 时,如果 Vault 已为该集群配置了 Kubernetes 认证,请优先使用 OPENCLAW_VAULT_AUTH_METHOD=kubernetes。仅当 Vault 被配置为将该集群视为通用的 JWT/OIDC 颁发者时,才使用 OPENCLAW_VAULT_AUTH_METHOD=jwt。这两种方式都比在 Kubernetes Secret 中使用长期有效的 Vault token 更好。Vault Agent sidecar 或 injector 部署则可以改用 token_file。
对于多租户 Vault 部署,请将租户路由保留在 Vault 策略和部署配置中。OpenClaw 不要求固定的 mount、role 或 path:每个 Gateway 环境都可以设置自己的 OPENCLAW_VAULT_KV_MOUNT、 OPENCLAW_VAULT_AUTH_ROLE 和 SecretRef ids。如果某个共享 Gateway 必须同时解析不同的 Vault 用户,请使用手动配置的 exec provider 来封装不同的认证环境,或者将租户按 Gateway 环境拆分,并使用独立的 Vault 环境。