SecretRefs do Vault
O plugin Vault incluído permite que o OpenClaw resolva SecretRefs de exec do
HashiCorp Vault na inicialização e no recarregamento do Gateway. O OpenClaw armazena
referências do Vault na configuração, mantém os valores resolvidos no snapshot de segredos em memória
e não grava as chaves de API resolvidas de volta no openclaw.json.
Use isso quando você já utiliza o Vault ou deseja manter as chaves dos provedores de modelos fora dos
arquivos de configuração do OpenClaw. Para conhecer o modelo de runtime do SecretRef, consulte
Gerenciamento de segredos.
Antes de começar
Você precisa de:
- OpenClaw com o plugin
vault incluído disponível
- um servidor Vault acessível
- autenticação do Vault capaz de gerar um token de cliente com acesso de leitura aos caminhos de
segredos que o OpenClaw deve resolver
- o ambiente que inicia o Gateway deve incluir
VAULT_ADDR e uma destas opções:
VAULT_TOKEN, OPENCLAW_VAULT_AUTH_METHOD=token_file com VAULT_TOKEN_FILE
ou um login JWT/Kubernetes configurado
O resolvedor se comunica com o Vault por HTTP a partir do Node. O Gateway não precisa da
CLI do Vault para resolver SecretRefs.
Ative o plugin incluído antes de executar os comandos openclaw vault:
Armazene uma chave de provedor no Vault
Por padrão, o OpenClaw usa KV v2 montado em secret, de acordo com os exemplos
do servidor de desenvolvimento do Vault. Para um Vault de produção, defina
OPENCLAW_VAULT_KV_MOUNT como o caminho de montagem KV real antes de criar IDs de SecretRef.
Com os padrões do OpenClaw, este ID de SecretRef:
lê este campo do Vault:
Uma forma de criá-lo com a CLI do Vault é:
Use um token de cliente com escopo definido para o OpenClaw, não um token raiz. Para o layout
KV v2 padrão, uma política mínima para chaves de provedores de modelos tem esta aparência:
Torne o Vault visível para o Gateway
Para um Gateway local sem contêiner, exporte as configurações do Vault no mesmo shell
que inicia o OpenClaw. O método de autenticação padrão lê um token de cliente do Vault de
VAULT_TOKEN:
Se o Vault Agent gravar um arquivo de destino do token, use a autenticação por arquivo de token:
Para um servidor Vault assinado por uma AC privada, instale essa AC no repositório de
confiança do host e ative a confiança do sistema no Node:
Ou forneça diretamente um pacote PEM:
Essas variáveis devem estar presentes quando o OpenClaw for iniciado. O plugin Vault as encaminha
para o processo resolvedor.
Para autenticação JWT não interativa, use um arquivo JWT da carga de trabalho e uma função do Vault do tipo
jwt:
O arquivo JWT deve ser um token projetado da carga de trabalho, como um token de conta de serviço
do Kubernetes com um público aceito pela função do Vault.
O login interativo OIDC pelo navegador é útil para pessoas, mas o runtime do Gateway precisa
de login JWT não interativo ou de um arquivo de token.
Para o método de autenticação Kubernetes do Vault, use kubernetes. Isso se destina a
Gateways executados como Pods; a montagem padrão é kubernetes, e o arquivo JWT padrão
é o caminho padrão do token da conta de serviço:
Defina OPENCLAW_VAULT_AUTH_MOUNT somente quando o Vault tiver montado a autenticação Kubernetes em outro local
que não seja auth/kubernetes. Defina OPENCLAW_VAULT_JWT_FILE somente quando o token da conta de
serviço for projetado em um caminho personalizado.
Configurações opcionais:
Verifique o que o shell atual consegue acessar:
Quando mais de um provedor de segredos baseado no Vault estiver configurado, selecione um pelo
alias:
openclaw vault status nunca exibe VAULT_TOKEN; ele informa apenas se o
token, o arquivo de token e o arquivo JWT estão definidos.
Se o Gateway for executado como um serviço, LaunchAgent, unidade systemd, tarefa agendada ou
contêiner, esse ambiente de runtime deverá receber as mesmas variáveis do Vault.
Definir variáveis apenas em um shell interativo comprova somente o funcionamento desse shell, não o do
Gateway que já está em execução.
Gere e aplique um plano de SecretRef
Crie um plano que mapeie a chave de API do provedor de modelos OpenRouter para o Vault:
Aplique e verifique o plano:
Use --allow-exec porque o plugin Vault faz a resolução por meio de um provedor
SecretRef de exec gerenciado pelo OpenClaw.
Se o Gateway ainda não estiver em execução, inicie-o normalmente após aplicar o plano,
em vez de executar openclaw secrets reload.
Atalhos integrados:
Várias chaves de provedores em um único plano:
Provedores incluídos sem atalhos, ou provedores de modelos personalizados e compatíveis com a OpenAI
já configurados, usam --provider-key:
Cada --provider-key <provider=id> grava um SecretRef em
models.providers.<provider>.apiKey. Para provedores personalizados, isso não cria
as configurações baseUrl, api ou models do provedor; configure-as primeiro.
Use --target <path=id> para qualquer caminho de destino SecretRef conhecido:
Caminhos de destino simples se aplicam ao openclaw.json. Use
auth-profiles:<agentId>:<path> para destinos existentes no auth-profiles.json.
O caminho de destino deve ser um destino SecretRef registrado no OpenClaw. O comando de
configuração não cria segredos nomeados arbitrários no OpenClaw; o Vault continua sendo o
armazenamento de segredos, e o OpenClaw armazena SecretRefs apenas em campos de configuração compatíveis.
Os IDs de SecretRef do Vault usam esta convenção:
Exemplos:
| ID de SecretRef | Leitura padrão do Vault KV v2 | Campo retornado |
|---|
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 |
providers/openrouter/apiKey lê:
O que o OpenClaw armazena
A aplicação de um plano de configuração do Vault armazena um provedor gerenciado pelo plugin:
Os campos de credenciais apontam para esse provedor:
O valor resolvido permanece apenas no snapshot de segredos do runtime ativo.
Contêineres e implantações gerenciadas
Gateways em contêineres ainda usam o mesmo plugin e a mesma configuração de SecretRef. O
contêiner deve receber:
VAULT_ADDR- uma fonte de autenticação:
VAULT_TOKENOPENCLAW_VAULT_AUTH_METHOD=token_file mais VAULT_TOKEN_FILEOPENCLAW_VAULT_AUTH_METHOD=jwt mais OPENCLAW_VAULT_AUTH_MOUNT,
OPENCLAW_VAULT_AUTH_ROLE e OPENCLAW_VAULT_JWT_FILEOPENCLAW_VAULT_AUTH_METHOD=kubernetes mais OPENCLAW_VAULT_AUTH_ROLE; opcionalmente,
substitua OPENCLAW_VAULT_AUTH_MOUNT ou OPENCLAW_VAULT_JWT_FILE
- opcionalmente,
VAULT_NAMESPACE, OPENCLAW_VAULT_KV_MOUNT e
OPENCLAW_VAULT_KV_VERSION
Ao usar o Kubernetes, prefira OPENCLAW_VAULT_AUTH_METHOD=kubernetes
quando o Vault tiver a autenticação Kubernetes configurada para o cluster. Use
OPENCLAW_VAULT_AUTH_METHOD=jwt somente quando o Vault estiver configurado para tratar o cluster
como um emissor JWT/OIDC genérico. Qualquer uma das opções é melhor do que um token do Vault
de longa duração em um Secret do Kubernetes. Implantações com contêiner auxiliar ou injetor do Vault Agent podem
usar token_file em vez disso.
Para configurações do Vault com vários locatários, mantenha o roteamento de locatários na política do Vault e na
configuração da implantação. O OpenClaw não exige uma montagem, função ou caminho fixos: cada
ambiente do Gateway pode definir seus próprios OPENCLAW_VAULT_KV_MOUNT,
OPENCLAW_VAULT_AUTH_ROLE e IDs de SecretRef. Se um único Gateway compartilhado precisar resolver
diferentes usuários do Vault ao mesmo tempo, use provedores de exec configurados manualmente
que encapsulem ambientes de autenticação distintos ou distribua os locatários entre ambientes do Gateway
com variáveis de ambiente do Vault separadas.
Relacionado
