Backends de la CLI

Documentation Index

Fetch the complete documentation index at: https://docs.openclaw.ai/llms.txt

Use this file to discover all available pages before exploring further.

• Las herramientas de OpenClaw no se inyectan directamente, pero los backends con bundleMcp: true pueden recibir herramientas del Gateway mediante un puente MCP de loopback.
• Streaming JSONL para las CLI que lo admiten.
• Se admiten sesiones (para que los turnos de seguimiento mantengan coherencia).
• Las imágenes pueden pasarse tal cual si la CLI acepta rutas de imagen.

​

Inicio rápido para principiantes

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

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

​

Usarlo como respaldo

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

• Si usas agents.defaults.models (lista de permitidos), también debes incluir ahí tus modelos de backend de CLI.
• Si el proveedor principal falla (autenticación, límites de tasa, tiempos de espera), OpenClaw probará después el backend de CLI.

​

Resumen de configuración

agents.defaults.cliBackends

<provider>/<model>

​

Configuración de ejemplo

{
  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",
          // For CLIs with a dedicated prompt-file flag:
          // systemPromptFileArg: "--system-file",
          // Codex-style CLIs can point at a prompt file instead:
          // systemPromptFileConfigArg: "-c",
          // systemPromptFileConfigKey: "model_instructions_file",
          systemPromptWhen: "first",
          imageArg: "--image",
          imageMode: "repeat",
          // Opt in only if this backend may reseed safe invalidated sessions
          // from bounded raw OpenClaw transcript history before compaction.
          reseedFromRawTranscriptWhenUncompacted: true,
          serialize: true,
        },
      },
    },
  },
}

​

Cómo funciona

1. Selecciona un backend según el prefijo de proveedor (codex-cli/...).
2. Construye un prompt de sistema usando el mismo prompt de OpenClaw + contexto del workspace.
3. Ejecuta la CLI con un id de sesión (si se admite) para que el historial se mantenga consistente. El backend claude-cli incluido mantiene activo un proceso stdio de Claude por cada sesión de OpenClaw y envía los turnos de seguimiento por stdin stream-json.
4. Analiza la salida (JSON o texto sin formato) y devuelve el texto final.
5. Persiste los ids de sesión por backend, para que los seguimientos reutilicen la misma sesión de CLI.

claude auth login
claude auth status --text
openclaw models auth login --provider anthropic --method cli --set-default

​

Sesiones

• Si la CLI admite sesiones, define sessionArg (por ejemplo, --session-id) o sessionArgs (marcador de posición {sessionId}) cuando el ID deba insertarse en varias banderas.
• Si la CLI usa un subcomando resume con banderas diferentes, define resumeArgs (reemplaza args al reanudar) y opcionalmente resumeOutput (para reanudaciones no JSON).
• sessionMode:
  • always: siempre envía un id de sesión (UUID nuevo si no hay ninguno almacenado).
  • existing: envía un id de sesión solo si ya se había almacenado uno.
  • none: nunca envía un id de sesión.
• claude-cli usa por defecto liveSession: "claude-stdio", output: "jsonl", e input: "stdin" para que los turnos de seguimiento reutilicen el proceso Claude activo mientras esté activo. Stdio cálido es ahora el valor predeterminado, incluso para configuraciones personalizadas que omiten campos de transporte. Si el Gateway se reinicia o el proceso inactivo sale, OpenClaw reanuda desde el id de sesión de Claude almacenado. Los ids de sesión almacenados se verifican contra una transcripción de proyecto existente y legible antes de reanudar, por lo que las vinculaciones fantasma se limpian con reason=transcript-missing en lugar de iniciar silenciosamente una nueva sesión de Claude CLI bajo --resume.
• Las sesiones en vivo de Claude mantienen protecciones acotadas de salida JSONL. Los valores predeterminados permiten hasta 8 MiB y 20.000 líneas JSONL raw por turno. Los turnos de Claude con muchas herramientas pueden aumentarlas por backend con agents.defaults.cliBackends.claude-cli.reliability.outputLimits.maxTurnRawChars y maxTurnLines; OpenClaw limita esos ajustes a 64 MiB y 100.000 líneas.
• Las sesiones de CLI almacenadas son continuidad propiedad del proveedor. El restablecimiento diario implícito de sesión no las corta; /reset y las políticas explícitas session.reset sí lo hacen.
• Las sesiones nuevas de CLI normalmente reseembran solo desde el resumen de Compaction de OpenClaw más la cola posterior a la Compaction. Para recuperar sesiones cortas que se invalidan antes de la Compaction, un backend puede optar por reseedFromRawTranscriptWhenUncompacted: true. OpenClaw aún mantiene la reseembra de transcripción raw acotada y la limita a invalidaciones seguras como transcripciones de CLI ausentes, cambios de prompt de sistema/MCP o reintento por sesión expirada; los cambios de perfil de autenticación o de época de credenciales nunca reseembran historial de transcripción raw.

• serialize: true mantiene ordenadas las ejecuciones del 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 la identidad de autenticación seleccionada, incluido un id de perfil de autenticación cambiado, API key estática, token estático o identidad de cuenta OAuth cuando la CLI expone una. La rotación de tokens de acceso y actualización OAuth no corta la sesión de CLI almacenada. Si una CLI no expone un id de cuenta OAuth estable, OpenClaw deja que esa CLI aplique los permisos de reanudación.

​

Preludio de respaldo desde sesiones claude-cli

• El preludio prefiere el resumen /compact más reciente o el marcador compact_boundary, y luego anexa los turnos posteriores al límite más recientes hasta un presupuesto de caracteres. Los turnos previos al límite se descartan porque el resumen ya los representa.
• Los bloques de herramientas se consolidan en pistas compactas (tool call: name) y (tool result: …) para mantener honesto el presupuesto del prompt. El resumen se etiqueta como (truncated) si se desborda.
• Los respaldos del mismo proveedor de claude-cli a claude-cli dependen del propio --resume de Claude y omiten el preludio.
• La siembra reutiliza la validación existente de rutas de archivo de sesión de Claude, por lo que no se pueden leer rutas arbitrarias.

​

Imágenes (paso directo)

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

​

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 respuesta desde response y el uso desde stats cuando usage falta o está vacío.
• output: "jsonl" analiza streams 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.

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

​

Valores predeterminados (propiedad del plugin)

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

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

• El texto de la respuesta se lee del campo JSON response.
• El uso recurre a stats cuando usage no existe o está vacío.
• stats.cached se normaliza como cacheRead de OpenClaw.
• Si falta stats.input, OpenClaw deriva los tokens de entrada de stats.input_tokens - stats.cached.

​

Valores predeterminados propios 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 de usuario en agents.defaults.cliBackends.<id> sigue sobrescribiendo el valor predeterminado del Plugin.
• La limpieza de configuración específica del backend sigue siendo propiedad del Plugin mediante el 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 MCP incluido

• claude-cli: archivo de configuración MCP estricto generado
• codex-cli: sobrescrituras de configuración en línea para mcp_servers; el servidor local loopback generado de OpenClaw se marca con el modo de aprobación de herramientas por servidor de Codex para que las llamadas MCP no puedan quedar bloqueadas por solicitudes locales de aprobación
• google-gemini-cli: archivo de configuración del sistema de Gemini generado

• inicia un servidor MCP HTTP de loopback que expone herramientas del Gateway al proceso CLI
• autentica el puente con un token por sesión (OPENCLAW_MCP_TOKEN)
• delimita el acceso a herramientas al contexto de la sesión, la cuenta y el canal actuales
• carga los servidores bundle-MCP habilitados para el espacio de trabajo actual
• los fusiona con cualquier forma existente de configuración/ajustes MCP del backend
• reescribe la configuración de inicio usando el modo de integración propio del backend de la extensión propietaria

​

Limitaciones

• Sin llamadas directas a herramientas de OpenClaw. OpenClaw no inyecta llamadas a herramientas en el protocolo del backend CLI. Los backends solo ven herramientas del Gateway cuando habilitan bundleMcp: true.
• El streaming depende del backend. Algunos backends transmiten JSONL; otros almacenan en búfer hasta salir.
• 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

• No se encuentra la CLI: establece command en una ruta completa.
• Nombre de modelo incorrecto: usa modelAliases para asignar provider/model → modelo de CLI.
• Sin continuidad de sesión: asegúrate de que sessionArg esté establecido y de que sessionMode no sea none (Codex CLI actualmente no puede reanudarse con salida JSON).
• Imágenes ignoradas: establece imageArg (y verifica que la CLI admita rutas de archivo).

​

Relacionado

• Runbook del Gateway
• Modelos locales