Esta página es una traducción de la documentación en inglés. Los comandos, identificadores y ejemplos no cambian. Runtime 7.24.4 · SDK 2.6.7. Original en inglés

Modo autónomo

Estado: Activo Alcance: estado actual Última revisión: 2026-08-25 Responsable: entorno de ejecución de ax-code

El modo autónomo permite que AX Code complete tareas sin esperar una confirmación humana en cada paso de bajo riesgo. Cuando está activado, los prompts de permiso se aprueban de forma automática salvo que estén bloqueados de forma explícita, y los diálogos de pregunta se responden solos con una heurística de buena práctica que favorece las opciones recomendadas, predeterminadas, habituales, simples y mínimas, y evita las opciones arriesgadas o sobrediseñadas.

De forma predeterminada, el modo autónomo está activado. Si lo desactivaste antes, esa preferencia se guarda y se restaura en el siguiente inicio.

Inicio rápido

Cámbialo desde la TUI:

• Escribe /autonomous en el prompt, o
• Pulsa Ctrl+P y busca «autonomous», o
• Haz clic en el indicador autónomo activado/desactivado de la barra de estado

La barra de estado muestra el estado actual:

• autónomo activado (fondo amarillo, texto rojo en negrita) — el agente se ejecuta sin pausas
• autónomo desactivado (texto verde) — el agente se detiene ante los prompts de permiso y de pregunta

El ajuste persiste entre sesiones en ax-code.json.

Qué cambia

Cómo funciona

El modo autónomo opera en tres capas:

Fuente de verdad

Esta página resume el comportamiento visible para el usuario. Cuando el comportamiento cambie, verifica la documentación contra:

• packages/ax-code/src/session/processor.ts para la autoaprobación de permisos, el comportamiento del bucle, el manejo de rechazos y los topes autónomos.
• packages/ax-code/src/session/system.ts y los archivos de prompt del proveedor bajo packages/ax-code/src/session/prompt/ para las instrucciones del flujo autónomo.
• packages/ax-code/src/question/ y packages/ax-code/test/question/question.test.ts para las heurísticas de respuesta automática a preguntas y el comportamiento de escalada.
• packages/ax-code/src/session/blast-radius.ts para los topes autónomos de pasos y de cambios de archivo.
• packages/ax-code/test/session/system.test.ts, packages/ax-code/test/session/prompt.test.ts y las pruebas de sesión relacionadas para el comportamiento del prompt y del libro de decisiones.

Mantén aquí las garantías de seguridad alineadas con la documentación del sandbox; el modo autónomo cambia el comportamiento de aprobación, no la aplicación del aislamiento.

1. Autoaprobación de permisos (lado del servidor)

El modo autónomo usa una política híbrida que prioriza la denegación (ADR-004 / PRD v4.2.0). Cuando una herramienta llama a ctx.ask() para pedir permiso, el módulo de permisos clasifica el permiso:

• Los permisos SAFE (read, glob, grep, list, lsp, code_intelligence, skill, todoread) se aprueban solos sin crear un prompt que bloquee.
• Los permisos RISK (edit, bash, external_directory, task, webfetch, websearch, codesearch, …) pasan al conjunto de reglas: siguen aplicándose las reglas de permiso y denegación configuradas del agente, y las reglas de denegación definidas por el usuario se aplican siempre. En el modo de sandbox full-access, los permisos RISK se aprueban solos después de evaluar las reglas de denegación.
• Los permisos desconocidos preguntan de forma predeterminada (experimental.autonomous_strict_permission: false conserva el comportamiento heredado de permitir).

Permisos que siempre llegan a una decisión por llamada en lugar de una aprobación inmediata basada en reglas: isolation_escalation (solicitudes de anulación del sandbox), permisos INTERACTIVE_ONLY y el conjunto NEVER_AUTONOMOUS_AUTOAPPROVE. Una acotación (ADR-098): en el modo de sandbox full-access, las solicitudes external_directory marcadas como solo interactivas — comandos bash cuyas rutas no se pueden verificar de forma estática porque usan un glob, una variable o una expansión de llaves — también se aprueban solas, porque un sandbox de acceso completo ya no tiene un límite de sistema de archivos que proteger. Las reglas de denegación explícitas siguen aplicándose, y los modos con sandbox activado (workspace-write, read-only) conservan el prompt por llamada.

«Permitir una vez» en inactividad (activado de forma predeterminada): Auto activado más Sandbox desactivado (full-access) significa interacción mínima: cada permiso pendiente puede autorresponderse una vez después de 15 segundos, incluidos requireInteractive y los prompts de hook y de escalada del sandbox. Auto desactivado o Sandbox activado exige una respuesta humana a los prompts pendientes. WebMCP exige además que el puente correspondiente esté conectado; otro puente conectado no basta. Las reglas de denegación explícitas siguen aplicándose. experimental.permission_idle_once.enabled: false desactiva las cuentas atrás, y permissions puede restringir su alcance. El ajuste heredado timeout_ms se acepta por compatibilidad, pero ya no cambia la duración fija de 15 segundos.

El servidor es dueño de la cuenta atrás. La solicitud más antigua de cada sesión recibe un plazo; las solicitudes en cola reciben 15 segundos nuevos cuando llegan al frente. Las respuestas humanas cancelan el temporizador. Desactivar Auto, activar Sandbox o desconectar el puente WebMCP pertinente cancela las cuentas atrás pendientes. Restaurar la aptitud inicia una cuenta atrás nueva. Los huecos temporales de recarga de configuración suspenden la cuenta atrás. Las respuestas automáticas vuelven a comprobar el modo actual, el puente y las reglas de denegación, y nunca guardan una aprobación persistente. La anulación interna de depuración y prueba AX_CODE_PERMISSION_IDLE_ONCE_MS sigue disponible y está limitada al máximo del temporizador de Node.

Los modos se limitan al directorio activo. Un ax-code.json anidado puede anular los ajustes de la raíz del repositorio; usa el interruptor de Sandbox de la sesión activa para cambiar su modo efectivo.

Rutas protegidas no anulables: el modo autónomo también se niega a escribir un conjunto fijo de rutas del plano de política y control — ax-code.json/ax-code.jsonc, .ax-code/**, .git/config y .git/refs/** — para que el agente no pueda editar su propia configuración, elevar sus propios topes de autonomía ni plantar hooks de git. A diferencia de la lista configurable de rutas bloqueadas, estas no se pueden quitar con la configuración del proyecto o del usuario.

2. Respuesta automática a preguntas (lado del servidor)

Cuando una herramienta hace una pregunta al usuario, el módulo de preguntas elige una respuesta de inmediato. Prefiere las opciones marcadas como recomendadas, predeterminadas, seguras, estándar, habituales, convencionales, de buena práctica, simples o mínimas. Evita las opciones marcadas como experimentales, arriesgadas, peligrosas, destructivas, avanzadas, complejas, de reescritura o sobrediseñadas. Si ninguna opción tiene una señal, elige la primera, porque la herramienta de preguntas indica a los agentes que pongan primero la opción recomendada.

3. Bucle del procesador (nivel de sesión)

Si un permiso se rechaza de algún modo (por ejemplo, por una regla de denegación explícita), el bucle del procesador no se detiene: continúa con el siguiente paso en lugar de frenar la sesión.

4. Marco de decisión al estilo PRD/ADR

El modo autónomo añade un recordatorio ligero de flujo al prompt de sistema. Antes de la implementación, el agente debe enmarcar el trabajo con el problema, las restricciones, la decisión, las compensaciones, el plan y la validación. Para cambios sustanciales de varios archivos, arquitectónicos o visibles en el producto, puede crear o actualizar un documento del repositorio cuando eso coincida con el patrón de documentación del repositorio. Para cambios triviales, debe mantener este marco ligero en el plan para evitar el sobrediseño.

Autónomo y sandbox

El modo autónomo y el modo sandbox son independientes. Puedes usar ambos a la vez:

La postura predeterminada del entorno de ejecución es autónomo activado más sandbox desactivado: full-access con la red habilitada. Esto da el comportamiento de CLI con menos fricción, pero sin límite de aislamiento. Usa /sandbox, --sandbox workspace-write, AX_CODE_ISOLATION_MODE o la configuración del proyecto para activar restricciones en trabajo no confiable o desatendido.

Configuración

Archivo de configuración

En ax-code.json:

{
  "autonomous": true
}

Establécelo en false para desactivarlo:

{
  "autonomous": false
}

Variable de entorno

AX_CODE_AUTONOMOUS=true ax-code    # force autonomous on
AX_CODE_AUTONOMOUS=false ax-code   # force autonomous off

Precedencia

Variable de entorno > archivo de configuración > predeterminado (activado)

Presupuestos de carga (turnos de modelo y llamadas a herramientas)

El modo autónomo no significa ejecución ilimitada. Se aplican varios topes independientes. Los valores de abajo son las constantes publicadas; súbelos o bájalos en ax-code.json cuando una carga necesite más margen.

Un turno de modelo es una solicitud de modelo del bucle exterior. Una llamada a herramienta es una invocación de herramienta dentro de un turno de modelo. Son presupuestos distintos: un solo turno de modelo puede emitir varias llamadas a herramienta. Los nombres de configuración heredados que contienen steps siguen admitiéndose, pero no hacen intercambiables las dos unidades.

Prefiere el objeto de primera clase autonomy. Las claves heredadas session.* y experimental.autonomous_caps.* siguen funcionando como alias (menor precedencia).

Los archivos binarios (cp de un ejecutable, curl -o de un zip y otras escrituras que no son texto) siguen contando para el tope de archivos, pero cargan cero líneas. El tope de líneas mide el cambio textual. Las escrituras de texto del shell conservan la estimación ceil(size / 80) para que una carga densa no pueda eludir el presupuesto por tener pocos saltos de línea.

Las rutas no rastreadas que git check-ignore informa como ignoradas también cargan cero líneas y siguen contando como un archivo. Eso cubre árboles generados como target/ cuando un verificador redirige allí su salida (cargo clippy > target/review/clippy.log). La exención se aplica solo cuando git sale con 0. Un repositorio ausente, un fallo de git y un archivo rastreado conservan el cargo normal de líneas, incluido un archivo rastreado cuyo nombre coincide con un patrón de ignorados.

Perfiles

Establece autonomy.profile para sembrar varios campos a la vez (los campos explícitos siguen ganando):

Inspeccionar con /limits

En una sesión, ejecuta /limits para imprimir la pila de presupuesto resuelta, el denominador efectivo de la TUI para el agente activo, las fuentes de configuración y los avisos de doctor (por ejemplo cuando agent.steps es más estricto que el segmento de la sesión). Usa /limits help para los nombres de clave.

Qué muestra la TUI: durante una ejecución autónoma la cabecera informa turn current/max · total current/max · cont current/max. turn es el segmento de continuación actual y usa el tope efectivo de ritmo del agente activo: min(agent.steps, session.max_steps) cuando el agente está limitado y, si no, el límite por segmento. total sobrevive a las autocontinuaciones. cont muestra ∞ cuando un objetivo activo o el modo Super-Long eleva el tope ordinario de continuación.

Enrutado automático: el enrutado por palabras clave puede cambiar la sesión a un agente especialista (Debug, Security, DevOps, …). Los especialistas comparten la misma política de turnos de modelo sin límite predeterminado que Dev, salvo que establezcas agent.<name>.steps. Desactiva el enrutado con "routing": { "disable": true } si quieres solo el agente Dev.

Ejecuciones largas: usa /goal o Super-Long para trabajo de varias horas: elevan los topes ordinarios de continuación y usan el techo acumulado mayor (predeterminado 20,000), con la semántica de verificación y pausa documentada en modo de bucle. /goal escribe primero un contrato revisable (criterios de aceptación y plan de verificación) y falla cerrado a pausado si ese plan no se puede producir.

Cuando un límite detiene una ejecución

Antes de que una ejecución ordinaria alcance su techo acumulado de turnos de modelo, AX Code inyecta una instrucción acotada de convergencia (como máximo los 50 turnos finales, reducida para presupuestos personalizados pequeños). Indica al modelo que detenga la exploración amplia, termine o aparque de forma segura el trabajo en curso, ejecute una verificación dirigida e informe con veracidad el trabajo inacabado. No añade presupuesto ni elude ningún tope.

Cuando se alcanza un presupuesto terminal, session.error incluye un code opcional legible por máquina, y el evento de reproducción session.end registra el mismo valor como stopCode. Los motivos de fin gruesos existentes permanecen sin cambios por compatibilidad. Los códigos de límite actuales son:

• MODEL_TURN_SEGMENT_LIMIT
• MODEL_TURN_TOTAL_LIMIT
• AGENT_MODEL_TURN_LIMIT
• AGGREGATE_TOOL_CALL_LIMIT
• FILE_CHANGE_LIMIT
• LINE_CHANGE_LIMIT

En un techo de segmento, AX Code continúa de forma automática mientras quede presupuesto de continuación configurado. Cuando ese presupuesto se agota, la ejecución se detiene y el mensaje dice qué ocurrió. Enviar un prompt nuevo como continue inicia una ejecución nueva dirigida por el usuario, con una contabilidad de ejecución nueva; no prolonga de forma retroactiva la ejecución detenida. Usa /goal cuando el objetivo deba seguir siendo explícito y reanudable hasta la finalización, un bloqueo o un límite de presupuesto de objetivo o del entorno de ejecución. /goal no desactiva las protecciones de permiso, aislamiento, radio de explosión, atasco, tokens, tiempo ni turnos de modelo acumulados.

Ejemplo: elevar presupuestos para un lote autónomo grande

{
  "autonomous": true,
  "autonomy": {
    "profile": "long",
    "budget": {
      "model_turns": { "per_segment": 500, "total": 20000 },
      "tool_calls": {
        "per_segment": 1000,
        "rate": { "count": 40, "window_seconds": 10 },
        "per_tool": { "bash": 80, "edit": 150 }
      },
      "changes": { "files_total": 100, "lines_total": 10000 }
    },
    "stall": {
      "tool_only_turns": 50,
      "tool_only_nudge": 20,
      "failed_mutation_attempts": 30,
      "max_consecutive_errors": 3
    }
  },
  "agent": {
    "debug": { "steps": 200 }
  }
}

Cuándo desactivar el modo autónomo

• Aprender AX Code — ver qué hace el agente en cada paso
• Operaciones sensibles — revisar cada cambio de archivo antes de que se aplique
• Depurar el comportamiento del agente — entender por qué el agente toma ciertas decisiones
• Código no confiable — revisar las llamadas a herramientas al trabajar con repositorios desconocidos

Cuándo mantener el modo autónomo activado

• Tareas rutinarias — refactorizaciones, correcciones de errores y migraciones en las que confías en el agente
• Canalizaciones de CI/CD — ejecución headless en la que la tarea ya está acotada por la política
• Uso del SDK — ejecución programática del agente mediante createAgent()
• Tareas grandes — cambios de varios archivos en los que detenerse en cada permiso llevaría horas

Uso headless y en CI

En modo headless (ax-code run, ax-code serve, SDK) el modo autónomo es esencial: no hay una TUI que muestre los prompts. La autoaprobación del lado del servidor asegura que el agente se ejecute hasta el final sin quedarse colgado en prompts sin respuesta.

# Headless one-shot with autonomous on (default)
ax-code run "Fix all TypeScript errors in src/"

# Explicit override
AX_CODE_AUTONOMOUS=true ax-code run "Migrate API routes"

ax-code run imprime de forma predeterminada una salida de herramientas concisa: la salida de comandos se reduce a su cola, las ediciones muestran un resumen del diff y las escrituras de tareas muestran un recuento de progreso de una línea. Los errores nunca se ocultan: se renderizan con el mismo tope de cola que el resto de la salida. Pasa --full para restaurar la salida completa de las herramientas (diffs completos, salida de comandos sin truncar, listas de tareas completas) para auditoría.

Garantías de seguridad

Incluso con el modo autónomo activado:

1. El sandbox sigue haciendo cumplir los límites — las escrituras fuera del espacio de trabajo se bloquean con independencia del modo autónomo
2. La escalada de aislamiento siempre pregunta — el agente no puede anular en silencio las restricciones del sandbox
3. Las reglas de denegación se aplican — las reglas de permiso explícitas "deny" siguen bloqueando llamadas a herramientas
4. Las elecciones autónomas quedan registradas — los metadatos de la herramienta de preguntas incluyen un libro estructurado autonomousDecisions, y la salida de la herramienta incluye las respuestas seleccionadas para que el agente pueda informarlas después
5. Evitar el sobrediseño — la continuación autónoma recuerda al agente que prefiera el cambio más simple de práctica habitual y evite abstracciones sin 3 o más casos de uso concretos
6. Se registran instantáneas de la sesión — cada llamada a herramienta se anota para auditoría y reproducción
7. Abortar siempre funciona — pulsar Esc (interrupción) detiene el agente de inmediato