Modo sin cabeza explicado: Ejecutar Claude Code sin terminal

Cada sesión de Claude Code que ejecutas en una terminal es interactiva: escribes una solicitud, Claude Code responde, quizás pide ejecutar una herramienta y tú la apruebas o deniegas en tiempo real.

Ese modelo se desmorona en el momento en que nadie está en la terminal para aprobar nada: dentro de un script, un trabajo programado o una canalización de CI.

El modo sin cabeza es cómo Claude Code maneja ese caso: se ejecuta como un único comando no interactivo que toma un prompt, hace el trabajo y sale, sin abrir nunca el REPL interactivo.

Comprender el modo sin cabeza es el requisito previo para todo lo demás en esta sección que toca CI: un bot de revisión automatizado, un trabajo de GitHub Actions, cualquier cosa que ejecute Claude Code sin una persona observando.

Resumen

Idea central: el modo sin cabeza invoca Claude Code como un único comando de script que ejecuta un prompt hasta su finalización y sale, en lugar de abrir una sesión de terminal interactiva.
Por qué importa: los scripts, los trabajos cron y las canalizaciones de CI no tienen a ningún humano presente para escribir mensajes de seguimiento o aprobar llamadas a herramientas una por una; el modo sin cabeza es la única forma de invocación que funciona en ese contexto.
Conceptos clave: sesión interactiva, invocación sin cabeza, modo de impresión, formato de salida, permisos no interactivos.
Cuándo usarlo: cualquier automatización donde Claude Code necesite ejecutarse sin una persona observando: trabajos de CI, tareas programadas, scripts por lotes o un bot de revisión activado por un evento de GitHub.
Limitaciones / Compensaciones: sin un humano para aprobar acciones en tiempo real, las invocaciones sin cabeza necesitan que sus herramientas y alcance permitidos se decidan de antemano, lo que significa menos margen para las decisiones de mitad de tarea que una sesión interactiva permite.
Temas relacionados: la CLI de gh, activadores de GitHub Actions, revisión automatizada de código, gestión de secretos de CI.

Fundamentos

Una sesión interactiva de Claude Code es una conversación. Tú envías un mensaje, Claude Code responde, quizás solicita ejecutar una herramienta, tú la apruebas y el intercambio continúa hasta que estés satisfecho.

El modo sin cabeza reemplaza esa conversación con una única instrucción. Le das a Claude Code un prompt que describe toda la tarea, y ejecuta todo lo necesario para completar esa tarea sin detenerse a preguntarte nada más.

La salida es texto (o un formato estructurado como JSON), devuelto una vez que la ejecución finaliza, en lugar de un flujo en vivo de mensajes a los que respondes a medida que llegan.

Una comparación útil: una sesión interactiva es como sentarse con un colega y hablar sobre una tarea juntos. El modo sin cabeza es como entregarle a ese colega un resumen escrito y recibir un informe terminado, sin conversación intermedia.

# Interactivo: abre una sesión en vivo, espera tu entrada.
claude
 
# Sin cabeza: ejecuta un prompt hasta su finalización y luego sale.
claude -p "Resume los pull requests abiertos en este repositorio." --output-format text

Ambas invocaciones utilizan la misma capacidad subyacente de Claude Code: los mismos modelos, el mismo modelo de acceso a herramientas. Lo que difiere es completamente la forma de la invocación: una te espera, la otra no.

Mecánica e Interacciones

Dado que el modo sin cabeza no tiene a un humano presente para aprobar las llamadas a herramientas a medida que surgen, su modelo de permisos debe decidirse antes de que comience la ejecución, no negociarse durante la misma.

En una sesión interactiva, una llamada a herramienta que no has pre-aprobado normalmente se detiene y pregunta. En una ejecución sin cabeza, no hay nadie allí para responder a ese prompt; por lo tanto, una invocación sin cabeza necesita sus herramientas permitidas, directorio de trabajo y cualquier alcance relevante configurado de antemano, de lo contrario, la ejecución falla o se queda atascada esperando una aprobación que nunca llegará.

Es por eso que las invocaciones sin cabeza generalmente se combinan con una configuración explícita de permisos o una lista blanca de herramientas que se pasa junto con el prompt, en lugar de depender del flujo de aprobación interactiva.

El formato de salida también importa más en el modo sin cabeza. La salida de una sesión interactiva está destinada a una persona que lee una terminal en tiempo real. La salida de una ejecución sin cabeza a menudo alimenta algo más: un script que la analiza, un paso de CI que la publica como un comentario de PR, un registro que una canalización archiva. Es por eso que las invocaciones sin cabeza comúnmente especifican un formato de salida explícito (texto plano, JSON o una transcripción estructurada) en lugar de depender del formato predeterminado para humanos.

# Modo sin cabeza invocado con salida estructurada, para que un script pueda analizar el resultado
# programáticamente en lugar de extraer texto legible por humanos.
claude -p "Revisa el diff en el PR #482 y resume cualquier riesgo." \
  --output-format json > review-result.json

El comentario que importa aquí: --output-format json existe específicamente porque el consumidor del modo sin cabeza suele ser otro programa, no una persona; la misma solicitud formulada para una sesión interactiva simplemente imprimiría prosa legible.

Consideraciones Avanzadas y Aplicaciones

El modo sin cabeza es el mecanismo que hace posible todo uso de Claude Code basado en CI, porque un trabajo de GitHub Actions, por definición, se ejecuta sin que nadie observe una terminal.

Un trabajo de GitHub Actions que ejecuta Claude Code sin cabeza necesita tres cosas conectadas: un activador (como on: pull_request), un secreto que contenga una clave API para que el trabajo se autentique, y la invocación sin cabeza en sí con sus indicadores y herramientas permitidas configuradas. Cada uno de estos se cubre con más detalle en otra parte de esta sección.

El modo sin cabeza también cambia el modo de fallo en el que los desarrolladores deben pensar. Una sesión interactiva que encuentra una situación ambigua puede hacerte una pregunta aclaratoria. Una ejecución sin cabeza no tiene a nadie a quien preguntar; por lo tanto, un prompt sin cabeza bien diseñado debe especificar suficientes restricciones y contexto de antemano para que la ambigüedad sea poco probable, o debe fallar con gracia (salir con un error claro) en lugar de adivinar.

Aspecto	Sesión Interactiva	Modo sin Cabeza
Quién aprueba las llamadas a herramientas	Tú, en tiempo real	Lista blanca preconfigurada, decidida antes de la ejecución
Forma de la salida	Legible por humanos, transmitida	Texto o estructurada (JSON), devuelta al finalizar
Maneja la ambigüedad mediante	Haciendo una pregunta de seguimiento	Fallando claramente, o actuando según la mejor instrucción disponible
Activador típico	Tú, escribiendo una solicitud	Un script, una programación o un evento de CI

Aquí es también donde la postura de seguridad del modo sin cabeza importa más. Dado que el acceso a las herramientas de una ejecución sin cabeza se decide de antemano en lugar de aprobarse interactivamente, los permisos y secretos otorgados a un trabajo de CI se convierten efectivamente en el límite de lo que esa invocación sin cabeza puede hacer: no hay una red de seguridad humana que atrape una concesión demasiado amplia en el momento, como la habría en una sesión interactiva.

Conceptos erróneos comunes

"El modo sin cabeza es una versión separada y menor de Claude Code." Es la misma capacidad subyacente —los mismos modelos, las mismas herramientas— invocada de manera diferente; nada sobre el modelo en sí cambia.
"El modo sin cabeza no puede pedir aclaraciones, por lo que debe ser menos capaz." No es menos capaz, está restringido de manera diferente: la compensación es intencional, porque el propósito es ejecutarse sin una persona disponible para responder preguntas de seguimiento.
"Cualquier comando de Claude Code funciona bien sin cabeza y sin cambios." Un comando que depende de la aprobación interactiva de llamadas a herramientas se detendrá o fallará en modo sin cabeza a menos que sus permisos se configuren para uso no interactivo de antemano.
"El modo sin cabeza solo importa para CI." CI es el caso de uso más común, pero los scripts programados, los trabajos por lotes y los scripts de automatización únicos en una máquina local también utilizan el modo sin cabeza, por la misma razón: nadie observa en tiempo real.

Preguntas frecuentes

¿Cuál es la forma más sencilla de ejecutar Claude Code sin cabeza?

Pasa un prompt con el indicador de impresión (-p) y deja que se ejecute hasta su finalización, por ejemplo, claude -p "tu instrucción aquí": la sesión se ejecuta una vez y sale, sin abrir el REPL interactivo.

¿El modo sin cabeza utiliza un modelo de Claude diferente al de las sesiones interactivas?

No: la elección del modelo es independiente de la invocación interactiva o sin cabeza; cualquier modo puede utilizar cualquier modelo de la línea actual.

¿Por qué las ejecuciones sin cabeza necesitan permisos configurados de antemano?

Porque no hay una persona presente para aprobar una llamada a herramienta en el momento, como la hay en una sesión interactiva; sin una lista blanca preconfigurada, una ejecución sin cabeza falla o se detiene esperando una aprobación que nadie dará.

¿Qué formatos de salida admite el modo sin cabeza?

Comúnmente texto plano y JSON estructurado; se prefiere JSON cuando la salida alimenta a otro programa, como un paso de CI que analiza el resultado para publicar un comentario.

¿Puede el modo sin cabeza hacerme una pregunta aclaratoria a mitad de la ejecución?

No: esa es la principal compensación del modo; un prompt sin cabeza necesita llevar suficiente contexto y restricciones de antemano, ya que no hay nadie disponible para responder a un seguimiento.

¿El modo sin cabeza solo se puede usar dentro de GitHub Actions?

No: funciona desde cualquier script o contexto de shell, incluida una terminal local; GitHub Actions es simplemente el caso de uso de CI más común para él en esta sección.

¿Qué sucede si una ejecución sin cabeza intenta usar una herramienta para la que no se le concedió permiso?

Se bloquea o la ejecución falla, ya que no hay un flujo de aprobación interactivo al que recurrir; por eso el conjunto de herramientas permitidas debe decidirse antes de que comience la ejecución.

¿Existe un riesgo de seguridad específico para el modo sin cabeza?

Sí: dado que los permisos se otorgan de antemano en lugar de aprobarse caso por caso, lo que una invocación sin cabeza tiene permitido hacer se convierte en el límite real de lo que puede hacer, sin que un humano atrape una concesión demasiado amplia a mitad de la ejecución.

¿Puedo probar una invocación sin cabeza localmente antes de ponerla en CI?

Sí: ejecutar el mismo comando claude -p "..." desde una terminal local es una forma confiable de validar un prompt y su formato de salida antes de conectarlo a un trabajo de GitHub Actions.

¿El modo sin cabeza todavía tiene acceso a las mismas herramientas que una sesión interactiva?

Tiene acceso a las herramientas que se permitan explícitamente para esa invocación, potencialmente el mismo conjunto que una sesión interactiva, o un conjunto más estrecho y deliberadamente limitado, dependiendo de cómo se configure.

Relacionados

Cómo Claude Code encaja en tu flujo de trabajo de GitHub Pull Request - dónde encaja el modo sin cabeza entre los puntos de contacto de PR.
Ejecución de Claude Code como un bot de revisión de código automatizado en CI - la principal aplicación en el mundo real del modo sin cabeza en esta sección.
Configuración de un trabajo de GitHub Actions que ejecuta Claude Code - conectando invocaciones sin cabeza a un trabajo de CI funcional.
Fundamentos de la integración de GitHub - una primera invocación sin cabeza práctica.

Versiones de Stack: Escrito contra la línea de modelos de Claude actual a partir de ~junio de 2026 - Claude Fable 5, Claude Opus 4.8, Claude Sonnet 5 (el predeterminado) y Claude Haiku 4.5. Los nombres de los modelos, los precios y las características del producto cambian rápidamente; verifique los detalles actuales en platform.claude.com/docs antes de confiar en ellos.