​

Backends de CLI (runtime de fallback)

• As ferramentas do OpenClaw não são injetadas diretamente, mas backends com bundleMcp: true (o padrão do Claude CLI) podem receber ferramentas do gateway por uma bridge MCP local loopback.
• Streaming JSONL (o Claude CLI usa --output-format stream-json com --include-partial-messages; os prompts são enviados via stdin).
• 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 --message "hi" --model claude-cli/claude-sonnet-4-6

openclaw agent --message "hi" --model codex-cli/gpt-5.4

{
  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", "claude-cli/claude-opus-4-6"],
      },
      models: {
        "anthropic/claude-opus-4-6": { alias: "Opus" },
        "claude-cli/claude-sonnet-4-6": {},
        "claude-cli/claude-opus-4-6": {},
      },
    },
  },
}

• Se você usar agents.defaults.models (allowlist), deverá incluir claude-cli/....
• Se o provedor principal falhar (autenticação, limites de taxa, timeouts), o OpenClaw tentará o backend de CLI em seguida.
• O backend incluído do Claude CLI ainda aceita aliases mais curtos como claude-cli/opus, claude-cli/opus-4.6 ou claude-cli/sonnet, mas a documentação e os exemplos de configuração usam as referências canônicas claude-cli/claude-*.

​

Visão geral da configuração

agents.defaults.cliBackends

<provider>/<model>

​

Exemplo de configuração

{
  agents: {
    defaults: {
      cliBackends: {
        "claude-cli": {
          command: "/opt/homebrew/bin/claude",
        },
        "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",
          systemPromptWhen: "first",
          imageArg: "--image",
          imageMode: "repeat",
          serialize: true,
        },
      },
    },
  },
}

​

Como funciona

1. Seleciona um backend com base no prefixo do provedor (claude-cli/...).
2. Constrói 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.
4. Analisa a saída (JSON ou texto simples) e retorna o texto final.
5. Persiste ids de sessão por backend, para que turnos de acompanhamento reutilizem a mesma sessão da CLI.

​

Sessões

• Se a CLI oferecer 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 usar um subcomando de retomada com flags diferentes, defina resumeArgs (substitui args ao retomar) e opcionalmente resumeOutput (para retomadas sem 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.

• serialize: true mantém execuções da mesma faixa em ordem.
• A maioria das CLIs serializa em uma única faixa de provedor.
• claude-cli é mais restrito: execuções retomadas serializam por id de sessão do Claude, e execuções novas serializam por caminho do workspace. Workspaces independentes podem ser executados em paralelo.
• O OpenClaw descarta a reutilização de sessão de CLI armazenada quando o estado de autenticação do backend muda, incluindo novo login, rotação de token ou alteração de credencial do perfil de autenticação.

​

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 do Gemini CLI, o OpenClaw lê o texto da resposta de response e o uso de stats quando usage está ausente ou vazio.
• output: "jsonl" analisa streams JSONL (por exemplo Claude CLI stream-json e Codex CLI --json) 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 (de propriedade do plugin)

• command: "claude"
• args: ["-p", "--output-format", "stream-json", "--include-partial-messages", "--verbose", "--permission-mode", "bypassPermissions"]
• resumeArgs: ["-p", "--output-format", "stream-json", "--include-partial-messages", "--verbose", "--permission-mode", "bypassPermissions", "--resume", "{sessionId}"]
• output: "jsonl"
• input: "stdin"
• modelArg: "--model"
• systemPromptArg: "--append-system-prompt"
• sessionArg: "--session-id"
• systemPromptWhen: "first"
• sessionMode: "always"

• command: "codex"
• args: ["exec","--json","--color","never","--sandbox","workspace-write","--skip-git-repo-check"]
• resumeArgs: ["exec","resume","{sessionId}","--color","never","--sandbox","workspace-write","--skip-git-repo-check"]
• output: "jsonl"
• resumeOutput: "text"
• modelArg: "--model"
• imageArg: "--image"
• sessionMode: "existing"

• command: "gemini"
• args: ["--prompt", "--output-format", "json"]
• resumeArgs: ["--resume", "{sessionId}", "--prompt", "--output-format", "json"]
• modelArg: "--model"
• sessionMode: "existing"
• sessionIdFields: ["session_id", "sessionId"]

• O texto da resposta é lido do campo JSON response.
• O uso usa stats como fallback quando usage está ausente ou vazio.
• stats.cached é normalizado para cacheRead do OpenClaw.
• Se stats.input estiver ausente, o OpenClaw deriva tokens de entrada de stats.input_tokens - stats.cached.

​

Padrões de propriedade do plugin

• Os plugins os registram com api.registerCliBackend(...).
• O id do backend se torna o prefixo do provedor nas referências 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 de propriedade do plugin por meio do hook opcional normalizeConfig.

​

Overlays MCP incluídos

• claude-cli: bundleMcp: true (padrão)
• codex-cli: sem overlay MCP incluído
• google-gemini-cli: sem overlay MCP incluído

• inicia um servidor MCP HTTP local loopback que expõe ferramentas do gateway ao processo da CLI
• autentica a bridge com um token por sessão (OPENCLAW_MCP_TOKEN)
• delimita o acesso às ferramentas à sessão, conta e contexto de canal atuais
• carrega servidores MCP incluídos ativados para o workspace atual
• os mescla com qualquer --mcp-config já existente no backend
• reescreve os argumentos da CLI para passar --strict-mcp-config --mcp-config <generated-file>

​

Limitações

• Sem chamadas diretas de ferramenta do OpenClaw. O OpenClaw não injeta chamadas de ferramenta no protocolo do backend de CLI. No entanto, backends com bundleMcp: true (o padrão do Claude CLI) recebem ferramentas do gateway por uma bridge MCP local loopback, de modo que o Claude CLI pode invocar ferramentas do OpenClaw por seu suporte MCP nativo.
• O streaming é específico do backend. O Claude CLI usa streaming JSONL (stream-json com --include-partial-messages); outros backends de CLI podem continuar em buffer até a saída.
• Saídas estruturadas dependem do formato JSON da CLI.
• Sessões do Codex CLI retomam via saída de texto (sem JSONL), o que é menos estruturado do que a execução inicial com --json. As sessões do OpenClaw ainda funcionam normalmente.

​

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: verifique se sessionArg está definido e se sessionMode não é none (o Codex CLI atualmente não consegue retomar com saída JSON).
• Imagens ignoradas: defina imageArg (e verifique se a CLI oferece suporte a caminhos de arquivo).