Ir al contenido
OpenClaw Docs

CLI de inferencia

openclaw infer es la superficie principal sin interfaz para los flujos de trabajo de inferencia respaldados por proveedores.

Intencionalmente expone familias de capacidades, no nombres de RPC de puerta de enlace sin procesar ni identificadores de herramientas de agente sin procesar.

Convierta infer en una habilidad

Sección titulada «Convierta infer en una habilidad»

Copie y pegue esto en un agente:

Read https://docs.openclaw.ai/cli/infer, then create a skill that routes my common workflows to `openclaw infer`.
Focus on model runs, image generation, video generation, audio transcription, TTS, web search, and embeddings.

Una buena habilidad basada en infer debería:

  • asignar las intenciones comunes del usuario al subcomando de infer correcto
  • incluir algunos ejemplos canónicos de infer para los flujos de trabajo que cubre
  • prefiera openclaw infer ... en ejemplos y sugerencias
  • evitar volver a documentar toda la superficie de infer dentro del cuerpo de la habilidad

Cobertura típica de habilidad centrada en infer:

  • openclaw infer model run
  • openclaw infer image generate
  • openclaw infer audio transcribe
  • openclaw infer tts convert
  • openclaw infer web search
  • openclaw infer embedding create

Por qué usar infer

Sección titulada «Por qué usar infer»

openclaw infer proporciona una CLI consistente para las tareas de inferencia respaldadas por proveedores dentro de OpenClaw.

Beneficios:

  • Utilice los proveedores y modelos ya configurados en OpenClaw en lugar de crear envoltorios únicos para cada backend.
  • Mantenga los flujos de trabajo de modelo, imagen, transcripción de audio, TTS, video, web e incrustaciones bajo un mismo árbol de comandos.
  • Utilice una forma de salida --json estable para scripts, automatización y flujos de trabajo impulsados por agentes.
  • Prefiera una superficie de primera parte de OpenClaw cuando la tarea sea fundamentalmente “ejecutar inferencia”.
  • Utilice la ruta local normal sin requerir la puerta de enlace para la mayoría de los comandos de infer.

Para las comprobaciones de extremo a extremo del proveedor, prefiera openclaw infer ... una vez que las pruebas de menor nivel del proveedor sean exitosas. Ejecuta la CLI enviada, la carga de configuración, la resolución del agente predeterminado, la activación del complemento incluido y el tiempo de ejecución de capacidad compartida antes de que se realice la solicitud del proveedor.

Árbol de comandos

Sección titulada «Árbol de comandos»
 openclaw infer
  list
  inspect


  model
    run
    list
    inspect
    providers
    auth login
    auth logout
    auth status


  image
    generate
    edit
    describe
    describe-many
    providers


  audio
    transcribe
    providers


  tts
    convert
    voices
    providers
    status
    enable
    disable
    set-provider


  video
    generate
    describe
    providers


  web
    search
    fetch
    providers


  embedding
    create
    providers

Tareas comunes

Sección titulada «Tareas comunes»

Esta tabla asigna tareas de inferencia comunes al comando infer correspondiente.

TareaComandoNotas
Ejecutar un prompt de texto/modeloopenclaw infer model run --prompt "..." --jsonUsa la ruta local normal de forma predeterminada
Ejecutar un aviso de modelo en imágenesopenclaw infer model run --prompt "Describe this" --file ./image.png --model provider/modelRepita --file para múltiples entradas de imagen
Generar una imagenopenclaw infer image generate --prompt "..." --jsonUse image edit cuando comience desde un archivo existente
Describir un archivo de imagen o URLopenclaw infer image describe --file ./image.png --prompt "..." --json--model debe ser un <provider/model> con capacidad de imagen
Transcribir audioopenclaw infer audio transcribe --file ./memo.m4a --json--model debe ser <provider/model>
Sintetizar vozopenclaw infer tts convert --text "..." --output ./speech.mp3 --jsontts status está orientado a la puerta de enlace
Generar un videoopenclaw infer video generate --prompt "..." --jsonAdmite sugerencias de proveedor como --resolution
Describir un archivo de videoopenclaw infer video describe --file ./clip.mp4 --json--model debe ser <provider/model>
Buscar en la webopenclaw infer web search --query "..." --json
Recuperar una página webopenclaw infer web fetch --url https://example.com --json
Crear incrustacionesopenclaw infer embedding create --text "..." --json

Comportamiento

Sección titulada «Comportamiento»
  • openclaw infer ... es la superficie principal de la CLI para estos flujos de trabajo.
  • Use --json cuando la salida vaya a ser consumida por otro comando o script.
  • Use --provider o --model provider/model cuando se requiera un backend específico.
  • Use model run --thinking <level> para pasar un nivel de razonamiento/pensamiento de un solo disparo (off, minimal, low, medium, high, adaptive, xhigh o max) mientras mantiene la ejecución sin procesar.
  • Para image describe, audio transcribe y video describe, --model debe usar el formulario <provider/model>.
  • Para image describe, --file acepta rutas locales y URL de imagen HTTP(S). Las URL remotas utilizan la política SSRF de obtención de medios normal.
  • Para image describe, un --model explícito ejecuta ese proveedor/modelo directamente. El modelo debe ser capaz de procesar imágenes en el catálogo de modelos o en la configuración del proveedor. codex/<model> ejecuta un turno de comprensión de imágenes del servidor de aplicaciones Codex delimitado; openai/<model> usa la ruta del proveedor OpenAI con autenticación mediante clave de API u OAuth de ChatGPT/Codex.
  • Los comandos de ejecución sin estado predeterminan a local.
  • Los comandos de estado administrados por Gateway predeterminan a gateway.
  • La ruta local normal no requiere que el gateway esté en ejecución.
  • El model run local es una finalización de proveedor de un solo tiro ligera. Resuelve el modelo de agente configurado y la autenticación, pero no inicia un turno de agente de chat, carga herramientas ni abre servidores MCP empaquetados.
  • model run --file acepta archivos de imagen, detecta su tipo MIME y los envía con el mensaje proporcionado al modelo seleccionado. Repita --file para varias imágenes.
  • model run --file rechaza las entradas que no son imágenes. Use infer audio transcribe para archivos de audio y infer video describe para archivos de video.
  • model run --gateway ejerce el enrutamiento de Gateway, la autenticación guardada, la selección de proveedor y el tiempo de ejecución integrado, pero aún se ejecuta como una sonda de modelo sin formato: envía el mensaje proporcionado y cualquier archivo adjunto de imagen sin transcripción de sesión previa, contexto de arranque/AGENTS, ensamblaje del motor de contexto, herramientas o servidores MCP empaquetados.
  • model run --gateway --model <provider/model> requiere una credencial de gateway de operador de confianza porque la solicitud le pide al Gateway que ejecute una anulación única de proveedor/modelo.
  • El model run --thinking local utiliza la ruta de finalización de proveedor ligera; los niveles específicos del proveedor, como adaptive y max, se asignan al nivel portátil de finalización simple más cercano.

Modelo

Sección titulada «Modelo»

Use model para la inferencia de texto respaldada por el proveedor y la inspección de modelo/proveedor.

Ventana de terminal
openclaw infer model run --prompt "Reply with exactly: smoke-ok" --json
openclaw infer model run --prompt "Summarize this changelog entry" --model openai/gpt-5.4 --json
openclaw infer model run --prompt "Describe this image in one sentence" --file ./photo.jpg --model google/gemini-2.5-flash --json
openclaw infer model run --prompt "Use more reasoning here" --thinking high --json
openclaw infer model providers --json
openclaw infer model inspect --name gpt-5.5 --json

Use full <provider/model> refs to smoke-test a specific provider without starting the Gateway or loading the full agent tool surface:

Ventana de terminal
openclaw infer model run --local --model anthropic/claude-sonnet-4-6 --prompt "Reply with exactly: pong" --json
openclaw infer model run --local --model cerebras/zai-glm-4.7 --prompt "Reply with exactly: pong" --json
openclaw infer model run --local --model google/gemini-2.5-flash --prompt "Reply with exactly: pong" --json
openclaw infer model run --local --model groq/llama-3.1-8b-instant --prompt "Reply with exactly: pong" --json
openclaw infer model run --local --model mistral/mistral-medium-3-5 --prompt "Reply with exactly: pong" --json
openclaw infer model run --local --model mistral/mistral-small-latest --prompt "Reply with exactly: pong" --json
openclaw infer model run --local --model openai/gpt-5.5 --prompt "Reply with exactly: pong" --json
openclaw infer model run --local --model ollama/qwen2.5vl:7b --prompt "Describe this image." --file ./photo.jpg --json

Notas:

  • Local model run es la prueba de humo CLI más estrecha para la salud del proveedor/modelo/autenticación porque, para los proveedores que no son Codex, envía solo el mensaje suministrado al modelo seleccionado.
  • Local model run --model <provider/model> puede usar filas exactas del catálogo estático incluido de models list --all antes de que ese proveedor se escriba en la configuración. La autenticación del proveedor aún es necesaria; las credenciales faltantes fallan como errores de autenticación, no como Unknown model.
  • Para las sondas de razonamiento Mistral Medium 3.5, deje la temperatura sin establecer/predeterminada. Mistral rechaza reasoning_effort="high" más temperature: 0; use mistral/mistral-medium-3-5 con la temperatura predeterminada o un valor distinto de cero del modo de razonamiento, como 0.7.
  • Las sondas locales de Codex Responses son la estrecha excepción: OpenClaw añade una instrucción mínima del sistema para que el transporte pueda rellenar su campo requerido instructions, sin añadir el contexto completo del agente, herramientas, memoria o transcripción de la sesión.
  • El model run --file local mantiene esa ruta ligera y adjunta el contenido de la imagen directamente al mensaje único del usuario. Los archivos de imagen comunes como PNG, JPEG y WebP funcionan cuando su tipo MIME se detecta como image/*; los archivos no admitidos o no reconocidos fallan antes de que se llame al proveedor.
  • model run --file es lo mejor cuando desea probar directamente el modelo de texto multimodal seleccionado. Use infer image describe cuando desee la selección del proveedor de comprensión de imágenes de OpenClaw y el enrutamiento predeterminado del modelo de imagen.
  • El modelo seleccionado debe admitir la entrada de imagen; los modelos de solo texto pueden rechazar la solicitud en la capa del proveedor.
  • model run --prompt debe contener texto que no sea solo espacios en blanco; los mensajes vacíos se rechazan antes de llamar a los proveedores locales o a la Gateway.
  • El model run local sale con un valor distinto de cero cuando el proveedor no devuelve ninguna salida de texto, por lo que los proveedores locales inalcanzables y las finalizaciones vacías no parecen sondas exitosas.
  • Use model run --gateway cuando necesite probar el enrutamiento de la Gateway, la configuración del tiempo de ejecución del agente o el estado del proveedor administrado por la Gateway manteniendo la entrada del modelo sin procesar. Use openclaw agent o superficies de chat cuando desee el contexto completo del agente, herramientas, memoria y transcripción de la sesión.
  • model auth login, model auth logout y model auth status gestionan el estado de autenticación del proveedor guardado.

Imagen

Sección titulada «Imagen»

Use image para generación, edición y descripción.

Ventana de terminal
openclaw infer image generate --prompt "friendly lobster illustration" --json
openclaw infer image generate --prompt "cinematic product photo of headphones" --json
openclaw infer image generate --model openai/gpt-image-1.5 --output-format png --background transparent --prompt "simple red circle sticker on a transparent background" --json
openclaw infer image generate --prompt "slow image backend" --timeout-ms 180000 --json
openclaw infer image edit --file ./logo.png --model openai/gpt-image-1.5 --output-format png --background transparent --prompt "keep the logo, remove the background" --json
openclaw infer image edit --file ./poster.png --prompt "make this a vertical story ad" --size 2160x3840 --aspect-ratio 9:16 --resolution 4K --json
openclaw infer image describe --file ./photo.jpg --json
openclaw infer image describe --file https://example.com/photo.png --json
openclaw infer image describe --file ./receipt.jpg --prompt "Extract the merchant, date, and total" --json
openclaw infer image describe-many --file ./before.png --file ./after.png --prompt "Compare the screenshots and list visible UI changes" --json
openclaw infer image describe --file ./ui-screenshot.png --model openai/gpt-5.4-mini --json
openclaw infer image describe --file ./photo.jpg --model ollama/qwen2.5vl:7b --prompt "Describe the image in one sentence" --timeout-ms 300000 --json

Notas:

  • Use image edit cuando comience a partir de archivos de entrada existentes.

  • Use --size, --aspect-ratio, or --resolution with image edit for providers/models that support geometry hints on reference-image edits.

  • Use --output-format png --background transparent with --model openai/gpt-image-1.5 for transparent-background OpenAI PNG output; --openai-background remains available as an OpenAI-specific alias. Providers that do not declare background support report the hint as an ignored override.

  • Use image providers --json to verify which bundled image providers are discoverable, configured, selected, and which generation/edit capabilities each provider exposes.

  • Use image generate --model <provider/model> --json as the narrowest live CLI smoke for image generation changes. Example:

    Ventana de terminal
    openclaw infer image providers --json
    openclaw infer image generate \
      --model google/gemini-3.1-flash-image-preview \
      --prompt "Minimal flat test image: one blue square on a white background, no text." \
      --output ./openclaw-infer-image-smoke.png \
      --json

    The JSON response reports ok, provider, model, attempts, and written output paths. When --output is set, the final extension may follow the provider’s returned MIME type.

  • For image describe and image describe-many, use --prompt to give the vision model a task-specific instruction such as OCR, comparison, UI inspection, or concise captioning.

  • Use --timeout-ms with slow local vision models or cold Ollama starts.

  • For image describe, --model must be an image-capable <provider/model>.

  • For local Ollama vision models, pull the model first and set OLLAMA_API_KEY to any placeholder value, for example ollama-local. See Ollama.

Audio

Sección titulada «Audio»

Use audio for file transcription.

Ventana de terminal
openclaw infer audio transcribe --file ./memo.m4a --json
openclaw infer audio transcribe --file ./team-sync.m4a --language en --prompt "Focus on names and action items" --json
openclaw infer audio transcribe --file ./memo.m4a --model openai/whisper-1 --json

Notas:

  • audio transcribe is for file transcription, not realtime session management.
  • --model must be <provider/model>.

TTS

Sección titulada «TTS»

Use tts for speech synthesis and TTS provider state.

Ventana de terminal
openclaw infer tts convert --text "hello from openclaw" --output ./hello.mp3 --json
openclaw infer tts convert --text "Your build is complete" --output ./build-complete.mp3 --json
openclaw infer tts providers --json
openclaw infer tts status --json

Notas:

  • tts status defaults to gateway because it reflects gateway-managed TTS state.
  • Use tts providers, tts voices, y tts set-provider para inspeccionar y configurar el comportamiento de TTS.

Video

Sección titulada «Video»

Use video para la generación y la descripción.

Ventana de terminal
openclaw infer video generate --prompt "cinematic sunset over the ocean" --json
openclaw infer video generate --prompt "slow drone shot over a forest lake" --resolution 768P --duration 6 --json
openclaw infer video describe --file ./clip.mp4 --json
openclaw infer video describe --file ./clip.mp4 --model openai/gpt-5.4-mini --json

Notas:

  • video generate acepta --size, --aspect-ratio, --resolution, --duration, --audio, --watermark y --timeout-ms y los reenvía al tiempo de ejecución de generación de video.
  • --model debe ser <provider/model> para video describe.

Web

Sección titulada «Web»

Use web para flujos de trabajo de búsqueda y recuperación.

Ventana de terminal
openclaw infer web search --query "OpenClaw docs" --json
openclaw infer web search --query "OpenClaw infer web providers" --json
openclaw infer web fetch --url https://docs.openclaw.ai/cli/infer --json
openclaw infer web providers --json

Notas:

  • Use web providers para inspeccionar los proveedores disponibles, configurados y seleccionados.

Embedding

Sección titulada «Embedding»

Use embedding para la creación de vectores y la inspección de proveedores de incrustaciones.

Ventana de terminal
openclaw infer embedding create --text "friendly lobster" --json
openclaw infer embedding create --text "customer support ticket: delayed shipment" --model openai/text-embedding-3-large --json
openclaw infer embedding providers --json

Salida JSON

Sección titulada «Salida JSON»

Los comandos de inferencia normalizan la salida JSON bajo un sobre compartido:

{
  "ok": true,
  "capability": "image.generate",
  "transport": "local",
  "provider": "openai",
  "model": "gpt-image-2",
  "attempts": [],
  "outputs": []
}

Los campos de nivel superior son estables:

  • ok
  • capability
  • transport
  • provider
  • model
  • attempts
  • outputs
  • error

Para los comandos de medios generados, outputs contiene los archivos escritos por OpenClaw. Use path, mimeType, size y cualquier dimensión específica del medio en esa matriz para la automatización en lugar de analizar el stdout legible por humanos.

Errores comunes

Sección titulada «Errores comunes»
Ventana de terminal
# Bad
openclaw infer media image generate --prompt "friendly lobster"


# Good
openclaw infer image generate --prompt "friendly lobster"
Ventana de terminal
# Bad
openclaw infer audio transcribe --file ./memo.m4a --model whisper-1 --json


# Good
openclaw infer audio transcribe --file ./memo.m4a --model openai/whisper-1 --json

Notas

Sección titulada «Notas»
  • openclaw capability ... es un alias de openclaw infer ....

Relacionado

Sección titulada «Relacionado»