chore(i18n): refresh zh-CN translations

This commit is contained in:
openclaw-docs-i18n[bot] 2026-04-22 04:51:45 +00:00
parent d1dcd97ce4
commit 42a327bf6c

View File

@ -6,20 +6,20 @@ read_when:
summary: 使用 Ollama 运行 OpenClaw云端和本地模型
title: Ollama
x-i18n:
generated_at: "2026-04-21T21:37:02Z"
generated_at: "2026-04-22T04:50:54Z"
model: gpt-5.4
provider: openai
source_hash: 32623b6523f22930a5987fb22d2074f1e9bb274cc01ae1ad1837825cc04ec179
source_hash: 704beed3bf988d6c2ad50b2a1533f6dcef655e44b34f23104827d2acb71b8655
source_path: providers/ollama.md
workflow: 15
---
# Ollama
OpenClaw 集成了 Ollama 的原生 API`/api/chat`),可用于托管云模型和本地/自托管的 Ollama 服务器。你可以通过三种模式使用 Ollama通过可访问的 Ollama 主机使用 `云端 + 本地`,针对 `https://ollama.com` 使用 `仅云端`,或针对可访问的 Ollama 主机使用 `仅本地`。
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`)。
**远程 Ollama 用户**:不要在 OpenClaw 中使用 `/v1` 的 OpenAI 兼容 URL`http://host:11434/v1`)。这会破坏工具调用,模型还可能原始工具 JSON 作为纯文本输出。请改用原生 Ollama API URL`baseUrl: "http://host:11434"`(不要加 `/v1`)。
</Warning>
## 入门指南
@ -39,12 +39,12 @@ OpenClaw 集成了 Ollama 的原生 API`/api/chat`),可用于托管云模
从提供商列表中选择 **Ollama**
</Step>
<Step title="选择你的模式">
- **云端 + 本地** — 本地 Ollama 主机,加上通过该主机路由的云模型
- **仅云端** — 通过 `https://ollama.com` 使用托管的 Ollama 模型
- **仅本地** — 仅使用本地模型
- **Cloud + Local** — 本地 Ollama 主机,加上通过该主机路由的云模型
- **Cloud only** — 通过 `https://ollama.com` 使用托管的 Ollama 模型
- **Local only** — 仅使用本地模型
</Step>
<Step title="选择模型">
`仅云端` 会提示输入 `OLLAMA_API_KEY`,并推荐托管云端默认模型。`云端 + 本地` 和 `仅本地` 会要求提供 Ollama 基础 URL发现可用模型并在所选本地模型尚不可用时自动拉取。`云端 + 本地` 还会检查该 Ollama 主机是否已登录以启用云访问。
`Cloud only` 会提示输入 `OLLAMA_API_KEY`,并建议托管云端默认模型。`Cloud + Local` 和 `Local only` 会要求提供 Ollama 基础 URL发现可用模型并在所选本地模型尚不可用时自动拉取。`Cloud + Local` 还会检查该 Ollama 主机是否已登录以启用云访问。
</Step>
<Step title="验证模型可用">
```bash
@ -61,7 +61,7 @@ OpenClaw 集成了 Ollama 的原生 API`/api/chat`),可用于托管云模
--accept-risk
```
你也可以选择指定自定义基础 URL 或模型:
你也可以选择指定自定义基础 URL 或模型:
```bash
openclaw onboard --non-interactive \
@ -74,13 +74,13 @@ OpenClaw 集成了 Ollama 的原生 API`/api/chat`),可用于托管云模
</Tab>
<Tab title="手动设置">
**最适合:** 完全控云端或本地设置。
**最适合:** 完全控云端或本地设置。
<Steps>
<Step title="选择云端或本地">
- **云端 + 本地**:安装 Ollama使用 `ollama signin` 登录,并通过该主机路由云请求
- **仅云端**:使用带有 `OLLAMA_API_KEY``https://ollama.com`
- **仅本地**:从 [ollama.com/download](https://ollama.com/download) 安装 Ollama
- **Cloud + Local**:安装 Ollama使用 `ollama signin` 登录,并通过该主机路由云请求
- **Cloud only**:使用带有 `OLLAMA_API_KEY``https://ollama.com`
- **Local only**:从 [ollama.com/download](https://ollama.com/download) 安装 Ollama
</Step>
<Step title="拉取本地模型(仅本地)">
```bash
@ -92,7 +92,7 @@ OpenClaw 集成了 Ollama 的原生 API`/api/chat`),可用于托管云模
```
</Step>
<Step title="为 OpenClaw 启用 Ollama">
对于 `仅云端`,请使用你真实的 `OLLAMA_API_KEY`。对于基于主机的设置,任意占位值都可以:
对于 `Cloud only`,请使用你真实的 `OLLAMA_API_KEY`。对于基于主机的设置,任意占位值都可以:
```bash
# 云端
@ -105,7 +105,7 @@ OpenClaw 集成了 Ollama 的原生 API`/api/chat`),可用于托管云模
openclaw config set models.providers.ollama.apiKey "OLLAMA_API_KEY"
```
</Step>
<Step title="查并设置你的模型">
<Step title="并设置你的模型">
```bash
openclaw models list
openclaw models set ollama/gemma4
@ -128,47 +128,47 @@ OpenClaw 集成了 Ollama 的原生 API`/api/chat`),可用于托管云模
</Tab>
</Tabs>
## 云模型
## 云模型
<Tabs>
<Tab title="云端 + 本地">
`云端 + 本地` 会把可访问的 Ollama 主机作为本地模型和云模型的统一控制点。这是 Ollama 偏好的混合使用流程。
<Tab title="Cloud + Local">
`Cloud + Local` 使用一个可访问的 Ollama 主机作为本地和云端模型的控制点。这是 Ollama 推荐的混合流程。
在设置期间使用 **云端 + 本地**。OpenClaw 会提示输入 Ollama 基础 URL从该主机发现本地模型并检查该主机是否已通过 `ollama signin` 登录以启用云访问。当主机已登录时OpenClaw 还会推荐托管云端默认模型,例如 `kimi-k2.5:cloud`、`minimax-m2.7:cloud` 和 `glm-5.1:cloud`
在设置期间使用 **Cloud + Local**。OpenClaw 会提示输入 Ollama 基础 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="仅云端">
`仅云端` 通过 Ollama 的托管 API `https://ollama.com` 运行。
<Tab title="Cloud only">
`Cloud only` 通过 Ollama 的托管 API `https://ollama.com` 运行。
在设置期间使用 **仅云端**。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="仅本地">
在仅本地模式下OpenClaw 会从已配置的 Ollama 实例发现模型。此路径适用于本地或自托管的 Ollama 服务器。
<Tab title="Local only">
在仅本地模式下OpenClaw 会从已配置的 Ollama 实例发现模型。此路径适用于本地或自托管的 Ollama 服务器。
OpenClaw 当前推荐 `gemma4` 作为本地默认模型。
OpenClaw 当前建议 `gemma4` 作为本地默认模型。
</Tab>
</Tabs>
## 模型发现(隐式提供商)
当你设置了 `OLLAMA_API_KEY`(或证配置文件),并且**没有**定义 `models.providers.ollama`OpenClaw 会从位于 `http://127.0.0.1:11434` 的本地 Ollama 实例发现模型。
当你设置了 `OLLAMA_API_KEY`(或证配置文件),并且**没有**定义 `models.providers.ollama`OpenClaw 会从位于 `http://127.0.0.1:11434` 的本地 Ollama 实例发现模型。
| 行为 | 说明 |
| 行为 | 详情 |
| -------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| 目录查询 | 查询 `/api/tags` |
| 能力检测 | 使用尽力而为的 `/api/show` 查询读取 `contextWindow` 并检测能力(包括视觉) |
| 视觉模型 | 对于 `/api/show` 报告了 `vision` 能力的模型,会标记为支持图像(`input: ["text", "image"]`),因此 OpenClaw 会自动将图像注入提示词 |
| 能力检测 | 使用尽力而为的 `/api/show` 查询读取 `contextWindow` 并检测能力(包括视觉) |
| 视觉模型 | 如果 `/api/show` 报告模型具有 `vision` 能力,则该模型会被标记为支持图像(`input: ["text", "image"]`),因此 OpenClaw 会自动将图像注入提示词 |
| 推理检测 | 使用模型名称启发式(`r1`、`reasoning`、`think`)标记 `reasoning` |
| Token 限制 | 将 `maxTokens` 设置为 OpenClaw 使用的默认 Ollama 最大 token 上限 |
| 成本 | 所有成本设为 `0` |
| token 限制 | 将 `maxTokens` 设置为 OpenClaw 使用的默认 Ollama 最大 token 上限 |
| 成本 | 所有成本设`0` |
这样可以避免手动录入模型,同时让模型目录与本地 Ollama 实例保持一致。
@ -178,21 +178,21 @@ ollama list
openclaw models list
```
要添加新模型,只需使用 Ollama 拉取即可
要添加新模型,只需使用 Ollama 拉取
```bash
ollama pull mistral
```
新模型会被自动发现并可立即使用。
新模型会被自动发现并可直接使用。
<Note>
如果你显式设置了 `models.providers.ollama`,自动发现将被跳过,你必须手动定义模型。参见下方的显式配置部分。
如果你显式设置了 `models.providers.ollama`将跳过自动发现,此时你必须手动定义模型。参见下方的显式配置部分。
</Note>
## 视觉与图像描述
内置的 Ollama 插件会将 Ollama 注册为支持图像的媒体理解提供商。这使 OpenClaw 能够将显式的图像描述请求以及已配置的图像模型默认值,路由到本地或托管的 Ollama 视觉模型
内置的 Ollama 插件会将 Ollama 注册为支持图像的媒体理解提供商。这使 OpenClaw 能够通过本地或托管的 Ollama 视觉模型,路由显式图像描述请求以及已配置的图像模型默认值。
对于本地视觉模型,请拉取一个支持图像的模型:
@ -210,9 +210,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
{
@ -226,7 +226,7 @@ openclaw infer image describe \
}
```
如果你手动定义 `models.providers.ollama.models`,请为视觉模型标记图像输入支持:
如果你手动定义 `models.providers.ollama.models`,请为视觉模型标记图像输入支持:
```json5
{
@ -238,7 +238,7 @@ openclaw infer image describe \
}
```
OpenClaw 会拒绝未标记为支持图像的模型所发起的图像描述请求。在隐式发现模式下,当 `/api/show` 报告视觉能力时OpenClaw 会从 Ollama 中读取此信息。
对于未标记为支持图像的模型OpenClaw 会拒绝图像描述请求。在隐式发现模式下,如果 `/api/show` 报告了视觉能力OpenClaw 会从 Ollama 读取此信息。
## 配置
@ -251,13 +251,13 @@ OpenClaw 会拒绝未标记为支持图像的模型所发起的图像描述请
```
<Tip>
如果设置 `OLLAMA_API_KEY`,你可以在提供商条目中省略 `apiKey`OpenClaw 会在可用性检查时自动填入
如果设置 `OLLAMA_API_KEY`,你可以在提供商条目中省略 `apiKey`OpenClaw 会自动填入它以进行可用性检查
</Tip>
</Tab>
<Tab title="显式(手动模型)">
当你需要托管云设置、Ollama 运行在其他主机/端口、想强制指定特定上下文窗口或模型列表,或者需要完全手动定义模型时,请使用显式配置。
当你希望使用托管云端设置、Ollama 运行在其他主机 / 端口上、你想强制指定特定的上下文窗口或模型列表,或者你想完全手动定义模型时,请使用显式配置。
```json5
{
@ -287,7 +287,7 @@ OpenClaw 会拒绝未标记为支持图像的模型所发起的图像描述请
</Tab>
<Tab title="自定义基础 URL">
如果 Ollama 运行在不同的主机或端口上(显式配置会禁用自动发现,因此你需要手动定义模型):
如果 Ollama 运行在其他主机或端口上(显式配置会禁用自动发现,因此你需要手动定义模型):
```json5
{
@ -296,7 +296,7 @@ OpenClaw 会拒绝未标记为支持图像的模型所发起的图像描述请
ollama: {
apiKey: "ollama-local",
baseUrl: "http://ollama-host:11434", // 不要加 /v1 - 使用原生 Ollama API URL
api: "ollama", // 显式设置以确保原生工具调用行为
api: "ollama", // 显式设置以确保原生工具调用行为
},
},
},
@ -312,7 +312,7 @@ OpenClaw 会拒绝未标记为支持图像的模型所发起的图像描述请
### 模型选择
配置完成后,你的所有 Ollama 模型都可用:
配置完成后,你的所有 Ollama 模型都可用:
```json5
{
@ -329,15 +329,15 @@ OpenClaw 会拒绝未标记为支持图像的模型所发起的图像描述请
## Ollama Web 搜索
OpenClaw 支持**Ollama Web 搜索** 作为内置的 `web_search` 提供商。
OpenClaw 支持 **Ollama Web 搜索**作为内置的 `web_search` 提供商。
| 属性 | 说明 |
| 属性 | 详情 |
| ----------- | ----------------------------------------------------------------------------------------------------------------- |
| 主机 | 使用你配置的 Ollama 主机(设置了 `models.providers.ollama.baseUrl` 时使用该值,否则使用 `http://127.0.0.1:11434` |
| 主机 | 使用你配置的 Ollama 主机(设置了 `models.providers.ollama.baseUrl` 时使用该值,否则使用 `http://127.0.0.1:11434` |
| 认证 | 无需密钥 |
| 要求 | Ollama 必须正在运行,并已通过 `ollama signin` 登录 |
`openclaw onboard``openclaw configure --section web` 期间选择 **Ollama Web 搜索**,或设置:
`openclaw onboard``openclaw configure --section web` 期间选择 **Ollama Web 搜索**,或设置:
```json5
{
@ -360,10 +360,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
{
@ -381,9 +381,9 @@ OpenClaw 支持将 **Ollama Web 搜索** 作为内置的 `web_search` 提供商
}
```
此模式可能无法同时支持流式传输和工具调用。你可能需要在模型配置中使用 `params: { streaming: false }` 禁用流式传输。
此模式可能不支持同时进行流式传输和工具调用。你可能需要在模型配置中使用 `params: { streaming: false }` 禁用流式传输。
当 Ollama 使用 `api: "openai-completions"`OpenClaw 默认会注入 `options.num_ctx`,以避免 Ollama 悄悄回退到 4096 的上下文窗口。如果你的代理/上游拒绝未知的 `options` 字段,请禁用此行为:
当 Ollama 使用 `api: "openai-completions"`OpenClaw 默认会注入 `options.num_ctx`,以避免 Ollama 静默回退到 4096 的上下文窗口。如果你的代理 / 上游拒绝未知的 `options` 字段,请禁用此行为:
```json5
{
@ -404,7 +404,7 @@ OpenClaw 支持将 **Ollama Web 搜索** 作为内置的 `web_search` 提供商
</Accordion>
<Accordion title="上下文窗口">
对于自动发现的模型OpenClaw 会在可用时使用 Ollama 报告的上下文窗口;否则会回退到 OpenClaw 使用的默认 Ollama 上下文窗口。
对于自动发现的模型OpenClaw 会优先使用 Ollama 报告的上下文窗口;如果不可用,则回退到 OpenClaw 为 Ollama 使用的默认上下文窗口。
你可以在显式提供商配置中覆盖 `contextWindow``maxTokens`
@ -429,29 +429,27 @@ OpenClaw 支持将 **Ollama Web 搜索** 作为内置的 `web_search` 提供商
</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="内存嵌入">
内置的 Ollama 插件为
[memory search](/zh-CN/concepts/memory) 注册了一个内存嵌入提供商。它使用已配置的 Ollama 基础 URL
和 API 密钥。
内置的 Ollama 插件为 [memory search](/zh-CN/concepts/memory) 注册了一个内存嵌入提供商。它使用已配置的 Ollama 基础 URL 和 API 密钥。
| 属性 | 值 |
| ------------- | ------------------- |
| 默认模型 | `nomic-embed-text` |
| 自动拉取 | 是——如果本地不存在,该嵌入模型会自动拉取 |
| 自动拉取 | 是——如果本地不存在,该嵌入模型会自动拉取 |
要将 Ollama 选为 memory search 的嵌入提供商:
@ -468,7 +466,9 @@ 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`,而非 `off` 的 thinking 级别会发送 `think: true`
<Tip>
如果你需要使用 OpenAI 兼容端点,请参见上方的“旧版 OpenAI 兼容模式”部分。在该模式下,流式传输和工具调用可能无法同时工作。
@ -481,13 +481,13 @@ OpenClaw 支持将 **Ollama Web 搜索** 作为内置的 `web_search` 提供商
<AccordionGroup>
<Accordion title="未检测到 Ollama">
请确保 Ollama 正在运行,并且你已设置 `OLLAMA_API_KEY`(或认证配置文件),同时你**没有**定义显式的 `models.providers.ollama` 条目:
请确保 Ollama 正在运行,并且你已设置 `OLLAMA_API_KEY`(或凭证配置文件),同时**没有**定义显式的 `models.providers.ollama` 条目:
```bash
ollama serve
```
验证 API 是否可访问:
验证 API 可访问:
```bash
curl http://localhost:11434/api/tags
@ -496,7 +496,7 @@ OpenClaw 支持将 **Ollama Web 搜索** 作为内置的 `web_search` 提供商
</Accordion>
<Accordion title="没有可用模型">
如果列表中没有你的模型,请在本地拉取该模型,或`models.providers.ollama` 中显式定义它。
如果列表中没有你的模型,请在本地拉取该模型,或在 `models.providers.ollama` 中显式定义它。
```bash
ollama list # 查看已安装的模型
@ -522,7 +522,7 @@ OpenClaw 支持将 **Ollama Web 搜索** 作为内置的 `web_search` 提供商
</AccordionGroup>
<Note>
更多帮助:[故障排除](/zh-CN/help/troubleshooting) 和 [常见问题](/zh-CN/help/faq)。
更多帮助:参见 [故障排除](/zh-CN/help/troubleshooting) 和 [常见问题](/zh-CN/help/faq)。
</Note>
## 相关内容
@ -535,7 +535,7 @@ OpenClaw 支持将 **Ollama Web 搜索** 作为内置的 `web_search` 提供商
如何选择和配置模型。
</Card>
<Card title="Ollama Web 搜索" href="/zh-CN/tools/ollama-search" icon="magnifying-glass">
由 Ollama 驱动的 web search 的完整设置和行为细节。
由 Ollama 驱动的 Web 搜索的完整设置和行为细节。
</Card>
<Card title="配置" href="/zh-CN/gateway/configuration" icon="gear">
完整配置参考。