From fbb5e1815ed484d99cbcc838f50b73c5449a1680 Mon Sep 17 00:00:00 2001 From: "openclaw-docs-i18n[bot]" Date: Mon, 27 Apr 2026 22:08:19 +0000 Subject: [PATCH] chore(i18n): refresh zh-CN translations --- docs/zh-CN/cli/infer.md | 110 ++++++----- docs/zh-CN/gateway/local-models.md | 105 ++++++---- docs/zh-CN/providers/ollama.md | 295 ++++++++++++++++------------- 3 files changed, 284 insertions(+), 226 deletions(-) diff --git a/docs/zh-CN/cli/infer.md b/docs/zh-CN/cli/infer.md index e223c08f2..cbfa36ca5 100644 --- a/docs/zh-CN/cli/infer.md +++ b/docs/zh-CN/cli/infer.md @@ -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` 必须是支持图像的 `` | | 转录音频 | `openclaw infer audio transcribe --file ./memo.m4a --json` | `--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` 必须是 `` | -| 搜索 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` 必须使用 `` 形式。 -- 对于 `image describe`，显式传入 `--model` 会直接运行该提供商/模型。该模型必须在模型目录或提供商配置中具备图像能力。`codex/` 会运行一次受限的 Codex app-server 图像理解轮次；`openai-codex/` 则使用 OpenAI Codex OAuth 提供商路径。 +- 对于 `image describe`，显式传入 `--model` 会直接运行该提供商/模型。该模型必须在模型目录或提供商配置中具备图像能力。`codex/` 会运行一次受限的 Codex app-server 图像理解回合；`openai-codex/` 使用 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 ``` +使用完整的 `` 引用来对特定提供商进行冒烟测试，而无需启动 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 --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 --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` 必须是支持图像的 ``。 -- 对于本地 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` 必须是 ``。 -## 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。 ## 常见陷阱 diff --git a/docs/zh-CN/gateway/local-models.md b/docs/zh-CN/gateway/local-models.md index 5b19cc186..97cd90e3d 100644 --- a/docs/zh-CN/gateway/local-models.md +++ b/docs/zh-CN/gateway/local-models.md @@ -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 本地服务器的偏好型指南。 -**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)。 ## 推荐：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..models[].id` 的值是 provider 本地值。不要在其中包含 provider 前缀。例如，用 `mlx_lm.server --model mlx-community/Qwen3-30B-A3B-6bit` 启动的 MLX 服务器应使用以下目录 ID 和模型引用： +`models.providers..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..timeoutSeconds`，再考虑提高 `agents.defaults.timeoutSeconds`。provider 超时仅适用于模型 HTTP 请求，包括连接、响应头、流式响应体以及整个 guarded-fetch 的中止。 +保留 `models.mode: "merge"`，这样托管模型仍可作为回退使用。 +对于较慢的本地或远程模型服务器，应优先使用 `models.providers..timeoutSeconds`，再考虑提高 `agents.defaults.timeoutSeconds`。provider 超时仅适用于模型 HTTP 请求，包括连接、响应头、流式响应体，以及整个 guarded-fetch 的中止控制。 -对于自定义兼容 OpenAI 的提供商，当 `baseUrl` 解析到 loopback、私有 LAN、`.local` 或裸主机名时，可以持久化一个非敏感的本地标记，例如 `apiKey: "ollama-local"`。OpenClaw 会将其视为有效的本地凭证，而不会报告缺少 key。对于接受公网主机名的提供商，请使用真实值。 +对于自定义兼容 OpenAI 的提供商，当 `baseUrl` 解析到 loopback、私有 LAN、`.local` 或裸主机名时，持久化一个非机密的本地标记（例如 `apiKey: "ollama-local"`）是允许的。OpenClaw 会将其视为有效的本地凭证，而不是报告缺失 key。对于接受公共主机名的任何提供商，请使用真实值。 关于本地 / 代理 `/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..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..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..models[].compat.supportsTools: false`。 -- 如果后端仍然只在较大的 OpenClaw 运行中失败，剩余问题通常是上游模型 / 服务器容量不足，或后端 bug，而不是 OpenClaw 的传输层问题。 +- 某些较小或更严格的本地后端在面对 OpenClaw 完整的智能体运行时提示结构时会不稳定，尤其是在包含工具 schema 时。请先使用精简的本地探针验证 provider 路径： + + ```bash + openclaw infer model run --local --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..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，以限制提示注入的影响范围。 ## 相关内容 diff --git a/docs/zh-CN/providers/ollama.md b/docs/zh-CN/providers/ollama.md index c53c681ba..b57f16a95 100644 --- a/docs/zh-CN/providers/ollama.md +++ b/docs/zh-CN/providers/ollama.md @@ -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`。 **远程 Ollama 用户**：不要在 OpenClaw 中使用 `/v1` OpenAI 兼容 URL（`http://host:11434/v1`）。这会破坏工具调用，模型还可能将原始工具 JSON 作为纯文本输出。请改用原生 Ollama API URL：`baseUrl: "http://host:11434"`（不要带 `/v1`）。 -Ollama 提供商配置使用 `baseUrl` 作为规范键名。出于与 OpenAI SDK 风格示例兼容的考虑，OpenClaw 也接受 `baseURL`，但新配置应优先使用 `baseUrl`。 +Ollama provider 配置使用 `baseUrl` 作为规范键名。OpenClaw 也接受 `baseURL` 以兼容 OpenAI SDK 风格的示例，但新配置应优先使用 `baseUrl`。 -## 认证规则 +## 凭证规则 - 本地和局域网中的 Ollama 主机不需要真实的 bearer token。对于 loopback、私有网络、`.local` 和裸主机名的 Ollama base URL，OpenClaw 仅使用本地 `ollama-local` 标记。 + 本地和局域网 Ollama 主机不需要真实的 bearer token。OpenClaw 仅将本地 `ollama-local` 标记用于 loopback、私有网络、`.local` 和裸主机名 Ollama base URL。 - 远程公网主机和 Ollama Cloud（`https://ollama.com`）需要通过 `OLLAMA_API_KEY`、认证配置文件或提供商的 `apiKey` 提供真实凭证。 + 远程公网主机和 Ollama Cloud（`https://ollama.com`）需要通过 `OLLAMA_API_KEY`、auth profile 或 provider 的 `apiKey` 提供真实凭证。 - - 将 `api: "ollama"` 作为配置的自定义提供商 id 遵循相同规则。例如，指向私有局域网 Ollama 主机的 `ollama-remote` 提供商可以使用 `apiKey: "ollama-local"`，子智能体会通过 Ollama 提供商钩子解析该标记，而不会将其视为缺失凭证。 + + 将 `api: "ollama"` 设为自定义 provider id 时，也遵循相同规则。例如，指向私有局域网 Ollama 主机的 `ollama-remote` provider 可以使用 `apiKey: "ollama-local"`，子智能体会通过 Ollama provider hook 解析该标记，而不是将其视为缺失的凭证。 - 当 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 约定，默认不会发送到本地或自托管主机。 ## 入门指南 -请选择你偏好的设置方式和模式。 +选择你偏好的设置方法和模式。 - **最适合：** 以最快方式完成可用的 Ollama 云端或本地设置。 + **最适合：** 以最快路径完成可用的 Ollama 云端或本地设置。 @@ -58,15 +58,15 @@ Ollama 提供商配置使用 `baseUrl` 作为规范键名。出于与 OpenAI SDK openclaw onboard ``` - 在提供商列表中选择 **Ollama**。 + 从 provider 列表中选择 **Ollama**。 - **Cloud + Local** — 本地 Ollama 主机，加上通过该主机路由的云模型 - - **Cloud only** — 通过 `https://ollama.com` 使用托管的 Ollama 模型 + - **Cloud only** — 通过 `https://ollama.com` 使用托管 Ollama 模型 - **Local only** — 仅使用本地模型 - - `Cloud only` 会提示输入 `OLLAMA_API_KEY`，并推荐托管云端默认模型。`Cloud + Local` 和 `Local only` 会要求提供 Ollama base URL，发现可用模型，并在所选本地模型尚不可用时自动拉取该模型。当 Ollama 报告已安装的 `:latest` 标签，例如 `gemma4:latest` 时，设置界面会仅显示该已安装模型一次，而不会同时显示 `gemma4` 和 `gemma4:latest`，也不会再次拉取裸别名。`Cloud + Local` 还会检查该 Ollama 主机是否已登录以访问云服务。 + + `Cloud only` 会提示输入 `OLLAMA_API_KEY`，并推荐托管云默认模型。`Cloud + Local` 和 `Local only` 会要求提供一个 Ollama base URL，发现可用模型，并在所选本地模型尚不可用时自动拉取。当 Ollama 报告已安装的 `:latest` 标签（例如 `gemma4:latest`）时，设置界面只显示这一个已安装模型，而不会同时显示 `gemma4` 和 `gemma4:latest`，也不会再次拉取不带标签的别名。`Cloud + Local` 还会检查该 Ollama 主机是否已登录并启用云访问。 ```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" ``` - + ```bash openclaw models list openclaw models set ollama/gemma4 @@ -154,76 +154,99 @@ Ollama 提供商配置使用 `baseUrl` 作为规范键名。出于与 OpenAI SDK - `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`。 - `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 会回退到之前硬编码的推荐项，以便新手引导仍可完成。 - 在仅本地模式下，OpenClaw 会从已配置的 Ollama 实例发现模型。此路径适用于本地或自托管 Ollama 服务器。 + 在仅本地模式下，OpenClaw 会从已配置的 Ollama 实例中发现模型。此路径适用于本地或自托管 Ollama 服务器。 OpenClaw 当前推荐 `gemma4` 作为本地默认模型。 -## 模型发现（隐式提供商） +## 模型发现（隐式 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/: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 ``` -新模型会被自动发现，并可直接使用。 +新模型会被自动发现并可立即使用。 -如果你显式设置了 `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 仍会被视为本地。请参阅下面的显式配置部分。 -## 视觉与图像描述 +## 视觉和图像描述 -内置的 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` 必须是完整的 `` 引用。设置后，`openclaw infer image describe` 会直接运行该模型，而不会因为模型支持原生视觉就跳过描述。 +`--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 \ ``` - 如果设置了 `OLLAMA_API_KEY`，你可以在提供商条目中省略 `apiKey`，OpenClaw 会在可用性检查时自动补全它。 + 如果已设置 `OLLAMA_API_KEY`，你可以在 provider 条目中省略 `apiKey`，OpenClaw 会自动填充它以进行可用性检查。 - - 当你想使用托管云端设置、Ollama 运行在其他主机/端口、想强制指定特定上下文窗口或模型列表，或想完全手动定义模型时，请使用显式配置。 + + 如果你想使用托管云设置、Ollama 运行在其他主机/端口、想强制指定特定上下文窗口或模型列表，或想完全手动定义模型，请使用显式配置。 ```json5 { @@ -347,7 +370,7 @@ OPENCLAW_LIVE_TEST=1 OPENCLAW_LIVE_OLLAMA_IMAGE=1 \ - 如果 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 \ ``` - 不要在 URL 中添加 `/v1`。`/v1` 路径使用 OpenAI 兼容模式，此模式下工具调用并不可靠。请使用不带路径后缀的基础 Ollama URL。 + 不要在 URL 中添加 `/v1`。`/v1` 路径使用 OpenAI 兼容模式，在该模式下工具调用并不可靠。请使用不带路径后缀的 Ollama 基础 URL。 -## 常见配方 +## 常见方案 -请将这些作为起点，并将模型 id 替换为 `ollama list` 或 `openclaw models list --provider ollama` 中显示的精确名称。 +你可以将这些作为起点，然后用 `ollama list` 或 `openclaw models list --provider ollama` 中显示的准确模型名称替换模型 ID。 - - 当 Ollama 与 Gateway 网关 运行在同一台机器上，并且你希望 OpenClaw 自动发现已安装模型时，请使用此方式。 + + 当 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` 配置块。 - 对于局域网主机，请使用原生 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。当你的硬件无法运行模型宣称的完整上下文时，请保持两者一致。 - 当你不运行本地守护进程，而想直接使用托管的 Ollama 模型时，请使用此方式。 + 当你不运行本地守护进程，并且想直接使用托管 Ollama 模型时，请使用此方案。 ```bash export OLLAMA_API_KEY="your-ollama-api-key" @@ -481,7 +504,7 @@ OPENCLAW_LIVE_TEST=1 OPENCLAW_LIVE_OLLAMA_IMAGE=1 \ - 当本地或局域网 Ollama 守护进程已通过 `ollama signin` 登录，并且应同时提供本地模型和 `:cloud` 模型时，请使用此方式。 + 当本地或局域网 Ollama 守护进程已通过 `ollama signin` 登录，并且应该同时提供本地模型和 `:cloud` 模型时，请使用此方案。 ```bash ollama signin @@ -518,7 +541,7 @@ OPENCLAW_LIVE_TEST=1 OPENCLAW_LIVE_OLLAMA_IMAGE=1 \ - 当你有多个 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`。 - 一些本地模型可以回答简单提示，但难以处理完整的智能体工具接口。在修改全局运行时设置之前，请先从限制工具和上下文开始。 + 某些本地模型可以回答简单提示，但难以应对完整的智能体工具面。开始时，先限制工具和上下文，再考虑更改全局运行时设置。 ```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` 搭配使用。 @@ -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` 端点。 -完整的设置和行为细节请参见 [Ollama Web 搜索](/zh-CN/tools/ollama-search)。 +有关完整的设置和行为细节，请参阅 [Ollama Web 搜索](/zh-CN/tools/ollama-search)。 ## 高级配置 @@ -721,10 +744,10 @@ OpenClaw 支持 **Ollama Web 搜索**，作为内置 `web_search` 提供商。 - **在 OpenAI 兼容模式下，工具调用并不可靠。** 仅当你需要为某个代理使用 OpenAI 格式，并且不依赖原生工具调用行为时，才应使用此模式。 + **在 OpenAI 兼容模式下，工具调用并不可靠。** 仅当你需要为代理使用 OpenAI 格式，并且不依赖原生工具调用行为时，才使用此模式。 - 如果你确实需要改用 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` 提供商。 - 对于自动发现的模型，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/"].params.num_ctx` 也同样有效。如果两者都已配置，则显式的提供商模型条目优先于智能体默认值。 + 按模型设置的 `agents.defaults.models["ollama/"].params.num_ctx` 也同样有效。如果两者都已配置，则显式的 provider 模型条目优先生效。 - 对于原生 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`）仍会应用于当前运行。 - OpenClaw 默认会将名称中带有 `deepseek-r1`、`reasoning` 或 `think` 的模型视为支持推理的模型。 + OpenClaw 默认将名称中包含 `deepseek-r1`、`reasoning` 或 `think` 的模型视为支持推理的模型。 ```bash ollama pull deepseek-r1:32b ``` - 无需额外配置。OpenClaw 会自动标记它们。 + 不需要额外配置。OpenClaw 会自动标记它们。 - Ollama 是免费的，并且在本地运行，因此所有模型成本都设置为 $0。这同时适用于自动发现和手动定义的模型。 + Ollama 可免费使用并在本地运行，因此所有模型成本都设为 $0。这同时适用于自动发现和手动定义的模型。 内置的 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` 提供商。 - 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"`。 - 如果你需要使用 OpenAI 兼容端点，请参见上方“旧版 OpenAI 兼容模式”一节。在那种模式下，流式传输和工具调用可能无法同时工作。 + 如果你需要使用 OpenAI 兼容端点，请参阅上面的“旧版 OpenAI 兼容模式”部分。在该模式下，流式传输和工具调用可能无法同时工作。 @@ -905,15 +928,15 @@ OpenClaw 支持 **Ollama Web 搜索**，作为内置 `web_search` 提供商。 - 在使用 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)。 - 请确保 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` 提供商。 - 如果你的模型未列出，请在本地拉取该模型，或在 `models.providers.ollama` 中显式定义它。 + 如果列表中没有你的模型，请在本地拉取该模型，或者在 `models.providers.ollama` 中显式定义它。 ```bash ollama list # 查看已安装内容 @@ -967,7 +990,7 @@ OpenClaw 支持 **Ollama Web 搜索**，作为内置 `web_search` 提供商。 - 检查 Ollama 是否运行在正确端口： + 检查 Ollama 是否运行在正确端口上： ```bash # 检查 Ollama 是否正在运行 @@ -980,7 +1003,7 @@ OpenClaw 支持 **Ollama Web 搜索**，作为内置 `web_search` 提供商。 - 请从运行 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 侧需要调整防火墙或局域网绑定设置。 + - 模型存在于你笔记本电脑上的守护进程中，但不存在于远程守护进程中。 - 这通常意味着提供商正在使用 OpenAI 兼容模式，或该模型无法处理工具 schema。 + 这通常意味着 provider 正在使用 OpenAI 兼容模式，或模型无法处理工具 schema。 优先使用原生 Ollama 模式： @@ -1019,7 +1042,7 @@ OpenClaw 支持 **Ollama Web 搜索**，作为内置 `web_search` 提供商。 - 大型本地模型在开始流式传输前，首次加载可能需要很长时间。请将超时限制在 Ollama 提供商范围内，并可选择要求 Ollama 在轮次之间保持模型已加载： + 大型本地模型在开始流式传输前，首次加载可能需要较长时间。请将超时限制在 Ollama provider 作用域内，并可选择要求 Ollama 在轮次之间保持模型已加载： ```json5 { @@ -1040,12 +1063,12 @@ OpenClaw 支持 **Ollama Web 搜索**，作为内置 `web_search` 提供商。 } ``` - 如果主机本身接受连接的速度较慢，`timeoutSeconds` 也会为该提供商延长受保护的 Undici 连接超时。 + 如果主机本身接受连接的速度很慢，`timeoutSeconds` 也会延长该 provider 的受保护 Undici 连接超时。 - - 许多 Ollama 模型宣称的上下文大小都超过了你的硬件能够轻松运行的范围。原生 Ollama 会使用 Ollama 自己的运行时上下文默认值，除非你设置 `params.num_ctx`。当你希望获得可预测的首 token 延迟时，请同时限制 OpenClaw 的预算和 Ollama 的请求上下文： + + 许多 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`。 -更多帮助：[故障排除](/zh-CN/help/troubleshooting) 和 [常见问题](/zh-CN/help/faq)。 +更多帮助：请参阅 [故障排除](/zh-CN/help/troubleshooting) 和 [常见问题](/zh-CN/help/faq)。 -## 相关 +## 相关内容 - 所有提供商、模型引用和故障转移行为概览。 + 所有提供商、模型引用和故障切换行为的概览。 如何选择和配置模型。 - 关于由 Ollama 驱动的网页搜索的完整设置和行为细节。 + 由 Ollama 驱动的 web search 的完整设置和行为细节。 - 完整配置参考。 + 完整的配置参考。