OpenClawDocs
View as MarkdownView this page as plain textOpen in ChatGPTAsk questions about this pageOpen in ClaudeAsk questions about this page

扩展

Vault SecretRefs

Vault SecretRefs

内置的 Vault 插件允许 OpenClaw 在 Gateway 网关启动和重新加载时从 HashiCorp Vault 解析 exec SecretRefs。OpenClaw 将 Vault 引用存储在配置中，将解析后的值保留在内存中的密钥快照中，并且不会将解析后的 API 密钥写回 openclaw.json。

如果你已经在运行 Vault，或希望将模型提供商密钥存放在 OpenClaw 配置文件之外，请使用此功能。有关 SecretRef 运行时模型，请参阅密钥管理。

开始之前

你需要：

  • 具有可用内置 vault 插件的 OpenClaw
  • 可访问的 Vault 服务器
  • 能够生成客户端令牌的 Vault 身份验证，该令牌对 OpenClaw 应解析的密钥路径具有读取权限
  • 启动 Gateway 网关的环境必须包含 VAULT_ADDR，以及 VAULT_TOKEN、带有 VAULT_TOKEN_FILE 的 OPENCLAW_VAULT_AUTH_METHOD=token_file，或已配置的 JWT/Kubernetes 登录方式之一

解析器通过 Node 使用 HTTP 与 Vault 通信。Gateway 网关无需 Vault CLI 即可解析 SecretRefs。

运行 openclaw vault 命令前，请启用内置插件：

bash
openclaw plugins enable vault

在 Vault 中存储提供商密钥

OpenClaw 默认使用挂载在 secret 的 KV v2，这与 Vault 开发服务器示例一致。对于生产环境中的 Vault，请在创建 SecretRef ID 前，将 OPENCLAW_VAULT_KV_MOUNT 设置为实际的 KV 挂载路径。使用 OpenClaw 默认设置时，此 SecretRef ID：

text
providers/openrouter/apiKey

会读取此 Vault 字段：

text
secret/data/providers/openrouter -> apiKey

使用 Vault CLI 创建它的一种方式是：

bash
export OPENROUTER_API_KEY=<openrouter-api-key>vault kv put secret/providers/openrouter apiKey="$OPENROUTER_API_KEY"

请为 OpenClaw 使用权限受限的客户端令牌，而不是根令牌。对于默认的 KV v2 布局，模型提供商密钥的最小策略如下：

hcl
path "secret/data/providers/*" {  capabilities = ["read"]}

让 Gateway 网关能够访问 Vault

对于未容器化的本地 Gateway 网关，请在启动 OpenClaw 的同一 shell 中导出 Vault 设置。默认身份验证方法从 VAULT_TOKEN 读取 Vault 客户端令牌：

bash
export VAULT_ADDR=https://vault.example.comexport VAULT_TOKEN=<vault-client-token>

如果 Vault Agent 写入令牌接收文件，请使用令牌文件身份验证：

bash
export VAULT_ADDR=https://vault.example.comexport OPENCLAW_VAULT_AUTH_METHOD=token_fileexport VAULT_TOKEN_FILE=/vault/secrets/token

对于由私有 CA 签名的 Vault 服务器，可以将该 CA 安装到主机信任存储中，并启用 Node 系统信任：

bash
export NODE_USE_SYSTEM_CA=1

或者直接提供 PEM 包：

bash
export NODE_EXTRA_CA_CERTS=/path/to/vault-ca.pem

这些变量必须在 OpenClaw 启动时存在。Vault 插件会将它们转发给其解析器进程。

对于非交互式 JWT 身份验证，请使用工作负载 JWT 文件和类型为 jwt 的 Vault 角色：

bash
export VAULT_ADDR=https://vault.example.comexport OPENCLAW_VAULT_AUTH_METHOD=jwtexport OPENCLAW_VAULT_AUTH_MOUNT=jwtexport OPENCLAW_VAULT_AUTH_ROLE=openclawexport OPENCLAW_VAULT_JWT_FILE=/var/run/secrets/tokens/vault

JWT 文件应为投射的工作负载令牌，例如受 Vault 角色接受其受众的 Kubernetes 服务账号令牌。 交互式 OIDC 浏览器登录适合人类用户，但 Gateway 网关运行时需要非交互式 JWT 登录或令牌文件。

对于 Vault 的 Kubernetes 身份验证方法，请使用 kubernetes。此方法适用于以 Pod 形式运行的 Gateway 网关；默认挂载点为 kubernetes，默认 JWT 文件为标准服务账号令牌路径：

bash
export VAULT_ADDR=https://vault.example.comexport OPENCLAW_VAULT_AUTH_METHOD=kubernetesexport OPENCLAW_VAULT_AUTH_ROLE=openclaw

仅当 Vault 将 Kubernetes 身份验证挂载在 auth/kubernetes 以外的位置时，才设置 OPENCLAW_VAULT_AUTH_MOUNT。仅当服务账号令牌投射到自定义路径时，才设置 OPENCLAW_VAULT_JWT_FILE。

可选设置：

bash
export VAULT_NAMESPACE=<namespace-name>export OPENCLAW_VAULT_KV_MOUNT=secretexport OPENCLAW_VAULT_KV_VERSION=2

检查当前 shell 可看到的内容：

bash
openclaw vault status

配置了多个由 Vault 支持的密钥提供商时，请按别名选择一个：

bash
openclaw vault status --provider-alias corp-vault

openclaw vault status 绝不会打印 VAULT_TOKEN；它只报告令牌、令牌文件和 JWT 文件是否已设置。

生成并应用 SecretRef 计划

创建一个将 OpenRouter 的模型提供商 API 密钥映射到 Vault 的计划：

bash
openclaw vault setup \  --plan-out ./vault-secrets-plan.json \  --openrouter-id providers/openrouter/apiKey

应用并验证该计划：

bash
openclaw secrets apply --from ./vault-secrets-plan.json --dry-run --allow-execopenclaw secrets apply --from ./vault-secrets-plan.json --allow-execopenclaw secrets audit --check --allow-execopenclaw secrets reload

请使用 --allow-exec，因为 Vault 插件通过 OpenClaw 管理的 exec SecretRef 提供商进行解析。

如果 Gateway 网关尚未运行，请在应用计划后正常启动它，而不是运行 openclaw secrets reload。

配置更多提供商密钥

内置快捷选项：

bash
openclaw vault setup --openai-id providers/openai/apiKeyopenclaw vault setup --anthropic-id providers/anthropic/apiKeyopenclaw vault setup --openrouter-id providers/openrouter/apiKey

在一个计划中配置多个提供商密钥：

bash
openclaw vault setup \  --plan-out ./vault-secrets-plan.json \  --openai-id providers/openai/apiKey \  --anthropic-id providers/anthropic/apiKey \  --openrouter-id providers/openrouter/apiKey

对于没有快捷选项的内置提供商，或已配置的 OpenAI 兼容及自定义模型提供商，请使用 --provider-key：

bash
openclaw vault setup \  --plan-out ./vault-secrets-plan.json \  --provider-key local-openai=providers/local-openai/apiKey \  --provider-key groq=providers/groq/apiKey

每个 --provider-key <provider=id> 都会将 SecretRef 写入 models.providers.<provider>.apiKey。对于自定义提供商，它不会创建该提供商的 baseUrl、api 或 models 设置；请先配置这些设置。

对任何已知的 SecretRef 目标路径使用 --target <path=id>：

bash
openclaw vault setup \  --target channels.telegram.botToken=channels/telegram/botToken \  --target models.providers.openai.headers.x-api-key=providers/openai/proxyKey \  --target auth-profiles:main:profiles.openai.key=providers/openai/apiKey

不带限定符的目标路径应用于 openclaw.json。对现有 auth-profiles.json 目标使用 auth-profiles:<agentId>:<path>。目标路径必须是已注册的 OpenClaw SecretRef 目标。setup 命令不会在 OpenClaw 中创建任意命名的密钥；Vault 仍是密钥存储，而 OpenClaw 只在受支持的配置字段中存储 SecretRefs。

SecretRef ID 格式

Vault SecretRef ID 使用以下约定：

text
<vault-secret-path>/<field>

示例：

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，请设置：

bash
export OPENCLAW_VAULT_KV_VERSION=1

此时，providers/openrouter/apiKey 会读取：

text
secret/providers/openrouter -> apiKey

OpenClaw 存储的内容

应用 Vault 设置计划会存储由插件管理的提供商：

json
{  "source": "exec",  "pluginIntegration": {    "pluginId": "vault",    "integrationId": "vault"  }}

凭据字段指向该提供商：

json
{ "source": "exec", "provider": "vault", "id": "providers/openrouter/apiKey" }

解析后的值仅存在于当前运行时密钥快照中。

容器和托管部署

容器化的 Gateway 网关仍使用相同的插件和 SecretRef 配置。容器必须接收：

  • VAULT_ADDR
  • 一种身份验证来源：
    • VAULT_TOKEN
    • OPENCLAW_VAULT_AUTH_METHOD=token_file 加上 VAULT_TOKEN_FILE
    • OPENCLAW_VAULT_AUTH_METHOD=jwt 加上 OPENCLAW_VAULT_AUTH_MOUNT、OPENCLAW_VAULT_AUTH_ROLE 和 OPENCLAW_VAULT_JWT_FILE
    • OPENCLAW_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 令牌。Vault Agent sidecar 或注入器部署可以改用 token_file。

对于多租户 Vault 设置，请在 Vault 策略和部署配置中保留租户路由。OpenClaw 不要求固定的挂载点、角色或路径：每个 Gateway 网关环境都可以设置自己的 OPENCLAW_VAULT_KV_MOUNT、OPENCLAW_VAULT_AUTH_ROLE 和 SecretRef ID。如果一个共享 Gateway 网关必须同时为不同的 Vault 用户解析密钥，请使用手动配置的 exec 提供商来封装不同的身份验证环境，或将租户拆分到具有独立 Vault 环境变量的不同 Gateway 网关环境中。

相关内容

Was this useful?
On this page

On this page