Cómo grabar una sesión de Claude Code, y a cualquier otro agente que se niegue a cooperar: una guía práctica de campo

Sí: hoy puedes grabar una sesión de Claude Code, y lo que obtienes es todo (cada turno del modelo, cada llamada a herramienta, cada archivo que el agente haya tocado) en una forma reproducible. Esa es la versión corta, y hoy es cierta. La versión larga es que la grababilidad se decide por harness según dos preguntas: ¿se puede apuntar el harness a un proxy? y ¿se entiende su formato de red una vez que llega el tráfico? Claude Code cumple ambas, y también lo hace un Codex CLI con la sesión iniciada mediante una clave de API. Un agente con la URL del proveedor codificada en el código fuente, un agente que corre en un contenedor o en un VPS y un harness con la sesión iniciada mediante una suscripción toman cada uno un camino distinto; uno de ellos, hoy, no llega.

Lo que cambió es que estos agentes dejaron de ser demos. Se encuentran en tu repositorio con acceso a la shell, editan archivos, ejecutan la suite de pruebas y abren pull requests. Cuando uno de ellos hace algo que no esperabas, ya sea borrar el archivo equivocado, quedarse en bucle con la misma prueba fallida o quemar una tarde de cómputo, el scrollback de la terminal no es evidencia. Es una representación, e incompleta.

Lo que necesitas es el cable: lo que realmente se envió al modelo, lo que realmente devolvió, y lo que el agente hizo entre turnos. Ese registro es también el comienzo de una suite de evaluación, porque una sesión capturada es una prueba de regresión que puedes reproducir contra el próximo modelo o el próximo prompt. El problema es que cada harness asume que está hablando directamente con su proveedor, y casi ninguno hace que sea fácil cambiarlo.

¿Qué determina si se puede grabar un arnés?

Toda pregunta del tipo "¿puedes grabarlo?" se reduce a las mismas dos preguntas.

La primera: ¿se puede apuntar el arnés a un proxy? Cuatro rutas lo cubren, en orden descendente de conveniencia.

• La variable de URL base. La ruta construida para esto: el arnés lee una variable de entorno de URL base, y tú la estableces.

• Iniciar el harness usted mismo. Un proceso hijo hereda el entorno de su proceso padre, por lo que una puerta de enlace que inicia un agente de programación también queda capturada, sin la cooperación del agente.

• Intercepción TLS. Para los bancos de pruebas que no leen ninguna configuración, el grabador lanza el agente y usted opta por la intercepción.

• Adjuntar.Cuando el agente se ejecuta en algún lugar donde el grabador no pueda iniciarlo, lo que queda es adjuntar.

Si ninguno de esos aplica, el tráfico nunca llega al grabador y no hay nada que discutir.

Lo segundo: una vez que llega el tráfico, ¿se entiende su formato de cable? Capturar bytes no es el producto. El grabador tiene que reconocer la conversación que sustituye: la forma de las llamadas a herramientas, las tramas de streaming y los reintentos; de lo contrario, la grabación es un pcap, no una reproducción. Un formato que el grabador entiende produce una sesión que puedes reproducir; un dialecto privado produce una captura que solo puedes mirar.

La respuesta varía según el harness, y difiere en detalles en los que es fácil equivocarse: es la misma lección que surgió al comparar cómo difiere el harness de DeepSeek de Claude Code. El resto de este artículo es cómo se ven las dos preguntas cuando realmente ejecutas los harnesses.

Claude Code, la CLI de Codex y el SDK de Agents

Claude Code es el referente contra el que se mide todo lo demás, porque lee ANTHROPIC_BASE_URL. Apunta esa variable al grabador, inicia el agente y la sesión llega turno a turno: los prompts, las llamadas a herramientas, las ediciones de archivos y las respuestas del modelo entre medias. Lo validamos de principio a fin contra una corrección de errores real (un repositorio real, un defecto real, una sesión que va desde el primer prompt hasta la solución que funciona), y ese primer agente real rompió cuatro cosas que ningún fixture había producido. Las cuatro ya están arregladas, que es la forma honesta de decir que el tráfico sintético no te prepara para lo que hace un agente real cuando se queda solo con un código base.

La CLI de Codex, autenticada con una clave de API, es la misma historia a través de OPENAI_BASE_URL. Apúntala al grabador y obtienes la sesión; nada más cambia en cuanto a cómo usas la herramienta.

Los agentes programáticos heredan la ruta más fácil de todas. Un proceso hijo hereda el entorno de su padre, por lo que una puerta de enlace que crea un agente de codificación también queda capturada, sin la cooperación del agente. Establezca la variable de URL base una vez en el proceso que realiza el lanzamiento, y cada agente que lance llegará por sí solo al registrador. Si ejecuta agentes desde CI, desde un orquestador, o mediante el SDK de Agents, este es el camino que ya está recorriendo.

El grabador en todos estos casos es OrcaReplay. Se instala con npm i -g orcareplay, requiere Node 20 o superior, y no tiene dependencias nativas: nada que compilar, nada que construir. Captura el mismo tráfico de agentes que OrcaRouter enruta a través de el catálogo de modelos de OrcaRouter.

Un agente que no lee ninguna variable de URL base.

Algunos entornos de ejecución fijan la URL del proveedor en su código fuente. No hay variable de entorno, ni archivo de configuración, ni opción. Definir ANTHROPIC_BASE_URL no hace nada, porque nada la lee. Si el registrador puede lanzar el agente, sigue habiendo una ruta, y es la que más preocupa: la interceptación TLS.

El opt-in es exactamente eso: un opt-in; está desactivado por defecto. Cuando lo habilitas para una ejecución, el registrador genera una autoridad de certificación única para esa ejecución, y esa autoridad solo es de confianza para el agente que el registrador lanza: se entrega a ese único proceso, no se instala en el llavero de tu sistema y no se deja para la siguiente ejecución. Cuando la ejecución termina, la autoridad se elimina. El agente se conecta a su host fijo exactamente como siempre lo hizo; el registrador responde, y la sesión llega como si la URL hubiera sido configurable desde el principio.

Lo que la ruta se niega deliberadamente a hacer importa tanto como lo que hace. Lee los hosts de su lista de permitidos y nada más. Los hosts que quedan fuera de la lista de permitidos se envían por túnel sin leerse y quedan registrados como una dirección y un recuento de bytes: prueba de que el agente contactó con algo, y ni un solo byte de lo que se dijo. Esa frontera es una decisión de diseño, no una limitación que aún no hayamos abordado; la misma disciplina impregna el firewall del agente de OrcaRouter, donde la lista de permitidos es el producto, y no un efecto secundario del registro.

El detalle es el mismo que en la primera pregunta: la interceptación funciona cuando el registrador lanza el agente. Un agente que ya se está ejecutando dentro de un contenedor nunca recibió la autoridad certificadora de esa ejecución y no confiará en la respuesta del registrador.

Un agente que no está en esta máquina

Un contenedor tiene su propio entorno. La variable de base-URL que configuras en tu shell no llega a su interior, y un grabador en el host no puede lanzar un proceso que ya existe en otro lugar: en un VPS, en CI, en un sandbox que el arnés construyó sin preguntarte. La captura basada en el lanzamiento falla aquí no porque el agente sea difícil, sino porque el grabador nunca llega a tocarlo.

Precisamente para este caso existe orca attach: graba un agente que el recorder no puede lanzar, como uno en un contenedor o en un VPS. La dirección se invierte: en lugar de que el recorder inicie el agente y le entregue un entorno, se adjunta a un agente que ya está en ejecución y lo graba.

Lo que attach no hace es responder la segunda pregunta por ti. Resuelve llevar el tráfico al registrador; que ese tráfico se convierta en una sesión que puedas reproducir todavía depende de que se comprenda el formato de transmisión. Adjunta un agente que hable un formato que el registrador conozca y obtendrás una sesión reproducible. Adjunta uno que no lo haga, y habrás encontrado el muro, que es más barato de encontrar a propósito que en pleno incidente.

¿Qué cambia con un inicio de sesión de suscripción?

El mismo binario puede ser capturado o no, dependiendo de cómo haya iniciado sesión. Una Codex CLI que ha iniciado sesión con una clave de API se captura a través de OPENAI_BASE_URL: apunta esa variable al capturador y listo. Si inicias la misma CLI con una suscripción de ChatGPT, deja de hablar con ese endpoint por completo; habla con su propio backend, autenticado como tú, y no hay origen que reescribir. La variable base-URL sigue existiendo, pero nada a lo que la apuntes se convierte en el servicio que el capturador está usando realmente.

Esta es la segunda pregunta que falla, no la primera. Se puede hacer que los bytes se muevan; el grabador incluso puede verlos. Pero la conversación está dirigida a un backend que el grabador no puede sustituir, en un flujo que no es la API que el grabador habla. No hay ninguna repetición que producir porque no hay un origen en el que el grabador pueda convertirse.

La respuesta honesta, hoy, para un banco de pruebas que inicia sesión con una suscripción es que no se puede grabar, y la lección útil es que el método de inicio de sesión forma parte de la decisión sobre la grababilidad. Si necesitas grabaciones para evaluaciones o para una pista de auditoría, ejecuta las sesiones que vayas a grabar con una clave de API y conserva la suscripción para el trabajo interactivo — cómo convertir una sesión grabada en una evaluación de regresión cubre todo ese ciclo de principio a fin. Y antes de estandarizar cualquier banco de pruebas, hazle primero las dos preguntas; seguimos haciendo exactamente eso con cada banco de pruebas, más recientemente con el banco de pruebas Prime Agent.

La conclusión

Puedes grabar una sesión de Claude Code hoy mismo con un solo comando y una variable de entorno:

• npm i -g orcareplay

• Apunta ANTHROPIC_BASE_URL al grabador

• Ejecutar el agente

Un Codex CLI con una clave de API está a la misma distancia. Una URL codificada te cuesta optar por una interceptación TLS que solo lee su lista de permitidos (la misma disciplina que aplica el firewall de agente de OrcaRouter) y olvida sus propios certificados cuando termina la ejecución. Un contenedor o una VPS te cuesta orca attach. Una suscripción con inicio de sesión te cuesta la grabación en sí: ese arnés no se grabará, y ningún cambio de configuración cambiará eso hoy.

Toda la decisión de un vistazo:

• Claude Code — Clave de API de inicio de sesión vs Ruta al registrador ANTHROPIC_BASE_URL vs Grabable hoy Sí

• Codex CLI — Clave de API de inicio de sesión vs Ruta al registrador OPENAI_BASE_URL vs Registrable hoy Sí

Banco de pruebas con la URL del proveedor fija en el código — Cualquier inicio de sesión vs. ruta al grabador; intercepción TLS opcional, lanzada por el grabador, vs. grabable hoy: Sí.

• Agente en un contenedor o en un VPS — Inicio de sesión desde cualquier lugar vs Enrutamiento al grabador orca attach vs Grabable hoy: Sí, si se conoce el formato de transmisión

• Codex CLI — Inicio de sesión de suscripción de ChatGPT vs Ruta al grabador Ninguno vs Grabable hoy No

La última fila es la única combinación sin ruta alguna hacia la grabadora.

Haz las dos preguntas antes de adoptar un arnés, no después de tu primer incidente; las respuestas son baratas de conseguir y deciden si la sesión que un día necesitarás desesperadamente existe siquiera.

Nota sobre las fuentes: todos los comportamientos y cifras de este artículo (las rutas de captura de `ANTHROPIC_BASE_URL` y `OPENAI_BASE_URL`, los cuatro fallos posteriores al fixture y sus correcciones, el ciclo de vida del certificado TLS, el comportamiento de lista blanca y túnel, `orca attach` y los requisitos de instalación) provienen de nuestras propias ejecuciones de validación contra los bancos de pruebas mencionados, la más reciente el 2026-09-04. No citamos benchmarks de terceros porque no ejecutamos ninguno.