Vault SecretRefs¶

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

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

开始前¶

你需要：

• OpenClaw，且内置 vault 插件可用
• 可访问的 Vault 服务器
• 能够生成客户端令牌的 Vault 认证，该令牌对 OpenClaw 需要解析的 secret 路径具有读取权限
• 启动 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 命令之前，先启用内置插件：

openclaw plugins enable vault

在 Vault 中存储提供商密钥¶

OpenClaw 默认使用挂载在 secret 的 KV v2，与 Vault dev-server 示例一致。对于生产 Vault，请在创建 SecretRef id 之前，将 OPENCLAW_VAULT_KV_MOUNT 设置为实际的 KV 挂载路径。使用 OpenClaw 默认设置时，此 SecretRef id：

providers/openrouter/apiKey

读取此 Vault 字段：

secret/data/providers/openrouter -> apiKey

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

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

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

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

让 Gateway 能够访问 Vault¶

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

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

如果 Vault Agent 写入 token sink 文件，请使用 token-file 认证：

export VAULT_ADDR=https://vault.example.com
export OPENCLAW_VAULT_AUTH_METHOD=token_file
export VAULT_TOKEN_FILE=/vault/secrets/token

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

export NODE_USE_SYSTEM_CA=1

或者直接提供 PEM 证书包：

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

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

对于非交互式 JWT 认证，请使用 workload JWT 文件和类型为 jwt 的 Vault role：

export VAULT_ADDR=https://vault.example.com
export OPENCLAW_VAULT_AUTH_METHOD=jwt
export OPENCLAW_VAULT_AUTH_MOUNT=jwt
export OPENCLAW_VAULT_AUTH_ROLE=openclaw
export OPENCLAW_VAULT_JWT_FILE=/var/run/secrets/tokens/vault

JWT 文件应为投影的 workload token，例如具有 Vault role 接受的 audience 的 Kubernetes service account token。 交互式 OIDC 浏览器登录对人类用户有用，但 Gateway 运行时需要使用非交互式 JWT 登录或 token 文件。

对于 Vault 的 Kubernetes 认证方法，请使用 kubernetes。这适用于作为 Pods 运行的 Gateway；默认挂载为 kubernetes，默认 JWT 文件是标准 service account token 路径：

export VAULT_ADDR=https://vault.example.com
export OPENCLAW_VAULT_AUTH_METHOD=kubernetes
export OPENCLAW_VAULT_AUTH_ROLE=openclaw

仅当 Vault 将 Kubernetes 认证挂载到 auth/kubernetes 以外的位置时，才设置 OPENCLAW_VAULT_AUTH_MOUNT。仅当 service account token 投影到自定义路径时，才设置 OPENCLAW_VAULT_JWT_FILE。

可选设置：

export VAULT_NAMESPACE=<namespace-name>
export OPENCLAW_VAULT_KV_MOUNT=secret
export OPENCLAW_VAULT_KV_VERSION=2

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

openclaw vault status

当配置了多个基于 Vault 的 secret provider 时，通过别名选择其中一个：

openclaw vault status --provider-alias corp-vault

openclaw vault status 从不打印 VAULT_TOKEN；它只报告 token、token 文件和 JWT 文件是否已设置。

生成并应用 SecretRef 计划¶

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

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

应用并验证计划：

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

由于 Vault 插件通过 OpenClaw 管理的 exec SecretRef provider 进行解析，因此请使用 --allow-exec。

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

配置更多提供商密钥¶

内置快捷方式：

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

在一个计划中包含多个提供商密钥：

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

没有快捷方式的内置 provider，或已配置的 OpenAI 兼容和自定义模型 provider，请使用 --provider-key：

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> 都会向 models.providers.<provider>.apiKey 写入一个 SecretRef。对于自定义 provider，它不会创建该 provider 的 baseUrl、api 或 models 设置；请先配置这些设置。

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

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。对于现有的 SQLite auth-profile 目标，使用 auth-profiles:<agentId>:<path>。 目标路径必须是已注册的 OpenClaw SecretRef 目标。setup 命令不会在 OpenClaw 中创建任意命名的 secrets；Vault 仍然是密钥存储，OpenClaw 仅在受支持的配置字段上存储 SecretRefs。

SecretRef id 格式¶

Vault SecretRef id 使用以下约定：

<vault-secret-path>/<field>

示例：

返回的 Vault 字段必须是字符串。

对于 KV v1，设置：

export OPENCLAW_VAULT_KV_VERSION=1

然后 providers/openrouter/apiKey 读取：

secret/providers/openrouter -> apiKey

OpenClaw 存储的内容¶

应用 Vault setup 计划会存储一个由插件管理的 provider：

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

凭据字段指向该 provider：

{ "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 token 更好。Vault Agent sidecar 或 injector 部署可以改用 token_file。

对于多租户 Vault 配置，请将租户路由保留在 Vault 策略和部署配置中。OpenClaw 不要求固定的 mount、role 或 path：每个 Gateway 环境都可以设置自己的 OPENCLAW_VAULT_KV_MOUNT、OPENCLAW_VAULT_AUTH_ROLE 和 SecretRef id。如果一个 共享 Gateway 必须同时解析不同的 Vault 用户，请使用手动配置的 exec provider 来封装不同的认证环境，或者将租户拆分到具有独立 Vault 环境的 Gateway 环境中。

相关¶

• 密钥管理
• openclaw secrets
• 插件清单