Como gravar uma sessão do Claude Code e todos os outros agentes que não cooperam: um guia prático de campo

Sim: você pode gravar uma sessão do Claude Code hoje, e o que você obtém é a sessão inteira (cada resposta do modelo, cada chamada de ferramenta, cada arquivo que o agente tocou) em um formato reproduzível. Essa é a versão curta, e é verdade hoje. A versão mais longa é que a capacidade de gravação é decidida por plataforma, com base em duas perguntas: a plataforma pode ser apontada para um proxy? E, quando o tráfego chega, o formato do protocolo é compreendido? O Claude Code passa nas duas, e o mesmo vale para um Codex CLI autenticado com uma chave de API. Um agente com a URL do provedor fixada no código-fonte, um agente rodando em um contêiner ou em uma VPS, e uma plataforma autenticada com uma assinatura seguem cada um um caminho diferente — e um deles, hoje, não chega.

O que mudou é que esses agentes deixaram de ser demonstrações. Eles ficam no seu repositório com acesso ao shell, editam arquivos, executam a suíte de testes e abrem pull requests. Quando um deles faz algo que você não esperava — seja apagar o arquivo errado, entrar em loop no mesmo teste que falha ou queimar uma tarde inteira de computação — o histórico do terminal não é evidência. É uma renderização, e incompleta.

O que você precisa é do wire: o que foi realmente enviado ao modelo, o que de fato voltou e o que o agente fez entre os turnos. Esse registro também é o início de uma suíte de avaliação, pois uma sessão capturada é um teste de regressão que você pode reproduzir contra o próximo modelo ou o próximo prompt. O problema é que todo harness assume que está falando diretamente com seu provedor, e quase nenhum deles torna isso fácil de mudar.

O que decide se um harness pode ser registrado?

Toda pergunta do tipo "você pode gravar isso?" se resume às mesmas duas perguntas.

O primeiro: o harness pode ser apontado para um proxy? Quatro rotas cobrem essa questão, em ordem decrescente de conveniência.

• A variável base-URL. A rota criada para isso: o harness lê uma variável de ambiente base-URL, e você a define.

• Criar o harness você mesmo. Um processo filho herda o ambiente de seu processo pai, portanto um gateway que cria um agente de codificação também é capturado, sem a cooperação do agente.

• Interceptação de TLS. Para os harnesses que não leem nenhuma configuração, o gravador inicia o agente e você opta pela interceptação.

• Anexar. Quando o agente é executado em algum lugar onde o gravador não pode iniciá-lo, o que resta é anexar.

Se nenhuma dessas se aplicar, o tráfego nunca chega ao gravador e não há nada a discutir.

A segunda: quando o tráfego chega, seu formato de transmissão é compreendido? Capturar bytes não é o produto. O gravador precisa reconhecer a conversa em que está se inserindo, incluindo os formatos de chamada de ferramenta, os quadros de streaming e as novas tentativas — caso contrário, a gravação é um pcap, não uma reprodução. Um formato que o gravador entende produz uma sessão que você pode reproduzir; um dialeto privado produz uma captura que você só consegue contemplar.

A resposta varia conforme o harness, e varia em detalhes em que é fácil errar: é a mesma lição que resultou de comparar como o harness do DeepSeek difere do Claude Code. O restante deste artigo mostra como são as duas perguntas quando você de fato executa os harnesses.

Claude Code, o Codex CLI e o Agents SDK

Claude Code é o caso de referência contra o qual tudo o mais é medido, porque ele lê ANTHROPIC_BASE_URL. Defina essa variável para o gravador, inicie o agente, e a sessão chega turno a turno: os prompts, as chamadas de ferramentas, as edições de arquivo e as respostas do modelo entre eles. Validamos isso de ponta a ponta contra uma correção de bug real (um repositório real, um defeito real, uma sessão que vai do primeiro prompt à correção em funcionamento), e esse primeiro agente real quebrou quatro coisas que nenhum fixture havia produzido. Todas as quatro foram corrigidas desde então, o que é a forma honesta de dizer que o tráfego sintético não prepara você para o que um agente real faz quando é deixado sozinho com uma base de código.

O Codex CLI, autenticado com uma chave de API, é a mesma história por meio de OPENAI_BASE_URL. Aponte-o para o gravador e você obtém a sessão; nada mais muda na forma como você usa o harness.

Agentes programáticos herdam o caminho mais fácil de todos. Um processo filho herda o ambiente do processo pai, então um gateway que gera um agente de codificação também é capturado, sem a cooperação do agente. Defina a variável base-URL uma vez no processo que faz a geração, e cada agente que ele lança chega ao gravador por conta própria. Se você executa agentes a partir de CI, de um orquestrador ou por meio do Agents SDK, este é o caminho em que você já está.

O gravador em todos esses casos é o OrcaReplay. Instala-se com npm i -g orcareplay, precisa do Node 20 ou superior e não tem dependências nativas: nada para compilar, nada para construir. Ele captura o mesmo tráfego de agentes que OrcaRouter roteia pelo catálogo de modelos do OrcaRouter.

Um agente que não lê nenhuma variável base-URL

Alguns harnesses embutem a URL do provedor no código-fonte. Não há variável de ambiente, nem arquivo de configuração, nem flag. Definir ANTHROPIC_BASE_URL não faz nada, porque nada a lê. Se o gravador puder iniciar o agente, ainda existe um caminho, e é o que mais preocupa: a interceptação de TLS.

Optar por participar é exatamente isso: um opt-in; está desativado por padrão. Quando você o ativa para uma execução, o gravador cria uma autoridade de certificação exclusiva para essa execução, e essa autoridade é confiável apenas pelo agente que o gravador inicia: ela é entregue a esse único processo, não é instalada no keychain do seu sistema, nem fica para a próxima execução. Quando a execução termina, a autoridade é excluída. O agente se conecta ao seu host embutido no código exatamente como sempre fez; o gravador responde, e a sessão chega como se a URL sempre tivesse sido configurável.

O que a rota deliberadamente recusa importa tanto quanto o que ela faz. Ela lê os hosts em sua lista de permissões e nada mais. Hosts fora da lista de permissões são tunelados sem serem lidos, e registrados como um endereço e uma contagem de bytes: prova de que o agente contatou algo, e não um único byte do que foi dito. Essa fronteira é uma decisão de design, não uma limitação que ainda não tenhamos abordado; a mesma disciplina perpassa o firewall de agente do OrcaRouter, onde a lista de permissões é o produto, e não um efeito colateral do registro.

A pegadinha é a mesma da primeira pergunta: a interceptação funciona quando o gravador inicia o agente. Um agente já em execução dentro de um contêiner nunca recebeu a autoridade certificadora daquela execução e não confiará na resposta do gravador.

Um agente que não está nesta máquina

Um contêiner possui seu próprio ambiente. A variável base-URL que você define no seu shell não chega ao interior dele, e um gravador no host não consegue iniciar um processo que já existe em outro lugar: em um VPS, em CI, em um sandbox que o harness construiu sem pedir a sua permissão. A captura baseada em inicialização falha aqui não porque o agente seja difícil, mas porque o gravador nunca chega a tocar nele.

Para exatamente este caso existe orca attach: ele grava um agente que o gravador não pode iniciar, como um que está em um contêiner ou em uma VPS. A direção se inverte: em vez de o gravador iniciar o agente e fornecer-lhe um ambiente, ele se anexa a um agente que já está em execução e o grava.

O que anexar não faz é responder à segunda pergunta por você. Ele resolve levar o tráfego até o gravador; se esse tráfego se torna uma sessão que você pode reproduzir ainda depende de o formato de transmissão ser compreendido. Anexe um agente que fale um formato que o gravador conheça e você obtém uma sessão reproduzível. Anexe um que não fale, e você encontrou a parede, que é mais barato encontrar de propósito do que no meio de um incidente.

O que muda com o login de assinatura?

O mesmo binário pode ser gravado ou não, dependendo de como ele fez login. Uma Codex CLI autenticada com uma chave de API é capturada por meio de OPENAI_BASE_URL: aponte-a para o gravador e pronto. Autentique a mesma CLI com uma assinatura do ChatGPT e ela para totalmente de falar com esse endpoint; ela fala com o próprio backend, autenticada como você, e não há nenhuma origem para reescrever. A variável base-URL ainda existe, mas nenhum destino para o qual você a aponte se torna o serviço que o harness está de fato usando.

Esta é a segunda pergunta que falha, não a primeira. Os bytes podem ser movidos; o gravador pode até vê-los. Mas a conversa é endereçada a um backend que o gravador não pode substituir, em um fluxo que não é a API que o gravador fala. Não há replay a produzir porque não existe uma origem na qual o gravador possa se tornar.

A resposta honesta, hoje, para um harness com login via assinatura, é que ele não é gravável; a lição útil é que o método de login faz parte da decisão sobre o que pode ser gravado. Se você precisa de gravações para evals ou para uma trilha de auditoria, rode as sessões gravadas com uma chave de API e mantenha a assinatura para o trabalho interativo — como transformar uma sessão gravada em um eval de regressão cobre esse ciclo de ponta a ponta. E antes de padronizar o uso de qualquer harness, faça as duas perguntas a ele primeiro; continuamos fazendo exatamente isso para cada harness, mais recentemente com o harness Prime Agent.

A conclusão

Você pode gravar uma sessão do Claude Code hoje com um comando e uma variável de ambiente:

• npm i -g orcareplay

• Aponte ANTHROPIC_BASE_URL para o gravador

• Execute o agente

Um Codex CLI com uma chave de API está à mesma distância. Uma URL fixa no código custa-lhe um aceite da interceptação de TLS que lê apenas a sua própria lista de permissões (a mesma disciplina que o firewall de agentes do OrcaRouter impõe) e esquece seus próprios certificados quando a execução termina. Um contêiner ou uma VPS custa-lhe orca attach. Um login por assinatura custa-lhe a própria gravação: esse harness não será gravado, e nenhuma mudança de configuração altera isso hoje.

Toda a decisão num relance:

• Claude Code — chave de API de login vs rota para o gravador ANTHROPIC_BASE_URL vs gravável hoje Sim

• Codex CLI — Chave de API de login vs rota para o gravador OPENAI_BASE_URL vs gravável hoje Sim

• Harness com a URL do provedor hardcoded — Login: Qualquer vs Rota para o gravador; Interceptação TLS opt-in, iniciada pelo gravador vs Gravável hoje: Sim

• Agente em um container ou em um VPS — Login em qualquer lugar vs. roteamento para o gravador orca attach vs. Gravável hoje: sim, se o formato de transmissão for conhecido

• Codex CLI — Início de sessão: assinatura do ChatGPT vs Rota para o gravador: Nenhuma vs Gravável hoje: Não

A última linha é a única combinação sem nenhuma rota para o gravador.

Faça as duas perguntas antes de adotar um arnês, não depois do seu primeiro incidente; as respostas são baratas de obter, e elas decidem se a sessão de que você um dia precisará desesperadamente existe sequer.

Nota sobre as fontes: todos os comportamentos e dados deste artigo (os caminhos de captura `ANTHROPIC_BASE_URL` e `OPENAI_BASE_URL`, as quatro quebras pós-fixture e suas correções, o ciclo de vida do certificado TLS, o comportamento de allowlist e túnel, `orca attach` e os requisitos de instalação) provêm de nossas próprias execuções de validação contra os harnesses mencionados, mais recentemente em 2026-09-04. Não citamos benchmarks de terceiros porque não executamos nenhum.