Skip to main content

​
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.

​
Configure mais chaves de provedores

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.

​
Formato do ID de SecretRef

Os IDs de SecretRef do Vault usam esta convenção:
Exemplos: O campo retornado pelo Vault deve ser uma string. Para KV v1, defina:
Em seguida, 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_TOKEN
    • OPENCLAW_VAULT_AUTH_METHOD=token_file mais VAULT_TOKEN_FILE
    • OPENCLAW_VAULT_AUTH_METHOD=jwt mais OPENCLAW_VAULT_AUTH_MOUNT, OPENCLAW_VAULT_AUTH_ROLE e OPENCLAW_VAULT_JWT_FILE
    • OPENCLAW_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