Esta página é uma tradução da documentação em inglês. Comandos, identificadores e exemplos permanecem iguais. Runtime 7.24.4 · SDK 2.6.7. Original em inglês

Modo autônomo

Status: Ativo Escopo: estado atual Última revisão: 2026-08-25 Responsável: runtime do ax-code

O modo autônomo permite que o ax-code conclua tarefas sem esperar confirmação humana em cada passo de baixo risco. Quando está ativo, os pedidos de permissão são aprovados automaticamente, salvo se estiverem bloqueados de forma explícita, e os diálogos de pergunta são respondidos automaticamente com uma heurística de boa prática, que prefere escolhas recomendadas, padrão, comuns, simples e mínimas, e evita opções arriscadas ou com excesso de engenharia.

Por padrão, o modo autônomo está ligado. Se você já o desligou, essa preferência fica salva e é restaurada na próxima inicialização.

Início rápido

Alterne a partir da TUI:

• Digite /autonomous no prompt, ou
• Pressione Ctrl+P e procure «autônomo», ou
• Clique no indicador autônomo ligado/desligado na barra de status

A barra de status mostra o estado atual:

• autônomo ligado (fundo amarelo, texto vermelho em negrito) — o agente executa sem pausar
• autônomo desligado (texto verde) — o agente pausa nos pedidos de permissão e de pergunta

A configuração persiste entre sessões em ax-code.json.

O que muda

Como funciona

O modo autônomo opera em três camadas:

Fonte da verdade

Esta página resume o comportamento visível para quem usa. Quando o comportamento mudar, confira a documentação em:

• packages/ax-code/src/session/processor.ts para aprovação automática de permissão, comportamento do laço, tratamento de rejeição e tetos autônomos.
• packages/ax-code/src/session/system.ts e os arquivos de prompt do provedor em packages/ax-code/src/session/prompt/, para as instruções do fluxo autônomo.
• packages/ax-code/src/question/ e packages/ax-code/test/question/question.test.ts para as heurísticas de resposta automática e o comportamento de escalada.
• packages/ax-code/src/session/blast-radius.ts para os tetos autônomos de passos e de mudança de arquivo.
• packages/ax-code/test/session/system.test.ts, packages/ax-code/test/session/prompt.test.ts e os testes de sessão relacionados, para o comportamento do prompt e do registro de decisões.

Mantenha as garantias de segurança desta página alinhadas à documentação do sandbox; o modo autônomo muda o comportamento de aprovação, não a aplicação do isolamento.

1. Aprovação automática de permissão (no servidor)

O modo autônomo usa uma política híbrida que nega primeiro (ADR-004 / PRD v4.2.0). Quando uma ferramenta chama ctx.ask() para pedir permissão, o módulo de permissão classifica o pedido:

• Permissões SAFE (read, glob, grep, list, lsp, code_intelligence, skill, todoread) são aprovadas sozinhas, sem criar um pedido que bloqueie.
• Permissões RISK (edit, bash, external_directory, task, webfetch, websearch, codesearch, …) seguem para o conjunto de regras — as regras de permissão e de negação configuradas no agente ainda valem, e as regras de negação definidas por quem usa são sempre aplicadas. No modo de sandbox full-access, as permissões RISK são aprovadas sozinhas depois que as regras de negação são avaliadas.
• Permissões desconhecidas perguntam por padrão (experimental.autonomous_strict_permission: false preserva o comportamento legado de permitir).

Permissões que sempre chegam a uma decisão por chamada, em vez de uma aprovação imediata baseada em regra: isolation_escalation (pedidos de substituição do sandbox), permissões INTERACTIVE_ONLY e o conjunto NEVER_AUTONOMOUS_AUTOAPPROVE. Um estreitamento (ADR-098): no modo de sandbox full-access, pedidos external_directory marcados como somente interativos — comandos bash cujos caminhos não podem ser verificados de forma estática porque usam glob, variável ou expansão de chaves — também são aprovados sozinhos, porque um sandbox de acesso total não tem mais fronteira de sistema de arquivos para proteger. Regras explícitas de negação ainda valem, e os modos com sandbox ligado (workspace-write, read-only) mantêm o pedido por chamada.

«Permitir uma vez» na ociosidade (ligado por padrão): Auto ligado mais Sandbox desligado (full-access) significa interação mínima: cada permissão pendente pode responder sozinha uma vez depois de 15 segundos, inclusive pedidos requireInteractive, de hook e de escalada de sandbox. Auto desligado ou Sandbox ligado exige resposta humana aos pedidos pendentes. O WebMCP ainda exige que a ponte correspondente esteja conectada; outra ponte conectada não serve. Regras explícitas de negação ainda valem. experimental.permission_idle_once.enabled: false desativa as contagens, e permissions pode restringir o escopo delas. A configuração legada timeout_ms é aceita por compatibilidade, mas não altera mais a duração fixa de 15 segundos.

O servidor é dono da contagem. O pedido mais antigo de cada sessão recebe um prazo; pedidos na fila recebem novos 15 segundos quando chegam à frente. Respostas humanas cancelam o temporizador. Desligar o Auto, ligar o Sandbox ou desconectar a ponte WebMCP relevante cancela as contagens pendentes. Restaurar a elegibilidade inicia uma contagem nova. Lacunas temporárias ao recarregar a configuração suspendem a contagem. Respostas automáticas conferem de novo o modo atual, a ponte e as regras de negação, e nunca salvam uma aprovação persistente. A substituição interna de depuração e teste AX_CODE_PERMISSION_IDLE_ONCE_MS continua disponível e tem teto no máximo do temporizador do Node.js.

Os modos têm escopo no diretório ativo. Um ax-code.json aninhado pode substituir as configurações da raiz do repositório; use o interruptor de Sandbox da sessão ativa para mudar o modo efetivo dela.

Caminhos protegidos que não podem ser substituídos: o modo autônomo também recusa gravar um conjunto fixo de caminhos de política e de plano de controle — ax-code.json/ax-code.jsonc, .ax-code/**, .git/config e .git/refs/** — para que o agente não edite a própria configuração, não eleve os próprios tetos de autonomia nem instale hooks do Git. Ao contrário da lista configurável de caminhos bloqueados, estes não podem ser removidos pela configuração do projeto nem pela do usuário.

2. Resposta automática a perguntas (no servidor)

Quando uma ferramenta faz uma pergunta, o módulo de perguntas escolhe uma resposta na hora. Prefere opções marcadas como recomendadas, padrão, seguras, habituais, comuns, convencionais, de boa prática, simples ou mínimas. Evita opções marcadas como experimentais, arriscadas, perigosas, destrutivas, avançadas, complexas, de reescrita ou com excesso de engenharia. Se nenhuma opção tiver um sinal, escolhe a primeira, porque a ferramenta de pergunta instrui os agentes a colocar a opção recomendada em primeiro lugar.

3. Laço do processador (no nível da sessão)

Se uma permissão for rejeitada de algum modo (por exemplo, por uma regra explícita de negação), o laço do processador não para — segue para o passo seguinte, em vez de interromper a sessão.

4. Quadro de decisão no estilo PRD/ADR

O modo autônomo acrescenta um lembrete leve de fluxo ao prompt de sistema. Antes da implementação, o agente deve enquadrar o trabalho com o problema, as restrições, a decisão, os compromissos, o plano e a validação. Para mudanças substanciais de vários arquivos, de arquitetura ou visíveis no produto, ele pode criar ou atualizar um documento do repositório quando isso combinar com o padrão de documentação do repositório. Para mudanças triviais, deve manter este quadro leve no plano, para evitar excesso de engenharia.

Autônomo e sandbox

O modo autônomo e o modo sandbox são independentes. Você pode usar os dois ao mesmo tempo:

A postura padrão do runtime é autônomo ligado e sandbox desligado: full-access com a rede ativada. Isso dá o comportamento de CLI com menos atrito, mas sem fronteira de isolamento. Use /sandbox, --sandbox workspace-write, AX_CODE_ISOLATION_MODE ou a configuração do projeto para ativar restrições em trabalho não confiável ou sem supervisão.

Configuração

Arquivo de configuração

Em ax-code.json:

{
  "autonomous": true
}

Defina como false para desativar:

{
  "autonomous": false
}

Variável de ambiente

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

Precedência

Variável de ambiente > arquivo de configuração > padrão (ligado)

Orçamentos de carga (turnos de modelo e chamadas de ferramenta)

O modo autônomo não significa execução ilimitada. Vários tetos independentes se aplicam. Os padrões abaixo são as constantes distribuídas; aumente ou diminua em ax-code.json quando a carga precisar de mais espaço.

Um turno de modelo é uma requisição de modelo do laço externo. Uma chamada de ferramenta é uma invocação de ferramenta dentro de um turno de modelo. São orçamentos separados: um único turno de modelo pode emitir várias chamadas de ferramenta. Nomes legados de configuração que contêm steps continuam suportados, mas não tornam as duas unidades intercambiáveis.

Prefira o objeto de primeira classe autonomy. As chaves legadas session.* e experimental.autonomous_caps.* ainda funcionam como aliases (precedência menor).

Arquivos binários (cp de um executável, curl -o de um zip e outras escritas que não são texto) ainda contam no teto de arquivos, mas custam zero linhas. O teto de linhas mede mudança textual. Escritas de texto pelo shell conservam a estimativa ceil(size / 80), para que uma carga densa não escape do orçamento por ter poucas quebras de linha.

Caminhos não rastreados que git check-ignore informa como ignorados também custam zero linhas e ainda contam como um arquivo. Isso cobre árvores geradas, como target/, quando um verificador redireciona a saída para lá (cargo clippy > target/review/clippy.log). A isenção vale somente quando o git termina com 0. Um repositório ausente, uma falha do git e um arquivo rastreado mantêm a cobrança normal de linhas, inclusive um arquivo rastreado cujo nome coincide com um padrão de ignore.

Perfis

Defina autonomy.profile para preencher vários campos de uma vez (campos explícitos ainda prevalecem):

Inspecionar com /limits

Em uma sessão, execute /limits para imprimir a pilha de orçamento resolvida, o denominador efetivo da TUI para o agente ativo, as fontes de configuração e os avisos do doctor (por exemplo, quando agent.steps é mais apertado do que o segmento da sessão). Use /limits help para os nomes das chaves.

O que a TUI mostra: durante uma execução autônoma, o cabeçalho informa turn current/max · total current/max · cont current/max. turn é o segmento de continuação atual e usa o teto efetivo de ritmo do agente ativo — min(agent.steps, session.max_steps) quando o agente tem teto e, caso contrário, o limite por segmento. total sobrevive às autocontinuações. cont mostra ∞ quando um objetivo ativo ou o modo Super-Long eleva o teto comum de continuação.

Roteamento automático: o roteamento por palavra-chave pode mudar a sessão para um agente especialista (Debug, Security, DevOps, …). Os especialistas compartilham, por padrão, a mesma política sem limite de turnos de modelo do agente Dev, a menos que você defina agent.<name>.steps. Desative o roteamento com "routing": { "disable": true } se quiser apenas o agente Dev.

Execuções longas: use /goal ou Super-Long para trabalho de várias horas — eles elevam os tetos comuns de continuação e usam o teto cumulativo maior (padrão 20000), com a semântica de verificação e de pausa documentada em Modo de laço. /goal primeiro grava um contrato revisável (critérios de aceitação e plano de verificação) e falha de forma fechada para pausado se esse plano não puder ser produzido.

Quando um limite interrompe uma execução

Antes de uma execução comum atingir o teto cumulativo de turnos de modelo, o AX Code injeta uma instrução limitada de convergência (no máximo os 50 turnos finais, reduzida para orçamentos personalizados pequenos). Ela pede ao modelo que pare a exploração ampla, termine ou estacione com segurança o trabalho em andamento, execute verificação direcionada e informe com honestidade o trabalho inacabado. Ela não acrescenta orçamento nem contorna nenhum teto.

Quando um orçamento terminal é atingido, session.error inclui um code opcional e legível por máquina, e o evento de reprodução session.end registra o mesmo valor como stopCode. Os motivos finais grosseiros já existentes permanecem inalterados, por compatibilidade. Os códigos de limite atuais são:

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

No teto de um segmento, o AX Code continua sozinho enquanto restar orçamento de continuação configurado. Quando esse orçamento se esgota, a execução para e a mensagem diz o que aconteceu. Enviar um prompt novo, como continue, inicia uma execução nova dirigida por quem usa, com contabilidade nova; não estende de forma retroativa a execução que parou. Use /goal quando o objetivo deve permanecer explícito e retomável até a conclusão, um bloqueio ou um limite de orçamento do objetivo ou do runtime. /goal não desativa as proteções de permissão, de isolamento, de raio de impacto, de estagnação, de token, de tempo nem de turnos cumulativos de modelo.

Exemplo: elevar orçamentos para um 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 }
  }
}

Quando desligar o modo autônomo

• Aprendendo o ax-code — veja o que o agente faz em cada passo
• Operações sensíveis — revise cada mudança de arquivo antes de ela ser aplicada
• Depurando o comportamento do agente — entenda por que o agente toma certas decisões
• Código não confiável — revise as chamadas de ferramenta ao trabalhar com repositórios desconhecidos

Quando manter o modo autônomo ligado

• Tarefas rotineiras — refatoração, correções e migrações em que você confia no agente
• Pipelines de CI/CD — execução sem interface, em que a tarefa já está limitada por política
• Uso do SDK — execução programática do agente por createAgent()
• Tarefas grandes — mudanças em vários arquivos, em que parar a cada permissão levaria horas

Uso sem interface e em CI

No modo sem interface (ax-code run, ax-code serve, SDK), o modo autônomo é essencial — não há TUI para mostrar os pedidos. A aprovação automática no servidor garante que o agente rode até o fim, sem travar em pedidos sem resposta.

# 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, por padrão, uma saída concisa de ferramenta: a saída de comando é reduzida à cauda, as edições mostram um resumo do diff e as escritas de tarefa mostram uma contagem de progresso em uma linha. Os erros nunca ficam ocultos — aparecem com o mesmo teto de cauda das outras saídas. Passe --full para restaurar a saída completa da ferramenta (diffs integrais, saída de comando sem truncar e listas completas de tarefas) para auditoria.

Garantias de segurança

Mesmo com o modo autônomo ligado:

1. O sandbox ainda impõe fronteiras — escritas fora do espaço de trabalho são bloqueadas, independentemente do modo autônomo
2. A escalada de isolamento sempre pergunta — o agente não pode substituir em silêncio as restrições do sandbox
3. As regras de negação são aplicadas — regras explícitas de permissão "deny" ainda bloqueiam chamadas de ferramenta
4. As escolhas autônomas são registradas — os metadados da ferramenta de pergunta incluem um registro estruturado autonomousDecisions, e a saída da ferramenta inclui as respostas escolhidas, para que o agente possa relatá-las depois
5. Evite excesso de engenharia — a continuação autônoma lembra o agente de preferir a mudança mais simples e habitual e de evitar abstrações sem 3 ou mais casos de uso concretos
6. Instantâneos da sessão são registrados — cada chamada de ferramenta é registrada para auditoria e reprodução
7. Interromper sempre funciona — pressionar Esc (interromper) para o agente na hora