Saltar al contenido principal

​
Backends de CLI (tiempo de ejecución alternativo)

OpenClaw puede ejecutar CLI de IA locales como una alternativa solo de texto cuando los proveedores de API no están disponibles, tienen límites de tasa o se comportan mal temporalmente. Esto es intencionalmente conservador:
  • Las herramientas de OpenClaw no se inyectan directamente, pero los backends con bundleMcp: true pueden recibir herramientas del gateway mediante un puente MCP de local loopback.
  • Streaming JSONL para las CLI que lo admiten.
  • Las sesiones son compatibles (para que los turnos de seguimiento mantengan la coherencia).
  • Las imágenes pueden pasarse si la CLI acepta rutas de imágenes.
Esto está diseñado como una red de seguridad más que como una ruta principal. Úselo cuando quiera respuestas de texto que “siempre funcionen” sin depender de API externas. Si quiere un tiempo de ejecución completo con controles de sesión de ACP, tareas en segundo plano, vinculación de hilo/conversación y sesiones de codificación externas persistentes, use Agentes ACP en su lugar. Los backends de CLI no son ACP.

​
Inicio rápido para principiantes

Puede usar Codex CLI sin ninguna configuración (el Plugin de OpenAI incluido registra un backend predeterminado): 
openclaw agent --message "hi" --model codex-cli/gpt-5.4
Si su gateway se ejecuta con launchd/systemd y PATH es mínimo, agregue solo la ruta del comando: 
{
  agents: {
    defaults: {
      cliBackends: {
        "codex-cli": {
          command: "/opt/homebrew/bin/codex",
        },
      },
    },
  },
}
Eso es todo. No se necesitan claves ni configuración de autenticación adicional más allá de la propia CLI. Si usa un backend de CLI incluido como proveedor principal de mensajes en un host de gateway, OpenClaw ahora carga automáticamente el Plugin incluido propietario cuando su configuración hace referencia explícita a ese backend en una referencia de modelo o en agents.defaults.cliBackends.

​
Uso como alternativa

Agregue un backend de CLI a su lista de alternativas para que solo se ejecute cuando fallen los modelos primarios: 
{
  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 usa agents.defaults.models (lista de permitidos), también debe incluir allí los modelos de su backend de CLI.
  • Si el proveedor primario falla (autenticación, límites de tasa, tiempos de espera), OpenClaw probará el backend de CLI a continuación.

​
Resumen de configuración

Todos los backends de CLI se encuentran en: 
agents.defaults.cliBackends
Cada entrada usa como clave un id de proveedor (por ejemplo, codex-cli, my-cli). El id del proveedor se convierte en el lado izquierdo de su 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",
          // Las CLI de estilo Codex pueden apuntar a un archivo de prompt en su lugar:
          // systemPromptFileConfigArg: "-c",
          // systemPromptFileConfigKey: "model_instructions_file",
          systemPromptWhen: "first",
          imageArg: "--image",
          imageMode: "repeat",
          serialize: true,
        },
      },
    },
  },
}

​
Cómo funciona

  1. Selecciona un backend según el prefijo del proveedor (codex-cli/...).
  2. Construye un prompt del sistema usando el mismo prompt de OpenClaw + contexto del espacio de trabajo.
  3. Ejecuta la CLI con un id de sesión (si es compatible) para que el historial se mantenga coherente.
  4. Analiza la salida (JSON o texto sin formato) y devuelve el texto final.
  5. Persiste los id de sesión por backend, para que los seguimientos reutilicen la misma sesión de CLI.
El backend incluido claude-cli de Anthropic vuelve a ser compatible. El personal de Anthropic nos dijo que el uso de Claude CLI al estilo OpenClaw vuelve a estar permitido, por lo que OpenClaw trata el uso de claude -p como autorizado para esta integración, a menos que Anthropic publique una nueva política.
El backend incluido codex-cli de OpenAI pasa el prompt del sistema de OpenClaw a través de la anulación de configuración model_instructions_file de Codex (-c model_instructions_file="..."). Codex no expone una marca de estilo Claude --append-system-prompt, por lo que OpenClaw escribe el prompt ensamblado en un archivo temporal para cada nueva sesión de Codex CLI. El backend incluido claude-cli de Anthropic recibe la instantánea de Skills de OpenClaw de dos formas: el catálogo compacto de Skills de OpenClaw en el prompt del sistema agregado, y un Plugin temporal de Claude Code pasado con --plugin-dir. El Plugin contiene solo las Skills aptas para ese agente/sesión, por lo que el resolvedor nativo de Skills de Claude Code ve el mismo conjunto filtrado que OpenClaw anunciaría de otro modo en el prompt. Las anulaciones de variables de entorno/API key de Skills siguen siendo aplicadas por OpenClaw al entorno del proceso hijo para la ejecución.

​
Sesiones

  • Si la CLI admite sesiones, configure sessionArg (por ejemplo, --session-id) o sessionArgs (marcador {sessionId}) cuando el ID deba insertarse en varias marcas.
  • Si la CLI usa un subcomando de reanudación con marcas diferentes, configure resumeArgs (reemplaza args al reanudar) y, opcionalmente, resumeOutput (para reanudaciones que no sean JSON).
  • sessionMode:
    • always: siempre envía un id de sesión (un UUID nuevo si no hay ninguno almacenado).
    • existing: solo envía un id de sesión si ya había uno almacenado.
    • none: nunca envía un id de sesión.
Notas sobre serialización:
  • serialize: true mantiene ordenadas las ejecuciones en el mismo carril.
  • La mayoría de las CLI serializan en un carril de proveedor.
  • OpenClaw descarta la reutilización de sesiones de CLI almacenadas cuando cambia el estado de autenticación del backend, incluyendo volver a iniciar sesión, rotación de tokens o un cambio en la credencial del perfil de autenticación.

​
Imágenes (paso directo)

Si su CLI acepta rutas de imágenes, configure imageArg: 
imageArg: "--image",
imageMode: "repeat"
OpenClaw escribirá las imágenes en base64 en archivos temporales. Si imageArg está configurado, esas rutas se pasan como argumentos de CLI. Si falta imageArg, OpenClaw agrega las rutas de archivo al prompt (inyección de ruta), lo que es suficiente para las CLI que cargan automáticamente archivos locales a partir de rutas simples.

​
Entradas / salidas

  • output: "json" (predeterminado) intenta analizar JSON y extraer texto + id de sesión.
  • Para la salida JSON de Gemini CLI, OpenClaw lee el texto de la respuesta desde response y el uso desde stats cuando falta usage 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 de CLI.
  • input: "stdin" envía el prompt mediante stdin.
  • Si el prompt es muy largo y maxPromptArgChars está configurado, se usa stdin.

​
Valores predeterminados (propiedad del Plugin)

El Plugin incluido de OpenAI 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 incluido de Google 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"]
Requisito previo: la Gemini CLI local debe estar instalada y disponible como gemini en PATH (brew install gemini-cli o npm install -g @google/gemini-cli). Notas sobre JSON de Gemini CLI:
  • El texto de respuesta se lee del campo JSON response.
  • El uso recurre a stats cuando usage no está presente o está vacío.
  • stats.cached se normaliza en OpenClaw como cacheRead.
  • Si falta stats.input, OpenClaw deriva los tokens de entrada a partir de stats.input_tokens - stats.cached.
Anule esto solo si es necesario (lo habitual: ruta absoluta de command).

​
Valores predeterminados propiedad del Plugin

Los valores predeterminados del backend de CLI ahora forman 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 anulando el valor predeterminado del Plugin.
  • La limpieza de configuración específica del backend sigue siendo propiedad del Plugin mediante el hook opcional normalizeConfig.
Los Plugins que necesiten pequeños ajustes de compatibilidad de prompt/mensaje pueden declarar transformaciones de texto bidireccionales sin reemplazar un proveedor ni un backend de CLI: 
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" },
  ],
});
input reescribe el prompt del sistema y el prompt del usuario enviados a la CLI. output reescribe los deltas en streaming del asistente y el texto final analizado antes de que OpenClaw maneje sus propios marcadores de control y la entrega por canal. Para CLI que emiten JSONL compatible con stream-json de Claude Code, configure jsonlDialect: "claude-stream-json" en la configuración de ese backend.

​
Superposiciones de bundle MCP

Los backends de CLI no reciben llamadas a herramientas de OpenClaw directamente, pero un backend puede optar por una superposición de configuración MCP generada con bundleMcp: true. Comportamiento incluido actual:
  • claude-cli: archivo de configuración MCP estricto generado
  • codex-cli: anulaciones de configuración en línea para mcp_servers
  • google-gemini-cli: archivo de configuración del sistema Gemini generado
Cuando bundle MCP está habilitado, OpenClaw:
  • inicia un servidor HTTP MCP de local loopback que expone herramientas del gateway al proceso de la CLI
  • autentica el puente con un token por sesión (OPENCLAW_MCP_TOKEN)
  • limita el acceso a herramientas a la sesión, cuenta y contexto de canal actuales
  • carga los servidores bundle-MCP habilitados para el espacio de trabajo actual
  • los fusiona con cualquier configuración MCP existente o forma de ajustes del backend
  • reescribe la configuración de inicio usando el modo de integración propiedad del backend desde la extensión propietaria
Si no hay servidores MCP habilitados, OpenClaw sigue inyectando una configuración estricta cuando un backend opta por bundle MCP para que las ejecuciones en segundo plano permanezcan aisladas.

​
Limitaciones

  • No hay llamadas directas a herramientas de OpenClaw. OpenClaw no inyecta llamadas a herramientas en el protocolo del backend de CLI. Los backends solo ven 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 de la CLI.
  • Las sesiones de Codex CLI se reanudan mediante salida de texto (sin JSONL), que es menos estructurada que la ejecución inicial con --json. Las sesiones de OpenClaw siguen funcionando normalmente.

​
Solución de problemas

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