Inference CLI: Headless Infer for Provider-Backed Workflows

openclaw infer serves as the primary headless interface for inference backed by providers. It exposes capability groups (model, image, audio, tts, video, web, embedding) rather than raw gateway RPC names or agent tool identifiers. openclaw capability ... provides an alternative name for the same command structure.

Choose this approach over a custom provider wrapper for these reasons:

• Providers and models already set up in OpenClaw are reused.
• A stable --json envelope is available for scripts and agent-driven automation (refer to JSON output).
• Most subcommands run through the normal local path, bypassing the gateway.
• For full provider verification, 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

Copy this and provide it 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.

An effective infer-based skill maps typical user requests to the appropriate subcommand, includes a few standard examples for each workflow, favors openclaw infer ... over lower-level options, and avoids re-documenting 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

infer list and infer inspect --name <capability> display this tree as data, including capability ID, transports, and description.

Common tasks

Behavior

• Pick --json when the result goes into another command or script; otherwise use plain text output.
• To lock in a particular backend, specify --provider or --model provider/model.
• For a single thinking or reasoning override, pass model run --thinking <level> with one of these values: off, minimal, low, medium, high, adaptive, xhigh, or max.
• When working with image describe, audio transcribe, and video describe, the --model parameter must follow the <provider/model> pattern.
• For image describe, --file accepts both local file paths and HTTP(S) links; remote URLs are subject to the standard SSRF policy for media fetching.
• Stateless execution commands (model run, image *, audio *, video *, web *, embedding *) use the local backend by default. Commands that manage gateway state (tts status) default to the gateway backend.
• The local path does not need the gateway to be running.
• In local mode, model run acts as a minimal one-shot provider completion: it resolves the configured agent model and its authentication, but does not initiate a chat agent turn, load tools, or open any bundled MCP servers.
• model run --file attaches image files (MIME type is detected automatically) to the prompt; repeat --file for several images. Non-image files are refused, use infer audio transcribe or infer video describe in that case.
• model run --gateway tests Gateway routing, stored authentication, provider selection, and the embedded runtime, but remains a raw model probe: no prior session transcript, bootstrap or AGENTS context, tools, or bundled MCP servers.
• model run --gateway --model <provider/model> needs a trusted operator gateway credential, because it tells the Gateway to execute a one off provider or model override.

Model

Model and provider inspection with text inference.

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 --model gpt-5.6-sol --json

To test one provider without launching the Gateway or loading the agent tool surface, use complete <provider/model> references together with --local:

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:

• The narrowest CLI smoke test for provider, model, and auth health is model run in local mode: for providers other than ChatGPT-Codex, it transmits only the prompt you provide.
• Before a provider is saved to config, model run --model <provider/model> can pinpoint exact rows from the bundled static catalog (the same rows displayed by openclaw models list --all). Provider authentication remains mandatory; absent credentials produce auth errors, not Unknown model.
• For Mistral Medium 3.5 reasoning probes, leave temperature at its default or unset. Mistral rejects reasoning_effort="high" with temperature: 0; apply the default temperature or a nonzero value like 0.7.
• Local probes for OpenAI ChatGPT/Codex OAuth (the openai-chatgpt-responses API) inject a minimal system instruction so the transport can fill its required instructions field, no full agent context, tools, memory, or session transcript is included.
• model run --file attaches image content directly to the single user message. Common formats (PNG, JPEG, WebP) work when the 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 probe.
• The chosen model must support image input; text-only models may reject the request at the provider layer.
• model run --prompt must contain non-whitespace text; empty prompts are rejected before any provider or Gateway call.
• Local model run exits non-zero when the provider returns no text output, so unreachable providers and empty completions do not appear as successful probes.
• 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.

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:

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

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

Audio

File transcription (not realtime session management).

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

--model must be <provider/model>.

TTS

TTS provider and persona state for speech synthesis.

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 personas --json
openclaw infer tts status --json

Remarks:

• Only tts status is supported by --gateway, as it mirrors TTS state managed through the gateway.
• To review or adjust TTS settings, use tts providers, tts voices, tts personas, tts set-provider, and tts set-persona.

Video

Description and generation.

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

Remarks:

• video generate forwards --size, --aspect-ratio, --resolution, --duration, --audio, --watermark, and --timeout-ms to the video generation runtime.
• For video describe to work, --model must be set to <provider/model>.

Web

Fetch and search.

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

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

Embedding

Embedding provider inspection and vector creation.

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

JSON output

A shared envelope normalizes JSON output across all infer commands:

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

Stable fields at the top level:

• ok
• capability
• transport
• provider
• model
• attempts
• inputs (any image attachments included with the request)
• outputs
• ignoredOverrides (hint keys unsupported by the provider, where applicable)
• error

For media generation commands, outputs holds files created by OpenClaw. Rather than parsing human readable stdout, rely on path, mimeType, size, and any media specific dimensions inside that array for automation.

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