古法编程

Appearance

OpenClaw 通过 Ollama 原生 /api/chat 接口支持本地和云端模型，自动发现本地实例的模型并提供工具调用。配置可使用 openclaw onboard 向导或手动设置 OLLAMA_API_KEY 环境变量，注意不要使用 /v1 路径以避免工具调用失败。验证命令：openclaw models list --provider ollama，或直接 curl http://localhost:11434/api/tags。

OpenClaw Ollama 本地与云端模型接入配置教程 ​

OpenClaw 集成 Ollama 的原生 API（/api/chat），可用于托管云端模型或本地/自部署的 Ollama 服务。支持三种模式：Cloud + Local（通过可访问的 Ollama 主机同时使用本地和云端模型）、Cloud only（直连 https://ollama.com）、Local only（仅连接本地主机）。

WARNING

远程 Ollama 用户注意：不要在 OpenClaw 中使用 /v1 的 OpenAI 兼容 URL（http://host:11434/v1）。这会破坏工具调用，模型可能将工具 JSON 以纯文本形式输出。请使用 Ollama 原生 API URL：baseUrl: "http://host:11434"（不含 /v1）。

Ollama 提供商配置使用 baseUrl 作为规范键。OpenClaw 也接受 baseURL（兼容 OpenAI SDK 写法），但新配置优先使用 baseUrl。

认证规则 ​

本地和局域网主机

本地和局域网 Ollama 主机无需真实令牌。OpenClaw 仅对回环地址、私有网络、`.local` 和裸主机名的 Ollama base URL 使用本地标记 `ollama-local`。

远程和 Ollama Cloud 主机

远程公共主机和 Ollama Cloud（`https://ollama.com`）需要通过 `OLLAMA_API_KEY`、认证配置文件或提供商的 `apiKey` 提供真实凭据。

自定义提供商 ID

设置了 `api: "ollama"` 的自定义提供商 ID 遵循相同规则。例如，指向私有局域网 Ollama 主机的 `ollama-remote` 提供商可以使用 `apiKey: "ollama-local"`，子智能体会通过 Ollama 提供商钩子解析该标记，不会将其视为缺失凭据。内存搜索也可设置 `agents.defaults.memorySearch.provider` 为该自定义提供商 ID，以便嵌入使用匹配的 Ollama 端点。

认证配置文件

`auth-profiles.json` 存储提供商 ID 的凭据。端点设置（`baseUrl`、`api`、模型 ID、请求头、超时）放在 `models.providers.<id>` 中。旧的扁平认证配置文件（如 `{ "ollama-windows": { "apiKey": "ollama-local" } }`）不是运行时格式；运行 `openclaw doctor --fix` 可将其重写为规范的 `ollama-windows:default` API-key 配置文件并保留备份。该文件中的 `baseUrl` 是兼容性噪音，应移入提供商配置。

内存嵌入作用域

当 Ollama 用于内存嵌入时，承载认证作用于声明时所在的主机：

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

快速开始 ​

选择首选设置方法和模式。

向导配置（推荐）

**适用场景：** 最快路径配置 Ollama 云端或本地。

运行 onboard

    ```bash
    openclaw onboard
    ```

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

选择模式

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

选择一个模型

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

验证模型可用

    ```bash
    openclaw models list --provider ollama
    ```



### 非交互模式

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

可选指定自定义 base URL 或模型：

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

手动配置

**适用场景：** 完全控制云端或本地设置。

选择云端或本地

    - **Cloud + Local**：安装 Ollama，使用 `ollama signin` 登录，通过该主机路由云端请求
    - **Cloud only**：使用 `https://ollama.com` 配合 `OLLAMA_API_KEY`
    - **Local only**：从 [ollama.com/download](https://ollama.com/download) 安装 Ollama

拉取本地模型（仅本地模式）

    ```bash
    ollama pull gemma4
    # 或
    ollama pull gpt-oss:20b
    # 或
    ollama pull llama3.3
    ```

为 OpenClaw 启用 Ollama

    对于 `Cloud only`，使用真实的 `OLLAMA_API_KEY`。对于基于主机的设置，任意占位值均可：

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

    # Local-only
    export OLLAMA_API_KEY="ollama-local"

    # 或在配置文件中设置
    openclaw config set models.providers.ollama.apiKey "OLLAMA_API_KEY"
    ```

查看并设置模型

    ```bash
    openclaw models list
    openclaw models set ollama/gemma4
    ```

    或在配置中设置默认值：

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

云端模型 ​

Cloud + Local

`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`。

如果主机尚未登录，OpenClaw 会保持本地仅模式，直到你运行 `ollama signin`。

Cloud only

`Cloud only` 直接连接 Ollama 的托管 API：`https://ollama.com`。

在设置中使用 **Cloud only**。OpenClaw 会提示输入 `OLLAMA_API_KEY`，设置 `baseUrl: "https://ollama.com"`，并预填充托管云端模型列表。此路径**不**需要本地 Ollama 服务器或 `ollama signin`。

`openclaw onboard` 期间显示的云端模型列表从 `https://ollama.com/api/tags` 实时获取，上限 500 个条目，因此选择器反映当前托管目录而非静态种子。如果 `ollama.com` 在设置时不可达或返回空模型列表，OpenClaw 会回退到之前的硬编码建议，以便 onboarding 仍能完成。

Local only

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

OpenClaw 目前建议 `gemma4` 作为本地默认模型。

模型自动发现（隐式提供商） ​

当你设置 OLLAMA_API_KEY（或认证配置文件）且未定义 models.providers.ollama 或其他自定义远程提供商（带 api: "ollama"）时，OpenClaw 会从本地 Ollama 实例 http://127.0.0.1:11434 自动发现模型。

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

这样避免手动维护模型条目，同时保持目录与本地 Ollama 实例同步。你可以在本地 infer model run 中使用完整引用如 ollama/<pulled-model>:latest；OpenClaw 从 Ollama 的实时目录解析该已安装模型，无需手动编写 models.json 条目。

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

bash
# 查看可用模型
ollama list
openclaw models list

要做一个避免完整智能体工具面的窄文本生成冒烟测试，使用 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 已配置的提供商、认证和原生 Ollama 传输，但不会启动聊天智能体回合或加载 MCP/工具上下文。如果此路径成功而正常智能体回复失败，接下来排查模型的智能体提示/工具能力。

要做一个兼容像模型的窄视觉模型冒烟测试，在 infer model run 中添加一个或多个图像文件。这会直接将提示和图像发送给所选 Ollama 视觉模型，不加载聊天工具、记忆或先前会话上下文：

bash
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 作业不会全部启动失败的模型请求。

使用以下命令实时验证本地文本路径、原生流路径和嵌入：

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

新模型会被自动发现并立即可用。

INFO

如果你显式设置了 models.providers.ollama，或配置了自定义远程提供商（如 models.providers.ollama-cloud 并带有 api: "ollama"），自动发现会被跳过，必须手动定义模型。回环自定义提供商（如 http://127.0.0.2:11434）仍被视为本地。参见下面的显式配置部分。

视觉与图像描述 ​

内置的 Ollama 插件将 Ollama 注册为支持图像的媒体理解提供商。这让 OpenClaw 能够将显式的图像描述请求和配置的图像模型默认值路由到本地或托管的 Ollama 视觉模型。

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

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

然后用 infer CLI 验证：

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

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

使用 infer image describe 当你想要 OpenClaw 的图像理解提供商流程、配置的 agents.defaults.imageModel 和图像描述输出格式。使用 infer model run --file 当你想要一个带有自定义提示和一个或多个图像的原始多模态模型探测。

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

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

优先使用完整的 ollama/&lt;model&gt; 引用。如果同一模型在 models.providers.ollama.models 中列出，带有 input: ["text", "image"]，并且没有其他已配置的图像提供商暴露该裸模型 ID，那么 OpenClaw 也会将裸 imageModel 引用（如 qwen2.5vl:7b）规范化为 ollama/qwen2.5vl:7b。如果多个已配置的图像提供商具有相同的裸 ID，请显式使用提供商前缀。

较慢的本地视觉模型可能需要比云端模型更长的图像理解超时。当 Ollama 试图在受限硬件上分配全部广告的视觉上下文时，它们也可能崩溃或停止。设置能力超时，并在模型条目上限制 num_ctx，当你只需要一个正常的图像描述回合时：

json5
{
  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.timeoutSeconds 仍控制底层 Ollama HTTP 请求保护。

使用以下命令实时验证显式图像工具：

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

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

OpenClaw 会拒绝未标记为图像能力的模型的图像描述请求。使用隐式发现时，OpenClaw 从 Ollama 的 /api/show 读取此信息。

配置 ​

基础（隐式发现）

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

```bash
export OLLAMA_API_KEY="ollama-local"
```

TIP

如果设置了 `OLLAMA_API_KEY`，可以在提供商条目中省略 `apiKey`，OpenClaw 会填充它以进行可用性检查。

显式（手动模型）

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

```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"],
            cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
            contextWindow: 128000,
            maxTokens: 8192
          }
        ]
      }
    }
  }
}
```

自定义 Base URL

如果 Ollama 运行在不同的主机或端口（显式配置会禁用自动发现，需手动定义模型）：

```json5
{
  models: {
    providers: {
      ollama: {
        apiKey: "ollama-local",
        baseUrl: "http://ollama-host:11434", // 不要加 /v1 - 使用 Ollama 原生 API URL
        api: "ollama", // 显式设置以保证原生工具调用行为
        timeoutSeconds: 300, // 可选：给冷启动本地模型更长的连接和流式时间
        models: [
          {
            id: "qwen3:32b",
            name: "qwen3:32b",
            params: {
              keep_alive: "15m", // 可选：在回合之间保持模型加载
            },
          },
        ],
      },
    },
  },
}
```

WARNING

不要在 URL 后加 `/v1`。`/v1` 路径使用 OpenAI 兼容模式，工具调用不可靠。请使用不带路径后缀的 Ollama base URL。

常用配置示例 ​

以下示例可作为起点，将模型 ID 替换为 ollama list 或 openclaw models list --provider ollama 中的确切名称。

本地模型自动发现

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

```bash
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 URL。不要添加 `/v1`。

```json5
{
  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" },
    },
  },
}
```

`contextWindow` 是 OpenClaw 端的上下文预算。`params.num_ctx` 会发送给 Ollama。当硬件无法运行模型的完整广告上下文时，请保持两者一致。

Ollama Cloud only

当你没有运行本地守护进程，想直接使用托管 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" },
    },
  },
}
```

云端 + 本地通过已登录守护进程

当本地或局域网 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"],
      },
    },
  },
}
```

多个 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 发送请求时，活动提供商前缀会被剥离，因此 `ollama-large/qwen3.5:27b` 到达 Ollama 时为 `qwen3.5:27b`。

精简本地模型配置

有些本地模型能回答简单提示，但难以处理完整的智能体工具面。先从限制工具和上下文开始，再更改全局运行时设置。

```json5
{
  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`。这会以牺牲智能体能力换取稳定性。`localModelLean` 会从智能体面中移除浏览器、cron 和消息工具，但不会改变 Ollama 的运行时上下文或思考模式。对于循环或将其回复预算花在隐藏推理上的小 Qwen 风格思考模型，配合显式的 `params.num_ctx` 和 `params.thinking: false` 使用。

模型选择 ​

配置完成后，所有 Ollama 模型即可使用：

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

自定义 Ollama 提供商 ID 也支持。当模型引用使用活动提供商前缀（如 ollama-spark/qwen3:32b）时，OpenClaw 在调用 Ollama 之前只剥离该前缀，因此服务器收到 qwen3:32b。

对于较慢的本地模型，优先使用提供商级别的请求调优，而不是提高整个智能体运行时超时：

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

timeoutSeconds 适用于模型 HTTP 请求，包括连接建立、请求头、体流式传输和总受保护获取中止。params.keep_alive 作为顶层的 keep_alive 转发到原生 /api/chat 请求；当首回合加载时间是瓶颈时，为每个模型设置。

快速验证 ​

bash
# 确认 Ollama 守护进程对此机器可见
curl http://127.0.0.1:11434/api/tags

# OpenClaw 目录和所选模型
openclaw models list --provider ollama
openclaw models status

# 直接模型冒烟
openclaw infer model run \
  --model ollama/gemma4 \
  --prompt "Reply with exactly: ok"

对于远程主机，将 127.0.0.1 替换为 baseUrl 中使用的主机。如果 curl 成功但 OpenClaw 失败，检查 Gateway 是否运行在不同的机器、容器或服务账户上。

OpenClaw 支持将 Ollama Web Search 作为内置的 web_search 提供商。

属性详情
主机使用已配置的 Ollama 主机（设置了 models.providers.ollama.baseUrl 时使用该值，否则使用 http://127.0.0.1:11434）；https://ollama.com 直接使用托管 API
认证已登录的本地 Ollama 主机无需密钥；OLLAMA_API_KEY 或已配置的提供商认证适用于直接 https://ollama.com 搜索或需要认证的主机
要求本地/自托管主机必须运行并使用 ollama signin 登录；直接托管搜索需要 baseUrl: "https://ollama.com" 和真实的 Ollama API 密钥

在 openclaw onboard 或 openclaw configure --section web 中选择 Ollama Web Search，或者设置：

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

通过 Ollama Cloud 直接托管搜索：

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", input: ["text"] }],
      },
    },
  },
  tools: {
    web: {
      search: { provider: "ollama" },
    },
  },
}

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

INFO

有关完整设置和行为详情，请参见 Ollama Web Search。

高级配置 ​

旧版 OpenAI 兼容模式

WARNING

**工具调用在 OpenAI 兼容模式下不可靠。** 仅在需要 OpenAI 格式的代理且不依赖原生工具调用时使用此模式。

如果需要使用 OpenAI 兼容端点（例如，背后的代理只支持 OpenAI 格式），显式设置 `api: "openai-completions"`：

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

此模式可能不支持流式输出和工具调用同时使用。可能需要在模型配置中禁用流式：`params: { streaming: false }`。

当 `api: "openai-completions"` 与 Ollama 配合使用时，OpenClaw 默认注入 `options.num_ctx`，防止 Ollama 悄悄退回到 4096 上下文窗口。如果你的代理/上游拒绝未知的 `options` 字段，可关闭此行为：

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

上下文窗口

对于自动发现的模型，OpenClaw 使用 Ollama 报告的上下文窗口（如有），包括来自自定义 Modelfiles 的 `PARAMETER num_ctx` 值。否则退回到 OpenClaw 使用的 Ollama 默认上下文窗口。

你可以在提供商级别设置 `contextWindow`、`contextTokens` 和 `maxTokens` 默认值，应用于该 Ollama 提供商下的每个模型，然后在需要时覆盖每个模型。`contextWindow` 是 OpenClaw 的提示和压缩预算。原生 Ollama 请求不会设置 `options.num_ctx`，除非你显式配置了 `params.num_ctx`，因此 Ollama 可以应用其自己的模型、`OLLAMA_CONTEXT_LENGTH` 或基于 VRAM 的默认值。要限制或强制 Ollama 的每个请求运行时上下文而不重建 Modelfile，设置 `params.num_ctx`；无效、零、负和非有限值会被忽略。如果你升级了旧配置，该配置仅使用 `contextWindow` 或 `maxTokens` 来强制 Ollama 请求上下文，运行 `openclaw doctor --fix` 以将显式的提供商或模型预算复制到 `params.num_ctx`。OpenAI 兼容的 Ollama 适配器仍默认从配置的 `params.num_ctx` 或 `contextWindow` 注入 `options.num_ctx`；如果您的上游拒绝了 `options`，请使用 `injectNumCtxForOpenAICompat: false` 禁用它。

原生 Ollama 模型条目也接受常见的 Ollama 运行时选项，放在 `params` 中，包括 `temperature`、`top_p`、`top_k`、`min_p`、`num_predict`、`stop`、`repeat_penalty`、`num_batch`、`num_thread` 和 `use_mmap`。OpenClaw 只转发 Ollama 请求键，因此 OpenClaw 运行时参数（如 `streaming`）不会泄漏给 Ollama。使用 `params.think` 或 `params.thinking` 发送顶层的 Ollama `think`；`false` 禁用 API 级别的思考（适用于 Qwen 风格思考模型）。

```json5
{
  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/&lt;model&gt;"].params.num_ctx` 也有效。如果两者都配置了，显式的提供商模型条目优先于智能体默认值。

思考控制

对于原生 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` 可以为特定配置的模型禁用或强制 Ollama API 思考。OpenClaw 在活动运行仅有隐式默认 `off` 时保留这些显式模型参数；非关闭运行时命令（如 `/think medium` 仍会覆盖活动运行。

推理模型

OpenClaw 默认将名称中包含 `deepseek-r1`、`reasoning` 或 `think` 的模型标记为具有推理能力。

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

无需额外配置。OpenClaw 会自动标记它们。

模型费用

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

内存嵌入

内置的 Ollama 插件注册了一个用于[内存搜索](/ai/ai-tools/openclaw/concepts/memory)的内存嵌入提供商。它使用已配置的 Ollama base URL 和 API 密钥，调用 Ollama 当前的 `/api/embed` 端点，并尽可能将多个内存块批处理到一个 `input` 请求中。

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

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

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

```json5
{
  agents: {
    defaults: {
      memorySearch: {
        provider: "ollama",
        remote: {
          // Ollama 的默认值。如果重新索引太慢，可在更大主机上提高。
          nonBatchConcurrency: 1,
        },
      },
    },
  },
}
```

对于远程嵌入主机，将认证作用域限于该主机：

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

流式配置

OpenClaw 的 Ollama 集成默认使用**原生 Ollama API**（`/api/chat`），完整支持流式输出和工具调用同时使用，无需特殊配置。

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

TIP

如果需要使用 OpenAI 兼容端点，请参见上面的“旧版 OpenAI 兼容模式”部分。在该模式下，流式输出和工具调用可能无法同时工作。

故障排查 ​

WSL2 崩溃循环（反复重启）

在 WSL2 上安装 NVIDIA/CUDA 时，官方 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 在检测到 WSL2、`ollama.service` 已启用且 `Restart=always`、并且有可见 CUDA 标记时，会记录启动警告。

缓解措施：

```bash
sudo systemctl disable ollama
```

在 Windows 侧的 `%USERPROFILE%\.wslconfig` 中添加如下内容，然后运行 `wsl --shutdown`：

```ini
[experimental]
autoMemoryReclaim=disabled
```

在 Ollama 服务环境中设置较短的 keep-alive，或仅在需要时手动启动 Ollama：

```bash
export OLLAMA_KEEP_ALIVE=5m
ollama serve
```

参考 [ollama/ollama#11317](https://github.com/ollama/ollama/issues/11317)。

Ollama 未被检测到

确认 Ollama 正在运行、已设置 `OLLAMA_API_KEY`（或认证配置文件），且**未**定义显式的 `models.providers.ollama` 条目：

```bash
ollama serve
```

同时确认 API 可访问：

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

没有可用模型

如果模型未显示在列表中，要么本地拉取该模型，要么在 `models.providers.ollama` 中显式定义。

```bash
ollama list  # 查看已安装的模型
ollama pull gemma4
ollama pull gpt-oss:20b
ollama pull llama3.3     # 或其他模型
```

连接被拒绝

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

```bash
# 检查 Ollama 是否在运行
ps aux | grep ollama

# 或重启 Ollama
ollama serve
```

远程主机 curl 成功但 OpenClaw 失败

从运行 Gateway 的同一台机器和运行时环境验证：

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

常见原因：

- `baseUrl` 指向 `localhost`，但 Gateway 运行在 Docker 或另一台主机上。
- URL 使用了 `/v1`，这会导致 OpenAI 兼容行为而非原生 Ollama。
- 远程主机需要在 Ollama 侧更改防火墙或 LAN 绑定。
- 模型存在于你笔记本电脑的守护进程中，但不在远程守护进程上。

模型输出工具 JSON 文本

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

优先使用原生 Ollama 模式：

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

如果小型本地模型仍在工具模式上失败，在该模型条目上设置 `compat.supportsTools: false` 并重新测试。

Kimi 或 GLM 返回乱码符号

托管的 Kimi/GLM 响应如果是长串非语言符号，会被视为失败提供商输出而不是成功的助手回答。这允许正常重试、回退或错误处理接管，而不会将损坏的文本持久化到会话中。

如果反复出现，捕获原始模型名称、当前会话文件，以及运行使用的是 `Cloud + Local` 还是 `Cloud only`，然后尝试新会话和回退模型：

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

冷启动本地模型超时

大型本地模型可能需要较长的首次加载时间才能开始流式传输。将超时限制在 Ollama 提供商级别，并可选择要求 Ollama 在回合之间保持模型加载：

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

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

大上下文模型太慢或内存不足

许多 Ollama 模型宣传的上下文大于硬件所能舒适运行的范围。默认情况下，原生 Ollama 使用 Ollama 自己的运行时上下文默认值，除非你设置 `params.num_ctx`。当你想获得可预测的首字符延迟时，同时限制 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`。如果 Ollama 加载的运行时上下文对机器来说太大，降低 `params.num_ctx`。如果生成时间太长，降低 `maxTokens`。

INFO

更多帮助：故障排查 和 FAQ。

常见问题 ​

OpenClaw 检测不到 Ollama 怎么办？ ​

确保 Ollama 在运行（ollama serve），并且设置了环境变量 OLLAMA_API_KEY（例如 export OLLAMA_API_KEY="ollama-local"）。确认未在配置中手动定义 models.providers.ollama 块，否则自动发现会被跳过。然后用 curl http://localhost:11434/api/tags 测试 API 是否可达。

Ollama 模型输出工具 JSON 文本，如何解决？ ​

这通常是因为使用了 OpenAI 兼容的 /v1 路径，或者模型不支持工具模式。确保 baseUrl 不含 /v1，并且显式设置 api: "ollama"。如果问题依旧，在小模型上可以设置 compat.supportsTools: false 来禁用工具调用，牺牲部分能力换取稳定性。

WSL2 环境出现反复崩溃重启怎么处理？ ​

这是 Ollama 在 WSL2 上的已知问题：使用 Restart=always 的 systemd 服务与 Hyper-V 内存回收冲突导致循环。建议运行 sudo systemctl disable ollama 禁用自动启动，并在 Windows 的 %USERPROFILE%\.wslconfig 中添加 [experimental] autoMemoryReclaim=disabled，然后 wsl --shutdown 重启。平时可手动启动 ollama serve。

友情链接： 能跑吗 · 打工算 · 车主算 · 开发工具 · 人工不智能

Copyright © 2026 古法编程 | 蜀ICP备2021007188号 | 关于本站 | 隐私政策