chore(i18n): refresh zh-CN translations
This commit is contained in:
openclaw-docs-i18n[bot]
parent
90e40ee77c
commit
fbb5e1815e
@ -2,36 +2,36 @@
|
||||
read_when:
|
||||
- 添加或修改 `openclaw infer` 命令
|
||||
- 设计稳定的无头能力自动化
|
||||
summary: 面向由提供商支持的模型、图像、音频、TTS、视频、Web 和嵌入工作流的推理优先 CLI
|
||||
summary: 面向提供商支持的模型、图像、音频、TTS、视频、网页和嵌入工作流的 infer-first CLI
|
||||
title: 推理 CLI
|
||||
x-i18n:
|
||||
generated_at: "2026-04-26T03:26:37Z"
|
||||
generated_at: "2026-04-27T22:06:15Z"
|
||||
model: gpt-5.4
|
||||
provider: openai
|
||||
source_hash: bf07b306d80535b58d811aa33c0bbe2ecac57b22c3ab27f6f2ae6518ceb21e49
|
||||
source_hash: 704f9ea60adb1b509f0b4f74ae79ffb70f12915a7e8a45d43ca28f5ac7d70af1
|
||||
source_path: cli/infer.md
|
||||
workflow: 15
|
||||
---
|
||||
|
||||
`openclaw infer` 是面向由提供商支持的推理工作流的规范无头入口。
|
||||
`openclaw infer` 是提供商支持的推理工作流的规范无头入口。
|
||||
|
||||
它有意公开的是能力族，而不是原始 Gateway 网关 RPC 名称，也不是原始智能体工具 id。
|
||||
它有意暴露的是能力家族，而不是原始的 Gateway 网关 RPC 名称，也不是原始的智能体工具 id。
|
||||
|
||||
## 将 infer 变成一个 Skills
|
||||
|
||||
把这段内容复制并粘贴给一个智能体：
|
||||
把下面这段内容复制粘贴给一个智能体：
|
||||
|
||||
```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 的 Skills 应该：
|
||||
一个基于 infer 的优秀 Skills 应该：
|
||||
|
||||
- 将常见用户意图映射到正确的 infer 子命令
|
||||
- 包含其所覆盖工作流的几个规范 infer 示例
|
||||
- 包含其所覆盖工作流的一些规范 infer 示例
|
||||
- 在示例和建议中优先使用 `openclaw infer ...`
|
||||
- 避免在 Skills 正文中重新记录整个 infer 功能面
|
||||
- 避免在 Skills 正文中重新记录完整的 infer 功能面
|
||||
|
||||
典型的 infer 导向 Skills 覆盖范围：
|
||||
|
||||
@ -44,17 +44,17 @@ Focus on model runs, image generation, video generation, audio transcription, TT
|
||||
|
||||
## 为什么使用 infer
|
||||
|
||||
`openclaw infer` 为 OpenClaw 内由提供商支持的推理任务提供了一个统一的 CLI。
|
||||
`openclaw infer` 为 OpenClaw 中由提供商支持的推理任务提供了一个统一的 CLI。
|
||||
|
||||
优势：
|
||||
|
||||
- 使用已在 OpenClaw 中配置好的提供商和模型，而不是为每个后端单独接入一次性包装器。
|
||||
- 将模型、图像、音频转录、TTS、视频、Web 和嵌入工作流统一放在同一棵命令树下。
|
||||
- 为脚本、自动化和智能体驱动的工作流提供稳定的 `--json` 输出结构。
|
||||
- 使用 OpenClaw 中已配置的提供商和模型，而不是为每个后端单独接入一次性包装器。
|
||||
- 将模型、图像、音频转录、TTS、视频、网页和嵌入工作流统一放在同一棵命令树下。
|
||||
- 为脚本、自动化和智能体驱动的工作流使用稳定的 `--json` 输出结构。
|
||||
- 当任务本质上是“运行推理”时，优先使用 OpenClaw 的第一方入口。
|
||||
- 对大多数 infer 命令，使用常规本地路径而不需要运行 Gateway 网关。
|
||||
- 对于大多数 infer 命令，使用常规本地路径而无需运行 Gateway 网关。
|
||||
|
||||
对于端到端提供商检查，在底层提供商测试通过后，优先使用 `openclaw infer ...`。它会在发起提供商请求之前，覆盖已发布的 CLI、配置加载、默认智能体解析、内置插件激活、运行时依赖修复以及共享能力运行时。
|
||||
对于端到端提供商检查，在较低层提供商测试已通过后，优先使用 `openclaw infer ...`。它会在发起提供商请求之前，覆盖已发布的 CLI、配置加载、默认智能体解析、内置插件激活、运行时依赖修复以及共享能力运行时。
|
||||
|
||||
## 命令树
|
||||
|
||||
@ -114,31 +114,32 @@ Focus on model runs, image generation, video generation, audio transcription, TT
|
||||
| 任务 | 命令 | 说明 |
|
||||
| ----------------------- | ---------------------------------------------------------------------- | ----------------------------------------------------- |
|
||||
| 运行文本/模型提示词 | `openclaw infer model run --prompt "..." --json` | 默认使用常规本地路径 |
|
||||
| 生成图像 | `openclaw infer image generate --prompt "..." --json` | 从现有文件开始时使用 `image edit` |
|
||||
| 生成图像 | `openclaw infer image generate --prompt "..." --json` | 如果从现有文件开始，使用 `image edit` |
|
||||
| 描述图像文件 | `openclaw infer image describe --file ./image.png --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 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 search --query "..." --json` | |
|
||||
| 抓取网页 | `openclaw infer web fetch --url https://example.com --json` | |
|
||||
| 创建嵌入 | `openclaw infer embedding create --text "..." --json` | |
|
||||
|
||||
## 行为
|
||||
|
||||
- `openclaw infer ...` 是这些工作流的主要 CLI 入口。
|
||||
- 当输出会被其他命令或脚本消费时，使用 `--json`。
|
||||
- 当输出将被另一个命令或脚本消费时，使用 `--json`。
|
||||
- 当需要特定后端时，使用 `--provider` 或 `--model provider/model`。
|
||||
- 对于 `image describe`、`audio transcribe` 和 `video describe`，`--model` 必须使用 `<provider/model>` 形式。
|
||||
- 对于 `image describe`，显式传入 `--model` 会直接运行该提供商/模型。该模型必须在模型目录或提供商配置中具备图像能力。`codex/<model>` 会运行一次受限的 Codex app-server 图像理解轮次；`openai-codex/<model>` 则使用 OpenAI Codex OAuth 提供商路径。
|
||||
- 对于 `image describe`，显式传入 `--model` 会直接运行该提供商/模型。该模型必须在模型目录或提供商配置中具备图像能力。`codex/<model>` 会运行一次受限的 Codex app-server 图像理解回合；`openai-codex/<model>` 使用 OpenAI Codex OAuth provider 路径。
|
||||
- 无状态执行命令默认走本地。
|
||||
- 由 Gateway 网关管理状态的命令默认走 gateway。
|
||||
- 常规本地路径不要求 Gateway 网关处于运行状态。
|
||||
- `model run` 是一次性执行。通过该命令的智能体运行时打开的 MCP 服务器，在本地和 `--gateway` 执行模式下都会在回复完成后被回收，因此重复的脚本调用不会让 stdio MCP 子进程持续存活。
|
||||
- 由 Gateway 网关管理状态的命令默认走 Gateway 网关。
|
||||
- 常规本地路径不要求 Gateway 网关正在运行。
|
||||
- 本地 `model run` 是精简的一次性提供商补全。它会解析已配置的智能体模型和凭证，但不会启动聊天智能体回合、加载工具，也不会打开内置 MCP 服务器。
|
||||
- `model run --gateway` 仍然使用 Gateway 网关智能体运行时，因此它可以覆盖与普通 Gateway 网关支持回合同样的路由运行时路径。通过该运行时打开的 MCP 服务器会在回复后被回收，因此重复的脚本调用不会让 stdio MCP 子进程持续存活。
|
||||
|
||||
## Model
|
||||
## 模型
|
||||
|
||||
对由提供商支持的文本推理，以及模型/提供商检查，使用 `model`。
|
||||
使用 `model` 执行由提供商支持的文本推理，以及模型/提供商检查。
|
||||
|
||||
```bash
|
||||
openclaw infer model run --prompt "Reply with exactly: smoke-ok" --json
|
||||
@ -147,15 +148,26 @@ openclaw infer model providers --json
|
||||
openclaw infer model inspect --name gpt-5.5 --json
|
||||
```
|
||||
|
||||
使用完整的 `<provider/model>` 引用来对特定提供商进行冒烟测试，而无需启动 Gateway 网关或加载完整的智能体工具面：
|
||||
|
||||
```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-small-latest --prompt "Reply with exactly: pong" --json
|
||||
openclaw infer model run --local --model openai/gpt-4.1 --prompt "Reply with exactly: pong" --json
|
||||
```
|
||||
|
||||
说明：
|
||||
|
||||
- `model run` 会复用智能体运行时，因此提供商/模型覆盖的行为与常规智能体执行一致。
|
||||
- 因为 `model run` 面向无头自动化，所以命令结束后不会保留该次会话的内置 MCP 运行时。
|
||||
- `model auth login`、`model auth logout` 和 `model auth status` 用于管理已保存的提供商认证状态。
|
||||
- 本地 `model run` 是最窄的 CLI 冒烟检查方式，可用于验证提供商/模型/凭证健康状态，因为它只会把提供的提示词发送给所选模型。
|
||||
- 当你需要测试 Gateway 网关路由、智能体运行时设置或 Gateway 网关管理的提供商状态，而不是精简的本地补全路径时，使用 `model run --gateway`。
|
||||
- `model auth login`、`model auth logout` 和 `model auth status` 用于管理已保存的提供商凭证状态。
|
||||
|
||||
## Image
|
||||
## 图像
|
||||
|
||||
对生成、编辑和描述图像，使用 `image`。
|
||||
使用 `image` 执行生成、编辑和描述。
|
||||
|
||||
```bash
|
||||
openclaw infer image generate --prompt "friendly lobster illustration" --json
|
||||
@ -172,10 +184,10 @@ openclaw infer image describe --file ./photo.jpg --model ollama/qwen2.5vl:7b --j
|
||||
说明：
|
||||
|
||||
- 从现有输入文件开始时，使用 `image edit`。
|
||||
- 对于支持在参考图像编辑时提供几何提示的提供商/模型，可在 `image edit` 中使用 `--size`、`--aspect-ratio` 或 `--resolution`。
|
||||
- 对于带透明背景的 OpenAI PNG 输出，使用 `--model openai/gpt-image-1.5` 配合 `--output-format png --background transparent`；`--openai-background` 仍可作为 OpenAI 专用别名使用。未声明支持背景控制的提供商会将该提示报告为被忽略的覆盖项。
|
||||
- 使用 `image providers --json` 可验证哪些内置图像提供商可被发现、已配置、已选中，以及每个提供商公开了哪些生成/编辑能力。
|
||||
- 使用 `image generate --model <provider/model> --json` 作为图像生成变更的最小化在线 CLI 冒烟检查。示例：
|
||||
- 对于支持参考图像编辑几何提示的提供商/模型，在 `image edit` 中使用 `--size`、`--aspect-ratio` 或 `--resolution`。
|
||||
- 对于透明背景的 OpenAI PNG 输出，结合 `--model openai/gpt-image-1.5` 使用 `--output-format png --background transparent`；`--openai-background` 仍然可作为 OpenAI 专用别名使用。未声明支持背景参数的提供商会将该提示报告为已忽略的覆盖项。
|
||||
- 使用 `image providers --json` 来验证哪些内置图像提供商可被发现、已配置、已选中，以及每个提供商暴露了哪些生成/编辑能力。
|
||||
- 使用 `image generate --model <provider/model> --json` 作为图像生成变更最窄的在线 CLI 冒烟检查。例如：
|
||||
|
||||
```bash
|
||||
openclaw infer image providers --json
|
||||
@ -186,14 +198,14 @@ openclaw infer image describe --file ./photo.jpg --model ollama/qwen2.5vl:7b --j
|
||||
--json
|
||||
```
|
||||
|
||||
JSON 响应会报告 `ok`、`provider`、`model`、`attempts` 和已写入的输出路径。设置 `--output` 时，最终扩展名可能会跟随提供商返回的 MIME type。
|
||||
JSON 响应会报告 `ok`、`provider`、`model`、`attempts` 以及写出的输出路径。设置 `--output` 时，最终扩展名可能会遵循提供商返回的 MIME 类型。
|
||||
|
||||
- 对于 `image describe`，`--model` 必须是支持图像的 `<provider/model>`。
|
||||
- 对于本地 Ollama 视觉模型，请先拉取模型，并将 `OLLAMA_API_KEY` 设为任意占位值，例如 `ollama-local`。参见 [Ollama](/zh-CN/providers/ollama#vision-and-image-description)。
|
||||
- 对于本地 Ollama 视觉模型，先拉取模型，并将 `OLLAMA_API_KEY` 设为任意占位值，例如 `ollama-local`。参见 [Ollama](/zh-CN/providers/ollama#vision-and-image-description)。
|
||||
|
||||
## Audio
|
||||
## 音频
|
||||
|
||||
对文件转录，使用 `audio`。
|
||||
使用 `audio` 执行文件转录。
|
||||
|
||||
```bash
|
||||
openclaw infer audio transcribe --file ./memo.m4a --json
|
||||
@ -208,7 +220,7 @@ openclaw infer audio transcribe --file ./memo.m4a --model openai/whisper-1 --jso
|
||||
|
||||
## TTS
|
||||
|
||||
对语音合成和 TTS 提供商状态，使用 `tts`。
|
||||
使用 `tts` 执行语音合成和 TTS 提供商状态管理。
|
||||
|
||||
```bash
|
||||
openclaw infer tts convert --text "hello from openclaw" --output ./hello.mp3 --json
|
||||
@ -219,12 +231,12 @@ openclaw infer tts status --json
|
||||
|
||||
说明：
|
||||
|
||||
- `tts status` 默认走 gateway，因为它反映的是由 Gateway 网关管理的 TTS 状态。
|
||||
- `tts status` 默认走 Gateway 网关，因为它反映的是由 Gateway 网关管理的 TTS 状态。
|
||||
- 使用 `tts providers`、`tts voices` 和 `tts set-provider` 来检查和配置 TTS 行为。
|
||||
|
||||
## Video
|
||||
## 视频
|
||||
|
||||
对视频生成和描述，使用 `video`。
|
||||
使用 `video` 执行生成和描述。
|
||||
|
||||
```bash
|
||||
openclaw infer video generate --prompt "cinematic sunset over the ocean" --json
|
||||
@ -235,12 +247,12 @@ openclaw infer video describe --file ./clip.mp4 --model openai/gpt-4.1-mini --js
|
||||
|
||||
说明：
|
||||
|
||||
- `video generate` 接受 `--size`、`--aspect-ratio`、`--resolution`、`--duration`、`--audio`、`--watermark` 和 `--timeout-ms`，并将其转发给视频生成运行时。
|
||||
- `video generate` 接受 `--size`、`--aspect-ratio`、`--resolution`、`--duration`、`--audio`、`--watermark` 和 `--timeout-ms`，并将它们转发给视频生成运行时。
|
||||
- 对于 `video describe`，`--model` 必须是 `<provider/model>`。
|
||||
|
||||
## Web
|
||||
## 网页
|
||||
|
||||
对搜索和抓取工作流，使用 `web`。
|
||||
使用 `web` 执行搜索和抓取工作流。
|
||||
|
||||
```bash
|
||||
openclaw infer web search --query "OpenClaw docs" --json
|
||||
@ -253,9 +265,9 @@ openclaw infer web providers --json
|
||||
|
||||
- 使用 `web providers` 来检查可用、已配置和已选中的提供商。
|
||||
|
||||
## Embedding
|
||||
## 嵌入
|
||||
|
||||
对向量创建和嵌入提供商检查，使用 `embedding`。
|
||||
使用 `embedding` 进行向量创建和嵌入提供商检查。
|
||||
|
||||
```bash
|
||||
openclaw infer embedding create --text "friendly lobster" --json
|
||||
@ -265,7 +277,7 @@ openclaw infer embedding providers --json
|
||||
|
||||
## JSON 输出
|
||||
|
||||
Infer 命令会在统一封装下标准化 JSON 输出：
|
||||
Infer 命令会在共享封装下规范化 JSON 输出：
|
||||
|
||||
```json
|
||||
{
|
||||
@ -290,7 +302,7 @@ Infer 命令会在统一封装下标准化 JSON 输出：
|
||||
- `outputs`
|
||||
- `error`
|
||||
|
||||
对于生成媒体的命令，`outputs` 包含由 OpenClaw 写入的文件。对于自动化，请使用该数组中的 `path`、`mimeType`、`size` 以及任何媒体特定尺寸信息，而不是解析人类可读的 stdout。
|
||||
对于生成媒体的命令，`outputs` 包含由 OpenClaw 写入的文件。对于自动化，请使用该数组中的 `path`、`mimeType`、`size` 以及任何媒体特定的尺寸信息，而不要解析面向人类可读的 stdout。
|
||||
|
||||
## 常见陷阱
|
||||
|
||||
|
||||
@ -1,30 +1,30 @@
|
||||
---
|
||||
read_when:
|
||||
- 你想从自己的 GPU 机器提供模型服务
|
||||
- 你想从你自己的 GPU 主机提供模型服务
|
||||
- 你正在接入 LM Studio 或兼容 OpenAI 的代理
|
||||
- 你需要最安全的本地模型使用指南
|
||||
summary: 在本地 LLM 上运行 OpenClaw（LM Studio、vLLM、LiteLLM、自定义 OpenAI 端点）
|
||||
title: 本地模型
|
||||
x-i18n:
|
||||
generated_at: "2026-04-27T12:52:12Z"
|
||||
generated_at: "2026-04-27T22:06:17Z"
|
||||
model: gpt-5.4
|
||||
provider: openai
|
||||
source_hash: 5b98d2d4b7e6162ca681f5d184ee6e075ea09e5e4b4544e6733c5e6b8ca4cc30
|
||||
source_hash: a6d16948f66e8ad5b11c82939f711ad7db9edeea565c77b293227612f7ab43b6
|
||||
source_path: gateway/local-models.md
|
||||
workflow: 15
|
||||
---
|
||||
|
||||
本地部署是可行的，但 OpenClaw 需要大上下文窗口以及强有力的提示注入防护。小显存卡会截断上下文并削弱安全性。目标应尽量高：**至少 2 台满配 Mac Studio 或同等级 GPU 机器（约 3 万美元以上）**。单张 **24 GB** GPU 只适用于较轻的提示，并且延迟更高。使用**你能运行的最大 / 全尺寸模型变体**；激进量化或“小型”检查点会提高提示注入风险（参见 [Security](/zh-CN/gateway/security)）。
|
||||
本地部署是可行的，但 OpenClaw 需要“大上下文窗口 + 强提示注入防护”。小显存卡会截断上下文，并削弱安全性。尽量拉高配置：**至少 2 台满配 Mac Studio，或同等级 GPU 设备（约 3 万美元以上）**。单张 **24 GB** GPU 仅适用于较轻量的提示词场景，而且延迟更高。使用**你能运行的最大 / 完整尺寸模型变体**；强量化或“small”检查点会提高提示注入风险（参见 [Security](/zh-CN/gateway/security)）。
|
||||
|
||||
如果你想要摩擦最小的本地方案，从 [LM Studio](/zh-CN/providers/lmstudio) 或 [Ollama](/zh-CN/providers/ollama) 加上 `openclaw onboard` 开始。本页是针对更高端本地栈和自定义兼容 OpenAI 的本地服务器的偏好型指南。
|
||||
如果你想要最低摩擦的本地部署方式，先从 [LM Studio](/zh-CN/providers/lmstudio) 或 [Ollama](/zh-CN/providers/ollama) 加 `openclaw onboard` 开始。本页是面向更高端本地栈和自定义兼容 OpenAI 本地服务器的偏好型指南。
|
||||
|
||||
<Warning>
|
||||
**WSL2 + Ollama + NVIDIA/CUDA 用户：** 官方 Ollama Linux 安装器会启用一个带 `Restart=always` 的 systemd 服务。在 WSL2 GPU 环境中，自动启动可能会在开机时重新加载上一次模型，并锁定宿主机内存。如果你在启用 Ollama 后发现 WSL2 虚拟机反复重启，请参见 [WSL2 crash loop](/zh-CN/providers/ollama#wsl2-crash-loop-repeated-reboots)。
|
||||
**WSL2 + Ollama + NVIDIA/CUDA 用户：** 官方 Ollama Linux 安装器会启用一个带有 `Restart=always` 的 systemd 服务。在 WSL2 GPU 配置中，自动启动可能会在系统启动时重新加载上次使用的模型，并占用宿主机内存。如果你在启用 Ollama 后遇到 WSL2 虚拟机反复重启，请参见 [WSL2 崩溃循环](/zh-CN/providers/ollama#wsl2-crash-loop-repeated-reboots)。
|
||||
</Warning>
|
||||
|
||||
## 推荐：LM Studio + 大型本地模型（Responses API）
|
||||
|
||||
这是当前最好的本地栈。先在 LM Studio 中加载一个大型模型（例如完整尺寸的 Qwen、DeepSeek 或 Llama 构建），启用本地服务器（默认 `http://127.0.0.1:1234`），并使用 Responses API 将推理过程与最终文本分离。
|
||||
这是目前最佳的本地栈。先在 LM Studio 中加载一个大型模型（例如完整尺寸的 Qwen、DeepSeek 或 Llama 构建），启用本地服务器（默认 `http://127.0.0.1:1234`），然后使用 Responses API，将推理过程与最终文本分离。
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -61,18 +61,18 @@ x-i18n:
|
||||
}
|
||||
```
|
||||
|
||||
**设置清单**
|
||||
**设置检查清单**
|
||||
|
||||
- 安装 LM Studio：[https://lmstudio.ai](https://lmstudio.ai)
|
||||
- 在 LM Studio 中，下载**可用的最大模型构建**（避免使用“小型” / 重度量化变体），启动服务器，并确认 `http://127.0.0.1:1234/v1/models` 中列出了该模型。
|
||||
- 安装 LM Studio： [https://lmstudio.ai](https://lmstudio.ai)
|
||||
- 在 LM Studio 中，下载**可用的最大模型构建**（避免 “small”/重度量化变体），启动服务器，并确认 `http://127.0.0.1:1234/v1/models` 能列出该模型。
|
||||
- 将 `my-local-model` 替换为 LM Studio 中显示的实际模型 ID。
|
||||
- 保持模型处于已加载状态；冷启动加载会增加启动延迟。
|
||||
- 如果你的 LM Studio 构建不同，请调整 `contextWindow` / `maxTokens`。
|
||||
- 对于 WhatsApp，请坚持使用 Responses API，这样只会发送最终文本。
|
||||
- 如果你的 LM Studio 构建不同，请调整 `contextWindow`/`maxTokens`。
|
||||
- 对于 WhatsApp，坚持使用 Responses API，这样只会发送最终文本。
|
||||
|
||||
即使在本地运行，也请保留托管模型配置；使用 `models.mode: "merge"`，这样回退模型仍然可用。
|
||||
即使在本地运行，也建议保留托管模型配置；使用 `models.mode: "merge"`，这样回退模型仍然可用。
|
||||
|
||||
### 混合配置：托管模型为主，本地模型为回退
|
||||
### 混合配置：托管主模型，本地回退
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -115,16 +115,16 @@ x-i18n:
|
||||
|
||||
### 本地优先，托管兜底
|
||||
|
||||
交换主模型与回退模型的顺序；保留相同的 provider 配置块和 `models.mode: "merge"`，这样当本地机器不可用时，你仍可以回退到 Sonnet 或 Opus。
|
||||
交换主模型和回退模型的顺序；保留相同的 providers 块和 `models.mode: "merge"`，这样当本地主机不可用时，你仍可回退到 Sonnet 或 Opus。
|
||||
|
||||
### 区域托管 / 数据路由
|
||||
|
||||
- 托管版的 MiniMax / Kimi / GLM 变体在 OpenRouter 上也有带区域固定端点的版本（例如托管在美国）。你可以在那里选择区域版本，把流量限制在你选定的司法辖区内，同时仍通过 `models.mode: "merge"` 使用 Anthropic / OpenAI 回退。
|
||||
- 纯本地仍然是隐私性最强的方案；当你需要提供商功能但又希望控制数据流向时，区域托管路由是折中方案。
|
||||
- 托管的 MiniMax/Kimi/GLM 变体也可通过 OpenRouter 获取，并提供区域固定端点（例如托管在美国）。你可以在那边选择区域变体，把流量限制在所选司法辖区内，同时继续使用 `models.mode: "merge"` 以保留 Anthropic/OpenAI 回退能力。
|
||||
- 纯本地仍然是隐私性最强的路径；当你需要提供商功能但又想控制数据流向时，托管的区域路由是折中方案。
|
||||
|
||||
## 其他兼容 OpenAI 的本地代理
|
||||
|
||||
如果 MLX（`mlx_lm.server`）、vLLM、SGLang、LiteLLM、OAI-proxy 或自定义 Gateway 网关暴露的是兼容 OpenAI 风格的 `/v1/chat/completions` 端点，就可以使用。除非后端明确记录支持 `/v1/responses`，否则请使用 Chat Completions 适配器。将上面的 provider 配置块替换为你的端点和模型 ID：
|
||||
MLX（`mlx_lm.server`）、vLLM、SGLang、LiteLLM、OAI-proxy 或自定义 Gateway 网关都可以使用，只要它们暴露兼容 OpenAI 风格的 `/v1/chat/completions` 端点。除非后端明确文档说明支持 `/v1/responses`，否则请使用 Chat Completions 适配器。将上面的 provider 块替换为你的端点和模型 ID：
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -158,31 +158,32 @@ x-i18n:
|
||||
}
|
||||
```
|
||||
|
||||
如果在带 `baseUrl` 的自定义 provider 上省略 `api`，OpenClaw 默认使用 `openai-completions`。像 `127.0.0.1` 这样的 loopback 端点会被自动信任；LAN、tailnet 和私有 DNS 端点仍需要设置 `request.allowPrivateNetwork: true`。
|
||||
如果在带有 `baseUrl` 的自定义提供商上省略 `api`，OpenClaw 默认使用 `openai-completions`。像 `127.0.0.1` 这样的 loopback 端点会被自动信任；但 LAN、tailnet 和私有 DNS 端点仍然需要设置 `request.allowPrivateNetwork: true`。
|
||||
|
||||
`models.providers.<id>.models[].id` 的值是 provider 本地值。不要在其中包含 provider 前缀。例如，用 `mlx_lm.server --model mlx-community/Qwen3-30B-A3B-6bit` 启动的 MLX 服务器应使用以下目录 ID 和模型引用：
|
||||
`models.providers.<id>.models[].id` 的值是提供商本地值。不要在这里包含提供商前缀。例如，使用 `mlx_lm.server --model mlx-community/Qwen3-30B-A3B-6bit` 启动的 MLX 服务器，应使用以下 catalog id 和模型引用：
|
||||
|
||||
- `models.providers.mlx.models[].id: "mlx-community/Qwen3-30B-A3B-6bit"`
|
||||
- `agents.defaults.model.primary: "mlx/mlx-community/Qwen3-30B-A3B-6bit"`
|
||||
|
||||
保留 `models.mode: "merge"`，这样托管模型仍可作为回退使用。对于慢速的本地或远程模型服务器，请优先使用 `models.providers.<id>.timeoutSeconds`，再考虑提高 `agents.defaults.timeoutSeconds`。provider 超时仅适用于模型 HTTP 请求，包括连接、响应头、流式响应体以及整个 guarded-fetch 的中止。
|
||||
保留 `models.mode: "merge"`，这样托管模型仍可作为回退使用。
|
||||
对于较慢的本地或远程模型服务器，应优先使用 `models.providers.<id>.timeoutSeconds`，再考虑提高 `agents.defaults.timeoutSeconds`。provider 超时仅适用于模型 HTTP 请求，包括连接、响应头、流式响应体，以及整个 guarded-fetch 的中止控制。
|
||||
|
||||
<Note>
|
||||
对于自定义兼容 OpenAI 的提供商，当 `baseUrl` 解析到 loopback、私有 LAN、`.local` 或裸主机名时，可以持久化一个非敏感的本地标记，例如 `apiKey: "ollama-local"`。OpenClaw 会将其视为有效的本地凭证，而不会报告缺少 key。对于接受公网主机名的提供商，请使用真实值。
|
||||
对于自定义兼容 OpenAI 的提供商，当 `baseUrl` 解析到 loopback、私有 LAN、`.local` 或裸主机名时，持久化一个非机密的本地标记（例如 `apiKey: "ollama-local"`）是允许的。OpenClaw 会将其视为有效的本地凭证，而不是报告缺失 key。对于接受公共主机名的任何提供商，请使用真实值。
|
||||
</Note>
|
||||
|
||||
关于本地 / 代理 `/v1` 后端的行为说明：
|
||||
|
||||
- OpenClaw 将这些视为代理风格的兼容 OpenAI 路由，而不是原生 OpenAI 端点
|
||||
- 仅适用于原生 OpenAI 的请求整形在这里不生效：没有 `service_tier`、没有 Responses `store`、没有 OpenAI 推理兼容载荷整形，也没有提示缓存提示
|
||||
- 在这些自定义代理 URL 上，不会注入隐藏的 OpenClaw 归因请求头（`originator`、`version`、`User-Agent`）
|
||||
- OpenClaw 会将这些视为代理风格的兼容 OpenAI 路由，而不是原生 OpenAI 端点
|
||||
- 原生 OpenAI 专用的请求整形在这里不适用：没有 `service_tier`、没有 Responses `store`、没有 OpenAI reasoning-compat payload shaping，也没有 prompt-cache 提示
|
||||
- 在这些自定义代理 URL 上，不会注入隐藏的 OpenClaw attribution headers（`originator`、`version`、`User-Agent`）
|
||||
|
||||
对于更严格的兼容 OpenAI 后端，兼容性注意事项如下：
|
||||
对于更严格的兼容 OpenAI 后端，兼容性说明如下：
|
||||
|
||||
- 有些服务器在 Chat Completions 中只接受字符串形式的 `messages[].content`，不接受结构化内容片段数组。对于这些端点，请设置 `models.providers.<provider>.models[].compat.requiresStringContent: true`。
|
||||
- 有些本地模型会以文本形式输出独立的方括号工具请求，例如 `[tool_name]` 后跟 JSON 和 `[END_TOOL_REQUEST]`。只有当该名称与本轮已注册工具完全匹配时，OpenClaw 才会将其提升为真实工具调用；否则，这个块会被视为不受支持的文本，并从用户可见回复中隐藏。
|
||||
- 如果模型输出了看起来像工具调用的 JSON、XML 或 ReAct 风格文本，但 provider 并未发出结构化调用，OpenClaw 会将其保留为文本，并记录一条警告，其中包含运行 id、provider / model、检测到的模式，以及可用时的工具名称。请将这视为 provider / model 的工具调用不兼容，而不是已完成的工具运行。
|
||||
- 如果工具以 assistant 文本形式出现而不是被执行，例如原始 JSON、XML、ReAct 语法，或 provider 响应中出现空的 `tool_calls` 数组，请先确认服务器使用的是支持工具调用的 chat template / parser。对于只有在强制使用工具时其 parser 才能正常工作的兼容 OpenAI Chat Completions 后端，请设置每模型请求覆盖，而不要依赖文本解析：
|
||||
- 某些服务器在 Chat Completions 中只接受字符串形式的 `messages[].content`，不接受结构化内容片段数组。对于这些端点，设置 `models.providers.<provider>.models[].compat.requiresStringContent: true`。
|
||||
- 某些本地模型会以文本形式输出独立的方括号工具请求，例如 `[tool_name]`，后接 JSON，再接 `[END_TOOL_REQUEST]`。只有当该名称与当前轮次已注册工具中的某个工具**完全匹配**时，OpenClaw 才会将其提升为真实工具调用；否则，该块会被视为不受支持的文本，并从面向用户的回复中隐藏。
|
||||
- 如果模型输出看起来像工具调用的 JSON、XML 或 ReAct 风格文本，但 provider 并未发出结构化调用，OpenClaw 会将其保留为文本，并在日志中记录警告，其中包含运行 id、provider/model、检测到的模式，以及可用时的工具名称。应将这视为 provider/model 的工具调用不兼容，而不是已完成的工具运行。
|
||||
- 如果工具以 assistant 文本形式出现而没有真正运行，例如原始 JSON、XML、ReAct 语法，或 provider 响应中出现空的 `tool_calls` 数组，请先确认服务器使用的是支持工具调用的 chat template/parser。对于那些只有在强制启用工具使用时其 parser 才能正常工作的兼容 OpenAI Chat Completions 后端，应设置按模型粒度的请求覆盖，而不是依赖文本解析：
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -202,26 +203,48 @@ x-i18n:
|
||||
}
|
||||
```
|
||||
|
||||
仅在每个正常轮次都应调用工具的模型 / 会话中使用此设置。它会覆盖 OpenClaw 默认的代理值 `tool_choice: "auto"`。将 `local/my-local-model` 替换为 `openclaw models list` 显示的精确 provider / model 引用。
|
||||
仅在每个普通轮次都应调用工具的模型 / 会话中使用此设置。
|
||||
它会覆盖 OpenClaw 默认的代理值 `tool_choice: "auto"`。
|
||||
将 `local/my-local-model` 替换为
|
||||
`openclaw models list` 显示的精确 provider/model 引用。
|
||||
|
||||
```bash
|
||||
openclaw config set agents.defaults.models '{"local/my-local-model":{"params":{"extra_body":{"tool_choice":"required"}}}}' --strict-json --merge
|
||||
```
|
||||
|
||||
- 某些较小或更严格的本地后端在面对 OpenClaw 完整的智能体运行时提示结构时不稳定，尤其是包含工具 schema 时。如果后端对于很小的直接 `/v1/chat/completions` 调用是正常的，但在正常 OpenClaw 智能体轮次中失败，请先尝试 `agents.defaults.experimental.localModelLean: true`，以去掉像 `browser`、`cron` 和 `message` 这样的重量级默认工具；这是实验性标志，不是稳定的默认模式设置。参见 [Experimental Features](/zh-CN/concepts/experimental-features)。如果仍然失败，再尝试 `models.providers.<provider>.models[].compat.supportsTools: false`。
|
||||
- 如果后端仍然只在较大的 OpenClaw 运行中失败，剩余问题通常是上游模型 / 服务器容量不足，或后端 bug，而不是 OpenClaw 的传输层问题。
|
||||
- 某些较小或更严格的本地后端在面对 OpenClaw 完整的智能体运行时提示结构时会不稳定，尤其是在包含工具 schema 时。请先使用精简的本地探针验证 provider 路径：
|
||||
|
||||
```bash
|
||||
openclaw infer model run --local --model <provider/model> --prompt "Reply with exactly: pong" --json
|
||||
```
|
||||
|
||||
如果这一步成功，但正常的 OpenClaw 智能体轮次失败，先尝试
|
||||
`agents.defaults.experimental.localModelLean: true`，以移除像 `browser`、`cron` 和 `message` 这样的重量级默认工具；这是一个实验性标志，不是稳定的默认模式设置。参见
|
||||
[Experimental Features](/zh-CN/concepts/experimental-features)。如果仍然失败，再尝试
|
||||
`models.providers.<provider>.models[].compat.supportsTools: false`。
|
||||
|
||||
- 如果后端仅在更大型的 OpenClaw 运行中仍然失败，剩余问题通常是上游模型 / 服务器容量不足或后端 bug，而不是 OpenClaw 的传输层问题。
|
||||
|
||||
## 故障排除
|
||||
|
||||
- Gateway 网关能访问代理吗？`curl http://127.0.0.1:1234/v1/models`
|
||||
- LM Studio 模型未加载？重新加载；冷启动是常见的“卡住”原因。
|
||||
- 本地服务器显示 `terminated`、`ECONNRESET`，或在轮次中途关闭流？OpenClaw 会在诊断中记录低基数的 `model.call.error.failureKind`，以及 OpenClaw 进程的 RSS / heap 快照。对于 LM Studio / Ollama 的内存压力问题，可将该时间戳与服务器日志或 macOS 崩溃 / jetsam 日志对照，以确认模型服务器是否被系统杀掉。
|
||||
- 当检测到上下文窗口低于 **32k** 时，OpenClaw 会发出警告；低于 **16k** 时会阻止运行。如果你触发了该 preflight，请提高服务器 / 模型的上下文限制，或选择更大的模型。
|
||||
- Gateway 网关能连到代理吗？`curl http://127.0.0.1:1234/v1/models`。
|
||||
- LM Studio 模型被卸载了？重新加载；冷启动是常见的“卡住”原因。
|
||||
- 本地服务器显示 `terminated`、`ECONNRESET`，或者在轮次进行中途关闭流？
|
||||
OpenClaw 会在诊断信息中记录低基数的 `model.call.error.failureKind`，以及
|
||||
OpenClaw 进程的 RSS/heap 快照。对于 LM Studio/Ollama 的内存压力问题，
|
||||
将该时间戳与服务器日志或 macOS 崩溃 / jetsam 日志对照，以确认模型服务器是否被系统杀掉。
|
||||
- 当检测到的上下文窗口低于 **32k** 时，OpenClaw 会发出警告；低于 **16k** 时会直接阻止运行。如果你触发了这个预检，请提高服务器 / 模型的上下文限制，或选择更大的模型。
|
||||
- 上下文错误？降低 `contextWindow` 或提高你的服务器限制。
|
||||
- 兼容 OpenAI 的服务器返回 `messages[].content ... expected a string`？在该模型条目上添加 `compat.requiresStringContent: true`。
|
||||
- 直接的小型 `/v1/chat/completions` 调用可以正常工作，但 `openclaw infer model run` 在 Gemma 或其他本地模型上失败？先用 `compat.supportsTools: false` 禁用工具 schema，然后重新测试。如果服务器仍然只在较大的 OpenClaw 提示下崩溃，请将其视为上游服务器 / 模型的限制。
|
||||
- 工具调用显示为原始 JSON / XML / ReAct 文本，或者 provider 返回空的 `tool_calls` 数组？不要添加一个盲目把 assistant 文本转换为工具执行的代理。先修复服务器的 chat template / parser。如果该模型只有在强制使用工具时才能工作，请添加上面的每模型 `params.extra_body.tool_choice: "required"` 覆盖，并且只在预计每轮都需要工具调用的会话中使用该模型条目。
|
||||
- 安全性：本地模型会跳过提供商侧过滤；请保持智能体范围狭窄，并开启压缩，以限制提示注入的影响范围。
|
||||
- 兼容 OpenAI 的服务器返回 `messages[].content ... expected a string`？
|
||||
在该模型条目上添加 `compat.requiresStringContent: true`。
|
||||
- 直接调用微型 `/v1/chat/completions` 可以工作，但 `openclaw infer model run --local`
|
||||
在 Gemma 或其他本地模型上失败？先检查 provider URL、模型引用、认证标记和服务器日志；本地 `model run` 不包含智能体工具。
|
||||
如果本地 `model run` 成功，但更大的智能体轮次失败，请使用 `localModelLean` 或 `compat.supportsTools: false` 来缩减智能体工具暴露面。
|
||||
- 工具调用以原始 JSON/XML/ReAct 文本形式出现，或者 provider 返回空的 `tool_calls` 数组？
|
||||
不要添加一个盲目把 assistant 文本转换为工具执行的代理。先修复服务器的 chat template/parser。
|
||||
如果模型只有在强制启用工具使用时才能正常工作，请添加上面的按模型粒度覆盖
|
||||
`params.extra_body.tool_choice: "required"`，并且仅在每轮都预期会调用工具的会话中使用该模型条目。
|
||||
- 安全性：本地模型会跳过提供商侧过滤；请保持智能体能力边界尽量收窄，并开启 compaction，以限制提示注入的影响范围。
|
||||
|
||||
## 相关内容
|
||||
|
||||
|
||||
@ -6,51 +6,51 @@ read_when:
|
||||
summary: 使用 Ollama 运行 OpenClaw（云端和本地模型）
|
||||
title: Ollama
|
||||
x-i18n:
|
||||
generated_at: "2026-04-27T12:55:46Z"
|
||||
generated_at: "2026-04-27T22:06:17Z"
|
||||
model: gpt-5.4
|
||||
provider: openai
|
||||
source_hash: a281eb9b7cf85705e749921f4fec7a998ea8bd186e7a95804cb307e41cd739cf
|
||||
source_hash: 965248027c46010cdd524d11afcfaeb7ccfb0dc326873bf5d9f3cd54569a4bfa
|
||||
source_path: providers/ollama.md
|
||||
workflow: 15
|
||||
---
|
||||
|
||||
OpenClaw 集成了 Ollama 的原生 API（`/api/chat`），可用于托管云模型以及本地/自托管的 Ollama 服务器。你可以通过三种模式使用 Ollama：通过可访问的 Ollama 主机使用 `Cloud + Local`、通过 `https://ollama.com` 使用 `Cloud only`，或通过可访问的 Ollama 主机使用 `Local only`。
|
||||
OpenClaw 通过 Ollama 的原生 API（`/api/chat`）集成托管云模型和本地/自托管 Ollama 服务器。你可以通过三种模式使用 Ollama：通过可访问的 Ollama 主机使用 `Cloud + Local`、对接 `https://ollama.com` 的 `Cloud only`，或对接可访问 Ollama 主机的 `Local only`。
|
||||
|
||||
<Warning>
|
||||
**远程 Ollama 用户**：不要在 OpenClaw 中使用 `/v1` OpenAI 兼容 URL（`http://host:11434/v1`）。这会破坏工具调用，模型还可能将原始工具 JSON 作为纯文本输出。请改用原生 Ollama API URL：`baseUrl: "http://host:11434"`（不要带 `/v1`）。
|
||||
</Warning>
|
||||
|
||||
Ollama 提供商配置使用 `baseUrl` 作为规范键名。出于与 OpenAI SDK 风格示例兼容的考虑，OpenClaw 也接受 `baseURL`，但新配置应优先使用 `baseUrl`。
|
||||
Ollama provider 配置使用 `baseUrl` 作为规范键名。OpenClaw 也接受 `baseURL` 以兼容 OpenAI SDK 风格的示例，但新配置应优先使用 `baseUrl`。
|
||||
|
||||
## 认证规则
|
||||
## 凭证规则
|
||||
|
||||
<AccordionGroup>
|
||||
<Accordion title="本地和局域网主机">
|
||||
本地和局域网中的 Ollama 主机不需要真实的 bearer token。对于 loopback、私有网络、`.local` 和裸主机名的 Ollama base URL，OpenClaw 仅使用本地 `ollama-local` 标记。
|
||||
本地和局域网 Ollama 主机不需要真实的 bearer token。OpenClaw 仅将本地 `ollama-local` 标记用于 loopback、私有网络、`.local` 和裸主机名 Ollama base URL。
|
||||
</Accordion>
|
||||
<Accordion title="远程和 Ollama Cloud 主机">
|
||||
远程公网主机和 Ollama Cloud（`https://ollama.com`）需要通过 `OLLAMA_API_KEY`、认证配置文件或提供商的 `apiKey` 提供真实凭证。
|
||||
远程公网主机和 Ollama Cloud（`https://ollama.com`）需要通过 `OLLAMA_API_KEY`、auth profile 或 provider 的 `apiKey` 提供真实凭证。
|
||||
</Accordion>
|
||||
<Accordion title="自定义提供商 id">
|
||||
将 `api: "ollama"` 作为配置的自定义提供商 id 遵循相同规则。例如，指向私有局域网 Ollama 主机的 `ollama-remote` 提供商可以使用 `apiKey: "ollama-local"`，子智能体会通过 Ollama 提供商钩子解析该标记，而不会将其视为缺失凭证。
|
||||
<Accordion title="自定义 provider id">
|
||||
将 `api: "ollama"` 设为自定义 provider id 时，也遵循相同规则。例如，指向私有局域网 Ollama 主机的 `ollama-remote` provider 可以使用 `apiKey: "ollama-local"`，子智能体会通过 Ollama provider hook 解析该标记，而不是将其视为缺失的凭证。
|
||||
</Accordion>
|
||||
<Accordion title="Memory 嵌入作用域">
|
||||
当 Ollama 用于 memory 嵌入时，bearer 认证会被限制在声明它的主机范围内：
|
||||
当 Ollama 用于 Memory 嵌入时，bearer 凭证会限定在声明它的主机作用域内：
|
||||
|
||||
- 提供商级别的密钥仅会发送到该提供商自己的 Ollama 主机。
|
||||
- `agents.*.memorySearch.remote.apiKey` 仅会发送到它自己的远程嵌入主机。
|
||||
- 纯 `OLLAMA_API_KEY` 环境变量值会被视为 Ollama Cloud 约定，默认不会发送到本地或自托管主机。
|
||||
- provider 级别的密钥只会发送到该 provider 的 Ollama 主机。
|
||||
- `agents.*.memorySearch.remote.apiKey` 只会发送到它自己的远程嵌入主机。
|
||||
- 单独的 `OLLAMA_API_KEY` 环境变量值会被视为 Ollama Cloud 约定，默认不会发送到本地或自托管主机。
|
||||
|
||||
</Accordion>
|
||||
</AccordionGroup>
|
||||
|
||||
## 入门指南
|
||||
|
||||
请选择你偏好的设置方式和模式。
|
||||
选择你偏好的设置方法和模式。
|
||||
|
||||
<Tabs>
|
||||
<Tab title="新手引导（推荐）">
|
||||
**最适合：** 以最快方式完成可用的 Ollama 云端或本地设置。
|
||||
**最适合：** 以最快路径完成可用的 Ollama 云端或本地设置。
|
||||
|
||||
<Steps>
|
||||
<Step title="运行新手引导">
|
||||
@ -58,15 +58,15 @@ Ollama 提供商配置使用 `baseUrl` 作为规范键名。出于与 OpenAI SDK
|
||||
openclaw onboard
|
||||
```
|
||||
|
||||
在提供商列表中选择 **Ollama**。
|
||||
从 provider 列表中选择 **Ollama**。
|
||||
</Step>
|
||||
<Step title="选择你的模式">
|
||||
- **Cloud + Local** — 本地 Ollama 主机，加上通过该主机路由的云模型
|
||||
- **Cloud only** — 通过 `https://ollama.com` 使用托管的 Ollama 模型
|
||||
- **Cloud only** — 通过 `https://ollama.com` 使用托管 Ollama 模型
|
||||
- **Local only** — 仅使用本地模型
|
||||
</Step>
|
||||
<Step title="选择一个模型">
|
||||
`Cloud only` 会提示输入 `OLLAMA_API_KEY`，并推荐托管云端默认模型。`Cloud + Local` 和 `Local only` 会要求提供 Ollama base URL，发现可用模型，并在所选本地模型尚不可用时自动拉取该模型。当 Ollama 报告已安装的 `:latest` 标签，例如 `gemma4:latest` 时，设置界面会仅显示该已安装模型一次，而不会同时显示 `gemma4` 和 `gemma4:latest`，也不会再次拉取裸别名。`Cloud + Local` 还会检查该 Ollama 主机是否已登录以访问云服务。
|
||||
<Step title="选择模型">
|
||||
`Cloud only` 会提示输入 `OLLAMA_API_KEY`，并推荐托管云默认模型。`Cloud + Local` 和 `Local only` 会要求提供一个 Ollama base URL，发现可用模型，并在所选本地模型尚不可用时自动拉取。当 Ollama 报告已安装的 `:latest` 标签（例如 `gemma4:latest`）时，设置界面只显示这一个已安装模型，而不会同时显示 `gemma4` 和 `gemma4:latest`，也不会再次拉取不带标签的别名。`Cloud + Local` 还会检查该 Ollama 主机是否已登录并启用云访问。
|
||||
</Step>
|
||||
<Step title="验证模型可用">
|
||||
```bash
|
||||
@ -83,7 +83,7 @@ Ollama 提供商配置使用 `baseUrl` 作为规范键名。出于与 OpenAI SDK
|
||||
--accept-risk
|
||||
```
|
||||
|
||||
也可以选择性指定自定义 base URL 或模型：
|
||||
也可以选择指定自定义 base URL 或模型：
|
||||
|
||||
```bash
|
||||
openclaw onboard --non-interactive \
|
||||
@ -127,7 +127,7 @@ Ollama 提供商配置使用 `baseUrl` 作为规范键名。出于与 OpenAI SDK
|
||||
openclaw config set models.providers.ollama.apiKey "OLLAMA_API_KEY"
|
||||
```
|
||||
</Step>
|
||||
<Step title="查看并设置你的模型">
|
||||
<Step title="检查并设置你的模型">
|
||||
```bash
|
||||
openclaw models list
|
||||
openclaw models set ollama/gemma4
|
||||
@ -154,76 +154,99 @@ Ollama 提供商配置使用 `baseUrl` 作为规范键名。出于与 OpenAI SDK
|
||||
|
||||
<Tabs>
|
||||
<Tab title="Cloud + Local">
|
||||
`Cloud + Local` 使用一个可访问的 Ollama 主机，作为本地和云模型的统一控制点。这是 Ollama 推荐的混合流程。
|
||||
`Cloud + Local` 使用一个可访问的 Ollama 主机作为本地模型和云模型的统一控制点。这是 Ollama 首选的混合工作流。
|
||||
|
||||
在设置期间使用 **Cloud + Local**。OpenClaw 会提示输入 Ollama base URL，从该主机发现本地模型，并检查该主机是否已通过 `ollama signin` 登录以访问云服务。当主机已登录时，OpenClaw 还会推荐托管云端默认模型，例如 `kimi-k2.5:cloud`、`minimax-m2.7:cloud` 和 `glm-5.1:cloud`。
|
||||
在设置期间使用 **Cloud + Local**。OpenClaw 会提示输入 Ollama base URL，从该主机发现本地模型，并检查该主机是否已通过 `ollama signin` 登录以启用云访问。当主机已登录时，OpenClaw 还会推荐托管云默认模型，例如 `kimi-k2.5:cloud`、`minimax-m2.7:cloud` 和 `glm-5.1:cloud`。
|
||||
|
||||
如果该主机尚未登录，OpenClaw 会将设置保持为仅本地模式，直到你运行 `ollama signin`。
|
||||
如果该主机尚未登录，OpenClaw 会保持仅本地设置，直到你运行 `ollama signin`。
|
||||
|
||||
</Tab>
|
||||
|
||||
<Tab title="Cloud only">
|
||||
`Cloud only` 通过 `https://ollama.com` 上的 Ollama 托管 API 运行。
|
||||
`Cloud only` 对接 Ollama 的托管 API：`https://ollama.com`。
|
||||
|
||||
在设置期间使用 **Cloud only**。OpenClaw 会提示输入 `OLLAMA_API_KEY`，设置 `baseUrl: "https://ollama.com"`，并初始化托管云模型列表。此路径**不需要**本地 Ollama 服务器或 `ollama signin`。
|
||||
在设置期间使用 **Cloud only**。OpenClaw 会提示输入 `OLLAMA_API_KEY`，设置 `baseUrl: "https://ollama.com"`，并初始化托管云模型列表。此路径**不**需要本地 Ollama 服务器或 `ollama signin`。
|
||||
|
||||
`openclaw onboard` 期间显示的云模型列表会通过 `https://ollama.com/api/tags` 实时填充，最多 500 条，因此选择器反映的是当前托管目录，而不是静态种子。如果设置时 `ollama.com` 不可达或未返回模型，OpenClaw 会回退到之前的硬编码建议，以便新手引导仍能完成。
|
||||
`openclaw onboard` 期间显示的云模型列表会从 `https://ollama.com/api/tags` 实时填充，最多 500 项，因此选择器反映的是当前托管目录，而不是静态种子列表。如果设置时 `ollama.com` 无法访问或未返回任何模型，OpenClaw 会回退到之前硬编码的推荐项，以便新手引导仍可完成。
|
||||
|
||||
</Tab>
|
||||
|
||||
<Tab title="Local only">
|
||||
在仅本地模式下，OpenClaw 会从已配置的 Ollama 实例发现模型。此路径适用于本地或自托管 Ollama 服务器。
|
||||
在仅本地模式下，OpenClaw 会从已配置的 Ollama 实例中发现模型。此路径适用于本地或自托管 Ollama 服务器。
|
||||
|
||||
OpenClaw 当前推荐 `gemma4` 作为本地默认模型。
|
||||
|
||||
</Tab>
|
||||
</Tabs>
|
||||
|
||||
## 模型发现（隐式提供商）
|
||||
## 模型发现（隐式 provider）
|
||||
|
||||
当你设置了 `OLLAMA_API_KEY`（或认证配置文件），并且**没有**定义 `models.providers.ollama` 或其他使用 `api: "ollama"` 的自定义远程提供商时，OpenClaw 会从本地 `http://127.0.0.1:11434` 上的 Ollama 实例发现模型。
|
||||
当你设置 `OLLAMA_API_KEY`（或 auth profile），并且**没有**定义 `models.providers.ollama` 或其他设置了 `api: "ollama"` 的自定义远程 provider 时，OpenClaw 会从 `http://127.0.0.1:11434` 上的本地 Ollama 实例发现模型。
|
||||
|
||||
| 行为 | 详情 |
|
||||
| -------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
||||
| 目录查询 | 查询 `/api/tags` |
|
||||
| 能力检测 | 使用尽力而为的 `/api/show` 查询来读取 `contextWindow`、展开的 `num_ctx` Modelfile 参数，以及包括 vision/tools 在内的能力 |
|
||||
| 视觉模型 | `/api/show` 报告具备 `vision` 能力的模型会被标记为支持图像（`input: ["text", "image"]`），因此 OpenClaw 会自动将图片注入提示中 |
|
||||
| 能力检测 | 使用尽力而为的 `/api/show` 查询读取 `contextWindow`、展开的 `num_ctx` Modelfile 参数，以及包括 vision/tools 在内的能力 |
|
||||
| 视觉模型 | 对于 `/api/show` 报告具有 `vision` 能力的模型，会标记为支持图像（`input: ["text", "image"]`），因此 OpenClaw 会自动将图像注入提示词 |
|
||||
| 推理检测 | 使用模型名称启发式（`r1`、`reasoning`、`think`）标记 `reasoning` |
|
||||
| Token 限制 | 将 `maxTokens` 设置为 OpenClaw 使用的默认 Ollama 最大 token 上限 |
|
||||
| 成本 | 将所有成本设置为 `0` |
|
||||
| Token 限制 | 将 `maxTokens` 设为 OpenClaw 使用的默认 Ollama 最大 token 上限 |
|
||||
| 成本 | 将所有成本设为 `0` |
|
||||
|
||||
这样可以避免手动填写模型条目，同时使目录与本地 Ollama 实例保持一致。
|
||||
这样可以避免手动录入模型，同时使模型目录与本地 Ollama 实例保持一致。你可以在本地 `infer model run` 中使用完整引用，例如 `ollama/<pulled-model>:latest`；OpenClaw 会从 Ollama 的实时目录中解析该已安装模型，而无需手写 `models.json` 条目。
|
||||
|
||||
```bash
|
||||
# 查看有哪些模型可用
|
||||
# 查看有哪些可用模型
|
||||
ollama list
|
||||
openclaw models list
|
||||
```
|
||||
|
||||
要添加新模型，只需用 Ollama 拉取它：
|
||||
对于避免加载完整智能体工具面的窄范围文本生成冒烟测试，
|
||||
请在本地 `infer model run` 中使用完整的 Ollama 模型引用：
|
||||
|
||||
```bash
|
||||
OLLAMA_API_KEY=ollama-local \
|
||||
openclaw infer model run \
|
||||
--local \
|
||||
--model ollama/llama3.2:latest \
|
||||
--prompt "Reply with exactly: pong" \
|
||||
--json
|
||||
```
|
||||
|
||||
这一路径仍然使用 OpenClaw 已配置的 provider、auth 和原生 Ollama
|
||||
传输，但不会启动聊天智能体轮次，也不会加载 MCP/工具上下文。如果
|
||||
这里成功而普通智能体回复失败，请接下来排查模型的智能体提示词/工具能力。
|
||||
|
||||
通过以下命令，你可以对接本地 Ollama，实时验证本地文本路径、原生流式路径和嵌入：
|
||||
|
||||
```bash
|
||||
OPENCLAW_LIVE_TEST=1 OPENCLAW_LIVE_OLLAMA=1 OPENCLAW_LIVE_OLLAMA_WEB_SEARCH=0 \
|
||||
pnpm test:live -- extensions/ollama/ollama.live.test.ts
|
||||
```
|
||||
|
||||
要添加新模型，只需使用 Ollama 拉取它：
|
||||
|
||||
```bash
|
||||
ollama pull mistral
|
||||
```
|
||||
|
||||
新模型会被自动发现，并可直接使用。
|
||||
新模型会被自动发现并可立即使用。
|
||||
|
||||
<Note>
|
||||
如果你显式设置了 `models.providers.ollama`，或配置了像 `models.providers.ollama-cloud` 这样的自定义远程提供商并设置 `api: "ollama"`，则会跳过自动发现，你必须手动定义模型。像 `http://127.0.0.2:11434` 这样的 loopback 自定义提供商仍会被视为本地。请参见下方的显式配置部分。
|
||||
如果你显式设置了 `models.providers.ollama`，或配置了像 `models.providers.ollama-cloud` 这样带有 `api: "ollama"` 的自定义远程 provider，则会跳过自动发现，你必须手动定义模型。像 `http://127.0.0.2:11434` 这样的 loopback 自定义 provider 仍会被视为本地。请参阅下面的显式配置部分。
|
||||
</Note>
|
||||
|
||||
## 视觉与图像描述
|
||||
## 视觉和图像描述
|
||||
|
||||
内置的 Ollama 插件将 Ollama 注册为支持图像的媒体理解提供商。这使得 OpenClaw 能够将显式图像描述请求以及已配置的默认图像模型，路由到本地或托管的 Ollama 视觉模型。
|
||||
内置的 Ollama 插件将 Ollama 注册为支持图像的媒体理解 provider。这使 OpenClaw 可以通过本地或托管的 Ollama 视觉模型，路由显式图像描述请求以及已配置的默认图像模型。
|
||||
|
||||
对于本地视觉，请拉取一个支持图像的模型：
|
||||
对于本地视觉支持，请拉取一个支持图像的模型：
|
||||
|
||||
```bash
|
||||
ollama pull qwen2.5vl:7b
|
||||
export OLLAMA_API_KEY="ollama-local"
|
||||
```
|
||||
|
||||
然后用 infer CLI 验证：
|
||||
然后使用 infer CLI 验证：
|
||||
|
||||
```bash
|
||||
openclaw infer image describe \
|
||||
@ -232,9 +255,9 @@ openclaw infer image describe \
|
||||
--json
|
||||
```
|
||||
|
||||
`--model` 必须是完整的 `<provider/model>` 引用。设置后，`openclaw infer image describe` 会直接运行该模型，而不会因为模型支持原生视觉就跳过描述。
|
||||
`--model` 必须是完整的 `<provider/model>` 引用。设置后，`openclaw infer image describe` 会直接运行该模型，而不会因为模型支持原生视觉能力而跳过描述。
|
||||
|
||||
要让 Ollama 成为入站媒体的默认图像理解模型，请配置 `agents.defaults.imageModel`：
|
||||
如果你想将 Ollama 设为入站媒体的默认图像理解模型，请配置 `agents.defaults.imageModel`：
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -248,7 +271,7 @@ openclaw infer image describe \
|
||||
}
|
||||
```
|
||||
|
||||
较慢的本地视觉模型通常比云模型需要更长的图像理解超时时间。它们还可能在硬件受限时，因为 Ollama 尝试分配完整宣告的视觉上下文而崩溃或停止。请设置能力超时，并在模型条目上限制 `num_ctx`，如果你只需要普通的图像描述轮次：
|
||||
较慢的本地视觉模型可能需要比云模型更长的图像理解超时时间。它们在硬件受限时，也可能会在 Ollama 尝试分配完整宣称的视觉上下文时崩溃或停止。请设置能力超时，并在模型条目上限制 `num_ctx`，如果你只需要普通的图像描述轮次：
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -277,16 +300,16 @@ openclaw infer image describe \
|
||||
}
|
||||
```
|
||||
|
||||
这个超时同时适用于入站图像理解，以及智能体在轮次中可调用的显式 `image` 工具。提供商级别的 `models.providers.ollama.timeoutSeconds` 仍然控制普通模型调用所使用的底层 Ollama HTTP 请求保护时间。
|
||||
此超时同时适用于入站图像理解，以及智能体在一次轮次中可以调用的显式 `image` 工具。provider 级别的 `models.providers.ollama.timeoutSeconds` 仍然控制普通模型调用时底层 Ollama HTTP 请求的保护超时。
|
||||
|
||||
你可以通过以下方式，对本地 Ollama 的显式图像工具进行实时验证：
|
||||
通过以下命令，你可以对接本地 Ollama，实时验证显式图像工具：
|
||||
|
||||
```bash
|
||||
OPENCLAW_LIVE_TEST=1 OPENCLAW_LIVE_OLLAMA_IMAGE=1 \
|
||||
pnpm test:live -- src/agents/tools/image-tool.ollama.live.test.ts
|
||||
```
|
||||
|
||||
如果你手动定义了 `models.providers.ollama.models`，请为视觉模型标记图像输入支持：
|
||||
如果你手动定义 `models.providers.ollama.models`，请将视觉模型标记为支持图像输入：
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -298,7 +321,7 @@ OPENCLAW_LIVE_TEST=1 OPENCLAW_LIVE_OLLAMA_IMAGE=1 \
|
||||
}
|
||||
```
|
||||
|
||||
对于未标记为支持图像的模型，OpenClaw 会拒绝图像描述请求。使用隐式发现时，如果 `/api/show` 报告了视觉能力，OpenClaw 会从 Ollama 读取这一点。
|
||||
OpenClaw 会拒绝未标记为支持图像能力的模型的图像描述请求。在隐式发现模式下，当 `/api/show` 报告 vision 能力时，OpenClaw 会从 Ollama 读取此信息。
|
||||
|
||||
## 配置
|
||||
|
||||
@ -311,13 +334,13 @@ OPENCLAW_LIVE_TEST=1 OPENCLAW_LIVE_OLLAMA_IMAGE=1 \
|
||||
```
|
||||
|
||||
<Tip>
|
||||
如果设置了 `OLLAMA_API_KEY`，你可以在提供商条目中省略 `apiKey`，OpenClaw 会在可用性检查时自动补全它。
|
||||
如果已设置 `OLLAMA_API_KEY`，你可以在 provider 条目中省略 `apiKey`，OpenClaw 会自动填充它以进行可用性检查。
|
||||
</Tip>
|
||||
|
||||
</Tab>
|
||||
|
||||
<Tab title="显式（手动模型）">
|
||||
当你想使用托管云端设置、Ollama 运行在其他主机/端口、想强制指定特定上下文窗口或模型列表，或想完全手动定义模型时，请使用显式配置。
|
||||
<Tab title="显式配置（手动模型）">
|
||||
如果你想使用托管云设置、Ollama 运行在其他主机/端口、想强制指定特定上下文窗口或模型列表，或想完全手动定义模型，请使用显式配置。
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -347,7 +370,7 @@ OPENCLAW_LIVE_TEST=1 OPENCLAW_LIVE_OLLAMA_IMAGE=1 \
|
||||
</Tab>
|
||||
|
||||
<Tab title="自定义 base URL">
|
||||
如果 Ollama 运行在其他主机或端口上（显式配置会禁用自动发现，因此你需要手动定义模型）：
|
||||
如果 Ollama 运行在不同的主机或端口上（显式配置会禁用自动发现，因此需要手动定义模型）：
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -355,9 +378,9 @@ OPENCLAW_LIVE_TEST=1 OPENCLAW_LIVE_OLLAMA_IMAGE=1 \
|
||||
providers: {
|
||||
ollama: {
|
||||
apiKey: "ollama-local",
|
||||
baseUrl: "http://ollama-host:11434", // 不要加 /v1 - 使用原生 Ollama API URL
|
||||
baseUrl: "http://ollama-host:11434", // 不要加 /v1 —— 请使用原生 Ollama API URL
|
||||
api: "ollama", // 显式设置以确保原生工具调用行为
|
||||
timeoutSeconds: 300, // 可选：给冷启动的本地模型更长的连接和流式传输时间
|
||||
timeoutSeconds: 300, // 可选：为冷启动的本地模型提供更长的连接和流式传输时间
|
||||
models: [
|
||||
{
|
||||
id: "qwen3:32b",
|
||||
@ -374,19 +397,19 @@ OPENCLAW_LIVE_TEST=1 OPENCLAW_LIVE_OLLAMA_IMAGE=1 \
|
||||
```
|
||||
|
||||
<Warning>
|
||||
不要在 URL 中添加 `/v1`。`/v1` 路径使用 OpenAI 兼容模式，此模式下工具调用并不可靠。请使用不带路径后缀的基础 Ollama URL。
|
||||
不要在 URL 中添加 `/v1`。`/v1` 路径使用 OpenAI 兼容模式，在该模式下工具调用并不可靠。请使用不带路径后缀的 Ollama 基础 URL。
|
||||
</Warning>
|
||||
|
||||
</Tab>
|
||||
</Tabs>
|
||||
|
||||
## 常见配方
|
||||
## 常见方案
|
||||
|
||||
请将这些作为起点，并将模型 id 替换为 `ollama list` 或 `openclaw models list --provider ollama` 中显示的精确名称。
|
||||
你可以将这些作为起点，然后用 `ollama list` 或 `openclaw models list --provider ollama` 中显示的准确模型名称替换模型 ID。
|
||||
|
||||
<AccordionGroup>
|
||||
<Accordion title="带自动发现的本地模型">
|
||||
当 Ollama 与 Gateway 网关 运行在同一台机器上，并且你希望 OpenClaw 自动发现已安装模型时，请使用此方式。
|
||||
<Accordion title="使用自动发现的本地模型">
|
||||
当 Ollama 与 Gateway 网关 运行在同一台机器上，并且你希望 OpenClaw 自动发现已安装模型时，请使用此方案。
|
||||
|
||||
```bash
|
||||
ollama serve
|
||||
@ -396,12 +419,12 @@ OPENCLAW_LIVE_TEST=1 OPENCLAW_LIVE_OLLAMA_IMAGE=1 \
|
||||
openclaw models set ollama/gemma4
|
||||
```
|
||||
|
||||
这种方式能保持配置最简。除非你想手动定义模型，否则不要添加 `models.providers.ollama` 块。
|
||||
该路径可保持配置最简。除非你想手动定义模型，否则不要添加 `models.providers.ollama` 配置块。
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="带手动模型的局域网 Ollama 主机">
|
||||
对于局域网主机，请使用原生 Ollama URL。不要添加 `/v1`。
|
||||
对局域网主机请使用原生 Ollama URL。不要添加 `/v1`。
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -438,12 +461,12 @@ OPENCLAW_LIVE_TEST=1 OPENCLAW_LIVE_OLLAMA_IMAGE=1 \
|
||||
}
|
||||
```
|
||||
|
||||
`contextWindow` 是 OpenClaw 侧的上下文预算。`params.num_ctx` 会随请求发送到 Ollama。当你的硬件无法运行模型宣称的完整上下文时，请保持两者一致。
|
||||
`contextWindow` 是 OpenClaw 侧的上下文预算。`params.num_ctx` 会随请求发送给 Ollama。当你的硬件无法运行模型宣称的完整上下文时，请保持两者一致。
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="仅 Ollama Cloud">
|
||||
当你不运行本地守护进程，而想直接使用托管的 Ollama 模型时，请使用此方式。
|
||||
当你不运行本地守护进程，并且想直接使用托管 Ollama 模型时，请使用此方案。
|
||||
|
||||
```bash
|
||||
export OLLAMA_API_KEY="your-ollama-api-key"
|
||||
@ -481,7 +504,7 @@ OPENCLAW_LIVE_TEST=1 OPENCLAW_LIVE_OLLAMA_IMAGE=1 \
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="通过已登录守护进程同时使用云端和本地">
|
||||
当本地或局域网 Ollama 守护进程已通过 `ollama signin` 登录，并且应同时提供本地模型和 `:cloud` 模型时，请使用此方式。
|
||||
当本地或局域网 Ollama 守护进程已通过 `ollama signin` 登录，并且应该同时提供本地模型和 `:cloud` 模型时，请使用此方案。
|
||||
|
||||
```bash
|
||||
ollama signin
|
||||
@ -518,7 +541,7 @@ OPENCLAW_LIVE_TEST=1 OPENCLAW_LIVE_OLLAMA_IMAGE=1 \
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="多个 Ollama 主机">
|
||||
当你有多个 Ollama 服务器时，请使用自定义提供商 id。每个提供商都有各自的主机、模型、认证、超时和模型引用。
|
||||
当你拥有多个 Ollama 服务器时，请使用自定义 provider ID。每个 provider 都有自己的主机、模型、凭证、超时和模型引用。
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -553,12 +576,12 @@ OPENCLAW_LIVE_TEST=1 OPENCLAW_LIVE_OLLAMA_IMAGE=1 \
|
||||
}
|
||||
```
|
||||
|
||||
当 OpenClaw 发送请求时，活动提供商前缀会被去掉，因此 `ollama-large/qwen3.5:27b` 到达 Ollama 时会变成 `qwen3.5:27b`。
|
||||
当 OpenClaw 发送请求时，活动 provider 前缀会被去掉，因此 `ollama-large/qwen3.5:27b` 到达 Ollama 时会变成 `qwen3.5:27b`。
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="精简的本地模型配置">
|
||||
一些本地模型可以回答简单提示，但难以处理完整的智能体工具接口。在修改全局运行时设置之前，请先从限制工具和上下文开始。
|
||||
某些本地模型可以回答简单提示，但难以应对完整的智能体工具面。开始时，先限制工具和上下文，再考虑更改全局运行时设置。
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -592,8 +615,8 @@ OPENCLAW_LIVE_TEST=1 OPENCLAW_LIVE_OLLAMA_IMAGE=1 \
|
||||
}
|
||||
```
|
||||
|
||||
仅当模型或服务器在工具 schema 上稳定失败时，才使用 `compat.supportsTools: false`。它是用智能体能力换取稳定性。
|
||||
`localModelLean` 会从智能体接口中移除浏览器、cron 和消息工具，但不会改变 Ollama 的运行时上下文或 thinking 模式。对于会循环或把回复预算耗费在隐藏推理上的小型 Qwen 风格 thinking 模型，请将它与显式的 `params.num_ctx` 和 `params.thinking: false` 搭配使用。
|
||||
仅当模型或服务器在工具 schema 上稳定失败时，才使用 `compat.supportsTools: false`。这会以牺牲智能体能力换取稳定性。
|
||||
`localModelLean` 会从智能体面中移除浏览器、cron 和消息工具，但不会改变 Ollama 的运行时上下文或 thinking 模式。对于会循环或将回复预算耗费在隐藏推理上的小型 Qwen 风格 thinking 模型，请将它与显式的 `params.num_ctx` 和 `params.thinking: false` 搭配使用。
|
||||
|
||||
</Accordion>
|
||||
</AccordionGroup>
|
||||
@ -615,12 +638,12 @@ OPENCLAW_LIVE_TEST=1 OPENCLAW_LIVE_OLLAMA_IMAGE=1 \
|
||||
}
|
||||
```
|
||||
|
||||
也支持自定义 Ollama 提供商 id。当模型引用使用活动中的
|
||||
提供商前缀，例如 `ollama-spark/qwen3:32b` 时，OpenClaw 只会去掉该
|
||||
前缀，然后再调用 Ollama，因此服务器接收到的是 `qwen3:32b`。
|
||||
也支持自定义 Ollama provider ID。当模型引用使用活动
|
||||
provider 前缀时，例如 `ollama-spark/qwen3:32b`，OpenClaw 在调用 Ollama 前只会去掉该
|
||||
前缀，因此服务器接收到的是 `qwen3:32b`。
|
||||
|
||||
对于较慢的本地模型，优先考虑对提供商范围的请求进行调优，而不是提高
|
||||
整个智能体运行时超时：
|
||||
对于较慢的本地模型，优先考虑使用 provider 作用域的请求调优，而不是提升整个
|
||||
智能体运行时超时：
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -642,17 +665,17 @@ OPENCLAW_LIVE_TEST=1 OPENCLAW_LIVE_OLLAMA_IMAGE=1 \
|
||||
```
|
||||
|
||||
`timeoutSeconds` 适用于模型 HTTP 请求，包括连接建立、
|
||||
请求头、正文流式传输以及总的 guarded-fetch 中止。`params.keep_alive`
|
||||
会在原生 `/api/chat` 请求中作为顶层 `keep_alive` 转发给 Ollama；
|
||||
headers、正文流式传输，以及整个受保护获取请求的中止。`params.keep_alive`
|
||||
会作为顶层 `keep_alive` 转发给 Ollama 的原生 `/api/chat` 请求；
|
||||
当首轮加载时间是瓶颈时，请按模型设置它。
|
||||
|
||||
### 快速验证
|
||||
|
||||
```bash
|
||||
# 当前机器可见的 Ollama 守护进程
|
||||
# 此机器可见的 Ollama 守护进程
|
||||
curl http://127.0.0.1:11434/api/tags
|
||||
|
||||
# OpenClaw 目录和已选模型
|
||||
# OpenClaw 目录和已选择模型
|
||||
openclaw models list --provider ollama
|
||||
openclaw models status
|
||||
|
||||
@ -662,19 +685,19 @@ openclaw infer model run \
|
||||
--prompt "Reply with exactly: ok"
|
||||
```
|
||||
|
||||
对于远程主机，请将 `127.0.0.1` 替换为 `baseUrl` 中使用的主机。如果 `curl` 能工作但 OpenClaw 不行，请检查 Gateway 网关 是否运行在不同的机器、容器或服务账户中。
|
||||
对于远程主机，请将 `127.0.0.1` 替换为 `baseUrl` 中使用的主机。如果 `curl` 可用但 OpenClaw 不可用，请检查 Gateway 网关 是否运行在不同的机器、容器或服务账户下。
|
||||
|
||||
## Ollama Web 搜索
|
||||
|
||||
OpenClaw 支持 **Ollama Web 搜索**，作为内置 `web_search` 提供商。
|
||||
OpenClaw 支持将 **Ollama Web 搜索** 作为内置 `web_search` provider。
|
||||
|
||||
| 属性 | 详情 |
|
||||
| ----------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
||||
| 主机 | 使用你已配置的 Ollama 主机（设置了 `models.providers.ollama.baseUrl` 时使用它，否则使用 `http://127.0.0.1:11434`）；`https://ollama.com` 会直接使用托管 API |
|
||||
| 认证 | 对已登录的本地 Ollama 主机无需密钥；对直接的 `https://ollama.com` 搜索或受保护主机，使用 `OLLAMA_API_KEY` 或已配置的提供商认证 |
|
||||
| 要求 | 本地/自托管主机必须正在运行并已通过 `ollama signin` 登录；直接的托管搜索需要 `baseUrl: "https://ollama.com"` 并提供真实的 Ollama API 密钥 |
|
||||
| 主机 | 使用你配置的 Ollama 主机（设置了 `models.providers.ollama.baseUrl` 时使用该值，否则使用 `http://127.0.0.1:11434`）；`https://ollama.com` 直接使用托管 API |
|
||||
| 凭证 | 对已登录的本地 Ollama 主机无需密钥；对于直接 `https://ollama.com` 搜索或受保护的主机，使用 `OLLAMA_API_KEY` 或已配置的 provider 凭证 |
|
||||
| 要求 | 本地/自托管主机必须正在运行，并已通过 `ollama signin` 登录；直接使用托管搜索则需要 `baseUrl: "https://ollama.com"` 加上真实的 Ollama API 密钥 |
|
||||
|
||||
在 `openclaw onboard` 或 `openclaw configure --section web` 期间选择 **Ollama Web 搜索**，或设置：
|
||||
在 `openclaw onboard` 或 `openclaw configure --section web` 期间选择 **Ollama Web 搜索**，或者设置：
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -688,7 +711,7 @@ OpenClaw 支持 **Ollama Web 搜索**，作为内置 `web_search` 提供商。
|
||||
}
|
||||
```
|
||||
|
||||
如需通过 Ollama Cloud 直接进行托管搜索：
|
||||
若要通过 Ollama Cloud 直接使用托管搜索：
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -713,7 +736,7 @@ OpenClaw 支持 **Ollama Web 搜索**，作为内置 `web_search` 提供商。
|
||||
对于已登录的本地守护进程，OpenClaw 会使用该守护进程的 `/api/experimental/web_search` 代理。对于 `https://ollama.com`，它会直接调用托管的 `/api/web_search` 端点。
|
||||
|
||||
<Note>
|
||||
完整的设置和行为细节请参见 [Ollama Web 搜索](/zh-CN/tools/ollama-search)。
|
||||
有关完整的设置和行为细节，请参阅 [Ollama Web 搜索](/zh-CN/tools/ollama-search)。
|
||||
</Note>
|
||||
|
||||
## 高级配置
|
||||
@ -721,10 +744,10 @@ OpenClaw 支持 **Ollama Web 搜索**，作为内置 `web_search` 提供商。
|
||||
<AccordionGroup>
|
||||
<Accordion title="旧版 OpenAI 兼容模式">
|
||||
<Warning>
|
||||
**在 OpenAI 兼容模式下，工具调用并不可靠。** 仅当你需要为某个代理使用 OpenAI 格式，并且不依赖原生工具调用行为时，才应使用此模式。
|
||||
**在 OpenAI 兼容模式下，工具调用并不可靠。** 仅当你需要为代理使用 OpenAI 格式，并且不依赖原生工具调用行为时，才使用此模式。
|
||||
</Warning>
|
||||
|
||||
如果你确实需要改用 OpenAI 兼容端点（例如，在仅支持 OpenAI 格式的代理后面），请显式设置 `api: "openai-completions"`：
|
||||
如果你确实需要改用 OpenAI 兼容端点（例如位于仅支持 OpenAI 格式的代理后面），请显式设置 `api: "openai-completions"`：
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -742,9 +765,9 @@ OpenClaw 支持 **Ollama Web 搜索**，作为内置 `web_search` 提供商。
|
||||
}
|
||||
```
|
||||
|
||||
在此模式下，可能无法同时支持流式传输和工具调用。你可能需要在模型配置中使用 `params: { streaming: false }` 禁用流式传输。
|
||||
该模式可能不支持同时进行流式传输和工具调用。你可能需要在模型配置中使用 `params: { streaming: false }` 禁用流式传输。
|
||||
|
||||
当 Ollama 使用 `api: "openai-completions"` 时，OpenClaw 默认会注入 `options.num_ctx`，这样 Ollama 就不会悄悄回退到 4096 的上下文窗口。如果你的代理/上游拒绝未知的 `options` 字段，请禁用此行为：
|
||||
当 `api: "openai-completions"` 与 Ollama 一起使用时，OpenClaw 默认会注入 `options.num_ctx`，这样 Ollama 就不会悄悄回退到 4096 的上下文窗口。如果你的代理/上游拒绝未知的 `options` 字段，请禁用此行为：
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -765,11 +788,11 @@ OpenClaw 支持 **Ollama Web 搜索**，作为内置 `web_search` 提供商。
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="上下文窗口">
|
||||
对于自动发现的模型，OpenClaw 会在可用时使用 Ollama 报告的上下文窗口，包括来自自定义 Modelfile 的更大 `PARAMETER num_ctx` 值。否则，它会回退到 OpenClaw 使用的默认 Ollama 上下文窗口。
|
||||
对于自动发现的模型，OpenClaw 会在可用时使用 Ollama 报告的上下文窗口，包括来自自定义 Modelfiles 的更大 `PARAMETER num_ctx` 值。否则，它会回退到 OpenClaw 使用的默认 Ollama 上下文窗口。
|
||||
|
||||
你可以为该 Ollama 提供商下的每个模型设置提供商级别的 `contextWindow`、`contextTokens` 和 `maxTokens` 默认值，然后在需要时按模型覆盖。`contextWindow` 是 OpenClaw 的提示和压缩摘要预算。原生 Ollama 请求默认不会设置 `options.num_ctx`，除非你显式配置了 `params.num_ctx`，这样 Ollama 就可以应用它自己的模型、`OLLAMA_CONTEXT_LENGTH` 或基于 VRAM 的默认值。要在不重建 Modelfile 的情况下限制或强制 Ollama 的逐请求运行时上下文，请设置 `params.num_ctx`；无效、零、负数和非有限值会被忽略。OpenAI 兼容的 Ollama 适配器仍会默认从配置的 `params.num_ctx` 或 `contextWindow` 注入 `options.num_ctx`；如果你的上游拒绝 `options`，请使用 `injectNumCtxForOpenAICompat: false` 禁用此行为。
|
||||
你可以为该 Ollama provider 下的每个模型设置 provider 级别的 `contextWindow`、`contextTokens` 和 `maxTokens` 默认值，然后在需要时按模型覆盖。`contextWindow` 是 OpenClaw 的提示词和压缩预算。原生 Ollama 请求不会设置 `options.num_ctx`，除非你显式配置 `params.num_ctx`，这样 Ollama 就可以应用自己的模型、`OLLAMA_CONTEXT_LENGTH` 或基于 VRAM 的默认值。若要在不重建 Modelfile 的情况下限制或强制 Ollama 每次请求的运行时上下文，请设置 `params.num_ctx`；无效、零、负数和非有限值会被忽略。OpenAI 兼容的 Ollama 适配器仍会默认根据已配置的 `params.num_ctx` 或 `contextWindow` 注入 `options.num_ctx`；如果你的上游拒绝 `options`，请使用 `injectNumCtxForOpenAICompat: false` 禁用它。
|
||||
|
||||
原生 Ollama 模型条目还接受 `params` 下的常见 Ollama 运行时选项，包括 `temperature`、`top_p`、`top_k`、`min_p`、`num_predict`、`stop`、`repeat_penalty`、`num_batch`、`num_thread` 和 `use_mmap`。OpenClaw 只会转发 Ollama 请求键，因此像 `streaming` 这样的 OpenClaw 运行时参数不会泄漏到 Ollama。使用 `params.think` 或 `params.thinking` 发送顶层 Ollama `think`；对于 Qwen 风格的 thinking 模型，`false` 会禁用 API 级别的 thinking。
|
||||
原生 Ollama 模型条目还接受 `params` 下常见的 Ollama 运行时选项，包括 `temperature`、`top_p`、`top_k`、`min_p`、`num_predict`、`stop`、`repeat_penalty`、`num_batch`、`num_thread` 和 `use_mmap`。OpenClaw 只会转发 Ollama 请求键，因此像 `streaming` 这样的 OpenClaw 运行时参数不会泄露给 Ollama。使用 `params.think` 或 `params.thinking` 可发送顶层 Ollama `think`；对于 Qwen 风格的 thinking 模型，`false` 会禁用 API 级 thinking。
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -796,12 +819,12 @@ OpenClaw 支持 **Ollama Web 搜索**，作为内置 `web_search` 提供商。
|
||||
}
|
||||
```
|
||||
|
||||
按模型配置的 `agents.defaults.models["ollama/<model>"].params.num_ctx` 也同样有效。如果两者都已配置，则显式的提供商模型条目优先于智能体默认值。
|
||||
按模型设置的 `agents.defaults.models["ollama/<model>"].params.num_ctx` 也同样有效。如果两者都已配置，则显式的 provider 模型条目优先生效。
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Thinking 控制">
|
||||
对于原生 Ollama 模型，OpenClaw 会按 Ollama 期望的方式转发 thinking 控制：使用顶层 `think`，而不是 `options.think`。
|
||||
对于原生 Ollama 模型，OpenClaw 会按 Ollama 预期转发 thinking 控制：使用顶层 `think`，而不是 `options.think`。
|
||||
|
||||
```bash
|
||||
openclaw agent --model ollama/gemma4 --thinking off
|
||||
@ -824,39 +847,39 @@ OpenClaw 支持 **Ollama Web 搜索**，作为内置 `web_search` 提供商。
|
||||
}
|
||||
```
|
||||
|
||||
按模型配置的 `params.think` 或 `params.thinking` 可以为特定已配置模型禁用或强制启用 Ollama API 的 thinking。像 `/think off` 这样的运行时命令仍然适用于当前运行。
|
||||
按模型设置的 `params.think` 或 `params.thinking` 可以为特定配置模型禁用或强制启用 Ollama API thinking。运行时命令（如 `/think off`）仍会应用于当前运行。
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="推理模型">
|
||||
OpenClaw 默认会将名称中带有 `deepseek-r1`、`reasoning` 或 `think` 的模型视为支持推理的模型。
|
||||
OpenClaw 默认将名称中包含 `deepseek-r1`、`reasoning` 或 `think` 的模型视为支持推理的模型。
|
||||
|
||||
```bash
|
||||
ollama pull deepseek-r1:32b
|
||||
```
|
||||
|
||||
无需额外配置。OpenClaw 会自动标记它们。
|
||||
不需要额外配置。OpenClaw 会自动标记它们。
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="模型成本">
|
||||
Ollama 是免费的，并且在本地运行，因此所有模型成本都设置为 $0。这同时适用于自动发现和手动定义的模型。
|
||||
Ollama 可免费使用并在本地运行，因此所有模型成本都设为 $0。这同时适用于自动发现和手动定义的模型。
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Memory 嵌入">
|
||||
内置的 Ollama 插件为
|
||||
[memory 搜索](/zh-CN/concepts/memory) 注册了一个 memory 嵌入提供商。它使用已配置的 Ollama base URL
|
||||
[memory search](/zh-CN/concepts/memory) 注册了一个 Memory 嵌入 provider。它使用已配置的 Ollama base URL
|
||||
和 API 密钥，调用 Ollama 当前的 `/api/embed` 端点，并在可能时
|
||||
将多个 memory 分块批量合并到一个 `input` 请求中。
|
||||
将多个 Memory 块批量合并到一个 `input` 请求中。
|
||||
|
||||
| 属性 | 值 |
|
||||
| ------------- | ------------------- |
|
||||
| 默认模型 | `nomic-embed-text` |
|
||||
| 自动拉取 | 是 — 如果嵌入模型在本地不存在，会自动拉取 |
|
||||
| 自动拉取 | 是 —— 如果本地不存在，该嵌入模型会被自动拉取 |
|
||||
|
||||
查询时嵌入会为需要或建议此做法的模型使用检索前缀，包括 `nomic-embed-text`、`qwen3-embedding` 和 `mxbai-embed-large`。Memory 文档批次保持原始格式，因此现有索引不需要执行格式迁移。
|
||||
查询时嵌入会对那些需要或建议此前缀的模型使用检索前缀，包括 `nomic-embed-text`、`qwen3-embedding` 和 `mxbai-embed-large`。Memory 文档批次保持原始形式，因此现有索引不需要做格式迁移。
|
||||
|
||||
要将 Ollama 选为 memory 搜索嵌入提供商：
|
||||
若要将 Ollama 选为 memory search 的嵌入 provider：
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -868,7 +891,7 @@ OpenClaw 支持 **Ollama Web 搜索**，作为内置 `web_search` 提供商。
|
||||
}
|
||||
```
|
||||
|
||||
对于远程嵌入主机，请将认证限制在该主机范围内：
|
||||
对于远程嵌入主机，请将凭证限定在该主机作用域内：
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -890,12 +913,12 @@ OpenClaw 支持 **Ollama Web 搜索**，作为内置 `web_search` 提供商。
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="流式传输配置">
|
||||
OpenClaw 的 Ollama 集成默认使用**原生 Ollama API**（`/api/chat`），它完全支持同时进行流式传输和工具调用。无需任何特殊配置。
|
||||
OpenClaw 的 Ollama 集成默认使用**原生 Ollama API**（`/api/chat`），它完全支持同时进行流式传输和工具调用。不需要额外配置。
|
||||
|
||||
对于原生 `/api/chat` 请求，OpenClaw 还会直接将 thinking 控制转发给 Ollama：`/think off` 和 `openclaw agent --thinking off` 会发送顶层 `think: false`，而 `/think low|medium|high` 会发送匹配的顶层 `think` effort 字符串。`/think max` 会映射到 Ollama 的最高原生 effort，即 `think: "high"`。
|
||||
对于原生 `/api/chat` 请求，OpenClaw 还会将 thinking 控制直接转发给 Ollama：`/think off` 和 `openclaw agent --thinking off` 会发送顶层 `think: false`，而 `/think low|medium|high` 会发送对应的顶层 `think` 强度字符串。`/think max` 会映射到 Ollama 原生支持的最高强度，即 `think: "high"`。
|
||||
|
||||
<Tip>
|
||||
如果你需要使用 OpenAI 兼容端点，请参见上方“旧版 OpenAI 兼容模式”一节。在那种模式下，流式传输和工具调用可能无法同时工作。
|
||||
如果你需要使用 OpenAI 兼容端点，请参阅上面的“旧版 OpenAI 兼容模式”部分。在该模式下，流式传输和工具调用可能无法同时工作。
|
||||
</Tip>
|
||||
|
||||
</Accordion>
|
||||
@ -905,15 +928,15 @@ OpenClaw 支持 **Ollama Web 搜索**，作为内置 `web_search` 提供商。
|
||||
|
||||
<AccordionGroup>
|
||||
<Accordion title="WSL2 崩溃循环（重复重启）">
|
||||
在使用 NVIDIA/CUDA 的 WSL2 上，官方 Ollama Linux 安装器会创建一个 `ollama.service` systemd 单元，并设置 `Restart=always`。如果该服务在 WSL2 启动时自动启动，并加载一个 GPU 支持的模型，Ollama 可能会在模型加载期间占用主机内存。Hyper-V 内存回收并不总能回收这些被固定的页面，因此 Windows 可能终止 WSL2 VM，随后 systemd 再次启动 Ollama，于是循环反复发生。
|
||||
在使用 NVIDIA/CUDA 的 WSL2 上，官方 Ollama Linux 安装器会创建一个 `ollama.service` systemd 单元，并设置 `Restart=always`。如果该服务在 WSL2 启动期间自动启动，并加载一个 GPU 支持的模型，Ollama 可能会在模型加载时锁定主机内存。Hyper-V 的内存回收机制并不总能回收这些被锁定的页面，因此 Windows 可能会终止 WSL2 VM，systemd 又会重新启动 Ollama，于是循环反复发生。
|
||||
|
||||
常见证据：
|
||||
|
||||
- Windows 侧重复出现 WSL2 重启或终止
|
||||
- WSL2 启动后不久，`app.slice` 或 `ollama.service` 的 CPU 使用率很高
|
||||
- systemd 发出 SIGTERM，而不是 Linux OOM-killer 事件
|
||||
- WSL2 从 Windows 侧反复重启或被终止
|
||||
- WSL2 启动后不久，`app.slice` 或 `ollama.service` 的 CPU 占用很高
|
||||
- 来自 systemd 的 SIGTERM，而不是 Linux OOM-killer 事件
|
||||
|
||||
当 OpenClaw 检测到 WSL2、已启用且带有 `Restart=always` 的 `ollama.service`，以及可见的 CUDA 标记时，会记录一条启动警告。
|
||||
当 OpenClaw 检测到 WSL2、启用了 `Restart=always` 的 `ollama.service`，以及可见的 CUDA 标记时，会记录一条启动警告。
|
||||
|
||||
缓解方法：
|
||||
|
||||
@ -921,7 +944,7 @@ OpenClaw 支持 **Ollama Web 搜索**，作为内置 `web_search` 提供商。
|
||||
sudo systemctl disable ollama
|
||||
```
|
||||
|
||||
在 Windows 侧，将以下内容添加到 `%USERPROFILE%\.wslconfig`，然后运行 `wsl --shutdown`：
|
||||
在 Windows 侧将以下内容添加到 `%USERPROFILE%\.wslconfig`，然后运行 `wsl --shutdown`：
|
||||
|
||||
```ini
|
||||
[experimental]
|
||||
@ -935,12 +958,12 @@ OpenClaw 支持 **Ollama Web 搜索**，作为内置 `web_search` 提供商。
|
||||
ollama serve
|
||||
```
|
||||
|
||||
请参见 [ollama/ollama#11317](https://github.com/ollama/ollama/issues/11317)。
|
||||
请参阅 [ollama/ollama#11317](https://github.com/ollama/ollama/issues/11317)。
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="未检测到 Ollama">
|
||||
请确保 Ollama 正在运行，并且你已设置 `OLLAMA_API_KEY`（或认证配置文件），同时你**没有**定义显式的 `models.providers.ollama` 条目：
|
||||
请确保 Ollama 正在运行，并且你已设置 `OLLAMA_API_KEY`（或 auth profile），同时**没有**定义显式的 `models.providers.ollama` 条目：
|
||||
|
||||
```bash
|
||||
ollama serve
|
||||
@ -955,7 +978,7 @@ OpenClaw 支持 **Ollama Web 搜索**，作为内置 `web_search` 提供商。
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="没有可用模型">
|
||||
如果你的模型未列出，请在本地拉取该模型，或在 `models.providers.ollama` 中显式定义它。
|
||||
如果列表中没有你的模型，请在本地拉取该模型，或者在 `models.providers.ollama` 中显式定义它。
|
||||
|
||||
```bash
|
||||
ollama list # 查看已安装内容
|
||||
@ -967,7 +990,7 @@ OpenClaw 支持 **Ollama Web 搜索**，作为内置 `web_search` 提供商。
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="连接被拒绝">
|
||||
检查 Ollama 是否运行在正确端口：
|
||||
检查 Ollama 是否运行在正确端口上：
|
||||
|
||||
```bash
|
||||
# 检查 Ollama 是否正在运行
|
||||
@ -980,7 +1003,7 @@ OpenClaw 支持 **Ollama Web 搜索**，作为内置 `web_search` 提供商。
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="远程主机用 curl 可用，但 OpenClaw 不可用">
|
||||
请从运行 Gateway 网关 的同一台机器和运行时环境中进行验证：
|
||||
请从运行 Gateway 网关 的同一台机器和运行时环境中验证：
|
||||
|
||||
```bash
|
||||
openclaw gateway status --deep
|
||||
@ -989,15 +1012,15 @@ OpenClaw 支持 **Ollama Web 搜索**，作为内置 `web_search` 提供商。
|
||||
|
||||
常见原因：
|
||||
|
||||
- `baseUrl` 指向 `localhost`，但 Gateway 网关 运行在 Docker 或其他主机中。
|
||||
- URL 使用了 `/v1`，这会选择 OpenAI 兼容行为，而不是原生 Ollama。
|
||||
- 远程主机在 Ollama 端需要调整防火墙或局域网绑定设置。
|
||||
- 模型存在于你笔记本的守护进程中，但不存在于远程守护进程中。
|
||||
- `baseUrl` 指向 `localhost`，但 Gateway 网关 运行在 Docker 中或另一台主机上。
|
||||
- 该 URL 使用了 `/v1`，这会选择 OpenAI 兼容行为，而不是原生 Ollama。
|
||||
- 远程主机在 Ollama 侧需要调整防火墙或局域网绑定设置。
|
||||
- 模型存在于你笔记本电脑上的守护进程中，但不存在于远程守护进程中。
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="模型将工具 JSON 作为文本输出">
|
||||
这通常意味着提供商正在使用 OpenAI 兼容模式，或该模型无法处理工具 schema。
|
||||
这通常意味着 provider 正在使用 OpenAI 兼容模式，或模型无法处理工具 schema。
|
||||
|
||||
优先使用原生 Ollama 模式：
|
||||
|
||||
@ -1019,7 +1042,7 @@ OpenClaw 支持 **Ollama Web 搜索**，作为内置 `web_search` 提供商。
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="冷启动的本地模型超时">
|
||||
大型本地模型在开始流式传输前，首次加载可能需要很长时间。请将超时限制在 Ollama 提供商范围内，并可选择要求 Ollama 在轮次之间保持模型已加载：
|
||||
大型本地模型在开始流式传输前，首次加载可能需要较长时间。请将超时限制在 Ollama provider 作用域内，并可选择要求 Ollama 在轮次之间保持模型已加载：
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -1040,12 +1063,12 @@ OpenClaw 支持 **Ollama Web 搜索**，作为内置 `web_search` 提供商。
|
||||
}
|
||||
```
|
||||
|
||||
如果主机本身接受连接的速度较慢，`timeoutSeconds` 也会为该提供商延长受保护的 Undici 连接超时。
|
||||
如果主机本身接受连接的速度很慢，`timeoutSeconds` 也会延长该 provider 的受保护 Undici 连接超时。
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="大上下文模型太慢或内存耗尽">
|
||||
许多 Ollama 模型宣称的上下文大小都超过了你的硬件能够轻松运行的范围。原生 Ollama 会使用 Ollama 自己的运行时上下文默认值，除非你设置 `params.num_ctx`。当你希望获得可预测的首 token 延迟时，请同时限制 OpenClaw 的预算和 Ollama 的请求上下文：
|
||||
<Accordion title="大上下文模型太慢或内存不足">
|
||||
许多 Ollama 模型宣称的上下文大小，实际上超过了你的硬件能够舒适运行的范围。原生 Ollama 使用 Ollama 自己的运行时上下文默认值，除非你设置 `params.num_ctx`。当你需要可预测的首 token 延迟时，请同时限制 OpenClaw 的预算和 Ollama 的请求上下文：
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -1067,28 +1090,28 @@ OpenClaw 支持 **Ollama Web 搜索**，作为内置 `web_search` 提供商。
|
||||
}
|
||||
```
|
||||
|
||||
如果是 OpenClaw 发送了过多提示，请先降低 `contextWindow`。如果是 Ollama 正在加载对机器来说过大的运行时上下文，请降低 `params.num_ctx`。如果生成耗时过长，请降低 `maxTokens`。
|
||||
如果 OpenClaw 发送的提示词过多，请先降低 `contextWindow`。如果 Ollama 加载的运行时上下文对当前机器来说过大，请降低 `params.num_ctx`。如果生成耗时过长，请降低 `maxTokens`。
|
||||
|
||||
</Accordion>
|
||||
</AccordionGroup>
|
||||
|
||||
<Note>
|
||||
更多帮助：[故障排除](/zh-CN/help/troubleshooting) 和 [常见问题](/zh-CN/help/faq)。
|
||||
更多帮助：请参阅 [故障排除](/zh-CN/help/troubleshooting) 和 [常见问题](/zh-CN/help/faq)。
|
||||
</Note>
|
||||
|
||||
## 相关
|
||||
## 相关内容
|
||||
|
||||
<CardGroup cols={2}>
|
||||
<Card title="模型提供商" href="/zh-CN/concepts/model-providers" icon="layers">
|
||||
所有提供商、模型引用和故障转移行为概览。
|
||||
所有提供商、模型引用和故障切换行为的概览。
|
||||
</Card>
|
||||
<Card title="模型选择" href="/zh-CN/concepts/models" icon="brain">
|
||||
如何选择和配置模型。
|
||||
</Card>
|
||||
<Card title="Ollama Web 搜索" href="/zh-CN/tools/ollama-search" icon="magnifying-glass">
|
||||
关于由 Ollama 驱动的网页搜索的完整设置和行为细节。
|
||||
由 Ollama 驱动的 web search 的完整设置和行为细节。
|
||||
</Card>
|
||||
<Card title="配置" href="/zh-CN/gateway/configuration" icon="gear">
|
||||
完整配置参考。
|
||||
完整的配置参考。
|
||||
</Card>
|
||||
</CardGroup>
|
||||
|
||||
Loading…
Reference in New Issue
Block a user