Inference CLI

openclaw infer is the main headless command for provider-backed inference. It exposes capability families (model, image, audio, tts, video, web, embedding), not raw gateway RPC names or agent tool ids. openclaw capability ... is an alias for the same command tree.

Reasons to prefer it over a one-off provider wrapper:

• Reuses providers and models already configured in OpenClaw.
• Stable --json envelope for scripts and agent-driven automation (see JSON output).
• Runs the normal local path without the gateway for most subcommands.
• For end-to-end provider checks, it exercises the shipped CLI, config loading, default-agent resolution, bundled plugin activation, and the shared capability runtime before the provider request goes out.

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

infer list / infer inspect --name <capability> show this tree as data (capability id, transports, description).

Parent and subcommand help expose the full inference command tree without loading provider execution runtimes. These command definitions also supply inference shell-completion metadata.

Common tasks

Behavior

• Use --json when the output feeds another command or script; text output otherwise.
• Use --provider or --model provider/model to pin a specific backend.
• Explicitly empty or whitespace-only values for --limit, --count, --duration, and --timeout-ms are errors. Omit the flag to retain its default behavior.
• image edit and image describe-many require at least one --file; embedding create requires at least one --text. Repeat the flag for multiple inputs. Omitting it is a usage error, not an empty successful result, and no inference request is sent.
• Use model run --thinking <level> for a one-shot thinking/reasoning override: off, minimal, low, medium, high, adaptive, xhigh, or max.
• For image describe, audio transcribe, and video describe, --model must use the form <provider/model>.
• For image describe, --file accepts local paths and HTTP(S) URLs; remote URLs go through the normal media-fetch SSRF policy.
• Stateless execution commands (model run, image *, audio *, video *, web *, embedding *) default to local. Gateway-managed state commands (tts status) default to gateway.
• The local path never requires the gateway to be running.
• Provider inventory commands whose configured state can come from saved agent auth accept --agent <id>. Without it, they use agents.defaults.systemAgent.agentId or the sole configured agent; explicit multi-agent fleets with no system owner must pass --agent. The provider catalog remains aggregate; --agent scopes saved-auth and per-agent selection facts. Gateway-owned TTS provider state remains Gateway-global, so tts providers --gateway does not accept --agent.
• Commands that resolve 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 accept --agent <id>. They resolve an explicit id first, then agents.defaults.systemAgent.agentId, then the sole configured agent.
• Generated image and video --output files are staged beside the destination and replace it only after the complete buffer is written; a failed write leaves an existing destination unchanged. An interrupt cancels image generation or editing and discards late provider results before output writes begin. It also stops an in-progress provider-URL video download instead of letting it finish and publish a late result.
• Ctrl-C or SIGTERM cancels image description downloads and provider requests, and prevents later model fallback attempts.
• Local model run is a lean one-shot provider completion: it resolves the configured agent model and auth but does not start a chat-agent turn, load tools, or open bundled MCP servers.
• Model runs load the catalog for case correction only when an explicit model override contains uppercase characters. Runs using the configured default or a lowercase model ref skip that catalog lookup.
• model run --file attaches image files (auto-detected MIME type) to the prompt; repeat --file for multiple images. Non-image files are rejected — use infer audio transcribe or infer video describe instead.
• Local model run --file requires an image-capable model and fails before the provider call when the model's catalog input is text-only. model run --gateway --file instead offloads images for text-only models and describes them through the Gateway's media understanding.
• model run --gateway exercises Gateway routing, saved auth, provider selection, and the embedded runtime, but stays a raw model check: no prior session transcript, bootstrap/AGENTS context, tools, or bundled MCP servers.
• model run --gateway --model <provider/model> requires a trusted-operator gateway credential, because it asks the Gateway to run a one-off provider/model override.

Model

Text inference and model/provider inspection.

model list, model inspect, and model providers read the selected agent's model catalog. They preserve configured model details and exclude models outside that catalog. Use infer model --agent <id> list --json or infer model --agent <id> inspect --model <provider/model> --json to select an agent. Provider counts use the same inventory.

openclaw infer model run --prompt "Reply with exactly: smoke-ok" --jsonopenclaw infer model run --prompt-file ./prompts/judge.txt --jsonopenclaw infer model run --prompt-stdin --json < ./prompts/judge.txtopenclaw infer model run --prompt "Summarize this changelog entry" --model openai/gpt-5.4 --jsonopenclaw infer model run --prompt "Describe this image in one sentence" --file ./photo.jpg --model google/gemini-2.5-flash --jsonopenclaw infer model run --prompt "Use more reasoning here" --thinking high --jsonopenclaw infer model providers --agent <id> --jsonopenclaw infer model inspect --model gpt-6-astra --json

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

openclaw infer model run --local --model anthropic/claude-sonnet-4-6 --prompt "Reply with exactly: pong" --jsonopenclaw infer model run --local --model cerebras/gpt-oss-120b --prompt "Reply with exactly: pong" --jsonopenclaw infer model run --local --model google/gemini-2.5-flash --prompt "Reply with exactly: pong" --jsonopenclaw infer model run --local --model groq/openai/gpt-oss-120b --prompt "Reply with exactly: pong" --jsonopenclaw infer model run --local --model llmman/qwen3.8 --prompt "Reply with exactly: pong" --jsonopenclaw infer model run --local --model llmman/gemma4:e4b --prompt "Describe this image." --file ./photo.jpg --jsonopenclaw infer model run --local --model mistral/mistral-medium-3-5 --prompt "Reply with exactly: pong" --jsonopenclaw infer model run --local --model mistral/mistral-small-latest --prompt "Reply with exactly: pong" --jsonopenclaw infer model run --local --model openai/gpt-5.6-luna --prompt "Reply with exactly: pong" --jsonopenclaw infer model run --local --model ollama/qwen2.5vl:7b --prompt "Describe this image." --file ./photo.jpg --json

Notes:

• Local model run is the narrowest CLI smoke for provider/model/auth health: for non-ChatGPT-Codex providers it sends only the supplied prompt.
• Local model run --model <provider/model> can resolve exact bundled static-catalog rows (the same rows openclaw models list --all shows) before that provider is written to config. Provider auth is still required; missing credentials fail as auth errors, not Unknown model.
• For Mistral Medium 3.5 reasoning checks, leave temperature unset/default. Mistral rejects reasoning_effort="high" with temperature: 0; use default temperature or a non-zero value such as 0.7.
• OpenAI ChatGPT/Codex OAuth (openai-chatgpt-responses API) local checks add a minimal system instruction so the transport can populate its required instructions field — no full agent context, tools, memory, or session transcript.
• model run --file attaches image content directly to the single user message. Common formats (PNG, JPEG, WebP) work when MIME type is detected as image/*; unsupported or unrecognized files fail before the provider is called. Use infer image describe instead when you want OpenClaw's image-model routing and fallbacks rather than a direct multimodal-model check.
• The selected model must support image input; text-only models may reject the request at the provider layer.
• Use exactly one of model run --prompt <text>, --prompt-file <path>, or --prompt-stdin. The file path must be relative to the current directory and remain inside it; symlinks and hardlinks are rejected. File and stdin input are read at invocation time as UTF-8 with a 1 MiB limit. Malformed UTF-8 files are rejected rather than silently replacing invalid bytes. Stdin is read only with --prompt-stdin; invalid UTF-8, read errors, and overflow fail before inference. Empty or whitespace-only prompts are rejected before any provider or Gateway call. File and stdin input keep prompt text out of process arguments and do not add it to command output or a chat transcript; the selected provider still receives the prompt.
• Local model run exits non-zero for empty output or a failed/aborted response, even when partial text was received. These runs do not emit a successful JSON envelope.
• model run --gateway also exits non-zero when the Gateway reports a failed, timed-out, or cancelled run, preserving its error detail instead of wrapping the reply in a successful JSON envelope.
• When a completed response contains only reasoning and no final text, local model run reports that it returned reasoning but no text output, and notes when it stopped at the output token limit. Failed or aborted responses keep the generic no-text error with any provider error detail. Reasoning content is not printed as the answer.
• Use model run --gateway to test Gateway routing or agent-runtime setup while keeping the model input raw. Use openclaw agent or a chat surface for full agent context, tools, memory, and session transcript.
• --thinking adaptive maps to the completion-runtime level medium; --thinking max maps to max for OpenAI models that support the native max effort, otherwise xhigh.
• model auth login, model auth logout, and model auth status manage saved provider auth state.
• An interrupt accepted during generation cancels the in-flight local request or Gateway call and stops waiting for it instead of letting the run finish, and publishes no output for the interrupted run.
• For model run --gateway, interruption cancels the caller's RPC and does not change the lifetime of Gateway-owned generation.

Image

Generation, edit, and description.

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

Notes:

• Use image edit when starting from existing input files; --size, --aspect-ratio, or --resolution add geometry hints on providers/models that support them.

• image edit --file accepts regular files and symlinks to regular files. Special files such as FIFOs are refused before any provider request.

• image generate and image edit accept positive numeric W:H aspect ratios, including 7:5 and 1.5:1. Malformed values such as 16x9, 16/9, or 0:5 fail before a provider request or output file is created.

• --output-format png --background transparent with --model openai/gpt-image-1.5 gives transparent-background OpenAI PNG output; --openai-background is an OpenAI-specific alias for the same hint. Providers that do not declare background support report it as an ignored override (see ignoredOverrides in the JSON envelope).

• --quality low|medium|high|auto works for providers that support image-quality hints, including OpenAI. OpenAI also accepts --openai-moderation low|auto.

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

• image generate --model <provider/model> --json is the narrowest live smoke for image-generation changes:

  openclaw infer image providers --jsonopenclaw 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 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 for a task-specific instruction (OCR, comparison, UI inspection, concise captioning).

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

• For image describe, an explicit --model (must be an image-capable <provider/model>) runs first, then tries configured agents.defaults.imageModel.fallbacks if that call fails. Input-preparation errors (missing file, unsupported URL) fail 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.

• For llmman vision models such as llmman/gemma4:e4b, configure the llmman provider with input: ["text", "image"] on the model entry and set LLMMAN_API_KEY to a placeholder such as llmman-local. See llmman.

Audio

File transcription (not realtime session management).

openclaw infer audio transcribe --file ./memo.m4a --jsonopenclaw infer audio transcribe --agent <id> --file ./memo.m4a --jsonopenclaw infer audio transcribe --file ./team-sync.m4a --language en --prompt "Focus on names and action items" --jsonopenclaw infer audio transcribe --file ./memo.m4a --model openai/whisper-1 --json

--model must be <provider/model>.

An accepted interrupt cancels the pending transcription request and suppresses late transcript output.

The same cancellation behavior applies to infer video describe: interruption stops the pending provider request and suppresses late description output.

For audio transcription and video description on POSIX systems, --file follows directory symlinks before resolving .., matching filesystem path resolution. Final-file symlinks remain subject to the existing media-directory checks.

For CLI-backed transcription, the result's provider identifies the tool family and model reports the executed command. Auto-detected tools report their resolved executable path; explicit CLI entries retain their authored command value. This field does not identify the speech model loaded internally by the tool.

TTS

Speech synthesis and TTS provider/persona state.

openclaw infer tts convert --text "hello from openclaw" --output ./hello.mp3 --jsonopenclaw infer tts convert --text "Your build is complete" --output ./build-complete.mp3 --jsonopenclaw infer tts convert --provider xiaomi --text "Provider-only selection" --output ./xiaomi.mp3 --jsonopenclaw infer tts convert --channel telegram --text "Voice-note format" --output ./voice.opus --jsonopenclaw infer tts providers --jsonopenclaw infer tts personas --jsonopenclaw infer tts status --json

Notes:

• tts status only supports --gateway (it reflects gateway-managed TTS state).
• Local and loopback-Gateway tts convert --output copies stage beside the destination and replace it only after success; a failed copy leaves an existing file unchanged.
• If interruption is accepted before the output copy begins, tts convert leaves the requested destination unchanged. Completed synthesis audio remains in the media store for its normal lifetime.
• Interrupting tts convert --gateway cancels the caller's pending RPC and exits with status 130 without printing a late result. Gateway-owned speech synthesis keeps its existing lifetime.
• Remote-Gateway tts convert --output is rejected before requesting speech synthesis.
• Use tts convert --provider <id> when selecting a provider without overriding its model.
• --channel <id> is an output-format hint, not a delivery request. Local conversion uses bundled voice capabilities even without a loaded channel account; Telegram requests voice-note audio (Opus with OpenAI) instead of the default MP3 audio file.
• Use tts providers, tts voices, tts personas, tts set-provider, and tts set-persona to inspect and configure TTS behavior.

Video

Generation and description.

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

Notes:

• video generate accepts --size, --aspect-ratio, --resolution, --duration, --audio, --watermark, and --timeout-ms, forwarded to the video-generation runtime.
• --duration is a number of seconds that must round to 1–9007199254740991 seconds. Zero, negative, nonnumeric, and smaller values that round to zero fail before provider dispatch. Valid fractions such as 2.5 retain normal provider-supported rounding; omitting the flag keeps the provider default.
• Provider-hosted video downloads reject empty, text, and JSON responses instead of reporting an unusable file as successful output.
• With --output, URL-backed video streams to a sibling temporary file and replaces the destination only after the complete non-empty download succeeds; a failed stream leaves an existing destination unchanged.
• --model must be <provider/model> for video describe.

Web

Search and fetch.

openclaw infer web search --query "OpenClaw docs" --jsonopenclaw infer web search --query "OpenClaw infer web providers" --jsonopenclaw infer web fetch --url https://docs.openclaw.ai/cli/infer --jsonopenclaw infer web providers --agent <id> --json

web providers lists available, configured, and selected providers for search and fetch.

Interrupting web search or fetch forwards cancellation to the request and suppresses late provider results and failures.

Embedding

Vector creation and embedding-provider inspection.

openclaw infer embedding create --text "friendly lobster" --jsonopenclaw infer embedding create --text "customer support ticket: delayed shipment" --model openai/text-embedding-3-large --jsonopenclaw infer embedding providers --agent <id> --json

--model takes <provider/model>. When you also pass --provider, it must match that prefix; model ids that contain a slash keep the provider prefix, for example --model deepinfra/Qwen/Qwen3-Embedding-8B.

Without --json, embedding create shows the provider and model, followed by each input, its dimension count, and a preview of the first eight vector values. Longer vectors end with ...; use --json to retrieve complete vectors.

An accepted interrupt forwards cancellation to the embedding provider and suppresses output from the interrupted batch.

JSON output

Infer commands normalize JSON output under a shared envelope:

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

Stable top-level fields:

• ok
• capability
• transport
• provider
• model
• usage (observed model-run usage, when available)
• lastCallUsage (observed usage from the last model API call, when available)
• attempts
• inputs (image attachments sent with the request, when applicable)
• outputs
• ignoredOverrides (hint keys a provider does not support, when applicable)
• error

For model.run, both transports expose normalized token counts such as input, output, cacheRead, cacheWrite, reasoningTokens, and total, plus usage availability and recorded cost metadata when supplied. Missing observations are omitted; adapter-default zeros are not treated as measurements. Explicitly measured zero counts are preserved, and explicitly unavailable usage is represented by usageReport.state: "unavailable" without invented token counts or cost.

With --local, a run is one completion, so usage and lastCallUsage contain the same snapshot. With --gateway, usage keeps the runtime's aggregate billing usage (which can span multiple calls or candidates), while lastCallUsage describes only the last physical API call. Cost values and their provenance come from the existing runtime accounting; the CLI does not estimate them.

For generated media commands, outputs contains files written by OpenClaw. Use the path, mimeType, size, and any media-specific dimensions in that array for automation instead of parsing human-readable stdout.

Common pitfalls

# Badopenclaw infer media image generate --prompt "friendly lobster" # Goodopenclaw infer image generate --prompt "friendly lobster"

# Badopenclaw infer audio transcribe --file ./memo.m4a --model whisper-1 --json # Goodopenclaw infer audio transcribe --file ./memo.m4a --model openai/whisper-1 --json

Turn infer into a skill

Copy and paste this to 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 good infer-based skill maps common user intents to the right subcommand, includes a few standard examples per workflow, prefers openclaw infer ... over lower-level alternatives, and does not re-document the entire infer surface in the skill body.

Related

• CLI reference
• Models