Ollama

Ollama 是一个本地 LLM 运行时，让你可以轻松在自己的机器上跑开源模型。OpenClaw 通过 Ollama 的原生 API（/api/chat）集成，支持流式输出和工具调用，还能在你设置了 OLLAMA_API_KEY（或认证配置）且没有显式定义 models.providers.ollama 的情况下自动发现本地模型。

注意： 远程 Ollama 用户：不要在 OpenClaw 中使用 /v1 OpenAI 兼容地址（http://host:11434/v1），这会导致工具调用失效，模型可能会把工具 JSON 当纯文本输出。请使用 Ollama 原生 API 地址：baseUrl: "http://host:11434"（不带 /v1）。

快速开始

引导向导（推荐）

最快的方式是通过引导向导来配置 Ollama：

openclaw onboard

从提供商列表中选择 Ollama。向导会：

询问你的 Ollama 实例地址（默认 http://127.0.0.1:11434）。
让你选择 Cloud + Local（云端 + 本地模型）或 Local（仅本地模型）。
如果选了 Cloud + Local 且尚未登录 ollama.com，会打开浏览器完成登录。
自动发现可用模型并推荐默认设置。
如果选中的模型在本地不存在，自动拉取。

也支持非交互模式：

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

可以指定自定义地址或模型：

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

手动配置

安装 Ollama：https://ollama.com/download
如果需要本地推理，先拉取模型：

ollama pull glm-4.7-flash
# 或者
ollama pull gpt-oss:20b
# 或者
ollama pull llama3.3

如果还想用云端模型，先登录：

ollama signin

运行引导向导，选择 Ollama：

openclaw onboard

Local：仅本地模型
Cloud + Local：本地模型 + 云端模型
云端模型如 kimi-k2.5:cloud、minimax-m2.5:cloud、glm-5:cloud 不需要 本地 ollama pull

OpenClaw 目前推荐的默认模型：

本地默认：glm-4.7-flash
云端默认：kimi-k2.5:cloud、minimax-m2.5:cloud、glm-5:cloud

如果你更喜欢手动配置，可以直接为 OpenClaw 启用 Ollama（填什么值都行，Ollama 不需要真正的密钥）：

# 设置环境变量
export OLLAMA_API_KEY="ollama-local"

# 或者写到配置文件
openclaw config set models.providers.ollama.apiKey "ollama-local"

查看或切换模型：

openclaw models list
openclaw models set ollama/glm-4.7-flash

或者在配置文件中设置默认模型：

{
  agents: {
    defaults: {
      model: { primary: "ollama/glm-4.7-flash" },
    },
  },
}

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

当你设置了 OLLAMA_API_KEY（或认证配置）且没有定义 models.providers.ollama 时，OpenClaw 会从本地 Ollama 实例 http://127.0.0.1:11434 自动发现模型：

查询 /api/tags
尽力通过 /api/show 读取 contextWindow
用模型名称启发式（r1、reasoning、think）标记 reasoning 能力
将 maxTokens 设为 OpenClaw 使用的默认 Ollama 最大 token 上限
所有费用设为 0

这样就不用手动写模型配置，目录会自动跟本地 Ollama 实例保持同步。

查看可用模型：

ollama list
openclaw models list

要添加新模型，直接用 Ollama 拉取即可：

ollama pull mistral

新模型会被自动发现并可以使用。

如果你显式设置了 models.providers.ollama，自动发现会被跳过，需要手动定义模型（见下文）。

配置

基本配置（隐式发现）

启用 Ollama 最简单的方式是设置环境变量：

export OLLAMA_API_KEY="ollama-local"

显式配置（手动定义模型）

以下场景适合用显式配置：

Ollama 运行在其他主机或端口。
你想手动指定上下文窗口或模型列表。
你需要完全手动定义模型。

{
  models: {
    providers: {
      ollama: {
        baseUrl: "http://ollama-host:11434",
        apiKey: "ollama-local",
        api: "ollama",
        models: [
          {
            id: "gpt-oss:20b",
            name: "GPT-OSS 20B",
            reasoning: false,
            input: ["text"],
            cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
            contextWindow: 8192,
            maxTokens: 8192 * 10
          }
        ]
      }
    }
  }
}

如果已经设置了 OLLAMA_API_KEY，提供商配置中可以省略 apiKey，OpenClaw 会自动补充用于可用性检查。

自定义地址（显式配置）

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

{
  models: {
    providers: {
      ollama: {
        apiKey: "ollama-local",
        baseUrl: "http://ollama-host:11434", // 不要加 /v1，使用原生 Ollama API 地址
        api: "ollama", // 显式设置，确保使用原生工具调用行为
      },
    },
  },
}

注意： 地址不要加 /v1。/v1 路径走的是 OpenAI 兼容模式，工具调用不可靠。请使用不带路径后缀的 Ollama 基础地址。

模型选择

配置完成后，所有 Ollama 模型都可以使用了：

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

云端模型

云端模型让你可以把云端托管的模型（比如 kimi-k2.5:cloud、minimax-m2.5:cloud、glm-5:cloud）和本地模型一起用。

要使用云端模型，在引导向导中选择 Cloud + Local 模式。向导会检查是否已登录，需要时会打开浏览器登录。如果无法验证认证，向导会回退到仅本地模型的默认配置。

你也可以直接在 ollama.com/signin 登录。

进阶

推理模型

OpenClaw 默认会将名称包含 deepseek-r1、reasoning 或 think 的模型视为支持推理：

ollama pull deepseek-r1:32b

模型费用

Ollama 免费且在本地运行，所有模型费用都设为 $0。

流式配置

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

旧版 OpenAI 兼容模式

注意： OpenAI 兼容模式下工具调用不可靠。 只有当你需要 OpenAI 格式给代理用、且不依赖原生工具调用时，才考虑使用这个模式。

如果确实需要 OpenAI 兼容端点（比如后面有个只支持 OpenAI 格式的代理），显式设置 api: "openai-completions"：

{
  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 字段，可以关闭这个行为：

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

上下文窗口

对于自动发现的模型，OpenClaw 会使用 Ollama 报告的上下文窗口大小（如果有的话），否则回退到 OpenClaw 使用的默认 Ollama 上下文窗口值。你也可以在显式提供商配置中覆盖 contextWindow 和 maxTokens。

常见问题排查

没检测到 Ollama

确保 Ollama 正在运行、设置了 OLLAMA_API_KEY（或认证配置），并且没有显式定义 models.providers.ollama：

ollama serve

检查 API 是否可访问：

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

没有可用模型

如果你的模型没有出现在列表中，可以：

在本地拉取模型，或
在 models.providers.ollama 中显式定义模型。

添加模型：

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

连接被拒绝

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

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

# 或重启 Ollama
ollama serve

参阅

模型提供商 - 所有提供商概览
模型选择 - 如何选择模型
配置 - 完整配置参考