Backends da CLI

Documentation Index

Fetch the complete documentation index at: https://docs.openclaw.ai/llms.txt

Use this file to discover all available pages before exploring further.

• 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 loopback.
• Streaming JSONL para CLIs que oferecem suporte a isso.
• 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 codex-cli/gpt-5.5

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

​

Usando como alternativa

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

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

​

Visão geral da configuração

agents.defaults.cliBackends

<provider>/<model>

​

Exemplo de configuração

{
  agents: {
    defaults: {
      cliBackends: {
        "codex-cli": {
          command: "/opt/homebrew/bin/codex",
        },
        "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 (codex-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 claude-cli incluído mantém um processo Claude stdio 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 da 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 precisa 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 ativo 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 Claude armazenado. IDs de sessão armazenados são verificados contra uma transcrição de projeto legível existente antes de retomar, então vínculos fantasmas são limpos com reason=transcript-missing em vez de iniciar silenciosamente uma nova sessão do Claude CLI sob --resume.
• Sessões live do Claude mantêm guardas de saída JSONL limitados. 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 CLI armazenadas são continuidade pertencente ao 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 CLI novas normalmente resemeiam 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 a resemeadura da transcrição bruta limitada e restringe a invalidações seguras, como transcrições 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 credenciais nunca resemeiam o histórico bruto de transcrição.

• serialize: true mantém execuções da mesma lane ordenadas.
• A maioria das CLIs serializa em uma lane de provedor.
• O OpenClaw descarta a reutilização de sessão CLI armazenada quando a identidade de autenticação selecionada muda, incluindo uma alteração no ID do 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 refresh não corta a sessão CLI armazenada. Se uma CLI não expõe um ID de conta OAuth estável, o OpenClaw deixa essa CLI impor permissões de retomada.

​

Prelúdio de fallback a partir 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 ferramentas 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 estourar.
• 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 de caminho de arquivo de sessão Claude existente, então caminhos arbitrários não podem 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 do Gemini CLI, o OpenClaw lê o texto da resposta em response e o uso em stats quando usage está ausente ou vazio.
• output: "jsonl" analisa streams JSONL (por exemplo, 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 arg 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: "codex"
• args: ["exec","--json","--color","never","--sandbox","workspace-write","--skip-git-repo-check"]
• resumeArgs: ["exec","resume","{sessionId}","-c","sandbox_mode=\"workspace-write\"","--skip-git-repo-check"]
• output: "jsonl"
• resumeOutput: "text"
• modelArg: "--model"
• imageArg: "--image"
• sessionMode: "existing"

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

• O texto da resposta é lido do campo JSON response.
• 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 referências de modelo.
• A configuração do usuário em agents.defaults.cliBackends.<id> ainda sobrescreve o padrão do Plugin.
• A limpeza de configuração específica do backend continua pertencendo 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" },
  ],
});

​

Sobreposições de MCP em pacote

• claude-cli: arquivo de configuração MCP estrito gerado
• codex-cli: sobrescritas de configuração inline para mcp_servers; o servidor de loopback do OpenClaw gerado é marcado com o modo de aprovação de ferramenta por servidor do Codex para que chamadas MCP não possam travar em prompts de aprovação local
• google-gemini-cli: arquivo de configurações de sistema Gemini gerado

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

​

Limitações

• Sem chamadas diretas de ferramenta do OpenClaw. O OpenClaw não injeta chamadas de ferramenta no protocolo de backend de CLI. Backends só veem ferramentas do Gateway quando aderem a bundleMcp: true.
• Streaming é específico do backend. Alguns backends transmitem JSONL; outros armazenam em buffer até a saída.
• Saídas estruturadas dependem do formato JSON da CLI.
• Sessões da CLI do Codex são retomadas por saída de texto (sem JSONL), que é menos estruturada 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: certifique-se de que sessionArg esteja definido e que sessionMode não seja none (a CLI do Codex atualmente não consegue retomar com saída JSON).
• Imagens ignoradas: defina imageArg (e verifique se a CLI aceita caminhos de arquivo).

​

Relacionado

• Runbook do Gateway
• Modelos locais