Modo Headless Explicado: Executando Claude Code Sem um Terminal
Toda sessão do Claude Code que você executa em um terminal é interativa: você digita uma solicitação, o Claude Code responde, talvez peça para executar uma ferramenta, e você aprova ou nega em tempo real.
Esse modelo falha no momento em que ninguém está no terminal para aprovar nada - dentro de um script, um job agendado ou um pipeline de CI.
O modo headless é como o Claude Code lida com esse caso: ele é executado como um único comando não interativo que recebe um prompt, faz o trabalho e sai, sem nunca abrir o REPL interativo.
Compreender o modo headless é o pré-requisito para todo o resto nesta seção que aborda CI - um bot de revisão automatizado, um job do GitHub Actions, qualquer coisa que execute o Claude Code sem uma pessoa observando.
Resumo
- Ideia Central: o modo headless invoca o Claude Code como um único comando de script que executa um prompt até a conclusão e sai, em vez de abrir uma sessão de terminal interativa.
- Por que Importa: scripts, jobs cron e pipelines de CI não têm um humano presente para digitar mensagens de acompanhamento ou aprovar chamadas de ferramenta uma a uma - o modo headless é a única forma de invocação que funciona nesse contexto.
- Conceitos Chave: sessão interativa, invocação headless, modo de impressão, formato de saída, permissões não interativas.
- Quando Usar: qualquer automação onde o Claude Code precise ser executado sem uma pessoa observando - jobs de CI, tarefas agendadas, scripts em lote ou um bot de revisão acionado por um evento do GitHub.
- Limitações / Compromissos: sem um humano para aprovar ações em tempo real, as invocações headless precisam ter suas ferramentas permitidas e escopo decididos antecipadamente, o que significa menos espaço para decisões no meio da tarefa do que uma sessão interativa permite.
- Tópicos Relacionados: a CLI
gh, gatilhos do GitHub Actions, revisão de código automatizada, gerenciamento de segredos de CI.
Fundamentos
Uma sessão interativa do Claude Code é uma conversa. Você envia uma mensagem, o Claude Code responde, talvez solicite a execução de uma ferramenta, você a aprova, e a troca continua até que você esteja satisfeito.
O modo headless substitui essa conversa por uma única instrução. Você dá ao Claude Code um prompt descrevendo toda a tarefa, e ele executa tudo o que é necessário para completar essa tarefa sem pausar para perguntar mais nada.
A saída é texto (ou um formato estruturado como JSON), retornado uma vez que a execução termina, em vez de um fluxo de mensagens ao vivo às quais você responde à medida que chegam.
Uma comparação útil: uma sessão interativa é como sentar com um colega e discutir uma tarefa juntos. O modo headless é como entregar a esse colega um resumo escrito e receber um relatório final, sem conversa entre eles.
# Interativo: abre uma sessão ativa, espera sua entrada.
claude
# Headless: executa um prompt até a conclusão e sai.
claude -p "Resuma os pull requests abertos neste repositório." --output-format textAmbas as invocações usam a mesma capacidade subjacente do Claude Code - os mesmos modelos, o mesmo modelo de acesso a ferramentas. O que difere é inteiramente a forma da invocação: uma espera por você, a outra não.
Mecânicas e Interações
Como o modo headless não tem um humano presente para aprovar chamadas de ferramenta conforme elas surgem, seu modelo de permissão precisa ser decidido antes do início da execução, não negociado durante ela.
Em uma sessão interativa, uma chamada de ferramenta que você não pré-aprovou normalmente pausa e pergunta. Em uma execução headless, não há ninguém lá para responder a essa solicitação - portanto, uma invocação headless precisa ter suas ferramentas permitidas, diretório de trabalho e quaisquer escopos relevantes configurados antecipadamente, caso contrário, a execução falhará ou ficará presa esperando por uma aprovação que nunca virá.
É por isso que as invocações headless são geralmente emparelhadas com uma configuração explícita de permissão ou lista de permissões de ferramentas passada junto com o prompt, em vez de depender do fluxo de aprovação interativa.
O formato de saída também é mais importante no modo headless. A saída de uma sessão interativa é destinada a uma pessoa lendo um terminal em tempo real. A saída de uma execução headless geralmente alimenta outra coisa - um script que a analisa, uma etapa de CI que a publica como um comentário de PR, um log que um pipeline arquiva. É por isso que as invocações headless comumente especificam um formato de saída explícito (texto puro, JSON ou uma transcrição estruturada) em vez de depender de qualquer formatação padrão voltada para humanos.
# Modo headless invocado com saída estruturada, para que um script possa analisar o resultado
# programaticamente em vez de raspar texto legível por humanos.
claude -p "Revise o diff no PR #482 e resuma quaisquer riscos." \
--output-format json > review-result.jsonO comentário que importa aqui: --output-format json existe especificamente porque o consumidor do modo headless é geralmente outro programa, não uma pessoa - a mesma solicitação formulada para uma sessão interativa apenas imprimiria prosa legível.
Considerações Avançadas e Aplicações
O modo headless é o mecanismo que torna possível todo uso do Claude Code baseado em CI, porque um job do GitHub Actions está, por definição, sendo executado sem ninguém observando um terminal.
Um job do GitHub Actions que executa o Claude Code em modo headless precisa de três coisas conectadas: um gatilho (como on: pull_request), um segredo contendo uma chave de API para que o job possa autenticar, e a invocação headless em si com suas flags e ferramentas permitidas configuradas. Cada um desses é abordado com mais detalhes em outras partes desta seção.
O modo headless também muda o modo de falha que os desenvolvedores precisam considerar. Uma sessão interativa que atinge uma situação ambígua pode fazer uma pergunta de esclarecimento. Uma execução headless não tem ninguém para perguntar - portanto, um prompt headless bem projetado precisa especificar restrições e contexto suficientes antecipadamente para que a ambiguidade seja improvável, ou precisa falhar graciosamente (sair com um erro claro) em vez de adivinhar.
| Aspecto | Sessão Interativa | Modo Headless |
|---|---|---|
| Quem aprova chamadas de ferramenta | Você, em tempo real | Lista de permissões pré-configurada, decidida antes da execução |
| Forma da saída | Legível por humanos, transmitida | Texto ou estruturada (JSON), retornada na conclusão |
| Lida com ambiguidade por | Fazendo uma pergunta de acompanhamento | Falhando claramente, ou agindo com a melhor instrução disponível |
| Gatilho Típico | Você, digitando uma solicitação | Um script, um agendamento ou um evento de CI |
É aqui que a postura de segurança do modo headless também é mais importante. Como o acesso a ferramentas de uma execução headless é decidido antecipadamente em vez de aprovado interativamente, as permissões e segredos concedidos a um job de CI efetivamente se tornam o limite do que essa invocação headless pode fazer - não há rede de segurança humana capturando uma concessão excessivamente ampla no momento, como haveria em uma sessão interativa.
Conceitos Equivocados Comuns
- "O modo headless é uma versão separada e inferior do Claude Code." É a mesma capacidade subjacente - os mesmos modelos, as mesmas ferramentas - invocada de forma diferente; nada sobre o modelo em si muda.
- "O modo headless não pode pedir esclarecimentos, então deve ser menos capaz." Não é menos capaz, é mais restrito de forma diferente - o compromisso é intencional, porque o objetivo é executar sem uma pessoa disponível para responder a perguntas de acompanhamento.
- "Qualquer comando do Claude Code funciona bem em modo headless sem alterações." Um comando que depende da aprovação interativa de chamadas de ferramenta irá travar ou falhar em modo headless, a menos que suas permissões sejam configuradas para uso não interativo antecipadamente.
- "O modo headless só é utilizável dentro do GitHub Actions." CI é o uso mais comum, mas scripts agendados, jobs em lote e scripts de automação únicos em uma máquina local também usam o modo headless, pela mesma razão: ninguém observando em tempo real.
FAQs
Qual é a maneira mais simples de executar o Claude Code em modo headless?
Passe um prompt com a flag de impressão e deixe-o executar até a conclusão, por exemplo, claude -p "sua instrução aqui" - a sessão é executada uma vez e sai, sem abrir o REPL interativo.
O modo headless usa um modelo Claude diferente das sessões interativas?
Não - a escolha do modelo é independente da invocação interativa versus headless; qualquer modo pode usar qualquer modelo da linha atual.
Por que as execuções headless precisam de permissões configuradas antecipadamente?
Porque não há uma pessoa presente para aprovar uma chamada de ferramenta no momento, como há em uma sessão interativa - sem uma lista de permissões pré-configurada, uma execução headless falha ou trava esperando por uma aprovação que ninguém dará.
Quais formatos de saída o modo headless suporta?
Comumente texto puro e JSON estruturado; JSON é preferível quando a saída alimenta outro programa, como uma etapa de CI que analisa o resultado para postar um comentário.
O modo headless pode me fazer uma pergunta de esclarecimento no meio da execução?
Não - essa é a principal troca do modo; um prompt headless precisa carregar contexto e restrições suficientes antecipadamente, pois não há ninguém disponível para responder a um acompanhamento.
O modo headless só pode ser usado dentro do GitHub Actions?
Não - funciona de qualquer script ou contexto de shell, incluindo um terminal local; o GitHub Actions é simplesmente o caso de uso de CI mais comum para ele nesta seção.
O que acontece se uma execução headless tentar usar uma ferramenta para a qual não foi concedida permissão?
Ela é bloqueada ou a execução falha, pois não há fluxo de aprovação interativo para recorrer - é por isso que o conjunto de ferramentas permitidas deve ser decidido antes do início da execução.
Existe um risco de segurança específico para o modo headless?
Sim - como as permissões são concedidas antecipadamente em vez de aprovadas caso a caso, o que uma invocação headless tem permissão para fazer se torna o limite real do que ela pode fazer, sem um humano capturando uma concessão excessivamente ampla no meio da execução.
Posso testar uma invocação headless localmente antes de colocá-la em CI?
Sim - executar o mesmo comando claude -p "..." de um terminal local é uma maneira confiável de validar um prompt e seu formato de saída antes de conectá-lo a um job do GitHub Actions.
O modo headless ainda tem acesso às mesmas ferramentas que uma sessão interativa?
Ele tem acesso a quaisquer ferramentas que sejam explicitamente permitidas para essa invocação - potencialmente o mesmo conjunto de uma sessão interativa, ou um conjunto mais restrito e deliberadamente reduzido, dependendo de como é configurado.
Relacionados
- Como o Claude Code se Encaixa no Fluxo de Trabalho do Seu GitHub Pull Request - onde o modo headless se encaixa entre os pontos de contato do PR.
- Executando Claude Code como um Bot de Revisão de Código Automatizado em CI - a principal aplicação prática do modo headless nesta seção.
- Configurando um Job do GitHub Actions que Executa Claude Code - conectando invocações headless a um job de CI funcional.
- Noções Básicas de Integração com o GitHub - uma primeira invocação headless prática.
Versões da Stack: Escrito com base na linha de modelos Claude atual em ~junho de 2026 - Claude Fable 5, Claude Opus 4.8, Claude Sonnet 5 (o padrão) e Claude Haiku 4.5. Nomes de modelos, preços e recursos de produtos mudam rapidamente - verifique os detalhes atuais em platform.claude.com/docs antes de confiar neles.