Come registrare una sessione di Claude Code e qualsiasi altro agente che non collabora: una guida pratica sul campo

Sì: puoi registrare una sessione di Claude Code oggi, e ciò che ottieni è l'intera cosa (ogni turno del modello, ogni chiamata di strumento, ogni file toccato dall'agente) in una forma che puoi riprodurre. Questa è la versione breve, ed è vera oggi. La versione più lunga è che la registrabilità è decisa per ogni harness, da due domande: l'harness può essere puntato a un proxy? E il suo formato di trasmissione è compreso una volta che il traffico arriva? Claude Code supera entrambe, e anche un Codex CLI con accesso tramite chiave API. Un agente con l'URL del provider hardcoded nel suo sorgente, un agente che gira in un container o su un VPS, e un harness con accesso tramite abbonamento seguono ciascuno un percorso diverso, e uno di essi, oggi, non arriva.

Quello che è cambiato è che questi agenti hanno smesso di essere demo. Si trovano nel tuo repository con accesso alla shell, modificano file, eseguono la suite di test, aprono pull request. Quando uno di loro fa qualcosa che non ti aspettavi, che si tratti di eliminare il file sbagliato, di ripetere in loop lo stesso test fallito, o di bruciare un pomeriggio di calcolo, lo scrollback del terminale non è una prova. È una rappresentazione, e per di più incompleta.

Quello che ti serve è il traffico reale: cosa è stato effettivamente inviato al modello, cosa è effettivamente tornato indietro e cosa ha fatto l'agente tra un turno e l'altro. Questa registrazione è anche l'inizio di una suite di valutazione, perché una sessione catturata è un test di regressione che puoi rieseguire sul prossimo modello o sul prossimo prompt. L'inghippo è che ogni harness presuppone di parlare direttamente con il proprio provider, e quasi nessuno di essi rende facile cambiare questa cosa.

Cosa decide se un harness può essere registrato?

Ogni domanda del tipo "puoi registrarlo?" si riduce alle stesse due domande.

La prima: si può puntare l'harness verso un proxy? Quattro percorsi la trattano, in ordine decrescente di comodità.

• La variabile base-URL. Il percorso costruito per questo: l'harness legge una variabile d'ambiente base-URL e tu la imposti.

• Avviare l'harness da soli. Un processo figlio eredita l'ambiente del processo padre, quindi anche un gateway che avvia un agente di programmazione viene catturato, senza la cooperazione dell'agente.

• Intercettazione TLS. Per i banchi di prova che non leggono alcuna configurazione, il registratore avvia l'agente e sei tu a scegliere se attivare l'intercettazione.

• Collega. Quando l'agente viene eseguito in un ambiente in cui il registratore non può avviarlo, non resta che collegarsi.

Se nessuna di queste condizioni si applica, il traffico non raggiunge mai il registratore e non c'è nulla da discutere.

Il secondo: una volta che il traffico arriva, il suo formato di trasmissione è compreso? Catturare byte non è il prodotto. Il registratore deve riconoscere la conversazione di cui fa le veci, incluse le forme delle chiamate agli strumenti, i frame di streaming e i nuovi tentativi; altrimenti la registrazione è un pcap, non un replay. Un formato che il registratore comprende produce una sessione che puoi riprodurre; un dialetto privato produce una cattura che puoi solo guardare.

La risposta varia a seconda dell'harness, e varia in dettagli facili da sbagliare: è la stessa lezione emersa confrontando come l'harness DeepSeek differisce da Claude Code. Il resto di questo articolo mostra come appaiono le due domande quando si eseguono davvero gli harness.

Claude Code, il Codex CLI e l'Agents SDK

Claude Code è lo standard rispetto a cui viene misurato tutto il resto, perché legge ANTHROPIC_BASE_URL. Imposta quella variabile sul recorder, avvia l’agente e la sessione arriva turno per turno: i prompt, le chiamate agli strumenti, le modifiche ai file e, in mezzo, le risposte del modello. L’abbiamo validato end-to-end su una correzione di bug reale (un repository reale, un bug reale, una sessione che parte dal primo prompt e arriva alla correzione funzionante), e quel primo agente reale ha rotto quattro cose che nessuna fixture aveva prodotto. Tutte e quattro sono state successivamente risolte, il che è il modo onesto di dire che il traffico sintetico non ti prepara a ciò che un agente reale fa quando viene lasciato da solo con un codebase.

Per la Codex CLI, autenticata con una chiave API, la storia è la stessa tramite OPENAI_BASE_URL. Puntala al recorder e ottieni la sessione; non cambia nient'altro nel modo in cui usi l'harness.

Gli agenti programmatici ereditano la via più semplice di tutte. Un processo figlio eredita l'ambiente del processo padre, quindi anche un gateway che avvia un agente di codifica viene catturato, senza bisogno della cooperazione dell'agente. Imposta la variabile base-URL una volta nel processo che effettua l'avvio, e ogni agente che viene lanciato arriva da solo al registratore. Se esegui agenti da CI, da un orchestratore o tramite Agents SDK, questo è il percorso su cui sei già.

Il registratore in tutti questi casi è OrcaReplay. Si installa con npm i -g orcareplay, richiede Node 20 o successivo e non ha dipendenze native: niente da compilare, niente da costruire. Cattura lo stesso traffico degli agenti che OrcaRouter instrada attraverso il catalogo dei modelli di OrcaRouter.

Un agente che non legge alcuna variabile base-URL.

Alcuni harness incorporano l'URL del provider nel loro codice sorgente. Nessuna variabile d'ambiente, nessun file di configurazione, nessun flag. Impostare ANTHROPIC_BASE_URL non fa nulla, perché nulla lo legge. Se il recorder può avviare l'agente, c'è ancora una via, ed è quella che preoccupa di più: l'intercettazione TLS.

Abilitare la funzionalità è esattamente questo: un opt-in; di default è disattivata. Quando la attivi per un'esecuzione, il registratore genera un'autorità di certificazione unica per quell'esecuzione, e tale autorità è considerata attendibile solo dall'agente che il registratore avvia: viene consegnata a quel singolo processo, non installata nel portachiavi di sistema e non conservata per l'esecuzione successiva. Quando l'esecuzione termina, l'autorità viene eliminata. L'agente si connette al suo host hardcoded esattamente come ha sempre fatto; il registratore risponde e la sessione arriva come se l'URL fosse stato configurabile fin dall'inizio.

Ciò che il percorso rifiuta deliberatamente è importante quanto ciò che fa. Legge gli host nella sua allowlist e nient'altro. Gli host al di fuori dell'allowlist vengono instradati in tunnel senza essere letti; se ne registrano soltanto l'indirizzo e il numero di byte: la prova che l'agente ha contattato qualcosa, e non un solo byte di ciò che è stato detto. Quel confine è una decisione progettuale, non una limitazione che non abbiamo ancora affrontato; la stessa disciplina attraversa il firewall per agenti di OrcaRouter, dove l'allowlist è il prodotto, non un effetto collaterale della registrazione.

L'inghippo è quello della prima domanda: l'intercettazione funziona quando il registratore avvia l'agente. Un agente già in esecuzione all'interno di un container non ha mai ricevuto l'autorità di certificazione di quella esecuzione, e non si fiderà della risposta del registratore.

Un agente che non si trova su questa macchina

Un container ha il proprio ambiente. La variabile base-URL che imposti nella tua shell non arriva al suo interno, e un registratore sull'host non può avviare un processo che esiste già altrove: su un VPS, in CI, in una sandbox che l'harness ha costruito senza chiederti. La cattura basata sull'avvio fallisce qui non perché l'agente sia difficile, ma perché il registratore non riesce mai a toccarlo.

Proprio per questo caso esiste orca attach: registra un agente che il recorder non può avviare, ad esempio uno in un container o su un VPS. La direzione si inverte: invece che il recorder avvii l'agente e gli passi un ambiente, si aggancia a un agente già in esecuzione e lo registra.

Quello che attach non fa è rispondere alla seconda domanda al posto tuo. Risolve il problema di portare il traffico al registratore; se quel traffico diventi una sessione riproducibile dipende comunque dal fatto che il formato di trasmissione venga compreso. Collega un agente che parli un formato noto al registratore e ottieni una sessione riproducibile. Collegane uno che non lo parli e avrai trovato il muro, che è più conveniente trovare di proposito che nel mezzo di un incidente.

Cosa cambia con un accesso in abbonamento?

Lo stesso binario può essere registrabile o meno a seconda di come ha effettuato l'accesso. Una Codex CLI autenticata con una chiave API viene catturata tramite OPENAI_BASE_URL: punta la variabile al registratore e il gioco è fatto. Se invece la stessa CLI viene autenticata con un abbonamento a ChatGPT, smette del tutto di parlare con quell'endpoint; parla con il proprio backend, autenticandosi come te, e non c'è alcuna origine da riscrivere. La variabile base-URL esiste ancora, ma qualunque valore tu le assegni non diventa il servizio che l'harness sta effettivamente usando.

Questa è la seconda domanda a fallire, non la prima. I byte possono essere indotti a muoversi; il registratore può persino vederli. Ma la conversazione è rivolta a un backend di cui il registratore non può fare le veci, in un flusso che non è l'API che il registratore parla. Non c'è alcun replay da produrre perché non c'è un'origine in cui il registratore possa diventare.

La risposta onesta per un harness con accesso tramite abbonamento, oggi, è che non è registrabile, e la lezione utile è che il metodo di accesso fa parte della decisione sulla registrabilità. Se ti servono registrazioni per le valutazioni o per una traccia di audit, esegui le sessioni registrate tramite una chiave API e tieni l'abbonamento per il lavoro interattivo — come trasformare una sessione registrata in una valutazione di regressione copre questo ciclo dall'inizio alla fine. E prima di standardizzare su un qualsiasi harness, ponigli le due domande; continuiamo a fare esattamente questo per ogni harness, più recentemente con l'harness Prime Agent.

Il punto chiave

Oggi puoi registrare una sessione di Claude Code con un solo comando e una sola variabile d'ambiente:

• npm i -g orcareplay

• Punta ANTHROPIC_BASE_URL al registratore

• Esegui l'agente

Una Codex CLI con una chiave API è alla stessa distanza. Un URL hardcoded ti costa un opt-in all'intercettazione TLS che legge solo la propria allowlist (la stessa disciplina che il firewall agente di OrcaRouter impone) e dimentica i propri certificati quando l'esecuzione termina. Un container o un VPS ti costa orca attach. Un accesso in abbonamento ti costa la registrazione stessa: quell'harness non sarà oggetto di registrazione, e nessuna modifica di configurazione può cambiare ciò oggi.

L'intera decisione a colpo d'occhio:

• Claude Code — Chiave API di accesso vs Percorso verso il registratore ANTHROPIC_BASE_URL vs Registrabile oggi Sì

• Codex CLI — Chiave API di accesso vs Percorso verso il registratore OPENAI_BASE_URL vs Registrabile oggi Sì

• Harness con URL del provider hardcoded — Accesso con qualsiasi account vs Instradamento al recorder. Intercettazione TLS opt-in, avviata dal recorder vs registrabile oggi: Sì.

• Agente in un container o su un VPS — Accesso ovunque vs Instradamento al registratore orca attach vs Registrabile oggi Sì, se il formato di trasmissione è noto

• Codex CLI — Accesso: abbonamento ChatGPT vs Percorso per il registratore: nessuno vs Registrabile oggi: No

L'ultima riga è l'unica combinazione che non ha alcun percorso verso il registratore.

Fai le due domande prima di adottare un'imbracatura, non dopo il tuo primo incidente; le risposte sono facili da ottenere, e decidono se la sessione di cui un giorno avrai disperatamente bisogno esista affatto.

Nota sulle fonti: ogni comportamento e dato in questo articolo (i percorsi di acquisizione di `ANTHROPIC_BASE_URL` e `OPENAI_BASE_URL`, i quattro guasti post-fixture e le relative correzioni, il ciclo di vita del certificato TLS, il comportamento di allowlist e tunnel, `orca attach` e i requisiti di installazione) proviene dalle nostre esecuzioni di validazione effettuate con gli harness citati, più recentemente il 2026-09-04. Non citiamo benchmark di terze parti perché non ne abbiamo eseguiti.