Como dar uma chave de API a um agente de IA sem que ele veja a chave?
Dê ao agente uma referência, não a chave, e deixe um proxy na mesma máquina colocar a chave real no pedido à saída. Eis porque as variáveis de ambiente deixaram de ser suficientes, e como configurar tudo.
Dê ao agente uma referência em vez da chave, e deixe um pequeno proxy na mesma máquina trocar a chave real no pedido à saída. O agente escreve clavitor://OpenAI/key onde iria o segredo. A API recebe a chave real. O agente nunca a tem na mão, por isso não a pode imprimir, registar em logs nem ser convencido a entregá-la.
Essa é toda a ideia. O resto desta página explica porque é que isso importa, e como configurar.
Porque é que "põe numa variável de ambiente" deixou de ser aceitável
Há um ano, export OPENAI_API_KEY=sk-... era a forma normal de entregar uma chave a um script. Ninguém pestanejava.
Depois o script começou a pensar por si.
Um agente de IA lê ficheiros, executa ferramentas, escreve logs e fala com desconhecidos na internet. Cada uma dessas coisas é uma porta de saída para uma chave que ele tenha:
- O ambiente. Tudo o que o agente executa herda a variável. Aparece em
/proc, em crash dumps, no output de CI. - A memória. Obter a chave em runtime e ela continua no processo durante todo o tempo em que o agente corre.
- A conversa. Uma injeção de prompt numa página web ou num comentário de issue pede ao agente para "incluir a sua configuração para depuração". Um agente prestável faz isso.
Nada disto precisa de um bug no agente. Só precisa de a chave estar num sítio ao alcance do agente.
O padrão: o agente pede, o proxy assina
Pense num cartão de chave de hotel. O hóspede consegue abrir o seu quarto. O hóspede nunca vê a chave mestra, e a porta regista cada passagem.
Para uma chave de API, é assim:
- A chave real vive num cofre, encriptada.
- Um proxy corre ao lado do agente, na mesma máquina.
- O agente envia o seu pedido HTTPS com uma referência onde iria a chave.
- O proxy obtém o valor do cofre, coloca-o no pedido e encaminha-o.
- O lado do agente só tem sempre a referência.
Os logs do agente mostram a referência. O mesmo acontece com a sua janela de contexto. Não há nada para vazar.
Como configurar com o Clavitor
Foi assim que o construímos. Um binário, uma variável de ambiente, sem alterações ao código do agente.
Crie um cliente para o agente no seu cofre com os scopes de que ele precisa, depois registe o proxy e inicie-o:
$ clavitor-proxy init $ clavitor-proxy ca $ clavitor-proxy serve
init regista o proxy como esse cliente. ca imprime a autoridade de certificação do proxy: adicione-a ao trust store que o cliente HTTP do seu agente usa, porque o proxy abre ele próprio a ligação HTTPS do agente. Depois aponte o agente para o proxy:
$ export HTTPS_PROXY="http://clavitor:$(cat proxy-auth)@127.0.0.1:1983"
$ curl -H "Authorization: Bearer clavitor://OpenAI/key" \
https://api.openai.com/v1/chat/completionsproxy-auth é o token de acesso do próprio proxy, o ficheiro ao lado do binário. Todas as ligações têm de o transportar, para que outro utilizador na mesma máquina não possa usar o proxy. O proxy escuta em 127.0.0.1:1983 e apenas nessa máquina, a menos que o configure deliberadamente para uma rede privada de confiança.
Funciona com qualquer agente cujo cliente HTTP respeite HTTPS_PROXY: Claude Code, Codex, os seus próprios scripts. Uma credencial só vai para um host que a sua entrada liste como endereço web, por isso um agente vítima de injeção de prompt não pode apontar a mesma referência para o servidor de um desconhecido. O passo a passo está na documentação do proxy.
E os outros segredos do agente?
Nem todos os segredos viajam num header HTTP. Uma palavra-passe de deploy, uma chave SSH, um código de dois fatores para um início de sessão.
Para esses, o agente pede ao cofre uma entrada nomeada de cada vez com clavitor-cli, e apenas para entradas que lhe foram atribuídas:
$ clavitor-cli get "GitHub Deploy" --field password $ clavitor-cli get "Stripe API" --field key clavitor-cli: CV-2041: Access denied.
O agente não consegue listar o cofre. Uma pesquisa por nome mostra no máximo cinco títulos correspondentes, e apenas uma contagem acima disso.
Os códigos de autenticador funcionam da mesma forma. clavitor-cli totp "GitHub" calcula o código atual na máquina do agente, para que ele consiga passar por um início de sessão de dois fatores sem ninguém ter de ler um telemóvel. O cofre guarda o segredo encriptado.
O que isto não resolve
Um proxy mantém a chave fora do agente. Não torna o agente de confiança.
- Um agente comprometido ainda pode usar o acesso que lhe foi dado. Só não consegue levar a chave para casa.
- Alguém com acesso de administrador à máquina também pode usar o proxy, ou ler a sua memória.
- Uma API que devolve a sua chave na resposta entrega-a ao agente. O proxy coloca chaves nos pedidos e não filtra respostas.
É por isso que o acesso à volta importa tanto como o proxy:
- Scope. Cada agente recebe apenas as entradas de que precisa. Um agente de trabalho vê GitHub e AWS. Um agente de deploy vê chaves SSH e a base de dados.
- Limites de leitura. Cada agente só pode ler um certo número de entradas diferentes por minuto e por hora, e é você que define os números. Um agente que exceda o seu limite horário duas vezes em duas horas fica bloqueado até que o desbloqueie.
- Um registo. Cada leitura é registada: que agente, que entrada, quando.
Corre vários agentes? Dê a cada um o seu próprio proxy e o seu próprio registo. Assim cada um tem o seu scope, os seus limites e o seu rasto, e o agente A não consegue ver as chaves do agente B.
A versão curta
Não entregue a sua chave a um agente. Entregue-lhe um nome para a chave, e mantenha a chave a um passo de distância, num lugar que decide, todas as vezes, se este agente a pode usar neste momento.
Configure o proxy ou veja como funciona o acesso de agentes.