OllamaOllama

OpenClaw 与 Ollama 的原生 API (OpenClawOllamaAPI/api/chatOllamaOllama) 集成，用于托管云模型和本地/自托管的 Ollama 服务器。您可以通过三种模式使用 Ollama：Cloud + LocalOllama 通过可访问的 Ollama 主机，Cloud only 针对 https://ollama.com，或 Local onlyOllama 针对可访问的 Ollama 主机。

OpenClaw 还将 OpenClawollama-cloudOllama 注册为一类托管提供商 ID，以便直接使用 Ollama Cloud。当您希望仅限云端路由而不共享本地 ollama 提供商 ID 时，请使用像 ollama-cloud/kimi-k2.5:cloud 这样的引用。

有关专用的纯云端设置页面，请参阅 Ollama Cloud。

Warning

远程 Ollama 用户

：请勿在 OpenClaw 中使用 Ollama

/v1

OpenAI OpenAI 兼容 URL (

http://host:11434/v1

OpenClawOllamaAPI)。这会破坏工具调用，模型可能会将原始工具 JSON 作为纯文本输出。请改用原生 Ollama API URL：

baseUrl: "http://host:11434"

（无

/v1

）。

Ollama 提供商配置使用 OllamabaseUrlOpenClaw 作为规范键。OpenClaw 也接受 baseURLOpenAI 以兼容 OpenAI SDK 风格的示例，但新配置应首选 baseUrl。

身份验证规则

Local and LAN hosts

本地和局域网 Ollama 主机不需要真实的 bearer 令牌。OpenClaw 仅对环回、专用网络、.localOllama 和仅主机名的 Ollama 基本 URL 使用本地 ollama-local 标记。

OllamaRemote and Ollama Cloud hosts

远程公共主机和 Ollama Cloud (https://ollama.com) 需要通过 OLLAMA_API_KEY、身份验证配置文件或提供商的 apiKey 提供真实的凭据。对于直接托管使用，首选提供商 ollama-cloud。

Custom 提供商 ids

设置 api: "ollama" 的自定义提供商 ID 遵循相同的规则。例如，指向专用局域网 Ollama 主机的 ollama-remoteOllama 提供商可以使用 apiKey: "ollama-local"Ollama，子代理将通过 Ollama 提供商挂钩解析该标记，而不是将其视为缺失的凭据。内存搜索还可以将 agents.defaults.memorySearch.providerOllama 设置为该自定义提供商 ID，以便嵌入使用匹配的 Ollama 端点。

Auth profiles

auth-profiles.json 存储提供商 ID 的凭据。将端点设置（baseUrl、api、模型 ID、标头、超时）放在 `models.providers.

中。较旧的扁平身份验证配置文件（如{ “ollama-windows”: { “apiKey”: “ollama-local” } }）不是运行时格式；请运行 openclaw doctor —fix将它们重写为带有备份的规范ollama-windows:defaultAPI API 密钥配置文件。该文件中的 baseUrl` 是兼容性干扰内容，应移至提供商配置。

Memory embedding scope

当 Ollama 用于记忆嵌入时，不记名认证 (bearer auth) 的范围限定在声明它的主机：

• 提供商级别的密钥仅发送到该提供商的 Ollama 主机。
• agents.*.memorySearch.remote.apiKey 仅发送到其远程嵌入主机。
• 纯 OLLAMA_API_KEY 环境变量值被视为 Ollama Cloud 约定，默认不会发送到本地或自托管主机。

入门指南

选择您偏好的设置方法和模式。

新手引导（推荐）Manual setup

最适用于： 快速搭建可用的 Ollama 云端或本地环境。

1. 运行新手引导

   openclaw onboard
   ```Ollama
   
   从提供商列表中选择 **Ollama**。

2. 选择您的模式

   • Cloud + Local — 本地 Ollama 主机加上通过该主机路由的云端模型
   • Cloud only — 通过 https://ollama.com 托管的 Ollama 模型
   • Local only — 仅本地模型

3. 选择一个模型

   Cloud only 会提示输入 OLLAMA_API_KEY 并建议托管的云端默认值。Cloud + Local 和 Local onlyOllamaOllama 会询问 Ollama 基础 URL，发现可用模型，并在所选本地模型尚未可用时自动拉取。当 Ollama 报告已安装的 :latest 标签（例如 gemma4:latest）时，设置会显示该已安装模型一次，而不是同时显示 gemma4 和 gemma4:latest 或再次拉取裸别名。Cloud + LocalOllama 还会检查该 Ollama 主机是否已登录以进行云端访问。

4. 验证模型是否可用

   openclaw models list --provider ollama

非交互模式

openclaw onboard --non-interactive \
  --auth-choice ollama \
  --accept-risk

可选指定自定义基础 URL 或模型：

openclaw onboard --non-interactive \
  --auth-choice ollama \
  --custom-base-url "http://ollama-host:11434" \
  --custom-model-id "qwen3.5:27b" \
  --accept-risk

最适合： 全面控制云端或本地设置。

1. Choose cloud or local

   • Cloud + Local: 安装 Ollama，使用 ollama signin 登录，并通过该主机路由云端请求
   • Cloud only: 将 https://ollama.com 与 OLLAMA_API_KEYOllama 结合使用
   • Local only: 从 ollama.com/download 安装 Ollama

2. Pull a local 模型 (local only)

   ollama pull gemma4
   # or
   ollama pull gpt-oss:20b
   # or
   ollama pull llama3.3

3. OllamaOpenClawEnable Ollama for OpenClaw

   对于 Cloud only，请使用您的真实 OLLAMA_API_KEY。对于主机支持的设置，任何占位符值均可使用：

   # Cloud
   export OLLAMA_API_KEY="your-ollama-api-key"
   
   # Local-only
   export OLLAMA_API_KEY="ollama-local"
   
   # Or configure in your config file
   openclaw config set models.providers.ollama.apiKey "OLLAMA_API_KEY"

4. Inspect and set your 模型

   openclaw models list
   openclaw models set ollama/gemma4

   或者在配置中设置默认值：

   {
     agents: {
       defaults: {
         model: { primary: "ollama/gemma4" },
       },
     },
   }

云端模型

Cloud + LocalCloud onlyLocal only

Cloud + LocalOllamaOllamaOpenClawOllama 使用可访问的 Ollama 主机作为本地和云端模型的控制点。这是 Ollama 推荐的混合流程。

在设置期间使用 Cloud + Local。OpenClaw 会提示输入 Ollama 基础 URL，从该主机发现本地模型，并检查主机是否使用 ollama signinOpenClaw 登录以进行云端访问。当主机已登录时，OpenClaw 还会建议托管的云端默认模型，例如 kimi-k2.5:cloud、minimax-m2.7:cloud 和 glm-5.1:cloudOpenClaw。

如果主机尚未登录，OpenClaw 会将设置保持为仅本地模式，直到您运行 ollama signin。

Cloud only 针对 Ollama 在 https://ollama.com 的托管 API 运行。

在设置过程中使用 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 --auth-choice ollama-cloud
openclaw models set ollama-cloud/kimi-k2.5:cloud

在仅本地模式下，OpenClaw 会从配置的 Ollama 实例中发现模型。此路径适用于本地或自托管的 Ollama 服务器。

OpenClaw 目前建议将 gemma4 作为本地默认值。

模型发现（隐式提供商）

当您设置 OLLAMA_API_KEY（或身份验证配置文件）并不定义 models.providers.ollama 或使用 api: "ollama" 定义其他自定义远程提供商时，OpenClaw 会从位于 http://127.0.0.1:11434 的本地 Ollama 实例中发现模型。

行为	详情
目录查询	查询 /api/tags
功能检测	使用尽力而为的 /api/show 查找来读取 contextWindow、扩展的 num_ctx Modelfile 参数以及包括视觉/工具在内的功能
视觉模型	据 /api/show 报告，具有 vision 能力的模型会被标记为支持图像（input: ["text", "image"]OpenClaw），因此 OpenClaw 会自动将图像注入到提示词中
推理检测	在可用时使用 /api/show 能力，包括 thinking；当 Ollama 省略能力时，回退到模型名称启发式方法（r1、reasoning、thinkOllama）
Token 限制	将 maxTokensOllamaOpenClaw 设置为 OpenClaw 使用的默认 Ollama 最大 token 上限
费用	将所有费用设置为 0

这避免了手动输入模型，同时使目录与本地 Ollama 实例保持一致。您可以在本地 infer model runOllamaOpenClaw 中使用完整的引用，例如 Ollamaollama/<pulled-model>:latest；OpenClaw 从 Ollama 的实时目录中解析该已安装的模型，而无需手写的 models.json 条目。

对于已登录的 Ollama 主机，某些 Ollama:cloud 模型可能可以通过 /api/chat 和 /api/show 使用，然后才出现在 /api/tags 中。当您明确选择一个 完整的 ollama/<model>:cloudOpenClaw 引用时，OpenClaw 会使用 /api/showOllama 验证该确切缺失的模型， 并且仅当 Ollama 确认模型元数据时才将其添加到运行时目录中。拼写错误仍将作为未知模型失败，而不会自动创建。

# See what models are available
ollama list
openclaw models list

为了进行避免完整 agent 工具表面的狭隘文本生成冒烟测试， 请使用带有完整 Ollama 模型引用的本地 infer model runOllama：

OLLAMA_API_KEY=ollama-local \
  openclaw infer model run \
    --local \
    --model ollama/llama3.2:latest \
    --prompt "Reply with exactly: pong" \
    --json

该路径仍然使用 OpenClaw 配置的提供商、身份验证和原生 Ollama 传输，但它不会启动聊天代理回合或加载 MCP/工具上下文。如果此操作成功，而正常的代理回复失败，请接下来排查模型的代理提示/工具容量。

要在同一条精简路径上进行狭义的视觉模型冒烟测试，请将一个或多个图像文件添加到 infer model run。这会将提示和图像直接发送到选定的 Ollama 视觉模型，而无需加载聊天工具、内存或先前的会话上下文：

OLLAMA_API_KEY=ollama-local \
  openclaw infer model run \
    --local \
    --model ollama/qwen2.5vl:7b \
    --prompt "Describe this image in one sentence." \
    --file ./photo.jpg \
    --json

model run --file 接受被检测为 image/* 的文件，包括常见的 PNG、JPEG 和 WebP 输入。非图像文件会在调用 Ollama 之前被拒绝。对于语音识别，请改用 openclaw infer audio transcribe。

当您使用 /model ollama/<model> 切换对话时，OpenClaw 会将其视为确切的用户选择。如果配置的 Ollama baseUrl 无法访问，则下一次回复将因提供商错误而失败，而不是静默地从另一个配置的回退模型进行回答。

隔离的 cron 作业在启动代理回合之前会执行一项额外的本地安全检查。如果所选的模型解析为本地、私有网络或 .local Ollama 提供商，并且 /api/tags 无法访问，OpenClaw 会将该 cron 运行记录为 skipped，并在错误文本中包含所选的 ollama/<model>。端点预检会缓存 5 分钟，因此指向同一已停止 Ollama 守护程序的多个 cron 作业不会全部发起失败的模型请求。

针对本地 Ollama 实时验证本地文本路径、原生流路径和嵌入：

OPENCLAW_LIVE_TEST=1 OPENCLAW_LIVE_OLLAMA=1 OPENCLAW_LIVE_OLLAMA_WEB_SEARCH=0 \
  pnpm test:live -- extensions/ollama/ollama.live.test.ts

对于 Ollama Cloud API 密钥冒烟测试，请将实时测试指向 https://ollama.com 并从当前目录中选择一个托管模型：

export OLLAMA_API_KEY='<your-ollama-cloud-api-key>'

OPENCLAW_LIVE_TEST=1 \
OPENCLAW_LIVE_OLLAMA=1 \
OPENCLAW_LIVE_OLLAMA_BASE_URL=https://ollama.com \
OPENCLAW_LIVE_OLLAMA_MODEL=glm-5.1:cloud \
OPENCLAW_LIVE_OLLAMA_WEB_SEARCH=1 \
pnpm test:live -- extensions/ollama/ollama.live.test.ts

云端冒烟测试会运行文本、原生流和 Web 搜索。默认情况下，它会跳过针对 https://ollama.comOllamaAPI 的嵌入（embeddings）操作，因为 Ollama Cloud API 密钥可能无法授权 /api/embed。如果您希望如果配置的云端密钥无法使用嵌入端点时实时测试失败，请设置 OPENCLAW_LIVE_OLLAMA_EMBEDDINGS=1。

要添加新模型，只需使用 Ollama 拉取它：

ollama pull mistral

新模型将被自动发现并可供使用。

Note

如果您显式设置了

models.providers.ollama

，或者配置了自定义远程提供商（例如使用

api: "ollama"

的

models.providers.ollama-cloud

），则将跳过自动发现，您必须手动定义模型。诸如

http://127.0.0.2:11434

之类的环回自定义提供商仍被视为本地提供商。请参阅下面的显式配置部分。

视觉与图像描述

捆绑的 Ollama 插件将 Ollama 注册为具有图像功能的媒体理解提供商。这使得 OpenClaw 可以将显式的图像描述请求和配置的图像模型默认值通过本地或托管的 Ollama 视觉模型进行路由。

对于本地视觉功能，请拉取一个支持图像的模型：

ollama pull qwen2.5vl:7b
export OLLAMA_API_KEY="ollama-local"

然后使用 infer CLI 进行验证：

openclaw infer image describe \
  --file ./photo.jpg \
  --model ollama/qwen2.5vl:7b \
  --json

--model 必须是完整的 <provider/model> 引用。设置后，openclaw infer image describe 将直接运行该模型，而不是跳过描述，因为该模型支持原生视觉。

当您想要 OpenClaw 的图像理解提供商流程、配置的 agents.defaults.imageModel 以及图像描述输出形状时，请使用 infer image describe。当您想要使用自定义提示词和一个或多个图像进行原始多模态模型探测时，请使用 infer model run --file。

要将 Ollama 设为传入媒体的默认图像理解模型，请配置 agents.defaults.imageModel：

{
  agents: {
    defaults: {
      imageModel: {
        primary: "ollama/qwen2.5vl:7b",
      },
    },
  },
}

首选完整的 ollama/<model> 引用。如果同一模型在 models.providers.ollama.models 下以 input: ["text", "image"]OpenClaw 列出，且没有其他已配置的图像提供商暴露该裸模型 ID，OpenClaw 还会将裸 imageModel 引用（如 qwen2.5vl:7b）标准化为 ollama/qwen2.5vl:7b。如果有多个已配置的图像提供商具有相同的裸 ID，请显式使用提供商前缀。

与云模型相比，运行缓慢的本地视觉模型可能需要更长的图像理解超时时间。当 Ollama 尝试在受限硬件上分配完整的 advertised 视觉上下文时，它们也可能崩溃或停止。当您只需要正常的图像描述轮次时，请在模型条目上设置 capability timeout，并限制 Ollamanum_ctx：

{
  models: {
    providers: {
      ollama: {
        models: [
          {
            id: "qwen2.5vl:7b",
            name: "qwen2.5vl:7b",
            input: ["text", "image"],
            params: { num_ctx: 2048, keep_alive: "1m" },
          },
        ],
      },
    },
  },
  tools: {
    media: {
      image: {
        timeoutSeconds: 180,
        models: [{ provider: "ollama", model: "qwen2.5vl:7b", timeoutSeconds: 300 }],
      },
    },
  },
}

此超时适用于传入的图像理解以及代理在轮次期间可以调用的显式 image 工具。提供商级别的 models.providers.ollama.timeoutSecondsOllama 仍然控制正常模型调用的基础 Ollama HTTP 请求守卫。

使用以下命令针对本地 Ollama 实时验证显式图像工具：

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，请用图像输入支持标记视觉模型：

{
  id: "qwen2.5vl:7b",
  name: "qwen2.5vl:7b",
  input: ["text", "image"],
  contextWindow: 128000,
  maxTokens: 8192,
}

OpenClaw 会拒绝针对未标记支持图像的模型的图像描述请求。通过隐式发现，当 OpenClawOpenClawOllama/api/show 报告视觉能力时，OpenClaw 会从 Ollama 读取此信息。

配置

Basic (implicit discovery)显式（手动模型）

最简单的仅本地启用路径是通过环境变量：

export OLLAMA_API_KEY="ollama-local"

Tip

如果设置了 OLLAMA_API_KEY，您可以在提供商条目中省略 apiKeyOpenClaw，OpenClaw 将为其填充用于可用性检查。

当您需要托管云设置、Ollama 运行在其他主机/端口上、想要强制指定特定的上下文窗口或模型列表，或者想要完全手动定义模型时，请使用显式配置。

{
  models: {
    providers: {
      ollama: {
        baseUrl: "https://ollama.com",
        apiKey: "OLLAMA_API_KEY",
        api: "ollama",
        models: [
          {
            id: "kimi-k2.5:cloud",
            name: "kimi-k2.5:cloud",
            reasoning: false,
            input: ["text", "image"],
            cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
            contextWindow: 128000,
            maxTokens: 8192
          }
        ]
      }
    }
  }
}

<Tab title=“自定义基础 URL”Ollama> 如果 Ollama 运行在不同的主机或端口上（显式配置会禁用自动发现，因此需手动定义模型）：

```json5
{
  models: {
    providers: {
      ollama: {
        apiKey: "ollama-local",
        baseUrl: "http://ollama-host:11434", // No /v1 - use native Ollama API URL
        api: "ollama", // Set explicitly to guarantee native tool-calling behavior
        timeoutSeconds: 300, // Optional: give cold local models longer to connect and stream
        models: [
          {
            id: "qwen3:32b",
            name: "qwen3:32b",
            params: {
              keep_alive: "15m", // Optional: keep the model loaded between turns
            },
          },
        ],
      },
    },
  },
}
```

<Warning>
不要在 URL 中添加 `/v1`。`/v1`OpenAIOllama 路径使用的是 OpenAI 兼容模式，该模式下的工具调用不可靠。请使用不带路径后缀的基础 Ollama URL。
</Warning>

常用方法

将这些作为起点，并将模型 ID 替换为 ollama list 或 openclaw models list --provider ollama 中的确切名称。

自动发现的本地模型

当 Ollama 与 Gateway 运行在同一台机器上，并且您希望 OpenClaw 自动发现已安装的模型时使用此选项。

ollama serve
ollama pull gemma4
export OLLAMA_API_KEY="ollama-local"
openclaw models list --provider ollama
openclaw models set ollama/gemma4

此路径可保持配置最简。除非您想手动定义模型，否则不要添加 models.providers.ollama 块。

Ollama使用手动模型的局域网 Ollama 主机

对局域网主机使用原生 Ollama URL。不要添加 /v1。

{
  models: {
    providers: {
      ollama: {
        baseUrl: "http://gpu-box.local:11434",
        apiKey: "ollama-local",
        api: "ollama",
        timeoutSeconds: 300,
        contextWindow: 32768,
        maxTokens: 8192,
        models: [
          {
            id: "qwen3.5:9b",
            name: "qwen3.5:9b",
            reasoning: true,
            input: ["text"],
            params: {
              num_ctx: 32768,
              thinking: false,
              keep_alive: "15m",
            },
          },
        ],
      },
    },
  },
  agents: {
    defaults: {
      model: { primary: "ollama/qwen3.5:9b" },
    },
  },
}

contextWindowOpenClaw 是 OpenClaw 端的上下文预算。params.num_ctxOllama 会随请求发送给 Ollama。当您的硬件无法运行模型所标称的完整上下文时，请保持两者一致。

<Accordion title=“Ollama仅 Ollama Cloud”Ollama> 当您不运行本地守护进程并希望直接使用托管的 Ollama 模型时使用此选项。

```bash
export OLLAMA_API_KEY="your-ollama-api-key"
```

```json5
{
  models: {
    providers: {
      ollama: {
        baseUrl: "https://ollama.com",
        apiKey: "OLLAMA_API_KEY",
        api: "ollama",
        models: [
          {
            id: "kimi-k2.5:cloud",
            name: "kimi-k2.5:cloud",
            reasoning: false,
            input: ["text", "image"],
            contextWindow: 128000,
            maxTokens: 8192,
          },
        ],
      },
    },
  },
  agents: {
    defaults: {
      model: { primary: "ollama/kimi-k2.5:cloud" },
    },
  },
}
```

<Accordion title=“通过已登录守护进程实现云端加本地模式”Ollama> 当本地或局域网 Ollama 守护进程已使用 ollama signin 登录，并且应同时提供本地模型和 :cloud 模型时使用此选项。

```bash
ollama signin
ollama pull gemma4
```

```json5
{
  models: {
    providers: {
      ollama: {
        baseUrl: "http://127.0.0.1:11434",
        apiKey: "ollama-local",
        api: "ollama",
        timeoutSeconds: 300,
        models: [
          { id: "gemma4", name: "gemma4", input: ["text"] },
          { id: "kimi-k2.5:cloud", name: "kimi-k2.5:cloud", input: ["text", "image"] },
        ],
      },
    },
  },
  agents: {
    defaults: {
      model: {
        primary: "ollama/gemma4",
        fallbacks: ["ollama/kimi-k2.5:cloud"],
      },
    },
  },
}
```

<Accordion title=“Ollama多个 Ollama 主机”Ollama> 当您拥有多个 Ollama 服务器时，请使用自定义提供商 ID。每个提供商都有自己的主机、模型、身份验证、超时和模型引用。

```json5
{
  models: {
    providers: {
      "ollama-fast": {
        baseUrl: "http://mini.local:11434",
        apiKey: "ollama-local",
        api: "ollama",
        contextWindow: 32768,
        models: [{ id: "gemma4", name: "gemma4", input: ["text"] }],
      },
      "ollama-large": {
        baseUrl: "http://gpu-box.local:11434",
        apiKey: "ollama-local",
        api: "ollama",
        timeoutSeconds: 420,
        contextWindow: 131072,
        maxTokens: 16384,
        models: [{ id: "qwen3.5:27b", name: "qwen3.5:27b", input: ["text"] }],
      },
    },
  },
  agents: {
    defaults: {
      model: {
        primary: "ollama-fast/gemma4",
        fallbacks: ["ollama-large/qwen3.5:27b"],
      },
    },
  },
}
```OpenClaw

当 OpenClaw 发送请求时，活动提供商前缀会被剥离，因此 `ollama-large/qwen3.5:27b`Ollama 会以 `qwen3.5:27b` 的形式到达 Ollama。

精简本地模型配置

某些本地模型可以回答简单的提示，但难以应对完整的代理工具界面。在更改全局运行时设置之前，请先尝试限制工具和上下文。

{
  agents: {
    list: [
      {
        id: "local",
        experimental: {
          localModelLean: true,
        },
        model: { primary: "ollama/gemma4" },
      },
    ],
  },
  models: {
    providers: {
      ollama: {
        baseUrl: "http://127.0.0.1:11434",
        apiKey: "ollama-local",
        api: "ollama",
        contextWindow: 32768,
        models: [
          {
            id: "gemma4",
            name: "gemma4",
            input: ["text"],
            params: { num_ctx: 32768 },
            compat: { supportsTools: false },
          },
        ],
      },
    },
  },
}

仅当模型或服务器在工具架构上可靠地失败时，才使用 compat.supportsTools: false。它以牺牲代理能力为代价换取稳定性。 localModelLeanOllama 从代理界面中移除了浏览器、cron 和消息工具，但它不会改变 Ollama 的运行时上下文或思考模式。对于会出现循环或在隐藏推理上消耗响应预算的小型 Qwen 风格思考模型，请将其与显式的 params.num_ctx 和 params.thinking: falseQwen 结合使用。

模型选择

配置完成后，您的所有 Ollama 模型均可用：

{
  agents: {
    defaults: {
      model: {
        primary: "ollama/gpt-oss:20b",
        fallbacks: ["ollama/llama3.3", "ollama/qwen2.5-coder:32b"],
      },
    },
  },
}

也支持自定义 Ollama 提供商 ID。当模型引用使用活动的提供商前缀（例如 Ollamaollama-spark/qwen3:32bOpenClawOllama）时，OpenClaw 会在调用 Ollama 之前仅去除该前缀，以便服务器接收到 qwen3:32b。

对于速度较慢的本地模型，建议优先在提高整个代理运行时超时之前进行提供商范围内的请求调优：

{
  models: {
    providers: {
      ollama: {
        timeoutSeconds: 300,
        models: [
          {
            id: "gemma4:26b",
            name: "gemma4:26b",
            params: { keep_alive: "15m" },
          },
        ],
      },
    },
  },
}

timeoutSeconds 适用于模型 HTTP 请求，包括连接建立、标头、主体流传输和整个受保护的 fetch 中止。params.keep_aliveOllama 将作为顶级 keep_alive 转发给 Ollama，用于原生 /api/chat 请求；当首轮加载时间是瓶颈时，请按模型进行设置。

快速验证

# Ollama daemon visible to this machine
curl http://127.0.0.1:11434/api/tags

# OpenClaw catalog and selected model
openclaw models list --provider ollama
openclaw models status

# Direct model smoke
openclaw infer model run \
  --model ollama/gemma4 \
  --prompt "Reply with exactly: ok"

对于远程主机，请将 127.0.0.1 替换为 baseUrl 中使用的主机。如果 curlOpenClawGateway(网关) 工作正常但 OpenClaw 不工作，请检查 Gateway 是否运行在不同的机器、容器或服务帐户上。

Ollama Web Search

OpenClaw 支持 Ollama Web Search 作为捆绑的 OpenClawOllamaweb_search 提供商。

属性	详细信息
主机	使用您配置的 Ollama 主机（如果已设置，则为 Ollamamodels.providers.ollama.baseUrl，否则为 http://127.0.0.1:11434）；https://ollama.comAPI 直接使用托管的 API
身份验证	对于已登录的本地 Ollama 主机无需密钥；对于直接 https://ollama.com 搜索或受身份验证保护的主机，需要 OllamaOLLAMA_API_KEY 或已配置的提供商身份验证
要求	本地/自托管主机必须正在运行并使用 ollama signin 登录；直接托管搜索需要 baseUrl: "https://ollama.com"OllamaAPI 以及真实的 Ollama API 密钥

在 Ollamaopenclaw onboard 或 openclaw configure --section web 期间选择 Ollama Web Search，或进行设置：

{
  tools: {
    web: {
      search: {
        provider: "ollama",
      },
    },
  },
}

对于通过 Ollama Cloud 进行的直接托管搜索：

{
  models: {
    providers: {
      ollama: {
        baseUrl: "https://ollama.com",
        apiKey: "OLLAMA_API_KEY",
        api: "ollama",
        models: [{ id: "kimi-k2.5:cloud", name: "kimi-k2.5:cloud", input: ["text"] }],
      },
    },
  },
  tools: {
    web: {
      search: { provider: "ollama" },
    },
  },
}

对于已登录的本地守护进程，OpenClaw 使用该守护进程的 /api/experimental/web_search 代理。对于 https://ollama.com，它直接调用托管的 /api/web_search 端点。

Note

有关完整的设置和行为详细信息，请参阅

Ollama Web Search

。

高级配置

Legacy OpenAI-compatible mode

Warning

在 OpenAI-compatible 模式下，工具调用不可靠。 仅当您需要代理使用 OpenAI 格式且不依赖于原生工具调用行为时，才使用此模式。

如果您需要改用 OpenAI-compatible 端点（例如，在仅支持 OpenAI 格式的代理之后），请显式设置 api: "openai-completions"：

{
  models: {
    providers: {
      ollama: {
        baseUrl: "http://ollama-host:11434/v1",
        api: "openai-completions",
        injectNumCtxForOpenAICompat: true, // default: true
        apiKey: "ollama-local",
        models: [...]
      }
    }
  }
}

此模式可能无法同时支持流式传输和工具调用。您可能需要在模型配置中通过 params: { streaming: false } 禁用流式传输。

当将 api: "openai-completions" 与 Ollama 一起使用时，OpenClaw 默认会注入 options.num_ctx，以防止 Ollama 静默回退到 4096 上下文窗口。如果您的代理/上游拒绝未知的 options 字段，请禁用此行为：

{
  models: {
    providers: {
      ollama: {
        baseUrl: "http://ollama-host:11434/v1",
        api: "openai-completions",
        injectNumCtxForOpenAICompat: false,
        apiKey: "ollama-local",
        models: [...]
      }
    }
  }
}

上下文窗口

对于自动发现的模型，OpenClaw 会尽可能使用 Ollama 报告的上下文窗口，包括来自自定义 Modelfile 的较大 PARAMETER num_ctxOllamaOpenClaw 值。否则将回退到 OpenClaw 使用的默认 Ollama 上下文窗口。

您可以为该 Ollama 提供商下的每个模型设置提供商级别的 contextWindow、contextTokens 和 maxTokensOllama 默认值，然后根据需要针对每个模型进行覆盖。contextWindowOpenClawOllama 是 OpenClaw 的提示和压缩预算。原生 Ollama 请求默认不设置 options.num_ctx，除非您显式配置了 params.num_ctxOllama，以便 Ollama 可以应用其自己的模型、OLLAMA_CONTEXT_LENGTHOllama 或基于 VRAM 的默认值。要在不重建 Modelfile 的情况下限制或强制 Ollama 的每次请求运行时上下文，请设置 params.num_ctx；无效、零、负数和非有限值将被忽略。如果您升级了仅使用 contextWindow 或 maxTokensOllama 来强制原生 Ollama 请求上下文的旧配置，请运行 openclaw doctor --fix 将这些显式的提供商或模型预算复制到 params.num_ctxOpenAIOllama 中。OpenAI 兼容的 Ollama 适配器仍然默认根据配置的 params.num_ctx 或 contextWindow 注入 options.num_ctx；如果您的上游拒绝 optionsOllamaOllama，请使用 injectNumCtxForOpenAICompat: false 禁用此功能。

原生 Ollama 模型条目还接受 params 下的常用 Ollama 运行时选项，包括 temperature、top_p、top_k、min_p、num_predict、stop、repeat_penalty、num_batch、num_thread 和 use_mmapOpenClawOllamaOpenClaw。OpenClaw 仅转发 Ollama 请求键，因此 OpenClaw 运行时参数（如 streamingOllama）不会泄露给 Ollama。使用 params.think 或 params.thinkingOllama 发送顶层 Ollama think；falseAPIQwen 可禁用 Qwen 风格思考模型的 API 级思考。

{
  models: {
    providers: {
      ollama: {
        contextWindow: 32768,
        models: [
          {
            id: "llama3.3",
            contextWindow: 131072,
            maxTokens: 65536,
            params: {
              num_ctx: 32768,
              temperature: 0.7,
              top_p: 0.9,
              thinking: false,
            },
          }
        ]
      }
    }
  }
}

每个模型的 `agents.defaults.models[“ollama/

“].params.num_ctx` 也可以使用。如果两者都配置了，显式的提供商模型条目将覆盖代理默认值。

<Accordion title=“思考控制”OllamaOpenClawOllama> 对于原生 Ollama 模型，OpenClaw 会按照 Ollama 期望的方式转发思考控制：顶层 think，而不是 options.think。如果自动发现的模型的 /api/show 响应包含 thinking 功能，则会暴露 /think low、/think medium、/think high 和 /think max；非思考模型仅暴露 /think off。

```bash
openclaw agent --model ollama/gemma4 --thinking off
openclaw agent --model ollama/gemma4 --thinking low
```

您还可以设置模型默认值：

```json5
{
  agents: {
    defaults: {
      models: {
        "ollama/gemma4": {
          thinking: "low",
        },
      },
    },
  },
}
```

特定模型的 `params.think` 或 `params.thinking`OllamaAPIOpenClaw 可以禁用或强制特定已配置模型的 Ollama API 思考功能。当活动运行仅具有隐式默认 `off` 时，OpenClaw 会保留这些显式模型参数；非运行时命令（如 `/think medium`）仍然会覆盖活动运行。

<Accordion title=“推理模型”OpenClaw> OpenClaw 默认将名称包含 deepseek-r1、reasoning 或 think 等的模型视为具备推理能力。

```bash
ollama pull deepseek-r1:32b
```OpenClaw

无需额外配置。OpenClaw 会自动将其标记。

模型成本

Ollama 是免费的且在本地运行，因此所有模型成本均设置为 $0。这适用于自动发现和手动定义的模型。

Memory embeddings

捆绑的 Ollama 插件为 memory search 注册了一个内存嵌入提供商。 它使用配置的 Ollama 基础 URL 和 API 密钥，调用 Ollama 当前的 /api/embed 端点，并尽可能将多个内存块批量处理到一个 input 请求中。

当 proxy.enabled=true 时，指向从配置的 baseUrl 派生的精确主机本地环回源的 Ollama 内存嵌入请求，使用 OpenClaw 的受保护直接路径，而不是受管理的转发代理。 配置的主机名本身必须是 localhost 或环回 IP 字面量；仅解析为环回的 DNS 名称仍使用受管理的代理路径。 LAN、tailnet、私有网络和公共 Ollama 主机也停留在受管理的代理路径上。 重定向到另一个主机或端口不会继承信任。 操作员仍可以设置全局 proxy.loopbackMode: "proxy" 设置以通过代理发送环回流量，或设置 proxy.loopbackMode: "block" 以在打开连接之前拒绝环回连接；请参阅 Managed proxy 了解此设置的进程范围影响。

属性	值
默认模型	nomic-embed-text
自动拉取	是 — 如果本地不存在嵌入模型，会自动拉取

查询时嵌入对需要或推荐检索前缀的模型使用检索前缀，包括 nomic-embed-text、qwen3-embedding 和 mxbai-embed-large。内存文档批次保持原始状态，因此现有索引不需要格式迁移。

要选择 Ollama 作为内存搜索嵌入提供商：

{
  agents: {
    defaults: {
      memorySearch: {
        provider: "ollama",
        remote: {
          // Default for Ollama. Raise on larger hosts if reindexing is too slow.
          nonBatchConcurrency: 1,
        },
      },
    },
  },
}

对于远程嵌入主机，请将 auth 限制在该主机范围内：

{
  agents: {
    defaults: {
      memorySearch: {
        provider: "ollama",
        model: "nomic-embed-text",
        remote: {
          baseUrl: "http://gpu-box.local:11434",
          apiKey: "ollama-local",
          nonBatchConcurrency: 2,
        },
      },
    },
  },
}

<Accordion title=“流式配置”OpenClawOllamaOllamaAPI> OpenClaw 的 Ollama 集成默认使用 原生 Ollama API (/api/chat)，它完全支持同时进行流式传输和工具调用。无需特殊配置。

对于原生 `/api/chat`OpenClawOllama 请求，OpenClaw 还会将思维控制直接转发给 Ollama：`/think off` 和 `openclaw agent --thinking off` 发送顶级 `think: false`，除非配置了显式的模型 `params.think`/`params.thinking` 值，而 `/think low|medium|high` 发送匹配的顶级 `think` 努力字符串。`/think max`Ollama 映射到 Ollama 的最高原生努力程度，`think: "high"`OpenAIOpenAI。

<Tip>
如果您需要使用 OpenAI 兼容端点，请参阅上面的“传统 OpenAI 兼容模式”部分。在该模式下，流式传输和工具调用可能无法同时工作。
</Tip>

故障排除

WSL2WSL2 崩溃循环（反复重启）

在带有 NVIDIA/CUDA 的 WSL2 上，官方 Ollama Linux 安装程序会创建一个具有 Restart=always 的 ollama.service systemd 单元。如果该服务在 WSL2 启动期间自动启动并加载 GPU 支持的模型，Ollama 可能会在模型加载时锁定主机内存。Hyper-V 内存回收并不总是能回收这些锁定的页面，因此 Windows 可能会终止 WSL2 VM，systemd 再次启动 Ollama，循环重复。

常见迹象：

• 从 WSL2 端反复重启或终止 Windows
• 在 WSL2 启动后不久，app.slice 或 ollama.service 占用高 CPU
• 来自 systemd 的 SIGTERM 信号，而不是 Linux OOM-killer 事件

当检测到 OpenClaw、启用了 ollama.service 并启用了 Restart=always 以及可见的 CUDA 标记时，WSL2 会记录启动警告。

缓解措施：

sudo systemctl disable ollama

将此添加到 Windows 端的 %USERPROFILE%\.wslconfig 中，然后运行 wsl --shutdown：

[experimental]
autoMemoryReclaim=disabled

在 Ollama 服务环境中设置更短的保持连接时间，或者仅在需要时手动启动 Ollama：

export OLLAMA_KEEP_ALIVE=5m
ollama serve

参见 ollama/ollama#11317。

Ollama未检测到 Ollama

确保 Ollama 正在运行，并且您设置了 OLLAMA_API_KEY（或身份验证配置文件），并且您没有定义显式的 models.providers.ollama 条目：

ollama serve

验证 API 是否可访问：

curl http://localhost:11434/api/tags

无可用模型

如果未列出您的模型，请在本地拉取该模型，或者在 models.providers.ollama 中显式定义它。

ollama list  # See what's installed
ollama pull gemma4
ollama pull gpt-oss:20b
ollama pull llama3.3     # Or another model

连接被拒绝

检查 Ollama 是否正在正确的端口上运行：

# Check if Ollama is running
ps aux | grep ollama

# Or restart Ollama
ollama serve

远程主机适用于 curl 但不适用于 OpenClaw

从运行 Gateway(网关) 的同一台机器和运行时进行验证：

openclaw gateway status --deep
curl http://ollama-host:11434/api/tags

常见原因：

• baseUrl 指向 localhost，但 Gateway(网关) 在 Docker 或另一台主机上运行。
• URL 使用了 /v1，这会选择 OpenAI 兼容行为，而不是原生 Ollama 行为。
• 远程主机需要在 Ollama 端更改防火墙或 LAN 绑定设置。
• 该模型存在于您笔记本电脑的守护进程上，但不存在于远程守护进程上。

模型将工具 JSON 输出为文本

这通常意味着提供商正在使用 OpenAI 兼容模式，或者模型无法处理工具架构。

首选原生 Ollama 模式：

{
  models: {
    providers: {
      ollama: {
        baseUrl: "http://ollama-host:11434",
        api: "ollama",
      },
    },
  },
}

如果小型本地模型仍然无法处理工具架构，请在该模型条目上设置 compat.supportsTools: false 并重新测试。

GLMKimi 或 GLM 返回乱码符号

托管的 Kimi/GLM 响应如果是长串的非语言符号，将被视为提供商输出失败，而不是成功的助手回答。这样可以让正常的重试、回退或错误处理机制介入，而不会将损坏的文本保存到会话中。

如果这种情况反复发生，请记录原始模型名称、当前会话文件，以及运行时使用的是 Cloud + Local 还是 Cloud only，然后尝试一个全新的会话和一个回退模型：

openclaw infer model run --model ollama/kimi-k2.5:cloud --prompt "Reply with exactly: ok" --json
openclaw models set ollama/gemma4

<Accordion title=“本地冷模型超时”OllamaOllama> 大型本地模型在开始流式传输之前可能需要很长的首次加载时间。请将超时限制在 Ollama 提供商范围内，并可选择要求 Ollama 在轮次之间保持模型加载状态：

```json5
{
  models: {
    providers: {
      ollama: {
        timeoutSeconds: 300,
        models: [
          {
            id: "gemma4:26b",
            name: "gemma4:26b",
            params: { keep_alive: "15m" },
          },
        ],
      },
    },
  },
}
```

如果主机本身接受连接很慢，`timeoutSeconds` 也会延长此提供商受保护的 Undici 连接超时时间。

<Accordion title=“大上下文模型太慢或内存不足”OllamaOllamaOllama> 许多 Ollama 模型宣传的上下文大小超出了您的硬件所能舒适运行的范围。原生 Ollama 使用 Ollama 自身的运行时上下文默认值，除非您设置了 params.num_ctxOpenClawOllama。当您需要可预测的首字节延迟时，请同时限制 OpenClaw 的预算和 Ollama 的请求上下文：

```json5
{
  models: {
    providers: {
      ollama: {
        contextWindow: 32768,
        maxTokens: 8192,
        models: [
          {
            id: "qwen3.5:9b",
            name: "qwen3.5:9b",
            params: { num_ctx: 32768, thinking: false },
          },
        ],
      },
    },
  },
}
```

如果 OpenClaw 发送的提示过多，请先降低 `contextWindow`OpenClaw。如果 Ollama 加载的运行时上下文对机器来说太大，请降低 `params.num_ctx`Ollama。如果生成时间过长，请降低 `maxTokens`。

Note

更多帮助：

故障排除

和

常见问题

。

相关

Model providers

所有提供商、模型引用和故障转移行为的概述。

Model selection

如何选择和配置模型。

Ollama Web Search

由 Ollama 驱动的网络搜索的完整设置和行为详细信息。

Configuration

完整的配置参考。