Backends CLI (runtime de respaldo)

OpenClaw puede ejecutar CLIs de IA locales como respaldo solo texto cuando los proveedores API están caídos, con límite de tasa, o con mal comportamiento temporal. Esto es intencionalmente conservador:

  • Las herramientas están deshabilitadas (sin llamadas a herramientas).
  • Texto entra → texto sale (confiable).
  • Las sesiones están soportadas (para que los turnos de seguimiento mantengan coherencia).
  • Se pueden pasar imágenes si el CLI acepta rutas de imagen.

Esto está diseñado como una red de seguridad más que como un camino principal. Úsalo cuando quieras respuestas de texto que “siempre funcionen” sin depender de APIs externas.

Inicio rápido para principiantes

Puedes usar el CLI de Claude Code sin ninguna configuración (OpenClaw incluye un valor por defecto integrado):

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

El CLI de Codex también funciona sin configuración adicional:

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

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

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

Eso es todo. No necesitas claves ni configuración de autenticación adicional más allá del CLI mismo.

Usarlo como respaldo

Agrega un backend CLI a tu lista de respaldos para que solo se ejecute cuando los modelos principales fallen:

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

Notas:

  • Si usas agents.defaults.models (lista de permitidos), debes incluir claude-cli/....
  • Si el proveedor principal falla (autenticación, límites de tasa, timeouts), OpenClaw probará el backend CLI a continuación.

Resumen de configuración

Todos los backends CLI se encuentran bajo:

agents.defaults.cliBackends

Cada entrada se identifica por un id de proveedor (por ejemplo claude-cli, my-cli). El id del proveedor se convierte en el lado izquierdo de tu referencia de modelo:

<provider>/<model>

Ejemplo de configuración

{
  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-opus-4-5": "opus",
            "claude-sonnet-4-5": "sonnet",
          },
          sessionArg: "--session",
          sessionMode: "existing",
          sessionIdFields: ["session_id", "conversation_id"],
          systemPromptArg: "--system",
          systemPromptWhen: "first",
          imageArg: "--image",
          imageMode: "repeat",
          serialize: true,
        },
      },
    },
  },
}

Cómo funciona

  1. Selecciona un backend basándose en el prefijo del proveedor (claude-cli/...).
  2. Construye un prompt de sistema usando el mismo prompt de OpenClaw + contexto del workspace.
  3. Ejecuta el CLI con un id de sesión (si está soportado) para que el historial se mantenga consistente.
  4. Analiza la salida (JSON o texto plano) y devuelve el texto final.
  5. Persiste los ids de sesión por backend, para que los seguimientos reutilicen la misma sesión CLI.

Sesiones

  • Si el CLI soporta sesiones, configura sessionArg (por ejemplo --session-id) o sessionArgs (marcador {sessionId}) cuando el ID necesita insertarse en múltiples flags.
  • Si el CLI usa un subcomando de reanudación con flags diferentes, configura resumeArgs (reemplaza args al reanudar) y opcionalmente resumeOutput (para reanudaciones sin JSON).
  • sessionMode:
    • always: siempre envía un id de sesión (UUID nuevo si no hay almacenado).
    • existing: solo envía un id de sesión si uno fue almacenado previamente.
    • none: nunca envía un id de sesión.

Imágenes (paso directo)

Si tu CLI acepta rutas de imagen, configura imageArg:

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

OpenClaw escribirá imágenes base64 en archivos temporales. Si imageArg está configurado, esas rutas se pasan como argumentos CLI. Si imageArg falta, OpenClaw agrega las rutas de archivo al prompt (inyección de ruta), que es suficiente para CLIs que auto- cargan archivos locales desde rutas simples (comportamiento del CLI de Claude Code).

Entradas / salidas

  • output: "json" (por defecto) intenta analizar JSON y extraer texto + id de sesión.
  • output: "jsonl" analiza flujos JSONL (Codex CLI --json) y extrae el último mensaje del agente más thread_id cuando está presente.
  • output: "text" trata stdout como la respuesta final.

Modos de entrada:

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

Valores por defecto (integrados)

OpenClaw incluye un valor por defecto para claude-cli:

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

OpenClaw también incluye un valor por defecto para codex-cli:

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

Modifica solo si es necesario (lo común: ruta absoluta del command).

Limitaciones

  • Sin herramientas de OpenClaw (el backend CLI nunca recibe llamadas a herramientas). Algunos CLIs pueden seguir ejecutando su propio tooling de agente.
  • Sin streaming (la salida del CLI se recolecta y luego se devuelve).
  • Las salidas estructuradas dependen del formato JSON del CLI.
  • Las sesiones de Codex CLI se reanudan vía salida de texto (sin JSONL), lo cual es menos estructurado que la ejecución inicial --json. Las sesiones de OpenClaw siguen funcionando normalmente.

Solución de problemas

  • CLI no encontrado: configura command con una ruta completa.
  • Nombre de modelo incorrecto: usa modelAliases para mapear provider/model → modelo CLI.
  • Sin continuidad de sesión: asegúrate de que sessionArg esté configurado y sessionMode no sea none (Codex CLI actualmente no puede reanudar con salida JSON).
  • Imágenes ignoradas: configura imageArg (y verifica que el CLI soporte rutas de archivo).
arrow_back
Anterior
Tools Invoke HTTP API
Siguiente
Local Models
arrow_forward