openclaw infer 是 OpenClaw 的核心推理 CLI，提供模型文本生成、图像生成/编辑/描述、音频转录、语音合成、视频生成/描述、网页搜索/抓取和嵌入创建等能力。使用 --json 输出可方便脚本和自动化集成；本地模型运行无需启动 Gateway，但图像描述和音频转录等命令的 --model 参数必须指定完整的 provider/model 格式。常见任务表覆盖 90% 的日常推理需求，JSON 输出信封包含 ok、capability、provider、model、outputs 等稳定字段。

OpenClaw infer CLI 命令参考：模型、图像、音频等推理操作

openclaw infer 是 OpenClaw 面向提供者（provider）支持的推理工作流的正式无头（headless）CLI。

它按能力族暴露命令，而不是直接暴露底层网关 RPC 或智能体工具 ID。

将 infer 转换成技能（skill）

复制以下提示词给智能体：

text

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.

一个好的 infer 技能应该：

将常见用户意图映射到正确的 infer 子命令
包含几个该技能覆盖工作流的典型 infer 示例
在示例和建议中优先使用 openclaw infer ...
避免在技能体内重新文档化整个 infer 表面

典型的 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

为什么使用 infer

openclaw infer 为 OpenClaw 内部的 provider 推理任务提供统一的 CLI。

优势：

使用 OpenClaw 已配置的 provider 和模型，而不是为每个后端单独编写适配器。
将模型、图像、音频转录、TTS、视频、网页搜索和嵌入工作流保持在同一命令树下。
使用稳定的 --json 输出结构，方便脚本、自动化和智能体驱动的工作流。
当任务本质是“运行推理”时，优先使用 OpenClaw 的一等 CLI 表面。
大多数 infer 命令使用正常本地路径（不需要 Gateway）。

对于端到端的 provider 检查，建议在底层 provider 测试通过后使用 openclaw infer ...。它会测试已交付的 CLI、配置加载、默认智能体解析、内置插件激活以及共享能力运行时，之后才发出 provider 请求。

命令树

text

 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

常见任务速查表

任务	命令	备注
运行文本/模型提示词	`openclaw infer model run --prompt "..." --json`	默认使用正常本地路径
对图像运行模型提示词	`openclaw infer model run --prompt "Describe this" --file ./image.png --model provider/model`	重复 `--file` 可传入多张图
生成图像	`openclaw infer image generate --prompt "..." --json`	从已有文件修改时用 `image edit`
描述图像文件或 URL	`openclaw infer image describe --file ./image.png --prompt "..." --json`	`--model` 必须是支持图像的 `provider/model`
转录音频	`openclaw infer audio transcribe --file ./memo.m4a --json`	`--model` 必须是 `provider/model`
语音合成	`openclaw infer tts convert --text "..." --output ./speech.mp3 --json`	`tts status` 面向 Gateway
生成视频	`openclaw infer video generate --prompt "..." --json`	支持 `--resolution` 等 provider 提示
描述视频文件	`openclaw infer video describe --file ./clip.mp4 --json`	`--model` 必须是 `provider/model`
搜索网页	`openclaw infer web search --query "..." --json`
抓取网页	`openclaw infer web fetch --url https://example.com --json`
创建嵌入向量	`openclaw infer embedding create --text "..." --json`

行为说明

openclaw infer ... 是这些工作流的主要 CLI 表面。
当输出将由另一个命令或脚本消费时，使用 --json。
当需要指定特定后端时，使用 --provider 或 --model provider/model。
使用 model run --thinking <level> 传递一次性思考/推理级别（off, minimal, low, medium, high, adaptive, xhigh, max），保持 raw 模式运行。
对于 image describe、audio transcribe 和 video describe，--model 必须使用 <provider/model> 形式。
对于 image describe，--file 接受本地路径和 HTTP(S) 图像 URL。远程 URL 遵循正常的媒体获取 SSRF 策略。
对于 image describe，显式指定 --model 时使用该 provider/model 直接运行。该模型必须在模型目录或 provider 配置中声明支持图像能力。codex/<model> 运行一次有界的 Codex 应用服务器图像理解回合；openai-codex/<model> 使用 OpenAI Codex OAuth provider 路径。
无状态执行命令默认使用本地路径。
Gateway 管理状态的命令默认使用 Gateway。
正常本地路径不需要 Gateway 正在运行。
本地 model run 是一次精简的 provider 补全。它解析配置的智能体模型和认证，但不会启动聊天智能体回合、加载工具或打开绑定的 MCP 服务器。
model run --file 接受图像文件，自动检测 MIME 类型，并将图像与提供的提示词一起发送给选定的模型。重复 --file 可传入多张图。
model run --file 拒绝非图像输入。对于音频文件使用 infer audio transcribe，对于视频文件使用 infer video describe。
model run --gateway 会经过 Gateway 路由、已保存认证、provider 选择和内置运行时，但它仍然是 raw 模型探测：只发送提供的提示词和图像附件，没有之前的会话文本、引导/AGENTS 上下文、上下文引擎组装、工具或绑定的 MCP 服务器。
model run --gateway --model <provider/model> 需要一个受信任的操作者 Gateway 凭证，因为请求要求 Gateway 运行一次性的 provider/model 覆盖。
本地 model run --thinking 使用精简的 provider 补全路径；provider 特定的级别（如 adaptive 和 max）会被映射到最接近的可移植简单补全级别。

model 子命令

用于 provider 支持的文本推理和模型/provider 检查。

bash

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

使用完整 <provider/model> 引用在无需启动 Gateway 或加载完整智能体工具表面的情况下测试特定 provider：

bash

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

注意事项：

本地 model run 是最窄的 provider/model/auth 健康检查 CLI，因为对于非 Codex provider，它只将提供的提示词发送给选定模型。
本地 model run --model <provider/model> 可以使用 models list --all 中精确的内置静态目录行，即使该 provider 尚未写入配置。provider 认证仍然必需；缺少凭据会以认证错误（而非“Unknown model”）失败。
对于 Mistral Medium 3.5 推理探测，保持 temperature 未设置/默认。Mistral 拒绝 reasoning_effort="high" 加上 temperature: 0；使用 mistral/mistral-medium-3-5 并保留默认 temperature 或非零的推理模式值（如 0.7）。
openai-codex/* 本地探测是窄例外：OpenClaw 会添加一条最小系统指令，以便 Codex Responses 传输可以填充其必需的 instructions 字段，而不添加完整的智能体上下文、工具、记忆或会话文本。
本地 model run --file 保持精简路径，并将图像内容直接附加到单条用户消息中。常见的图像文件（PNG、JPEG、WebP）在 MIME 类型被检测为 image/* 时正常工作；不支持或无法识别的文件会在调用 provider 之前失败。
model run --file 最适合测试选定的多模态文本模型。当您希望使用 OpenClaw 的图像理解 provider 选择和默认图像模型路由时，请使用 infer image describe。
选定的模型必须支持图像输入；纯文本模型可能会在 provider 层拒绝请求。
model run --prompt 必须包含非空白文本；空提示词会在调用本地 provider 或 Gateway 之前被拒绝。
当 provider 未返回任何文本输出时，本地 model run 会以非零退出代码退出，因此不可达的本地 provider 和空补全不会看起来像成功的探测。
使用 model run --gateway 测试 Gateway 路由、智能体运行时设置或 Gateway 管理的 provider 状态，同时保持模型输入为 raw。当需要完整的智能体上下文、工具、记忆和会话文本时，使用 openclaw agent 或聊天表面。
model auth login、model auth logout 和 model auth status 管理已保存的 provider 认证状态。

image 子命令

用于生成、编辑和描述图像。

bash

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-4.1-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

注意事项：

从现有文件修改时使用 image edit。
对于支持参考图像编辑几何提示的 provider/model，可以使用 --size、--aspect-ratio 或 --resolution 配合 image edit。
使用 --output-format png --background transparent 配合 --model openai/gpt-image-1.5 为 OpenAI 输出透明背景的 PNG；--openai-background 仍然可用作 OpenAI 特定的别名。未声明背景支持的 provider 会将该提示报告为被忽略的覆盖。
使用 image providers --json 检查哪些内置图像 provider 是可发现的、已配置的、已选择的，以及每个 provider 暴露了哪些生成/编辑能力。

使用 image generate --model <provider/model> --json 作为图像生成变更的最窄实时 CLI 探测。示例：

bash

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

JSON 响应报告 ok、provider、model、attempts 和写入的输出路径。当设置了 --output 时，最终扩展名可能跟随 provider 返回的 MIME 类型。

对于 image describe 和 image describe-many，使用 --prompt 给视觉模型一个任务特定指示，如 OCR、比较、UI 检查或简洁标题。
对于慢速本地视觉模型或冷启动的 Ollama，使用 --timeout-ms。
对于 image describe，--model 必须是支持图像的 <provider/model>。
对于本地 Ollama 视觉模型，请先拉取模型并设置 OLLAMA_API_KEY 为任意占位值，例如 ollama-local。见 Ollama。

audio 子命令

用于文件转录。

bash

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

注意事项：

audio transcribe 用于文件转录，不包含实时会话管理。
--model 必须是 <provider/model>。

tts 子命令

用于语音合成和 TTS provider 状态。

bash

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

注意事项：

tts status 默认使用 Gateway，因为它反映 Gateway 管理的 TTS 状态。
使用 tts providers、tts voices 和 tts set-provider 查看和配置 TTS 行为。

video 子命令

用于生成和描述视频。

bash

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-4.1-mini --json

注意事项：

video generate 接受 --size、--aspect-ratio、--resolution、--duration、--audio、--watermark 和 --timeout-ms，并传递给视频生成运行时。
对于 video describe，--model 必须是 <provider/model>。

web 子命令

用于搜索和抓取工作流。

bash

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

注意事项：

使用 web providers 检查可用、已配置和已选择的 provider。

embedding 子命令

用于创建向量和检查 embedding provider。

bash

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 输出结构

Infer 命令在共享信封下标准化 JSON 输出：

json

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

顶层字段是稳定的：

ok
capability
transport
provider
model
attempts
outputs
error

对于生成媒体命令，outputs 包含 OpenClaw 写入的文件。使用该数组中的 path、mimeType、size 以及任何媒体特定维度进行自动化，而不是解析人类可读的 stdout。

常见错误写法

bash

# 错误：使用了多余的 media 路径
openclaw infer media image generate --prompt "friendly lobster"

# 正确
openclaw infer image generate --prompt "friendly lobster"

bash

# 错误：--model 缺少 provider 前缀
openclaw infer audio transcribe --file ./memo.m4a --model whisper-1 --json

# 正确：必须指定 provider/model
openclaw infer audio transcribe --file ./memo.m4a --model openai/whisper-1 --json

备注

openclaw capability ... 是 openclaw infer ... 的别名。

常见问题

openclaw infer model run 报错 "auth errors" 怎么解决？

检查是否已为所选 model 的 provider 配置了正确的认证凭据。使用 openclaw infer model auth status 查看已保存的认证状态，或使用 openclaw infer model auth login 进行登录。如果使用的是本地模型（如 Ollama），确保设置了 OLLAMA_API_KEY 等环境变量。

openclaw infer image describe 不支持某些文件格式怎么办？

image describe 的 --file 接受本地路径和 HTTP(S) URL。支持常见的图像格式（PNG、JPEG、WebP），但必须能被检测为 image/* MIME 类型。不支持的视频文件应使用 infer video describe。如果文件扩展名不常见，可以先转换为标准格式再尝试。

openclaw infer TTS 状态怎么看，能否离线使用？

使用 openclaw infer tts status --json 查看当前 TTS provider 的状态。TTS 功能一般依赖云端 provider（如 OpenAI、Google），需要网络连接和有效认证。如果希望离线 TTS，可以配置本地 TTS provider（例如通过插件），但需满足相应依赖。

OpenClaw infer CLI 命令参考：模型、图像、音频等推理操作 ​

将 infer 转换成技能（skill） ​

为什么使用 infer ​

命令树 ​

常见任务速查表 ​

行为说明 ​

model 子命令 ​

image 子命令 ​

audio 子命令 ​

tts 子命令 ​

video 子命令 ​

web 子命令 ​

embedding 子命令 ​

JSON 输出结构 ​

常见错误写法 ​

备注 ​

相关文档 ​

常见问题 ​

openclaw infer model run 报错 "auth errors" 怎么解决？ ​

openclaw infer image describe 不支持某些文件格式怎么办？ ​

openclaw infer TTS 状态怎么看，能否离线使用？ ​

OpenClaw infer CLI 命令参考：模型、图像、音频等推理操作

将 infer 转换成技能（skill）

为什么使用 infer

命令树

常见任务速查表

行为说明

model 子命令

image 子命令

audio 子命令

tts 子命令

video 子命令

web 子命令

embedding 子命令

JSON 输出结构

常见错误写法

备注

相关文档

常见问题

openclaw infer model run 报错 "auth errors" 怎么解决？

openclaw infer image describe 不支持某些文件格式怎么办？

openclaw infer TTS 状态怎么看，能否离线使用？