Backends da CLI

• As ferramentas do OpenClaw não são injetadas diretamente, mas backends com bundleMcp: true podem receber ferramentas do Gateway por meio de uma ponte MCP de local loopback.
• Streaming JSONL para CLIs que oferecem suporte.
• Sessões são compatíveis (para que turnos de acompanhamento permaneçam coerentes).
• Imagens podem ser repassadas se a CLI aceitar caminhos de imagem.

​

Início rápido para iniciantes

openclaw agent --agent main --message "hi" --model claude-cli/claude-sonnet-4-6

{
  agents: {
    defaults: {
      cliBackends: {
        "claude-cli": {
          command: "/opt/homebrew/bin/claude",
        },
      },
    },
  },
}

​

Usando como fallback

{
  agents: {
    defaults: {
      model: {
        primary: "anthropic/claude-opus-4-6",
        fallbacks: ["claude-cli/claude-sonnet-4-6"],
      },
      models: {
        "anthropic/claude-opus-4-6": { alias: "Opus" },
        "claude-cli/claude-sonnet-4-6": {},
      },
    },
  },
}

• Se você usa agents.defaults.models (lista de permissões), também precisa incluir ali seus modelos de backend de CLI.
• Se o provedor principal falhar (autenticação, limites de taxa, timeouts), o OpenClaw tentará o backend de CLI em seguida.

​

Visão geral da configuração

agents.defaults.cliBackends

<provider>/<model>

​

Exemplo de configuração

{
  agents: {
    defaults: {
      cliBackends: {
        "my-cli": {
          command: "my-cli",
          args: ["--json"],
          output: "json",
          input: "arg",
          modelArg: "--model",
          modelAliases: {
            "claude-opus-4-6": "opus",
            "claude-sonnet-4-6": "sonnet",
          },
          sessionArg: "--session",
          sessionMode: "existing",
          sessionIdFields: ["session_id", "conversation_id"],
          systemPromptArg: "--system",
          // For CLIs with a dedicated prompt-file flag:
          // systemPromptFileArg: "--system-file",
          // Codex-style CLIs can point at a prompt file instead:
          // systemPromptFileConfigArg: "-c",
          // systemPromptFileConfigKey: "model_instructions_file",
          systemPromptWhen: "first",
          imageArg: "--image",
          imageMode: "repeat",
          // Opt in only if this backend may reseed safe invalidated sessions
          // from bounded raw OpenClaw transcript history before compaction.
          reseedFromRawTranscriptWhenUncompacted: true,
          serialize: true,
        },
      },
    },
  },
}

​

Como funciona

1. Seleciona um backend com base no prefixo do provedor (claude-cli/...).
2. Cria um prompt de sistema usando o mesmo prompt do OpenClaw + contexto do workspace.
3. Executa a CLI com um ID de sessão (se compatível) para que o histórico permaneça consistente. O backend integrado claude-cli mantém um processo stdio do Claude ativo por sessão do OpenClaw e envia turnos de acompanhamento por stdin stream-json.
4. Analisa a saída (JSON ou texto simples) e retorna o texto final.
5. Persiste IDs de sessão por backend, para que acompanhamentos reutilizem a mesma sessão de CLI.

claude auth login
claude auth status --text
openclaw models auth login --provider anthropic --method cli --set-default

​

Sessões

• Se a CLI oferece suporte a sessões, defina sessionArg (por exemplo, --session-id) ou sessionArgs (placeholder {sessionId}) quando o ID precisar ser inserido em várias flags.
• Se a CLI usa um subcomando de retomada com flags diferentes, defina resumeArgs (substitui args ao retomar) e opcionalmente resumeOutput (para retomadas não JSON).
• sessionMode:
  • always: sempre envia um ID de sessão (novo UUID se nenhum estiver armazenado).
  • existing: só envia um ID de sessão se um já tiver sido armazenado antes.
  • none: nunca envia um ID de sessão.
• claude-cli usa por padrão liveSession: "claude-stdio", output: "jsonl", e input: "stdin" para que turnos de acompanhamento reutilizem o processo Claude ao vivo enquanto ele estiver ativo. stdio aquecido agora é o padrão, inclusive para configurações personalizadas que omitem campos de transporte. Se o Gateway reiniciar ou o processo ocioso sair, o OpenClaw retoma a partir do ID de sessão armazenado do Claude. IDs de sessão armazenados são verificados contra uma transcrição de projeto existente e legível antes da retomada, então vínculos fantasma são limpos com reason=transcript-missing em vez de iniciar silenciosamente uma nova sessão da CLI do Claude sob --resume.
• Sessões Claude ao vivo mantêm guardas limitados de saída JSONL. Os padrões permitem até 8 MiB e 20.000 linhas JSONL brutas por turno. Turnos do Claude com muitas ferramentas podem aumentá-los por backend com agents.defaults.cliBackends.claude-cli.reliability.outputLimits.maxTurnRawChars e maxTurnLines; o OpenClaw limita essas configurações a 64 MiB e 100.000 linhas.
• Sessões de CLI armazenadas são continuidade de propriedade do provedor. A redefinição diária implícita de sessão não as corta; /reset e políticas explícitas session.reset ainda cortam.
• Sessões de CLI novas normalmente replantam apenas a partir do resumo de Compaction do OpenClaw mais a cauda pós-Compaction. Para recuperar sessões curtas que são invalidadas antes da Compaction, um backend pode optar por isso com reseedFromRawTranscriptWhenUncompacted: true. O OpenClaw ainda mantém o replantio de transcrição bruta limitado e o restringe a invalidações seguras, como transcrições de CLI ausentes, mudanças de prompt de sistema/MCP, ou nova tentativa por sessão expirada; mudanças de perfil de autenticação ou época de credencial nunca replantam histórico de transcrição bruta.

• serialize: true mantém execuções da mesma faixa ordenadas.
• A maioria das CLIs serializa em uma faixa de provedor.
• O OpenClaw descarta a reutilização de sessão de CLI armazenada quando a identidade de autenticação selecionada muda, incluindo mudança de ID de perfil de autenticação, chave de API estática, token estático, ou identidade de conta OAuth quando a CLI expõe uma. A rotação de tokens OAuth de acesso e atualização não corta a sessão de CLI armazenada. Se uma CLI não expuser um ID de conta OAuth estável, o OpenClaw deixa essa CLI impor permissões de retomada.

​

Prelúdio de fallback de sessões claude-cli

• O prelúdio prefere o resumo /compact mais recente ou o marcador compact_boundary, depois anexa os turnos pós-limite mais recentes até um orçamento de caracteres. Turnos pré-limite são descartados porque o resumo já os representa.
• Blocos de ferramenta são consolidados em dicas compactas (tool call: name) e (tool result: …) para manter o orçamento de prompt honesto. O resumo é rotulado como (truncated) se exceder o limite.
• Fallbacks claude-cli para claude-cli do mesmo provedor dependem do próprio --resume do Claude e pulam o prelúdio.
• A semente reutiliza a validação existente de caminho de arquivo de sessão do Claude, para que caminhos arbitrários não possam ser lidos.

​

Imagens (repasse)

imageArg: "--image",
imageMode: "repeat"

​

Entradas / saídas

• output: "json" (padrão) tenta analisar JSON e extrair texto + ID de sessão.
• Para saída JSON da CLI Gemini, o OpenClaw lê o texto de resposta de response e o uso de stats quando usage está ausente ou vazio. O padrão integrado da CLI Gemini usa stream-json, mas sobrescritas antigas --output-format json ainda usam o analisador JSON.
• output: "jsonl" analisa streams JSONL e extrai a mensagem final do agente mais identificadores de sessão quando presentes.
• output: "text" trata stdout como a resposta final.

• input: "arg" (padrão) passa o prompt como o último argumento da CLI.
• input: "stdin" envia o prompt via stdin.
• Se o prompt for muito longo e maxPromptArgChars estiver definido, stdin será usado.

​

Padrões (pertencentes ao Plugin)

• command: "claude"
• args: ["-p","--output-format","stream-json","--include-partial-messages","--verbose", ...]
• output: "jsonl"
• input: "stdin"
• modelArg: "--model"
• sessionMode: "always"

• command: "gemini"
• args: ["--skip-trust", "--approval-mode", "auto_edit", "--output-format", "stream-json", "--prompt", "{prompt}"]
• resumeArgs: ["--skip-trust", "--approval-mode", "auto_edit", "--resume", "{sessionId}", "--output-format", "stream-json", "--prompt", "{prompt}"]
• output: "jsonl"
• resumeOutput: "jsonl"
• jsonlDialect: "gemini-stream-json"
• imageArg: "@"
• imagePathScope: "workspace"
• modelArg: "--model"
• sessionMode: "existing"
• sessionIdFields: ["session_id", "sessionId"]

• O parser padrão de stream-json lê eventos message do assistente, eventos de ferramenta, uso final de result e eventos fatais de erro do Gemini.
• Se você substituir os argumentos do Gemini para --output-format json, o OpenClaw normaliza esse backend de volta para output: "json" e lê o texto da resposta no campo response do JSON.
• O uso recorre a stats quando usage está ausente ou vazio.
• stats.cached é normalizado para cacheRead do OpenClaw.
• Se stats.input estiver ausente, o OpenClaw deriva os tokens de entrada de stats.input_tokens - stats.cached.

​

Padrões pertencentes ao Plugin

• Plugins os registram com api.registerCliBackend(...).
• O id do backend se torna o prefixo do provedor nas refs de modelo.
• A configuração do usuário em agents.defaults.cliBackends.<id> ainda substitui o padrão do Plugin.
• A limpeza de configuração específica do backend permanece pertencente ao Plugin por meio do hook opcional normalizeConfig.

api.registerTextTransforms({
  input: [
    { from: /red basket/g, to: "blue basket" },
    { from: /paper ticket/g, to: "digital ticket" },
    { from: /left shelf/g, to: "right shelf" },
  ],
  output: [
    { from: /blue basket/g, to: "red basket" },
    { from: /digital ticket/g, to: "paper ticket" },
    { from: /right shelf/g, to: "left shelf" },
  ],
});

​

Propriedade da Compaction nativa

api.registerCliBackend({ id: "my-cli", ownsNativeCompaction: true /* ... */ });

​

Sobreposições MCP incluídas

• claude-cli: arquivo de configuração MCP estrito gerado
• google-gemini-cli: arquivo de configurações do sistema Gemini gerado

• inicia um servidor MCP HTTP de local loopback que expõe ferramentas do Gateway ao processo da CLI
• autentica a ponte com um token por sessão (OPENCLAW_MCP_TOKEN)
• restringe o acesso às ferramentas ao contexto da sessão, conta e canal atuais
• carrega servidores MCP incluídos habilitados para o workspace atual
• mescla-os com qualquer formato de configuração/definições MCP existente do backend
• reescreve a configuração de inicialização usando o modo de integração pertencente ao backend da extensão proprietária

​

Limite do histórico de reseed

• O limite governa apenas o bloco de histórico anterior do prompt de reseed. Limites de saída de sessão ativa são ajustados separadamente em reliability.outputLimits (veja Sessões).

​

Limitações

• Sem chamadas diretas de ferramenta do OpenClaw. O OpenClaw não injeta chamadas de ferramenta no protocolo do backend CLI. Backends só veem ferramentas do Gateway quando optam por bundleMcp: true.
• O streaming é específico do backend. Alguns backends transmitem JSONL; outros mantêm em buffer até a saída.
• Saídas estruturadas dependem do formato JSON da CLI.

​

Solução de problemas

• CLI não encontrada: defina command como um caminho completo.
• Nome de modelo incorreto: use modelAliases para mapear provider/model → modelo da CLI.
• Sem continuidade de sessão: garanta que sessionArg esteja definido e que sessionMode não seja none.
• Imagens ignoradas: defina imageArg (e verifique se a CLI aceita caminhos de arquivo).

​

Relacionado

• Runbook do Gateway
• Modelos locais