Backends CLI

OpenClaw puede ejecutar **CLIs de IA locales** como un **fallback de solo texto** cuando los proveedores de API están caídos, con límite de tasa o comportándose mal temporalmente. Esto es intencionalmente conservador:

Está diseñado como una **red de seguridad** más que un camino principal. Úsalo cuando quieras respuestas de texto "siempre funcionan" sin depender de APIs externas.

• **Las herramientas están deshabilitadas** (sin llamadas de herramienta).
• **Texto entra → texto sale** (confiable).
• **Las sesiones son soportadas** (así los turnos de seguimiento se mantienen coherentes).
• **Las imágenes pueden pasarse** si el CLI acepta rutas de imagen.

Está diseñado como una **red de seguridad** más que un camino principal. Úsalo cuando quieras respuestas de texto "siempre funcionan" sin depender de APIs externas.

Úsalo cuando quieras respuestas de texto "siempre funcionan" sin depender de APIs externas.

Puedes usar Claude Code CLI sin ninguna configuración (OpenClaw incluye un predeterminado integrado):

openclaw agent --message "hi" --model claude-cli/opus-4.5

Codex CLI también funciona out of the box:

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

Si tu gateway corre bajo launchd/systemd y el PATH es mínimo, agrega solo la ruta del comando:

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

Eso es todo. Sin claves, sin configuración de auth extra necesaria más allá del CLI mismo.

Agrega un backend CLI a tu lista de fallback para que solo corra cuando los modelos primarios fallan:

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

Notas:

• Si usas agents.defaults.models (lista permitida), debes incluir claude-cli/....
• Si el proveedor primario falla (auth, límites de tasa, timeouts), OpenClaw probará el backend CLI después.

Todos los backends CLI viven bajo:

agents.defaults.cliBackends

ReferenceGatewayCliBackendsPage.steps.overview.p2

ReferenceGatewayCliBackendsPage.steps.overview.p3

<provider>/<model>

1. Selects a backend based on the provider prefix (claude-cli/...).
2. Builds a system prompt using the same OpenClaw prompt + workspace context.
3. Executes the CLI with a session id (if supported) so history stays consistent.
4. Parses output (JSON or plain text) and returns the final text.
5. Persists session ids per backend, so follow-ups reuse the same CLI session.

• Si el CLI soporta sesiones, configura sessionArg (ej. --session-id) o sessionArgs (placeholder {{sessionId}}) cuando el ID necesita insertarse en múltiples flags.
• Si el CLI usa un subcomando resume con diferentes flags, configura resumeArgs (reemplaza args al resumir) y opcionalmente resumeOutput (para resumes no-JSON).

sessionMode：

• always: always send a session id (new UUID if none stored).
• existing: only send a session id if one was stored before.
• none: never send a session id.

Si tu CLI acepta rutas de imagen, establece imageArg:

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

OpenClaw escribirá imágenes base64 a archivos temporales. Si imageArg está establecido, esas rutas se pasan como args CLI. Si falta imageArg, OpenClaw adjunta las rutas de archivo al prompt (inyección de path), que es suficiente para CLIs que auto-cargan archivos locales desde paths planos (comportamiento de Claude Code CLI).

Si falta imageArg, OpenClaw adjunta las rutas de archivo al prompt (inyección de path), que es suficiente para CLIs que auto-cargan archivos locales desde paths planos (comportamiento de Claude Code CLI).

Modos de salida:

• output: "json" (predeterminado): parsear JSON y extraer texto + id de sesión.
• output: "jsonl": parsear streams JSONL (Codex CLI --json) y extraer el último mensaje de agente más thread_id cuando está presente.
• output: "text": tratar stdout como la respuesta final.

Modos de entrada:

• input: "arg" (predeterminado) pasa el prompt como el último arg CLI.
• input: "stdin" envía el prompt vía stdin.
• Si el prompt es largo y maxPromptArgChars está establecido, se usa stdin.

OpenClaw incluye predeterminados integrados así que usualmente solo necesitas anular lo necesario.

Predeterminados integrados para claude-cli:

• command: "claude"
• args: ["-p", "--output-format", "json", "--dangerously-skip-permissions"]
• ReferenceGatewayCliBackendsPage.steps.defaults.claude.resumeArgs
• modelArg: "--model"
• systemPromptArg: "--append-system-prompt"
• sessionArg: "--session-id"
• systemPromptWhen: "first"
• sessionMode: "always"

Predeterminados integrados para codex-cli:

• command: "codex"
• args: ["exec", "--json", "--color", "never", "--sandbox", "read-only", "--skip-git-repo-check"]
• ReferenceGatewayCliBackendsPage.steps.defaults.codex.resumeArgs
• output: "jsonl"
• resumeOutput: "text"
• modelArg: "--model"
• imageArg: "--image"
• sessionMode: "existing"

Solo anula lo necesario (usualmente la ruta absoluta de command).

• Sin herramientas OpenClaw (los backends CLI no reciben llamadas de herramienta). Sin embargo, el CLI mismo puede ejecutar sus propias herramientas.
• Sin streaming (la salida CLI se colecciona antes de retornar).
• Salida estructurada depende del formato JSON del CLI.
• Sesiones de Codex CLI reanudan vía salida de texto (sin JSONL), que es menos estructurada que la ejecución inicial --json. Las sesiones OpenClaw todavía funcionan normalmente.

• CLI no encontrado: establece command a una ruta completa.
• Nombre de modelo incorrecto: usa modelAliases para mapear provider/model → modelo CLI.
• Sin continuidad de sesión: asegúrate que sessionArg esté establecido y sessionMode no sea none (Codex CLI actualmente no puede reanudar con salida JSON).
• Imágenes ignoradas: establece imageArg (y verifica que el CLI soporte rutas de archivo).