Backends de CLI do OpenClaw

Quando um provedor de API está fora do ar, com limite de taxa atingido ou se comportando mal, o OpenClaw pode rodar uma CLI de IA local como fallback só de texto. A documentação é deliberada quanto ao formato: as ferramentas não são injetadas diretamente, embora um backend possa receber ferramentas do Gateway por uma ponte MCP em loopback, o streaming é em JSONL quando a CLI oferece suporte, as sessões são suportadas para que as mensagens seguintes continuem coerentes, e as imagens passam quando a CLI aceita caminhos. É uma rede de segurança, não um caminho principal, e não é ACP. Aqui estão o início rápido, a ligação do fallback, a mecânica de um turno, as particularidades da CLI do Claude, as sessões, a ponte MCP, a compactação e os limites.

Início rápido e fallback

• O plugin Anthropic integrado registra um backend da CLI do Claude que funciona sem nenhuma configuração além de ter o Claude Code instalado e com login feito; uma execução de agente com uma única mensagem e uma referência de modelo da CLI do Claude comprova isso, e o serviço do Gateway precisa ter a CLI no caminho de busca dele, com um plugin de backend para um executável fora do padrão.
• Para usá-lo só quando os modelos principais falharem, adicione um modelo da CLI do Claude à lista de fallback; fallbacks configurados continuam elegíveis quando o principal falha por autenticação, limites de taxa ou tempo limite, mesmo que não estejam na política de modelos permitidos, que só importa para a seleção direta.
• Para rotear um modelo canônico da Anthropic pela CLI, defina nesse modelo o id do motor do agente; as credenciais ficam nos perfis de autenticação ou na configuração do plugin, e o comando, os argumentos, o ambiente, o parsing, as sessões, as imagens e a mecânica do watchdog são código do plugin.
• Um turno seleciona o backend pelo prefixo do provedor, monta o prompt do sistema a partir do mesmo prompt do OpenClaw e do contexto do espaço de trabalho, executa a CLI com um id de sessão quando há suporte, faz o parsing de JSON ou texto e persiste os ids de sessão por backend para que as mensagens seguintes reutilizem a sessão.

Use-o como rede de segurança para respostas de texto que “sempre funcionam”, não como caminho principal.

Particularidades da CLI do Claude

O backend integrado conversa com o executável do Claude Code instalado pelo protocolo stdio estruturado dele, mantém um subprocesso aquecido entre turnos compatíveis, iniciando um novo quando o modelo, o prompt do sistema ou a política de ferramentas muda, e retoma a partir dos ids de sessão armazenados depois de uma reinicialização; o Claude Code é dono do próprio login e da própria assinatura, e o OpenClaw nunca lê, persiste, renova nem repassa os tokens nativos. O contexto dos hooks de montagem do prompt chega ao Claude como um anexo de hook nativo, as notas de sessão salvas são reproduzidas dentro de um orçamento ponderado limitado, o resolvedor nativo de skills é usado por meio de um diretório de plugin temporário quando uma skill tem um caminho materializado, e as instruções de Git do Claude Code são desativadas para que as edições no espaço de trabalho não invalidem o histórico em cache dele. O Claude Code inicia no modo de permissão padrão enquanto as respostas de permissão e o hook pré-ferramenta do OpenClaw mantêm as ferramentas nativas sob controle do host, projetando os nomes das ferramentas nativas e os argumentos de arquivo nos seus equivalentes do OpenClaw antes da política de exec e da aprovação; quando a configuração ask do exec pede confirmação, as solicitações de ferramentas nativas são repassadas ao canal da sessão com allow once, allow always para a mesma sessão aquecida, e deny, em que um tempo limite esgotado, uma rota inalcançável ou um turno encerrado resultam todos em negação, e allow always nunca se aplica ao Bash. Os níveis de raciocínio são mapeados para a flag de esforço do Claude Code e, para modelos com orçamento fixo, para um valor de max-thinking-tokens, e tanto o login nativo quanto um token de assinatura colado funcionam.

Bash nativo, sessões, a ponte

• Com a configuração ask em on-miss, os comandos Bash nativos são verificados contra a lista de permissões de exec do agente usando o avaliador de shell do próprio OpenClaw: uma chamada roda sem pedir confirmação apenas quando cada segmento resolve para um binário na lista de permissões e pode ser totalmente vinculado; pipelines, substituições, subshells e redirecionamentos são negados antes de qualquer pedido de confirmação; e essa é uma política no nível dos argumentos sobre o comando que o Claude Code vai rodar, não uma execução em sandbox, já que o Claude Code é dono do diretório de trabalho, do path, do ambiente e do sandboxing.
• As sessões de CLI armazenadas são uma continuidade de propriedade do provedor, verificada contra uma transcrição legível antes de retomar; sessões novas podem recuperar o histórico do OpenClaw a partir do banco de dados de sessões quando o limite de conta corresponde à credencial selecionada, e uma impressão digital privada da conta com cobertura contígua da transcrição decide a elegibilidade, de modo que trocar de conta torna o histórico misto inelegível e uma identidade de autenticação alterada descarta a reutilização da sessão. Uma tentativa malsucedida da CLI do Claude pode fazer failover para um modelo que não é de CLI, alimentado com um prelúdio extraído da transcrição local do Claude Code: o resumo de compactação mais recente dela mais os turnos recentes.
• Um backend que adere ao overlay bundle-MCP recebe um servidor MCP HTTP em loopback que expõe ferramentas do Gateway ao processo da CLI sob um token por execução, vinculado à sessão, à conta e ao canal selecionados pelo Gateway; as políticas de permissão e de bloqueio também restringem servidores MCP nativos, execuções restritas, como jobs de cron, desativam totalmente as ferramentas nativas e as personalizações do Claude e expõem apenas as ferramentas do OpenClaw permitidas, e runtimes de ponte com escopo de sessão são recolhidos após dez minutos ociosos.

OpenClaw e Claude Code é a mesma dupla vista do outro lado, e o failover de modelos do OpenClaw, o mecanismo que decide quando o fallback roda.

Tempos limite, compactação, limitações

Dois limites independentes: o orçamento do turno do agente, quarenta e oito horas por padrão e zero para ilimitado, e o watchdog de ausência de saída da CLI, controlado pelo backend, ativo mesmo quando o orçamento do turno é ilimitado; o trabalho em segundo plano iniciado dentro de uma CLI morre com o subprocesso quando o turno termina, então trabalho longo e durável cabe a um subagente destacado. O backend da CLI do Claude declara que é dono da compactação nativa, então o OpenClaw delega ao Claude Code e repassa o orçamento de contexto pela janela de autocompactação do Claude Code, enquanto um comando compact explícito retoma a sessão vinculada e envia o comando nativo; o backend da CLI do Gemini também é dono da própria compactação, sem comando manual. A Anthropic é dona do backend do Claude, e o Google, do backend do Gemini, cujos pré-requisitos são a CLI no caminho de busca e um perfil de chave do Google AI Studio; não há backend de CLI do Codex integrado, já que o Codex roda pelo harness de app-server. As limitações: nenhuma chamada de ferramenta injetada no protocolo da CLI sem a ponte, streaming que varia conforme o backend e saídas estruturadas que dependem do JSON da própria CLI. Aprovações de exec do OpenClaw cobre a lista de permissões contra a qual o Bash nativo é verificado, e OpenClaw e Gemini, o provedor por trás do segundo backend integrado.

Na Diali

Na Diali, não há CLI no host para usar como fallback: a rota do modelo é a chave de API no Vault ou os créditos gerenciados, e o failover acontece entre provedores, e não para um binário local. OpenClaw hospedado na Diali é o assistente, e o guia de modelos e provedores do OpenClaw cobre os provedores que essa rota pode usar.

• Um fallback, não um caminho principal.
• Subprocesso aquecido, login nativo, ferramentas só pela ponte.
• O OpenClaw aplica lista de permissões ao Bash nativo, mas nunca o coloca em sandbox.