openclaw infer 是面向提供商支持的推理的标准无头接口。它公开的是能力家族（model、image、audio、tts、video、web、embedding），而不是原始网关 RPC 名称或代理工具 id。openclaw capability ... 是同一命令树的别名。
优先使用它而不是一次性的提供商包装器，原因如下：
- 复用 OpenClaw 中已配置的提供商和模型。
- 为脚本和由代理驱动的自动化提供稳定的
--json封装（参见 JSON 输出）。 - 对于大多数子命令，会走正常的本地路径而不经过网关。
- 对于端到端提供商检查，它会在提供商请求发出之前，先验证随 CLI 一同发布的命令、配置加载、默认代理解析、内置插件激活以及共享的能力运行时。
将 infer 变成一项技能
把这段复制并粘贴给一个代理：openclaw infer ... 而不是更底层的替代方案，并且不会在技能正文中重新记录整个 infer 接口。
命令树
infer list / infer inspect --name <capability> 会将此树作为数据展示（能力 ID、传输方式、描述）。
常见任务
行为
- 当输出将作为其他命令或脚本的输入时，使用
--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 *）默认使用本地。由网关管理的状态命令（tts status）默认使用网关。 - 本地路径不要求网关正在运行。
- 生成的图像和视频
--output文件会暂存于目标位置旁边，只有在完整缓冲区写入后才会替换目标文件；写入失败会保留现有目标文件不变。 - 本地
model run是一次精简的提供商补全操作：它解析已配置的代理模型和身份验证，但不会启动聊天代理回合、加载工具或打开捆绑的 MCP 服务器。 model run --file会将图像文件（自动检测 MIME 类型）附加到提示中；重复使用--file可添加多个图像。不接受非图像文件——请改用infer audio transcribe或infer video describe。model run --gateway会使用网关路由、已保存的身份验证、提供商选择和嵌入式运行时，但仍是原始模型探测：不会加载先前的会话记录、bootstrap/AGENTS 上下文、工具或捆绑的 MCP 服务器。model run --gateway --model <provider/model>要求受信任操作员的网关凭据，因为它会要求网关运行一次性的提供商/模型覆盖。
模型
文本推理以及模型/提供方检查。--local 的完整 <provider/model> 引用，可以在不启动 Gateway 或加载 agent 工具表面的情况下，对单个提供方进行冒烟测试：
- 本地
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"；请使用默认温度或非零值，例如0.7。 - OpenAI ChatGPT/Codex OAuth（
openai-chatgpt-responsesAPI）本地探测会添加一个最小系统指令，以便传输层可以填充其必需的instructions字段——不会包含完整的 agent 上下文、工具、记忆或会话转录。 model run --file会将图片内容直接附加到单条用户消息上。检测到 MIME 类型为image/*时，常见格式（PNG、JPEG、WebP）可用；不受支持或无法识别的文件会在调用提供方之前失败。当你想要 OpenClaw 的图像模型路由和回退，而不是直接的多模态模型探测时，请改用infer image describe。- 所选模型必须支持图像输入；纯文本模型可能会在提供方层拒绝该请求。
model run --prompt必须包含非空白文本；空提示词会在任何提供方或 Gateway 调用之前被拒绝。- 当提供方没有返回任何文本输出时，本地
model run会以非零退出，因此不可达的提供方和空完成不会看起来像成功的探测。 - 使用
model run --gateway来测试 Gateway 路由或 agent 运行时设置，同时保持模型输入原始。使用openclaw agent或聊天界面来获得完整的 agent 上下文、工具、记忆和会话转录。 --thinking adaptive映射到 completion-runtime 级别的medium；--thinking max映射到支持原生 max effort 的 OpenAI 模型的max，否则映射到xhigh。model auth login、model auth logout和model auth status用于管理已保存的提供方认证状态。
图像
生成、编辑和描述。-
当从现有输入文件开始时，使用
image edit；--size、--aspect-ratio或--resolution会为支持这些参数的提供方/模型增加几何提示。 -
与
--model openai/gpt-image-1.5一起使用--output-format png --background transparent可得到 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）会在任何回退尝试之前失败，并且该模型必须在模型目录或提供方配置中具备图像能力。 -
对于本地 Ollama 视觉模型，请先拉取模型，并将
OLLAMA_API_KEY设置为任意占位值，例如ollama-local。参见 Ollama。
音频
文件转录（不是实时会话管理）。--model 必须是 <provider/model>。
TTS
语音合成和 TTS 提供方/角色状态。tts status仅支持--gateway（它反映由网关管理的 TTS 状态）。- 本地和回环网关的
tts convert --output会在目标文件旁执行复制阶段，并且仅在成功后替换目标文件；复制失败会保留现有文件不变。 - 在选择提供方但不覆盖其模型时，请使用
tts convert --provider <id>。 - 使用
tts providers、tts voices、tts personas、tts set-provider和tts set-persona来检查和配置 TTS 行为。
视频
生成和描述。video generate接受--size、--aspect-ratio、--resolution、--duration、--audio、--watermark和--timeout-ms，并将其转发给视频生成运行时。- Provider 托管的视频下载会拒绝空响应、文本响应和 JSON 响应，而不是将不可用的文件报告为成功输出。
- 使用
--output时，基于 URL 的视频会流式传输到同级临时文件，只有在完整且非空的下载成功后才会替换目标文件；流传输失败会保留现有目标文件不变。 - 对于
video describe，--model必须为<provider/model>。
网页
搜索并获取。web providers 列出用于搜索和获取的可用、已配置和已选定提供商。
嵌入
向量创建和嵌入提供方检查。JSON 输出
Infer 命令会在一个共享信封结构下规范化 JSON 输出：okcapabilitytransportprovidermodelattemptsinputs（在适用时，随请求发送的图像附件）outputsignoredOverrides（在适用时，提供方不支持的提示键）error
outputs 包含由 OpenClaw 写入的文件。请改为使用该数组中的 path、mimeType、size 以及任何媒体特定的尺寸信息进行自动化处理，而不是解析人类可读的标准输出。