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 de operações na nuvem

Status: Ativo Escopo: estado atual Última revisão: 2026-09-04 Responsável: ax-code runtime

O modo de operações na nuvem é uma postura pronta para administrar infraestrutura — provedores de nuvem (AWS, GCP, Cloudflare, OVHcloud, DigitalOcean, RunPod) e equipamentos de rede (VyOS, Juniper Junos) — em que um erro afeta sistemas ao vivo e um rollback do git não restaura o estado. Ele vem como o agente embutido cloudops: um prompt de sistema mais uma postura de permissão que você ativa com uma seleção, em vez de escrever regras à mão.

O que o modo oferece

Agente que começa somente pela leitura. O agente cloudops inicia cada tarefa com inventário e simulações, e o prompt dele proíbe mutação antes de existirem um plano, um diff e receitas de reversão.
Shell que pergunta antes de executar. bash fica em ask, então cada comando de shell é confirmado. Verbos de mutação de nuvem e de rede (família de exclusão aws/gcloud/az/doctl, kubectl delete/apply --prune, terraform apply sem um arquivo de plano, commit remoto por ssh sem commit-confirm, mutações curl contra APIs do plano de controle) são classificados como bash_destructive e têm uma barreira interativa separada, que não se pode contornar.
Ferramentas de operação de primeira classe. ops_plan, ops_diff, ops_verify e ops_journal já vêm permitidas; ops_approve e ops_apply permanecem nos caminhos interativos (abaixo).

O fluxo: planejar → comparar → aprovar → aplicar → verificar → registrar

ops_plan — abre um OperationPlan: alvo (provedor, conta, região ou equipamento), intenção, comando exato de aplicação e contexto do comando, e passos com efeito, reversibilidade (reversible | hard | irreversible) e raio de impacto (low | med | high). Produz um hash canônico do plano.
ops_diff — produz e revisa o artefato verificável por máquina (terraform plan -out, show | compare, saída de simulação da CLI) e o anexa. Sem diff, sem aprovação.
ops_approve — a pessoa aprova o plano fixado pelo hash. Esta barreira é só interativa: nenhuma regra curinga e nenhum modo autônomo podem pré-aprová-la, e não se oferece uma concessão durável de “sempre permitir”.
ops_apply — executa a mutação do plano aprovado com o token de aprovação. Este é o único caminho sancionado de mutação; o token é resgatado antes de qualquer coisa executar.
ops_verify — executa as asserções declarativas e somente leitura do plano e registra a evidência de aprovação ou falha.
ops_journal — consulta o diário de operações, somente de acréscimo e limitado ao projeto, por projeto, plano ou status.

Ativar o modo

Na TUI, escolha Cloud Ops no seletor de agente (ou mencione cloudops com @ para uma tarefa delimitada). Para torná-lo o padrão de um projeto, acrescente a ax-code.json:

{
  "default_agent": "cloudops",
  "isolation": {
    "mode": "workspace-write",
    "network": true
  }
}

workspace-write restringe alterações de arquivo ao workspace; network: true mantém webfetch, websearch e as CLIs de provedor alcançáveis (a rede fica desligada nos modos com sandbox — veja Modo sandbox). Os dois são ajustes de isolamento da sessão, independentes do agente, então se configuram aqui, e não dentro do preset do agente.

Você pode apertar ou estender a postura por projeto em agent.cloudops.permission, por exemplo negando ferramentas específicas. Configuração enviada pelo repositório só pode acrescentar regras de negação; afrouxar um ask para allow precisa vir da configuração confiável do usuário ou da gerenciada, nunca do repositório. Para remover o agente por completo, defina "agent": { "cloudops": { "disable": true } }.

Um exemplo prático

Aplicar uma mudança de firewall num roteador VyOS:

Você pede: “permitir tcp/8443 a partir de 10.0.0.0/8 no firewall de borda”.
O agente carrega a skill vyos-firewall, captura a configuração atual por SSH (show configuration commands salvo num arquivo com data) e abre um plano com ops_plan: um passo, efeito add firewall rule, reversibilidade reversible (apagar a regra restaura o estado), raio de impacto med.
Ele prepara a mudança no modo de configuração e anexa o diff do equipamento com ops_diff.
ops_approve mostra o hash do plano e a mudança exata preparada; você aprova, e um token de 10 minutos é emitido.
ops_apply resgata o token e executa a sequência commit-confirm; o temporizador automático de reversão permanece armado até a verificação.
ops_verify confere a alcançabilidade e se a regra corresponde ao tráfego pretendido; tanto a aprovação quanto o resultado entram no diário, então uma consulta posterior ops_journal reconstrói a mudança inteira.

Se a aplicação tivesse falhado no passo 5, o token já teria sido consumido — o passo 4 teria de executar de novo antes de qualquer nova tentativa.

Semântica do token de aprovação

Uso único — resgatado de forma atômica no início de ops_apply; um token consumido, desconhecido ou expirado falha sem nada executado.
Limitado por TTL — padrão de 10 minutos, máximo de 60. A expiração é conferida de forma preguiçosa no momento do consumo; não há um varredor em segundo plano.
Vinculado ao plano — o token é emitido contra o hash sha256 canônico do plano, que inclui o comando exato de aplicação, o comando opcional de instantâneo e o diretório de trabalho. Desvio de argumentos e tokens apresentados para outro plano são rejeitados antes do consumo, o que impede repetição, confusão entre planos e substituição de comando.
Revelado uma vez — o token bruto aparece exatamente uma vez no resultado de ops_approve e nunca é persistido (só o sha256 dele é armazenado).
Sem devolução — uma aplicação que falha ou estoura o tempo não devolve o token. Tentar de novo exige nova aprovação por ops_approve.

Modelo de segurança

bash_destructive continua sendo a barreira para mutações avulsas. O fluxo de operações cobre mudança planejada; comandos destrutivos isolados ainda passam pelo classificador destrutivo e pela barreira interativa, e nenhuma regra de permissão pode aprová-los sozinha.
ops_approve é só interativo, como isolation_escalation e bash_destructive: sempre pergunta, mesmo sob conjuntos de regras que permitem tudo e no modo autônomo headless.
O diário é somente de acréscimo do ponto de vista do agente e limitado ao projeto; ele sobrevive às sessões e não é apagado em cascata quando uma sessão é excluída.
Pacotes de skill carregam runbooks do provedor. cloud-ops-aws, cloud-ops-gcp, cloud-ops-cloudflare, cloud-ops-digitalocean, cloud-ops-runpod, vyos-firewall e junos-firewall guardam as listas de verificação que começam pela leitura, os passos de planejar antes de mutar e os padrões de reversão; o agente carrega o pacote correspondente antes de operar uma superfície. OVHcloud e outros provedores são cobertos por servidores MCP configurados e pela documentação deles, não por cadeias improvisadas de CLI.
Credenciais nunca chegam ao registro. Atribuições de credencial no próprio texto de entradas bash persistidas são redigidas antes de chegar ao log de eventos.

Modo estrito

Por padrão, um comando bash classificado como destrutivo (a família bash_destructive: verbos de mutação de nuvem e de rede, rm -rf, git push --force e o resto da lista do classificador) recebe uma pergunta interativa que não se pode contornar — o usuário pode aprovar o comando avulso e ele executa. O modo estrito remove essa opção.

Com o modo estrito ligado, um comando bash classificado como destrutivo é negado de imediato, antes de qualquer pergunta. A mensagem de negação lista os comandos classificados com os motivos e encaminha o modelo ao fluxo sancionado: ops_plan → ops_diff → ops_approve (emite um token de aprovação de uso único) → ops_apply. Mutações destrutivas avulsas de shell deixam de ser possíveis; toda mutação precisa ser planejada, comparada, aprovada e aplicada pelo caminho apoiado no diário.

Ative-o na configuração confiável (ax-code.json no diretório de configuração do usuário, na configuração gerenciada, ou numa configuração de projeto que o usuário tenha confiado de forma explícita):

{
  "ops": {
    "strict": true
  }
}

Notas:

Interação com a pergunta: o modo estrito substitui a pergunta bash_destructive por uma negação firme. Com a marca desligada (o padrão), o comportamento é exatamente o descrito acima — a barreira interativa permanece.
Escopo: a marca é configuração global, não por agente — vale para toda chamada bash da sessão, inclusive subagentes. O agente cloudops não pode ligá-la sozinho; agentes carregam permissões e prompts, não configuração.
Escopo de confiança: configuração de projeto não confiável, enviada pelo repositório, não pode ligar o modo estrito; opte por máquina (AX_CODE_TRUST_PROJECT_CONFIG=1) ou defina-o na configuração confiável do usuário ou gerenciada.
ops_apply não é afetado: o caminho sancionado de mutação tem a própria barreira de token vinculada ao plano, dentro da ferramenta, e nunca consulta esta marca.

Fonte da verdade

packages/ax-code/src/agent/agent.ts — a definição do agente cloudops e a mescla de permissões
packages/ax-code/src/agent/prompt/cloudops.txt — o prompt de sistema do agente
packages/ax-code/src/tool/ops_*.ts — as seis ferramentas de operação e as descrições delas
packages/ax-code/src/permission/index.ts — INTERACTIVE_ONLY (ops_approve, bash_destructive, isolation_escalation)
Modo sandbox — modos de isolamento, controles de rede e precedência