Los entornos autohospedados están en versión beta pública en planes Team y Enterprise; Disponibilidad y limitaciones cubre la ruta de habilitación. Esta página es la receta de prueba de CI; consulte el inicio rápido para la configuración y Implementar en producción para las recetas de flota.
Instale el hook de captura en su ejecutor de prueba
La lectura funciona a través de un hook Stop de Claude Code: cuando Claude termina un turno, el hook recibe el mensaje final del asistente comolast_assistant_message en su JSON de stdin y lo añade a $E2E_REPLY_DIR/<session_id>.txt. Instálelo de la misma manera que el hook Stop commit-nudge, en ~/.claude/ del host del ejecutor, que el ejecutor siembra en cada sesión.
Guarde los archivos del hook
Guarde los dos archivos a continuación en el host del ejecutor:- El bloque de configuración: fusione en
~/.claude/settings.jsonen el host del ejecutor - El script: guarde como
~/.claude/hooks/e2e-stop-hook-capture.shen el host del ejecutor y hágalo ejecutable
Antes de iniciar el ejecutor
Dos cosas de las que depende el hook:- Instálelo antes de iniciar el ejecutor. El ejecutor toma una instantánea de
~/.claude/una vez al inicio, por lo que un hook añadido a un ejecutor en ejecución solo tiene efecto después de un reinicio. - Exporte
E2E_REPLY_DIRal proceso del ejecutor. El hook es una operación sin efecto cuando la variable no está configurada o el directorio no existe, así que configúrelo donde inicie el ejecutor, como la unidad systemd, especificación de pod o paso de CI. El script de prueba a continuación también lo requiere.
E2E_REPLY_DIR exista, lo cual es inofensivo en un ejecutor de CI desechable pero no algo que deba llevar a una imagen de ejecutor de entorno de producción donde la variable podría configurarse accidentalmente.
Ejecute el bucle de prueba
Los indicadores de envío--environment y --ref requieren Claude Code v2.1.224 o posterior en la máquina que ejecuta el script, el mismo piso que el ejecutor en sí. Con el hook en su lugar y un ejecutor iniciado en este host, el script de prueba:
- Crea una sesión en el entorno de prueba con
claude -p "<prompt>" --environment <environment-id> --output-format json, ejecutado desde un checkout de git para que la CLI pueda detectar automáticamente el repositorio desde el remotoorigin. El--ref <branch>opcional basa el checkout de la sesión en una ref nombrada en lugar de HEAD local. El comando crea la sesión, imprime una línea de JSON que contienesession_idy sale sin esperar la respuesta de Claude. - Espera a que la respuesta aparezca en
$E2E_REPLY_DIR/<session_id>.txt, escrita por el hook Stop en el ejecutor una vez que el turno se completa. - Envía un seguimiento con
claude -p "<message>" --cloud <session_id> --output-format json(consulte Enviar un mensaje de seguimiento a una sesión en ejecución), que publica un evento de usuario en la sesión existente y sale. - Espera la respuesta del seguimiento de la misma manera que el paso 2.
Comportamiento de envío de --environment
Claude Code crea la sesión, imprime el ID de sesión y un enlace a ella, y sale.
El indicador tiene precedencia sobre la configuración remote.defaultEnvironmentId. No admite --output-format stream-json y no se puede combinar con indicadores que reanuden, se adjunten o preconfiguran una sesión, como --resume, --continue, --teleport, --session-id o --init-only. --cloud se rechaza con un ID de sesión o URL, y en ejecuciones no interactivas cuando lleva una descripción. Un --cloud desnudo se trata como ausente. Desde una terminal, puede pasar la tarea como la descripción de --cloud en lugar de un prompt posicional.
Script de ejemplo
El script a continuación ejecuta el bucle completo contra$CLAUDE_TEST_ENVIRONMENT_ID, el ID ccpool_... de su entorno de prueba, que se muestra en el diálogo de detalles del entorno en la página de administración o se devuelve por la llamada create-environment, y afirma una frase centinela en cada respuesta. Ejecute desde un checkout de git del repositorio en el que desea que la sesión funcione, después de iniciar un ejecutor en este host con el hook de captura instalado y E2E_REPLY_DIR exportado.
TURN1/TURN2 y los centinelas EXPECT1/EXPECT2 con lo que sea que ejercite su configuración, como pedirle a Claude que ejecute una de sus herramientas MCP personalizadas y afirmar su salida.
Ejecutores de prueba remotos
Si sus ejecutores de prueba están en infraestructura separada, como una flota de Kubernetes persistente con la que su trabajo de CI no puede compartir un sistema de archivos, cambie la escritura de archivo en el hook Stop por un POST a un endpoint que su controlador escuche:Autentíquese desde CI
Tantoclaude -p ... --environment como claude -p ... --cloud se autentican con un token OAuth de claude.ai; las claves API, como sk-ant-xxxxx, no se aceptan para ninguna de las dos llamadas. Dos enfoques hacen que un token esté disponible en CI.
Host de CI de larga duración
Ejecuteclaude auth login una vez de forma interactiva en la máquina que ejecuta el script, usando una cuenta de usuario dedicada para automatización. Claude Code almacena el token en el llavero del SO en macOS, o en ~/.claude/.credentials.json en Linux y Windows. En un host macOS cuyo Keychain no se puede escribir, como es típico en una sesión SSH donde el Keychain de inicio de sesión permanece bloqueado, Claude Code almacena el token en ~/.claude/.credentials.json también. Consulte Gestión de credenciales.
La CLI actualiza automáticamente el token de acceso de corta duración en cada invocación, pero la concesión de token de actualización subyacente está limitada a 30 días desde el inicio de sesión inicial, así que vuelva a ejecutar claude auth login de forma interactiva en ese host cada 30 días.
Ejecutores de CI efímeros
No hay un token de CI de larga duración para esto hoy. El alcance que otorga control de sesión remota,user:sessions:claude_code, está limitado en el servidor a 30 días, por lo que claude setup-token, que acuña un token de solo inferencia de un año, no lo cubre. El secreto del entorno tampoco se acepta, ya que solo autoriza a un ejecutor a registrarse con el entorno, no a crear sesiones.
Para aprovisionar un inicio de sesión almacenado en un ejecutor efímero, configure CLAUDE_CODE_OAUTH_REFRESH_TOKEN y CLAUDE_CODE_OAUTH_SCOPES para que claude auth login intercambie el token sin un navegador; el mismo límite de 30 días se aplica a la concesión de actualización. Póngase en contacto con su equipo de cuenta de Anthropic si necesita una ruta de identidad de máquina que no esté vinculada a una cuenta humana.
Cree un entorno de prueba dedicado
Cree y elimine entornos mediante programación para que cada ejecución de CI obtenga uno limpio; el ejecutor que su trabajo de CI inicia se registra en el entorno nuevo. Las llamadas de creación y eliminación a continuación son los mismos endpoints que la página de administración Cloud environments en claude.ai usa, y requieren el encabezadoanthropic-beta: ccr-byoc-2025-07-29.
Acuñe el token de administrador
$ADMIN_TOKEN es un token de acceso OAuth de claude.ai para una cuenta que tiene un rol de Propietario, acuñado de la misma manera que Autentíquese desde CI:
- Acuñelo: ejecute
claude auth logincon una cuenta que tenga un rol de Propietario, luego lea el token de acceso actual desde donde Host de CI de larga duración dice que Claude Code lo almacenó. - Léalo fresco en cada ejecución: la CLI rota el token de acceso, y el mismo límite de concesión de actualización de 30 días se aplica, así que no almacene una copia.
- Páselo a través de stdin: como hace el ejemplo, para que el token nunca llegue a la lista de argumentos de curl o su registro de compilación.
Cree el entorno
Capture la respuesta sin ecoarla:pool_secret es una credencial de larga duración que puede registrar ejecutores en el entorno, así que guárdela como un secreto de CI enmascarado e imprima solo el ID del entorno. La forma -H @- que mantiene el token fuera de la lista de procesos requiere curl 7.55 o posterior; curl más antiguo trata @- como un encabezado literal y envía la solicitud sin autorización.
403 permission_error que lee self-hosted runners are disabled by your organization's policy.
Inicie un ejecutor en este host con SELF_HOSTED_RUNNER_ENVIRONMENT_SECRET=$ENVIRONMENT_SECRET, más el hook de captura y E2E_REPLY_DIR por Instale el hook de captura, luego ejecute el script de prueba.