​

Backends de CLI (entorno de ejecución de respaldo)

• Las herramientas están deshabilitadas (sin llamadas a herramientas).
• Texto entra → texto sale (confiable).
• Se admiten sesiones (para que los turnos de seguimiento se mantengan coherentes).
• Las imágenes pueden pasarse si la CLI acepta rutas de imágenes.

​

Inicio rápido para principiantes

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

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

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

​

Uso como respaldo

{
  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": {},
      },
    },
  },
}

• Si usa agents.defaults.models (lista de permitidos), debe incluir claude-cli/....
• Si el proveedor principal falla (autenticación, límites de tasa, tiempos de espera), OpenClaw intentará el backend de CLI a continuación.

​

Descripción general de la configuración

agents.defaults.cliBackends

<provider>/<model>

​

Configuración de ejemplo

{
  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 según el prefijo del proveedor (claude-cli/...).
2. Construye un prompt del sistema usando el mismo prompt de OpenClaw + el contexto del espacio de trabajo.
3. Ejecuta la CLI con un id de sesión (si se admite) 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 de la CLI.

​

Sesiones

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

​

Imágenes (paso directo)

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

​

Entradas / salidas

• output: "json" (predeterminado) intenta analizar JSON y extraer texto + id de sesión.
• output: "jsonl" analiza streams 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.

• input: "arg" (predeterminado) pasa el prompt como el último argumento de la CLI.
• input: "stdin" envía el prompt vía stdin.
• Si el prompt es muy largo y se establece maxPromptArgChars, se usa stdin.

​

Valores predeterminados (integrados)

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

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

​

Limitaciones

• Sin herramientas de OpenClaw (el backend de CLI nunca recibe llamadas de herramientas). Algunas CLIs aún pueden ejecutar su propio tooling de agente.
• Sin streaming (la salida de la CLI se recopila y luego se devuelve).
• Salidas estructuradas dependen del formato JSON de la CLI.
• Sesiones de Codex CLI se reanudan mediante salida de texto (sin JSONL), lo que es menos estructurado que la ejecución inicial --json. Las sesiones de OpenClaw siguen funcionando con normalidad.

​

Solución de problemas

• CLI no encontrada: establezca command en una ruta completa.
• Nombre de modelo incorrecto: use modelAliases para mapear provider/model → modelo de la CLI.
• Sin continuidad de sesión: asegúrese de que sessionArg esté establecido y que sessionMode no sea none (Codex CLI actualmente no puede reanudar con salida JSON).
• Imágenes ignoradas: establezca imageArg (y verifique que la CLI admita rutas de archivos).