Configura backends CLI en OpenClaw como fallback seguro

A veces, cuando dependes de una API externa, te encuentras con límites de velocidad o caídas inesperadas que detienen tu flujo de trabajo por completo. Es frustrante cuando tu entorno de desarrollo se queda sin respuestas justo en el momento en que más las necesitas.

OpenClaw te permite configurar CLI backends como una alternativa de respaldo, asegurando que siempre tengas una forma de obtener respuestas de texto cuando los proveedores principales no están disponibles.

Inicio rápido para principiantes

Puedes usar el Codex CLI sin ninguna configuración adicional, ya que el plugin de OpenAI incluido registra un backend predeterminado automáticamente:

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

Si tu Gateway se ejecuta bajo launchd/systemd y el PATH es limitado, añade solo la ruta del comando:

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

Eso es todo. No necesitas llaves ni configuraciones de autenticación adicionales más allá de las que requiere el CLI por sí mismo.

Usarlo como respaldo

Añade un CLI backend 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: ["codex-cli/gpt-5.4"],
      },
      models: {
        "anthropic/claude-opus-4-6": { alias: "Opus" },
        "codex-cli/gpt-5.4": {},
      },
    },
  },
}

Notas:

Si usas agents.defaults.models (lista de permitidos), debes incluir también tus modelos de CLI backend allí.
Si el proveedor principal falla (autenticación, límites de velocidad, tiempos de espera), OpenClaw intentará usar el CLI backend a continuación.

Resumen de configuración

Todos los CLI backends se encuentran bajo la siguiente ruta:

agents.defaults.cliBackends

Cada entrada se identifica mediante un provider id (por ejemplo, codex-cli, my-cli). El ID del proveedor se convierte en la parte izquierda de tu referencia de modelo:

<provider>/<model>

Ejemplo de configuración

{
  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",
          // Codex-style CLIs can point at a prompt file instead:
          // systemPromptFileConfigArg: "-c",
          // systemPromptFileConfigKey: "model_instructions_file",
          systemPromptWhen: "first",
          imageArg: "--image",
          imageMode: "repeat",
          serialize: true,
        },
      },
    },
  },
}

Cómo funciona

Selecciona un backend basándose en el prefijo del proveedor (codex-cli/...).
Construye un system prompt usando el prompt de OpenClaw más el contexto del espacio de trabajo.
Ejecuta el CLI con un ID de sesión (si es compatible) para que el historial se mantenga coherente.
Analiza la salida (JSON o texto plano) y devuelve el texto final.
Persiste los IDs de sesión por backend, de modo que las consultas de seguimiento reutilicen la misma sesión de CLI.

Sesiones

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

Imágenes (paso a través)

Si tu CLI acepta rutas de imágenes, configura imageArg:

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

OpenClaw escribirá imágenes en base64 en archivos temporales. Si imageArg está configurado, esas rutas se pasan como argumentos de CLI. Si falta imageArg, OpenClaw añade las rutas de archivo al prompt (inyección de ruta), lo cual es suficiente para los CLIs que cargan automáticamente archivos locales desde rutas simples.

Entradas / salidas

output: "json" (predeterminado) intenta analizar JSON y extraer texto + ID de sesión.
Para la salida JSON del Gemini CLI, OpenClaw lee el texto de respuesta desde response y el uso desde stats cuando usage falta o está vacío.
output: "jsonl" analiza flujos JSONL (por ejemplo, Codex CLI --json) y extrae el mensaje final del agente más los identificadores de sesión cuando están presentes.
output: "text" trata stdout como la respuesta final.

Modos de entrada:

input: "arg" (predeterminado) pasa el prompt como el último argumento del CLI.
input: "stdin" envía el prompt a través de stdin.
Si el prompt es muy largo y maxPromptArgChars está configurado, se utiliza stdin.

Valores predeterminados (propiedad del plugin)

El plugin de OpenAI incluido también registra un valor predeterminado para codex-cli:

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"

El plugin de Google incluido también registra un valor predeterminado para google-gemini-cli:

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"]

Valores predeterminados propiedad del plugin

Los valores predeterminados del CLI backend ahora son parte de la superficie del plugin:

Los plugins los registran con api.registerCliBackend(...).
El id del backend se convierte en el prefijo del proveedor en las referencias de modelo.
La configuración del usuario en agents.defaults.cliBackends.<id> sigue sobrescribiendo el valor predeterminado del plugin.
La limpieza de la configuración específica del backend permanece bajo el control del plugin a través del 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" },
  ],
});

Superposiciones de Bundle MCP

Los CLI backends no reciben llamadas de herramientas de OpenClaw directamente, pero un backend puede optar por una superposición de configuración MCP generada con bundleMcp: true.

Cuando el bundle MCP está habilitado, OpenClaw:

Genera un servidor HTTP MCP de loopback que expone las herramientas del Gateway al proceso CLI.
Autentica el puente con un token por sesión (OPENCLAW_MCP_TOKEN).
Limita el acceso a herramientas al contexto actual de sesión, cuenta y canal.
Carga los servidores bundle-MCP habilitados para el espacio de trabajo actual.
Los fusiona con cualquier configuración MCP existente del backend.
Reescribe la configuración de lanzamiento usando el modo de integración propiedad del backend.

Limitaciones

Sin llamadas directas a herramientas de OpenClaw. OpenClaw no inyecta llamadas de herramientas en el protocolo del CLI backend. Los backends solo ven las herramientas del Gateway cuando optan por bundleMcp: true.
El streaming es específico del backend. Algunos backends transmiten JSONL; otros almacenan en búfer hasta la salida.
Las salidas estructuradas dependen del formato JSON del CLI.
Las sesiones de Codex CLI se reanudan mediante 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 absoluta.
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 admita rutas de archivo).

¿Necesitas más ayuda? Consulta nuestro AI Setup Assistant.

Siguientes pasos

OpenClaw Expert

Sigues atascado?

Si esta pagina no resolvio tu caso, pregunta a OpenClaw Expert para pasos concretos.