Documentation Index
Fetch the complete documentation index at: https://openclaw.zhcndoc.com/llms.txt
Use this file to discover all available pages before exploring further.
openclaw infer 是提供商支持的推理工作流的标准无头入口。
它有意暴露的是能力家族，而不是原始网关 RPC 名称，也不是原始代理工具 ID。
将 infer 变成一项技能
把这段复制并粘贴给一个 agent：- 将常见用户意图映射到正确的 infer 子命令
- 为其覆盖的工作流包含一些标准的 infer 示例
- 在示例和建议中优先使用
openclaw infer ... - 避免在技能正文中重新文档化整个 infer 表面
openclaw infer model runopenclaw infer image generateopenclaw infer audio transcribeopenclaw infer tts convertopenclaw infer web searchopenclaw infer embedding create
为什么使用 infer
openclaw infer 为 OpenClaw 内部提供了一套一致的 CLI，用于提供商支持的推理任务。
优点：
- 使用已在 OpenClaw 中配置好的提供商和模型，而不是为每个后端编写一次性的包装器。
- 将模型、图像、音频转录、TTS、视频、网页和嵌入工作流统一到一个命令树下。
- 为脚本、自动化和 agent 驱动的工作流使用稳定的
--json输出结构。 - 当任务本质上是“运行推理”时，优先使用第一方 OpenClaw 表面。
- 对于大多数 infer 命令，使用正常的本地路径，而无需依赖 gateway。
openclaw infer ...。它会在发出提供商请求之前，先对随附的 CLI、配置加载、
默认 agent 解析、捆绑插件激活以及共享能力
运行时进行演练。
命令树
常见任务
此表将常见推理任务映射到相应的 infer 命令。| 任务 | 命令 | 备注 |
|---|---|---|
| 运行文本/模型提示词 | 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 |
| 描述图像文件 | 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> |
| 搜索网页 | 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。 - 对于
image describe、audio transcribe和video describe，--model必须使用<provider/model>形式。 - 对于
image describe，显式的--model会直接运行该 provider/model。该模型必须在模型目录或提供商配置中支持图像。codex/<model>会运行一次受限的 Codex app-server 图像理解轮次；openai-codex/<model>使用 OpenAI Codex OAuth 提供商路径。 - 无状态执行命令默认使用 local。
- 由 gateway 管理状态的命令默认使用 gateway。
- 正常的本地路径不需要 gateway 正在运行。
- 本地
model run是一种精简的一次性提供商补全。它会解析已配置的 agent 模型和认证，但不会启动 chat-agent 轮次、加载工具或打开捆绑的 MCP 服务器。 model run --file接受图像文件，检测其 MIME 类型，并将它们与提供的提示一起发送给所选模型。对多个图像重复--file。model run --file会拒绝非图像输入。音频文件请使用infer audio transcribe，视频文件请使用infer video describe。model run --gateway会测试 Gateway 路由、已保存的认证、提供商选择以及嵌入式运行时，但仍然作为原始模型探测运行：它会发送提供的提示和任何图像附件，不会使用先前的会话转录、bootstrap/AGENTS 上下文、上下文引擎组装、工具或捆绑的 MCP 服务器。model run --gateway --model <provider/model>需要受信任的操作员 gateway 凭证，因为该请求要求 Gateway 运行一次性的 provider/model 覆盖。
模型
将model 用于提供商支持的文本推理以及模型/提供商检查。
<provider/model> 引用来对特定提供商进行冒烟测试，而无需
启动 Gateway 或加载完整的 agent 工具表面：
- 本地
model run是用于检查 provider/model/auth 健康状况的最窄 CLI 冒烟测试，因为它只会将提供的提示发送给所选模型。 - 本地
model run --file保持这种精简路径，并将图像内容直接附加到单个用户消息上。常见的图像文件，如 PNG、JPEG 和 WebP，只要其 MIME 类型被检测为image/*就可工作；不受支持或无法识别的文件会在调用提供商之前失败。 - 当你想直接测试所选的多模态文本模型时，
model run --file是最佳选择。当你想使用 OpenClaw 的图像理解提供商选择和默认图像模型路由时，请使用infer image describe。 - 所选模型必须支持图像输入；仅文本模型可能会在提供商层拒绝该请求。
model run --prompt必须包含非空白文本；空提示会在调用本地提供商或 Gateway 之前被拒绝。- 当提供商没有返回任何文本输出时，本地
model run会以非零状态退出，因此不可达的本地提供商和空补全不会看起来像成功探测。 - 当你需要测试 Gateway 路由、agent 运行时设置或 Gateway 管理的提供商状态，同时保持模型输入原始时，请使用
model run --gateway。当你想要完整的 agent 上下文、工具、记忆和会话转录时，请使用openclaw agent或聊天界面。 model auth login、model auth logout和model auth status管理已保存的提供商认证状态。
图像
将image 用于生成、编辑和描述。
-
从现有输入文件开始时，使用
image edit。 -
对支持参考图像编辑几何提示的提供商/模型，在
image edit中使用--size、--aspect-ratio或--resolution。 -
对于
--model openai/gpt-image-1.5，使用--output-format png --background transparent来输出透明背景的 OpenAI PNG；--openai-background仍然可用，作为 OpenAI 特定别名。未声明背景支持的提供商会将该提示报告为被忽略的覆盖项。 -
使用
image providers --json来验证哪些捆绑的图像提供商可发现、已配置、已选中，以及每个提供商暴露了哪些生成/编辑能力。 -
使用
image generate --model <provider/model> --json作为图像生成变更的最窄在线 CLI 冒烟测试。示例：JSON 响应会报告ok、provider、model、attempts和写入的输出路径。当设置了--output时，最终扩展名可能遵循提供商返回的 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 进行文件转录。
audio transcribe用于文件转录，不用于实时会话管理。--model必须是<provider/model>。
TTS
使用tts 进行语音合成和 TTS 提供商状态管理。
tts status默认使用 gateway，因为它反映的是由 gateway 管理的 TTS 状态。- 使用
tts providers、tts voices和tts set-provider来查看并配置 TTS 行为。
视频
使用video 进行生成和描述。
video generate接受--size、--aspect-ratio、--resolution、--duration、--audio、--watermark和--timeout-ms，并将它们转发到视频生成运行时。--model对于video describe必须是<provider/model>。
Web
使用web 进行搜索和抓取工作流。
- 使用
web providers来查看可用、已配置和已选定的提供商。
Embedding
使用embedding 进行向量创建和 embedding 提供商检查。
JSON 输出
Infer 命令会在一个共享信封结构下规范化 JSON 输出：okcapabilitytransportprovidermodelattemptsoutputserror
outputs 包含由 OpenClaw 写入的文件。请在自动化中使用
该数组中的 path、mimeType、size 以及任何媒体特定维度，
而不是解析人类可读的 stdout。
常见陷阱
注意
openclaw capability ...是openclaw infer ...的别名。