Backends de CLI

• Las herramientas de OpenClaw no se inyectan directamente, pero un backend con bundleMcp: true puede recibir herramientas del gateway mediante un puente MCP de loopback.
• Streaming JSONL para las CLI que lo admiten.
• Se admiten sesiones, por lo que los turnos de seguimiento se mantienen coherentes.
• Las imágenes pasan si la CLI acepta rutas de imágenes.

​

Inicio rápido

openclaw agent --agent main --message "hi" --model claude-cli/claude-sonnet-4-6

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

​

Uso como alternativa

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

​

Configuración

{
  agents: {
    defaults: {
      cliBackends: {
        "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",
          // Dedicated prompt-file flag:
          // systemPromptFileArg: "--system-file",
          // Codex-style config-override flag instead:
          // systemPromptFileConfigArg: "-c",
          // systemPromptFileConfigKey: "model_instructions_file",
          systemPromptWhen: "first",
          imageArg: "--image",
          imageMode: "repeat",
          // Opt in only if this backend may reseed invalidated sessions from
          // bounded raw OpenClaw transcript history before compaction.
          reseedFromRawTranscriptWhenUncompacted: true,
          serialize: true,
        },
      },
    },
  },
}

​

Cómo funciona

1. Selecciona un backend por prefijo de proveedor (claude-cli/...).
2. Construye un prompt de sistema usando el mismo prompt de OpenClaw y 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. El backend claude-cli incluido mantiene vivo un proceso stdio de Claude por 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.

​

Detalles específicos de Claude 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 (p. ej., --session-id), o sessionArgs (marcador de posición {sessionId}) cuando el id deba quedar en varias marcas.
• Si la CLI usa un subcomando de reanudación con marcas 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: solo envía un id de sesión si ya había uno almacenado.
  • none: nunca envía un id de sesión.
• claude-cli usa de forma predeterminada liveSession: "claude-stdio", output: "jsonl" e input: "stdin", por lo que los turnos de seguimiento reutilizan el proceso live de Claude mientras está activo, 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 legible antes de reanudar; una transcripción ausente limpia la vinculación (registrado como reason=transcript-missing) en lugar de iniciar silenciosamente una sesión nueva bajo --resume.
• Las sesiones live de Claude mantienen guardas acotadas de salida JSONL: 8 MiB y 20.000 líneas JSONL sin procesar por turno de forma predeterminada. Auméntalas 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 de session.reset sí.
• 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 invalidadas antes de la Compaction, un backend puede optar por hacerlo con reseedFromRawTranscriptWhenUncompacted: true. La resiembra desde transcripción sin procesar permanece acotada y limitada a invalidaciones seguras, como una transcripción de CLI ausente, una cola de uso de herramientas huérfana, cambios de política de mensajes/prompt de sistema/cwd/MCP o un reintento por sesión expirada; los cambios de perfil de autenticación o de época de credenciales nunca reseembran historial de transcripción sin procesar.

​

Preludio de alternativa desde sesiones claude-cli

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

​

Imágenes

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

​

Entradas y salidas

• output: "text" (predeterminado) trata stdout como la respuesta final.
• output: "json" intenta analizar JSON y extraer texto más un id de sesión.
• output: "jsonl" analiza un stream JSONL y extrae el mensaje final del agente más identificadores de sesión cuando están presentes.
• 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. El valor predeterminado incluido de Gemini CLI usa stream-json; las anulaciones antiguas de --output-format json siguen usando el analizador JSON.

• 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 en su lugar.

​

Valores predeterminados propiedad del Plugin

• Los Plugins los registran con api.registerCliBackend(...).
• El id del backend se convierte en el prefijo de proveedor en las referencias de modelo.
• La configuración de usuario en agents.defaults.cliBackends.<id> aún anula el valor predeterminado del Plugin.
• La limpieza de configuración específica del backend sigue siendo propiedad del Plugin mediante el hook opcional normalizeConfig.

• El analizador predeterminado de stream-json lee eventos message del asistente, eventos de herramientas, el uso final de result y eventos de error fatal de Gemini.
• Si sobrescribes los argumentos de Gemini a --output-format json, OpenClaw normaliza ese backend de nuevo a output: "json" y lee el texto de respuesta desde el campo JSON response.
• El uso recurre a stats cuando usage falta o está vacío; stats.cached se normaliza en cacheRead de OpenClaw y, si falta stats.input, los tokens de entrada se derivan de stats.input_tokens - stats.cached.

​

Superposiciones de transformación de texto

api.registerTextTransforms({
  input: [{ from: /red basket/g, to: "blue basket" }],
  output: [{ from: /blue basket/g, to: "red basket" }],
});

​

Propiedad de Compaction nativa

api.registerCliBackend({ id: "my-cli", ownsNativeCompaction: true /* ... */ });

​

Superposiciones MCP incluidas

• claude-cli: archivo de configuración MCP estricto generado.
• google-gemini-cli: archivo de configuración del sistema de Gemini generado.

• genera un servidor MCP HTTP de loopback que expone herramientas de Gateway al proceso de CLI, autenticado con un token por sesión (OPENCLAW_MCP_TOKEN);
• limita el acceso a herramientas a la sesión, la cuenta y el contexto del canal actuales;
• carga los servidores bundle-MCP habilitados para el espacio de trabajo actual y los combina con cualquier forma de configuración/ajustes MCP existente del backend;
• reescribe la configuración de inicio usando el modo de integración propiedad del backend desde el Plugin propietario.

​

Límite de historial de reseed

​

Limitaciones

• Sin llamadas directas a herramientas de OpenClaw: OpenClaw no inyecta llamadas a herramientas en el protocolo del backend de CLI. Los backends solo ven herramientas de Gateway cuando optan por bundleMcp: true.
• La transmisión es específica del backend: algunos backends transmiten JSONL, otros acumulan en búfer hasta salir.
• Las salidas estructuradas dependen del formato JSON propio de la CLI.

​

Solución de problemas

​

Relacionado

• Runbook de Gateway
• Modelos locales