OpenClaw Inference CLI: Unified Provider-Backed Model, Image, Audio, TTS, Video, Web, and Embedding Commands

openclaw infer serves as the primary non-interactive interface for inference backed by providers. Rather than exposing raw gateway RPC names or agent tool identifiers, it offers capability families (model, image, audio, tts, video, web, embedding). The same command tree is also reachable via openclaw capability ....

Choosing this over a one-off provider wrapper has several advantages:

• Providers and models already set up in OpenClaw are reused.
• A consistent --json envelope is maintained for scripts and agent-driven automation, as detailed in JSON output.
• Most subcommands execute the standard local path, bypassing the gateway.
• For full provider validation, the shipped CLI, config loading, default-agent resolution, bundled plugin activation, and the shared capability runtime are all exercised before the provider request is sent.

Turn infer into a skill

Paste the following into an agent:

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.

A well-designed infer-based skill translates common user intents into the appropriate subcommand, provides a few canonical examples for each workflow, favors openclaw infer ... over lower-level options, and avoids restating the entire infer surface within the skill body.

Command tree

 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
    personas
    status
    enable
    disable
    set-provider
    set-persona

  video
    generate
    describe
    providers

  web
    search
    fetch
    providers

  embedding
    create
    providers

The tree is presented as data by infer list / infer inspect --name <capability>, including capability id, transports, and description.

Common tasks

Behavior

• When the output is destined for another command or script, choose --json; otherwise, stick with plain text.
• To lock in a particular backend, reach for --provider or --model provider/model.
• At least one --file is mandatory for image edit and image describe-many, while embedding create needs a minimum of one --text. For multiple inputs, repeat the flag. Leaving it out counts as a usage error, not a successful empty run, and no inference request gets dispatched.
• For a single-shot thinking or reasoning override, use model run --thinking <level> with one of these values: off, minimal, low, medium, high, adaptive, xhigh, or max.
• When dealing with image describe, audio transcribe, or video describe, --model has to follow the <provider/model> pattern.
• In the case of image describe, --file takes both local paths and HTTP(S) URLs; remote addresses go through the standard media-fetch SSRF policy.
• Commands that run without state (model run, image *, audio *, video *, web *, embedding *) fall back to local by default. Those that manage gateway-held state (tts status) default to gateway.
• The gateway does not need to be up for the local path.
• Provider inventory commands, whose configured state can originate from stored agent auth, will accept --agent <id>. Without it, they rely on agents.defaults.systemAgent.agentId or the single configured agent; fleets with multiple agents and no system owner must supply --agent. The provider catalog stays aggregate, and --agent narrows saved-auth and per-agent selection details. Since gateway-owned TTS provider state is Gateway-global, tts providers --gateway rejects --agent.
• Commands that pull agent-owned model or auth state (model run, image generate, image edit, image describe, image describe-many, audio transcribe, video generate, video describe, embedding create, and model auth login/logout/status) also take --agent <id>. They check an explicit id first, then agents.defaults.systemAgent.agentId, then the sole configured agent.
• Generated image and video --output files are staged next to the target location and only overwrite it once the entire buffer is written; if the write fails, any existing destination stays untouched.
• Local model run performs a lean, one-shot provider completion: it pulls the configured agent model and auth but skips starting a chat-agent turn, loading tools, or opening bundled MCP servers.
• model run --file attaches image files (MIME type auto-detected) to the prompt; for multiple images, repeat --file. Anything that is not an image gets rejected, so use infer audio transcribe or infer video describe in those cases.
• model run --gateway goes through Gateway routing, saved auth, provider selection, and the embedded runtime, yet remains a raw model probe: no prior session transcript, bootstrap/AGENTS context, tools, or bundled MCP servers are involved.
• model run --gateway --model <provider/model> needs a trusted-operator gateway credential, since it asks the Gateway to apply a one-off provider/model override.

Model

Text inference and model/provider inspection.

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 --agent <id> --json
openclaw infer model inspect --model gpt-5.6-sol --json

Use complete <provider/model> references combined with --local to run a quick provider check without launching the Gateway or loading the agent tool surface:

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.6-luna --prompt "Reply with exactly: pong" --json
openclaw infer model run --local --model ollama/qwen2.5vl:7b --prompt "Describe this image." --file ./photo.jpg --json

Notes:

• For provider/model/auth health, local model run offers the most minimal CLI test: with non-ChatGPT-Codex providers, only the given prompt gets transmitted.
• Local model run --model <provider/model> can pull exact rows from the bundled static catalog (identical to what openclaw models list --all displays) even before that provider appears in config. Provider auth remains mandatory; absent credentials surface as authentication failures rather than Unknown model.
• When probing Mistral Medium 3.5 reasoning, keep temperature at its default. Mistral responds to reasoning_effort="high" with temperature: 0; stick with default temperature or pick a non-zero value like 0.7.
• For OpenAI ChatGPT/Codex OAuth (the openai-chatgpt-responses API), local probes inject a tiny system instruction so the transport can fill its mandatory instructions field, leaving out full agent context, tools, memory, and session transcript.
• model run --file attaches image content straight onto the single user message. Standard formats such as PNG, JPEG, and WebP work when the MIME type resolves to image/*; files that are unsupported or unrecognized fail before the provider gets invoked. Choose infer image describe instead when you prefer OpenClaw's image-model routing and fallback behavior over a direct multimodal-model probe.
• The chosen model has to accept image input; text-only models may decline the request at the provider layer.
• model run --prompt needs non-whitespace text; empty prompts get rejected prior to any provider or Gateway call.
• Local model run returns a non-zero exit code when the provider yields no text output, so unreachable providers and empty completions never masquerade as successful probes.
• To exercise Gateway routing or agent-runtime setup while leaving the model input untouched, use model run --gateway. For full agent context, tools, memory, and session transcript, turn to openclaw agent or a chat surface.
• --thinking adaptive corresponds to the completion-runtime level medium; --thinking max corresponds to max for OpenAI models that support native max effort, otherwise xhigh.
• Saved provider auth state is managed through model auth login, model auth logout, and model auth status.

Image

Generation, edit, and description.

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 --model openai/gpt-image-2 --quality low --openai-moderation low --prompt "low-cost draft poster" --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

Notes:

• Start from existing input files with image edit; geometry hints can be added via --size, --aspect-ratio, or --resolution on providers/models that support them.

• Pairing --output-format png --background transparent with --model openai/gpt-image-1.5 yields transparent-background PNG output from OpenAI; --openai-background serves as an OpenAI-specific alias for that same hint. Providers without declared background support flag it as an ignored override (see ignoredOverrides in the JSON envelope).

• --quality low|medium|high|auto applies to providers that honor image-quality hints, OpenAI included. OpenAI additionally accepts --openai-moderation low|auto.

• image providers --json shows which bundled image providers are discoverable, configured, selected, and what generation/edit capabilities each one exposes.

• For image-generation changes, image generate --model <provider/model> --json is the most minimal live smoke test:

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

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

• For image describe and image describe-many, use --prompt to supply a task-specific instruction (OCR, comparison, UI inspection, concise captioning).

• Slow local vision models or cold Ollama starts call for --timeout-ms.

• With image describe, an explicit --model (which must be an image-capable <provider/model>) executes first, then falls back to configured agents.defaults.imageModel.fallbacks if that call fails. Input-preparation errors (missing file, unsupported URL) stop before any fallback attempt, and the model must be image-capable in the model catalog or provider config.

• 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

File transcription, not live session management.

openclaw infer audio transcribe --file ./memo.m4a --json
openclaw infer audio transcribe --agent <id> --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

--model is required to be <provider/model>.

TTS

Speech synthesis, TTS provider, and persona state.

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 convert --provider xiaomi --text "Provider-only selection" --output ./xiaomi.mp3 --json
openclaw infer tts providers --json
openclaw infer tts personas --json
openclaw infer tts status --json

Notes:

• Only --gateway is supported by tts status, since it mirrors the TTS state managed by the gateway.
• For local and loopback-Gateway tts convert --output, copies are staged next to the destination and swapped in only after success; when a copy fails, any pre-existing file stays untouched.
• Pick tts convert --provider <id> to choose a provider while leaving its model unmodified.
• To review and adjust TTS settings, rely on tts providers, tts voices, tts personas, tts set-provider, and tts set-persona.

Video

Generation and description.

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 --agent <id> --file ./clip.mp4 --json
openclaw infer video describe --file ./clip.mp4 --model openai/gpt-5.4-mini --json

Notes:

• video generate takes --size, --aspect-ratio, --resolution, --duration, --audio, --watermark, and --timeout-ms, which get passed along to the video-generation runtime.
• When a provider hosts the video download, empty, text, and JSON responses are rejected rather than treated as a successful but unusable file.
• With --output, a URL-backed video streams to a sibling temporary file, and the destination is replaced only once the full non-empty download finishes; a failed stream leaves the existing destination as is.
• For video describe, --model must be set to <provider/model>.

Web

Search and fetch.

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 --agent <id> --json

Available, configured, and selected providers for search and fetch are listed by web providers.

Embedding

Vector creation and embedding-provider inspection.

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 --agent <id> --json

JSON output

Infer commands standardize JSON output under a common envelope:

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

Top-level fields that remain stable:

• ok
• capability
• transport
• provider
• model
• attempts
• inputs (image attachments sent with the request, if any)
• outputs
• ignoredOverrides (hint keys a provider does not support, if any)
• error

For generated media commands, files written by OpenClaw are held in outputs. Automate against the path, mimeType, size, and media-specific dimensions in that array instead of reading human-readable stdout.

Common pitfalls

# Bad
openclaw infer media image generate --prompt "friendly lobster"

# Good
openclaw infer image generate --prompt "friendly lobster"

# 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

Related

• CLI reference
• Models