Segredos, permissões e tecto de gasto

O sobrinho da dona da padaria quis pôr na página um mapa de um serviço pago. Colou a chave de API no código, fez commit e enviou tudo para um repositório público. No dia seguinte a conta tinha gastos que ninguém da padaria fizera: alguém encontrou a chave e estava a usá-la.

O que é um segredo

Um segredo é tudo o que abre uma porta: a palavra-passe do email, uma chave de API (o código que um programa usa para pagar um serviço) ou um token. O fornecedor não distingue se quem a usa és tu ou outra pessoa.

A regra de ouro: um segredo nunca vai para o código, para um commit nem para a conversa com o agente. A conversa fica guardada e passa pelo fornecedor. Se colaste lá uma chave, trata-a como exposta.

O conceito: um cofre e uma lista do que não sai

Os segredos ficam num ficheiro chamado .env (o ponto faz parte do nome). O programa lê-a pelo nome da variável. Outro ficheiro, o .gitignore, diz ao Git para deixar o .env de fora quando fazes git add. Assim o código vai para o GitHub sem o segredo.

Mas o .gitignore não é uma fechadura: o agente, ou qualquer programa teu, consegue ler o .env. E não esconde uma chave que vai no JavaScript que o browser descarrega, como a do mapa da padaria: quem abrir a página vê-a, com ou sem .env. Essas precisam de outras protecções, que ficam para mais tarde. Por isso, durante o curso, usa só a chave a fingir do exercício.

Como se faz hoje: .env e .gitignore

Isto é como está a 6 de Outubro de 2026; se o ecrã for diferente, procura o botão com o mesmo nome.

Na pasta do projecto, cria primeiro o .gitignore com esta linha:

.env

Só depois cria o .env, com uma linha por segredo:

CHAVE_API=cola-aqui-a-tua-chave

Ao agente dizes apenas o nome:

O programa deve ler a chave da variável CHAVE_API, que está no ficheiro .env.
Não leias nem mostres o conteúdo do .env.

Se uma chave escapar

Por esta ordem, já:

1. Entra na consola do fornecedor e revoga a chave: deixa de servir a quem for.
2. Cria uma chave nova e põe-na no .env.
3. Vê o consumo dos últimos dias: alguém a usou?
4. Só depois limpa o código e o histórico, com ajuda do agente.

Permissões: o que o agente pode fazer

Conforme o modo, o agente pede autorização antes de certas acções. As regras poupam-te perguntas repetidas e proíbem o que nunca deve acontecer. São três listas:

• Permitir (allow): faz sem perguntar (correr os testes).
• Perguntar (ask): pede sempre autorização (enviar para o GitHub).
• Proibir (deny): nunca faz, mesmo que lho peças (ler o .env).

No Claude Code, as regras ficam em .claude/settings.json, dentro do projecto. Este exemplo da documentação oficial proíbe a leitura do .env:

{
  "permissions": {
    "deny": ["Read(./.env)", "Read(./.env.*)"]
  }
}

A proibição ganha sempre: as regras deny são vistas primeiro. O comando /permissions mostra as regras activas. Guia: Permissões no Claude Code.

No Codex, a sandbox decide onde pode escrever e se usa a internet; a política de aprovação decide quando pergunta. No modo Auto, escreve só na pasta, sem rede, e pergunta antes de sair daí. /permissions muda o modo; /status mostra o activo. Os perfis de permissão, ainda em testes, também proíbem ler o .env. Guia: Aprovações e segurança no Codex.

O modo que não pergunta

As duas ferramentas têm um modo em que o agente faz tudo sem perguntar: --dangerously-skip-permissions no Claude Code e --dangerously-bypass-approvals-and-sandbox no Codex («dangerously» quer dizer «perigosamente»).

No Claude Code, as versões recentes podem arrancar em modo automático, em que outro modelo aprova por ti. Enquanto aprendes, usa Shift+Tab até ver manual mode on: o modo Manual pergunta antes da maior parte das acções.

Tecto de gasto: antes da primeira chamada

Com uma chave de API, cada pedido custa dinheiro. Antes da primeira chamada, liga na consola do fornecedor o controlo certo:

• tecto que bloqueia: quando o gasto chega ao valor, os pedidos são recusados;
• alerta: recebes um aviso, mas os pedidos continuam.

Liga sempre o tecto, com um valor baixo (subir é fácil); um alerta abaixo dele dá-te tempo para reagir. Na consola da Anthropic: Settings > Billing, secção Spend limits. Na da OpenAI: Spend, Edit spend limit, e liga Enforce a hard limit (sem ela, os pedidos não são recusados). A OpenAI avisa que o corte não é instantâneo: o gasto pode passar um pouco do tecto. Guias: limites de gasto da Anthropic e Spend limits da OpenAI. Valores de cada plano: consulta a página Estado actual.