openclaw infer 是用于提供商支持推理的规范无头界面。它公开能力族（model、image、audio、tts、video、web、embedding），而不是原始 Gateway 网关 RPC 名称或智能体工具 ID。openclaw capability ... 是同一命令树的别名。
相比一次性提供商包装器，更推荐使用它的原因：
- 复用 OpenClaw 中已配置的提供商和模型。
- 为脚本和智能体驱动的自动化提供稳定的
--json信封（参见 JSON 输出）。 - 对大多数子命令，运行正常的本地路径，无需 Gateway 网关。
- 对于端到端提供商检查，它会在提供商请求发出前，执行已发布的 CLI、配置加载、默认智能体解析、内置插件激活以及共享能力运行时。
将 infer 转换为技能
复制并粘贴给智能体：openclaw infer ... 而不是更底层的替代方案，并且不会在技能正文中重新记录整个 infer 界面。
命令树
infer list / infer inspect --name <capability> 会以数据形式显示此树（能力 ID、传输协议、描述）。
常见任务
| 任务 | 命令 | 说明 |
|---|---|---|
| 运行文本/模型提示 | 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 等提供商提示 |
| 描述视频文件 | openclaw infer video describe --file ./clip.mp4 --json | --model 必须是 <provider/model> |
| 搜索 Web | openclaw infer web search --query "..." --json | |
| 抓取网页 | openclaw infer web fetch --url https://example.com --json | |
| 创建嵌入 | openclaw infer embedding create --text "..." --json |
行为
- 当输出会馈送给另一个命令或脚本时使用
--json；否则使用文本输出。 - 使用
--provider或--model provider/model固定特定后端。 - 使用
model run --thinking <level>进行一次性思考/推理覆盖：off、minimal、low、medium、high、adaptive、xhigh或max。 - 对于
image describe、audio transcribe和video describe，--model必须使用<provider/model>形式。 - 对于
image describe，--file接受本地路径和 HTTP(S) URL；远程 URL 会经过正常的媒体抓取 SSRF 策略。 - 无状态执行命令（
model run、image *、audio *、video *、web *、embedding *）默认本地运行。Gateway 网关托管的状态命令（tts status）默认走 Gateway 网关。 - 本地路径从不要求 Gateway 网关正在运行。
- 本地
model run是精简的一次性提供商补全：它会解析已配置的智能体模型和认证，但不会启动聊天智能体轮次、加载工具或打开内置 MCP 服务器。 model run --file会把图像文件（自动检测 MIME 类型）附加到提示中；对多张图像重复使用--file。非图像文件会被拒绝——请改用infer audio transcribe或infer video describe。model run --gateway会执行 Gateway 网关路由、已保存认证、提供商选择和嵌入式运行时，但仍保持为原始模型探测：没有先前会话转录、bootstrap/AGENTS 上下文、工具或内置 MCP 服务器。model run --gateway --model <provider/model>需要可信操作员 Gateway 网关凭证，因为它会请求 Gateway 网关运行一次性提供商/模型覆盖。
模型
文本推理和模型/提供商检查。--local 使用完整 <provider/model> 引用，可以在不启动 Gateway 网关或加载智能体工具界面的情况下冒烟测试一个提供商：
- 本地
model run是用于提供商/模型/认证健康状况的最窄 CLI 冒烟测试：对于非 ChatGPT-Codex 提供商，它只发送提供的提示。 - 本地
model run --model <provider/model>可以在该提供商写入配置之前解析精确的内置静态目录行（即openclaw models list --all显示的相同行）。仍然需要提供商认证；缺少凭证会以认证错误失败，而不是Unknown model。 - 对于 Mistral Medium 3.5 推理探测，请保持 temperature 未设置/默认。Mistral 会拒绝带有
temperature: 0的reasoning_effort="high"；请使用默认 temperature 或非零值，例如0.7。 - OpenAI ChatGPT/Codex OAuth（
openai-chatgpt-responsesAPI）本地探测会添加一条最小系统指令，以便传输层填充其必需的instructions字段——没有完整智能体上下文、工具、记忆或会话转录。 model run --file会把图像内容直接附加到单条用户消息中。当 MIME 类型被检测为image/*时，常见格式（PNG、JPEG、WebP）可用；不支持或无法识别的文件会在调用提供商之前失败。如果你想使用 OpenClaw 的图像模型路由和回退，而不是直接的多模态模型探测，请改用infer image describe。- 所选模型必须支持图像输入；纯文本模型可能会在提供商层拒绝请求。
model run --prompt必须包含非空白文本；空提示会在任何提供商或 Gateway 网关调用前被拒绝。- 当提供商没有返回文本输出时，本地
model run会以非零状态退出，因此不可达的提供商和空补全不会看起来像成功的探测。 - 使用
model run --gateway测试 Gateway 网关路由或智能体运行时设置，同时保持模型输入为原始输入。使用openclaw agent或聊天界面来获得完整智能体上下文、工具、记忆和会话转录。 --thinking adaptive会映射到补全运行时级别medium；对于支持原生 max effort 的 OpenAI 模型，--thinking max会映射到max，否则映射到xhigh。model auth login、model auth logout和model auth status管理已保存的提供商认证状态。
图像
生成、编辑和描述。-
从现有输入文件开始时使用
image edit；在支持这些参数的提供商/模型上，--size、--aspect-ratio或--resolution会添加几何提示。 -
将
--output-format png --background transparent与--model openai/gpt-image-1.5搭配使用，会得到透明背景的 OpenAI PNG 输出；--openai-background是同一提示的 OpenAI 专用别名。未声明支持背景的提供商会将其报告为被忽略的覆盖项（参见 JSON 封套中的ignoredOverrides）。 -
--quality low|medium|high|auto适用于支持图像质量提示的提供商，包括 OpenAI。OpenAI 还接受--openai-moderation low|auto。 -
image providers --json会列出哪些内置图像提供商可发现、已配置、已选中，以及每个提供商公开了哪些生成/编辑能力。 -
image generate --model <provider/model> --json是用于图像生成变更的最小实时冒烟测试：响应会报告ok、provider、model、attempts和已写入的输出路径。设置--output时，最终扩展名可能会跟随提供商返回的 MIME 类型。 -
对于
image describe和image describe-many，使用--prompt提供特定任务的指令（OCR、对比、UI 检查、简洁描述）。 -
对于较慢的本地视觉模型或 Ollama 冷启动，使用
--timeout-ms。 -
对于
image describe，显式--model（必须是支持图像的<provider/model>）会先运行；如果该调用失败，再尝试已配置的agents.defaults.imageModel.fallbacks。输入准备错误（缺少文件、不支持的 URL）会在任何 fallback 尝试之前失败，并且模型必须在模型目录或提供商配置中支持图像。 -
对于本地 Ollama 视觉模型，请先拉取模型，并将
OLLAMA_API_KEY设置为任意占位值，例如ollama-local。参见 Ollama。
音频
文件转录（非实时会话管理）。--model 必须是 <provider/model>。
TTS
语音合成以及 TTS 提供商/语音角色状态。tts status仅支持--gateway（它反映由 Gateway 网关管理的 TTS 状态）。- 使用
tts providers、tts voices、tts personas、tts set-provider和tts set-persona检查并配置 TTS 行为。
视频
生成和描述。video generate接受--size、--aspect-ratio、--resolution、--duration、--audio、--watermark和--timeout-ms，并将它们转发给视频生成运行时。- 对于
video describe，--model必须是<provider/model>。
Web
搜索和获取。web providers 会列出可用于搜索和获取的可用、已配置和已选中的提供商。
嵌入
向量创建和嵌入提供商检查。JSON 输出
Infer 命令会将 JSON 输出规范化到共享封套下：okcapabilitytransportprovidermodelattemptsinputs（适用时，随请求发送的图像附件）outputsignoredOverrides（适用时，提供商不支持的提示键）error
outputs 包含 OpenClaw 写入的文件。自动化时，请使用该数组中的 path、mimeType、size 和任何媒体专用尺寸，而不是解析人类可读的 stdout。