Como manter as chaves de API fora do Codex CLI

O que o modelo do Codex CLI pode ver, o que os hooks do zn-gate verificam no Codex antes e depois de cada etapa e nos seus prompts, o que eles não conseguem fazer, como configurá-los e um teste curto com valores falsos.

Ver .md

O Codex CLI envia ao seu modelo tudo o que entra na conversa: os prompts que você digita, os arquivos que o agente lê, a saída dos comandos de shell e os resultados das ferramentas MCP. Uma chave de API em qualquer um desses pontos pode chegar ao modelo. O zn-gate instala hooks no Codex que verificam esses pontos. Esta página explica o que cada hook faz segundo a documentação do zn-gate, o que ele não consegue fazer, e traz um teste para você mesmo executar.

Por onde uma chave pode chegar ao modelo

Os hooks do zn-gate para o Codex observam quatro pontos de uma sessão:

  • Um prompt que você digita. Um segredo colado nele pode ser bloqueado antes do envio.
  • Um comando de shell ou um patch (apply_patch). Leituras de arquivos .env com valores e de arquivos de credenciais podem ser bloqueadas.
  • A saída de uma ferramenta. Ela pode ser limpa antes que o modelo a veja.

O registro de sessão do próprio Codex guarda a saída original, seja qual for o tratamento que o zn-gate dá ao que o modelo vê.

O que o zn-gate verifica no Codex

zn hooks install codex grava o hooks.json do Codex. Esta tabela segue o arquivo compat.md do repositório do zn-gate, que lista cada evento de hook do Codex e se ele foi executado em um Codex real.

Evento de hook O que o zn-gate faz
PreToolUse Verifica comandos de shell e patches (Bash, apply_patch) antes que sejam executados, e nega a chamada com um motivo quando encontra um segredo, um arquivo de credenciais ou ~/.zn. Não verifica chamadas de ferramentas MCP. Verificado no Codex CLI 0.163.0.
PostToolUse Limpa a saída da ferramenta: o resultado é substituído pelo seu texto limpo. Verificado no Codex CLI 0.163.0.

Um terceiro evento, UserPromptSubmit, bloqueia um segredo colado em um prompt (verificado no Codex CLI 0.163.0).

Em PreToolUse, o zn-gate não responde allow, então a sua própria política de aprovação do Codex continua valendo.

O que o zn-gate não cobre no Codex

  • O Codex descreve seus hooks como "a guardrail, not an enforcement boundary" (uma proteção, não um limite imposto). Se o hook do zn não puder ser executado, o Codex o registra como falho e a chamada ou o prompt seguem em frente.
  • A limpeza tem perdas. O Codex não tem nenhum campo que reescreva o resultado de uma ferramenta, então o resultado é substituído pelo texto limpo do zn-gate e o modelo recebe texto em vez do resultado estruturado.
  • O registro de sessão do próprio Codex guarda a saída original.
  • Um segredo sem formato conhecido que não esteja no cofre nem em um arquivo .env pode passar pela limpeza.
  • Um servidor definido na linha de comando do Codex com -c mcp_servers.secrets..., ou em um perfil, não é visível para o hook.
  • A verificação PreToolUse do zn-gate cobre comandos de shell e patches, não as chamadas de ferramentas MCP, e o zn-gate não usa os outros eventos de hook do Codex.
  • No Windows, o comando do hook foi executado manualmente no PowerShell e no Prompt de Comando, não nos testes automatizados.

Como configurar

Você precisa do Node.js 18 ou posterior:

npm install -g zn-gate
zn hooks install codex

Abra o Codex e revise os hooks novos ou alterados com /hooks. O Codex só executa hooks novos depois que você confia neles ali. Depois execute zn-gate check em um terminal. Ele deve mostrar OK para o Codex CLI (o que a saída significa). Os passos completos estão na página de instalação para o Codex CLI.

Para tirar por completo os valores reais do seu .env, guarde-os no cofre do zn-gate. O seu .env passa a ter marcadores como __ZN_STRIPE_KEY__:

zn unlock
zn env shadow .env

Mais em Scrubber. Para desfazer os hooks: zn hooks uninstall codex.

Teste na sua própria máquina

Este teste usa valores falsos. Partes dele seguem o que a documentação diz que deveria acontecer e não as executamos de ponta a ponta no Codex, então confira cada passo você mesmo.

  1. Em uma pasta nova e vazia, crie um arquivo .env apenas com valores falsos:

    EXAMPLE_API_KEY=sk-test-EXAMPLE-not-a-real-key
EXAMPLE_URL=https://example.com

  2. Instale os hooks (zn hooks install codex), abra o Codex nessa pasta, confie nos hooks com /hooks e execute zn-gate check em outro terminal.

  3. Peça ao Codex: "Run cat .env and tell me what it prints." Segundo o compat.md, o hook PreToolUse do zn-gate bloqueou cat .env no Codex CLI 0.163.0, e você deve ver uma mensagem do hook no lugar dos valores.

  4. Cole no prompt a chave de exemplo da documentação da AWS AKIAIOSFODNN7EXAMPLE. Se o zn-gate reconhecer o formato, o prompt deve ser bloqueado. Se não for bloqueado, o formato pode não ser um dos que o zn-gate detecta.

  5. Opcional: execute zn unlock e zn env shadow .env, abra o arquivo e confira que ele contém marcadores. Peça ao Codex que o leia de novo e compare.

  6. Apague a pasta de teste ao terminar. Para remover os hooks: zn hooks uninstall codex.

Aqui só contam os seus próprios resultados. Se algum passo se comportar de forma diferente do que esta página diz, escreva para nós informando a sua versão do Codex CLI.

Perguntas frequentes

O modelo do Codex pode ver as minhas chaves de API? Tudo o que o agente lê, executa ou recebe pode chegar ao modelo: arquivos, saída de shell, resultados MCP e prompts. Os hooks do zn-gate verificam esses pontos, com os limites descritos acima.

O zn-gate impede o Codex de ler o .env? Seus hooks bloqueiam leituras de arquivos .env com valores em comandos de shell e patches. O Codex chama seus hooks de uma proteção, não de um limite imposto.

Por que a saída limpa é texto simples? O Codex não tem nenhum campo que reescreva o resultado de uma ferramenta, então o zn-gate substitui o resultado inteiro pelo seu texto limpo.

Como desfazer? zn hooks uninstall codex.

Páginas relacionadas

Fontes