古法编程

Appearance

Ollama ​

Ollama 是一个本地 LLM 运行时，可以轻松在自己的机器上运行开源模型。OpenClaw 集成了 Ollama 的原生 API（/api/chat），支持流式输出和工具调用，并且在设置了 OLLAMA_API_KEY（或 auth profile）且未手动定义 models.providers.ollama 时，会自动发现本地 Ollama 模型。

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

快速开始 ​

向导配置（推荐） ​

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

bash
openclaw onboard

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

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

也支持非交互模式：

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

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

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

手动配置 ​

  1. 安装 Ollama：https://ollama.com/download

  2. 如果需要本地推理，先拉取模型：

bash
ollama pull glm-4.7-flash
# 或
ollama pull gpt-oss:20b
# 或
ollama pull llama3.3
  1. 如果还想使用云端模型，先登录：
bash
ollama signin
  1. 运行 onboard 并选择 Ollama：
bash
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
  1. 如果倾向手动配置，直接为 OpenClaw 启用 Ollama（任意值均可，Ollama 不需要真实 Key）：
bash
# 设置环境变量
export OLLAMA_API_KEY="ollama-local"

# 或在配置文件中设置
openclaw config set models.providers.ollama.apiKey "ollama-local"
  1. 查看或切换模型：
bash
openclaw models list
openclaw models set ollama/glm-4.7-flash
  1. 或在配置中设置默认值：
json5
{
  agents: {
    defaults: {
      model: { primary: "ollama/glm-4.7-flash" },
    },
  },
}

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

设置 OLLAMA_API_KEY（或 auth profile）且未定义 models.providers.ollama 时，OpenClaw 会从 http://127.0.0.1:11434 自动发现模型：

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

这样无需手动维护模型条目，目录也能随本地 Ollama 实例保持同步。

查看可用模型：

bash
ollama list
openclaw models list

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

bash
ollama pull mistral

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

注意：如果显式设置了 models.providers.ollama，自动发现会被跳过，必须手动定义模型（见下文）。

配置 ​

基础配置（隐式发现） ​

最简单的方式是通过环境变量启用 Ollama：

bash
export OLLAMA_API_KEY="ollama-local"

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

以下场景建议使用显式配置：

  • Ollama 运行在其他主机/端口
  • 需要强制指定上下文窗口或模型列表
  • 需要完全手动定义模型
json5
{
  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 会自动填充用于可用性检查。

自定义 Base URL（显式配置） ​

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

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

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

模型选择 ​

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

json5
{
  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 的模型视为具有推理能力：

bash
ollama pull deepseek-r1:32b

模型费用 ​

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

流式配置 ​

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

旧版 OpenAI 兼容模式 ​

工具调用在 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 报告的上下文窗口（如有），否则退回到 OpenClaw 的 Ollama 默认值。你可以在显式提供商配置中覆盖 contextWindow 和 maxTokens。

故障排查 ​

Ollama 未被检测到 ​

确认 Ollama 正在运行、已设置 OLLAMA_API_KEY（或 auth profile），且未定义显式的 models.providers.ollama 条目：

bash
ollama serve

同时确认 API 可访问：

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

没有可用模型 ​

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

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

连接被拒绝 ​

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

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

# 或重启 Ollama
ollama serve

另请参阅 ​

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

Copyright © 2026 地豆 蜀ICP备2021007188号 | 关于本站 | 隐私政策