Como manter chaves de API fora do OpenCode

O que o modelo do OpenCode pode ver, o que o plugin do zn-gate para o OpenCode bloqueia ou limpa antes e depois de cada chamada de ferramenta e nos seus prompts, o que ele não cobre, como configurá-lo e um teste curto com valores falsos.

Ver .md

O OpenCode 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 no OpenCode um plugin que verifica esses pontos. Esta página explica o que o plugin faz segundo a documentação do zn-gate, o que ele não pode fazer, e traz um teste para você rodar por conta própria.

Por onde uma chave pode chegar ao modelo

O plugin do zn-gate para o OpenCode olha para três momentos de uma sessão:

  • Um prompt que você digita. Um segredo colado nele pode ser bloqueado antes de ser enviado. O OpenCode mostra isso como um erro.
  • Uma chamada de ferramenta, antes de ser executada. As leituras de arquivos .env com valores, de arquivos de credenciais e da pasta ~/.zn do próprio zn-gate podem ser bloqueadas, qualquer que seja a ferramenta. As gravações em ~/.zn e na configuração de hooks e plugins dos agentes também podem ser bloqueadas.
  • A saída de uma ferramenta, antes de o modelo vê-la. Os valores secretos nela são trocados por marcadores. Isso vale para todas as ferramentas, inclusive as MCP, e para a prévia que o OpenCode mostra na interface de terminal.

O plugin não verifica a resposta final do modelo. Além disso, o OpenCode guarda localmente a própria cópia da sessão, então o que o zn-gate faz com o que o modelo vê não limpa tudo o que o OpenCode armazena (veja os limites abaixo).

O que o zn-gate verifica no OpenCode

zn hooks install opencode grava um plugin pequeno, zn-gate.js, na pasta de plugins do OpenCode. Esta tabela segue o arquivo compat.md do repositório do zn-gate, para a versão publicada atual.

Ponto O que o zn-gate faz no OpenCode
Leituras de arquivos .env com valores, arquivos de credenciais e ~/.zn Bloqueadas em todas as ferramentas.
Gravações em ~/.zn e na configuração de hooks e plugins dos agentes Bloqueadas (write, edit, apply_patch e shell).
Saída das ferramentas Limpa em todas as ferramentas antes de o modelo vê-la, e na prévia do terminal.
Um segredo colado em um prompt Bloqueado. O OpenCode mostra isso como um erro.
Um comando que usa marcadores __ZN_<NAME>__ Reescrito automaticamente para rodar por zn run. As regras de permissão do próprio OpenCode continuam valendo.
O servidor MCP secrets Opcional. zn hooks install opencode imprime o trecho a adicionar ao opencode.json.
Execução de ponta a ponta do zn-gate com o OpenCode Sim: 0 valores enviados ao provedor do modelo.

Uma reescrita não aprova nada, e as regras de permissão do próprio OpenCode continuam valendo.

O zn-gate não restaura um valor detectado dentro de um comando no OpenCode: os marcadores ficam como estão, porque o OpenCode guarda na sessão os argumentos com que uma ferramenta rodou, e o modelo pode lê-los.

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

  • Se o plugin do zn não puder rodar, as chamadas e as mensagens do OpenCode são bloqueadas em vez de passarem. Uma instalação de projeto nomeia zn no PATH, então em uma máquina sem o zn o plugin não consegue rodar e as chamadas são bloqueadas ali.
  • Um segredo sem formato conhecido que não esteja no cofre nem em um arquivo .env pode passar pela limpeza.
  • O modelo vê o comando envolvido no próprio histórico, inclusive os caminhos locais de node e do zn (nenhum valor secreto).
  • A saída ao vivo que o OpenCode guarda enquanto um comando ainda está rodando permanece no banco de dados local dele, porque é gravada antes de o plugin poder limpá-la.
  • Um comando de shell ou um patch com mais de 100 KB é bloqueado, porque o zn-gate não consegue verificá-lo no tempo que o OpenCode espera pelo plugin.
  • No Windows, não foi testado. O envoltório de comandos é escrito para bash: com o PowerShell como shell do OpenCode, um comando com marcador falha em vez de rodar (nenhum valor é exposto).
  • A documentação do OpenCode não lista nenhuma configuração que desative plugins sem deixar sinal no agente, então o zn-gate não tem o que detectar aí (verificado pelo zn-gate em 2026-10-17).

Como configurar

Você precisa do Node.js 18 ou mais recente. Se você já instalou o zn-gate para o OpenCode, atualize-o e rode a segunda linha de novo:

npm install -g zn-gate
zn hooks install opencode

Reinicie o OpenCode. Depois rode zn-gate check em um terminal. Ele deve mostrar OK para o OpenCode (o que a saída significa). O zn-gate check confirma as regras do zn para o OpenCode, mas não inicia o OpenCode. Os passos completos estão na página de instalação para o OpenCode.

Para tirar de vez os valores reais do seu .env, guarde-os no cofre do zn-gate. O seu .env passa a conter marcadores como __ZN_STRIPE_KEY__:

zn unlock
zn env shadow .env

Mais em Scrubber. Para desfazer o plugin: zn hooks uninstall opencode.

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 foram executadas de ponta a ponta por nós com a sua versão do OpenCode, então confira cada passo por conta própria.

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

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

  2. Instale o plugin (zn hooks install opencode), reinicie o OpenCode nessa pasta e rode zn-gate check em outro terminal.

  3. Peça ao OpenCode: "Read the file .env and tell me what it contains." Segundo o compat.md, o zn-gate bloqueia as leituras de arquivos .env com valores em todas as ferramentas, então você deve ver uma mensagem do zn-gate 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 OpenCode deve mostrar um erro e não enviar o prompt. Se não for bloqueada, o formato pode não ser um dos que o zn-gate detecta.

  5. Opcional: rode zn unlock e zn env shadow .env, abra o arquivo e confira que ele contém marcadores. Peça ao OpenCode que o leia de novo e compare. Na execução de ponta a ponta do próprio zn-gate, o OpenCode recebeu os marcadores e não os valores.

  6. Apague a pasta de exemplo ao terminar. Para remover o plugin: zn hooks uninstall opencode.

Aqui só contam os seus próprios resultados. Se algum passo se comportar de modo diferente do que esta página diz, fale com a gente e informe a sua versão do OpenCode.

Perguntas frequentes

O modelo do OpenCode consegue 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. O plugin do zn-gate verifica esses pontos, com os limites indicados acima.

O zn-gate impede o OpenCode de ler o .env? O plugin bloqueia as leituras de arquivos .env com valores em todas as ferramentas.

Ele verifica a resposta do modelo? Não. O plugin verifica os seus prompts, as chamadas de ferramentas e a saída das ferramentas.

E se o plugin quebrar? As chamadas e as mensagens do OpenCode ficam bloqueadas até você consertar. Rode zn-gate check para ver o que fazer.

Como desfaço? zn hooks uninstall opencode e reinicie o OpenCode.

Páginas relacionadas

Fontes