Skip to content
Clawd中文手册

Ollama

Ollama 是一个本地 LLM 运行时，可以让你轻松在自己的机器上运行开源模型。OpenClaw 集成了 Ollama 的原生 API（/api/chat），支持流式传输和工具调用，并且在你选择使用 OLLAMA_API_KEY（或凭证配置文件）且未定义显式 models.providers.ollama 条目时，可以自动发现本地 Ollama 模型。

快速开始

Section titled “快速开始”

新手引导向导（推荐）

Section titled “新手引导向导（推荐）”

通过设置向导配置 Ollama 是最快的方法：

Terminal window
openclaw onboard

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

  1. 询问你的 Ollama base URL，也就是可以访问你的实例的地址（默认 http://127.0.0.1:11434）。
  2. 让你选择 Cloud + Local（云端模型和本地模型）或 Local（仅本地模型）。
  3. 如果你选择 Cloud + Local 且尚未登录 ollama.com，则打开浏览器登录流程。
  4. 发现可用模型并建议默认值。
  5. 如果所选模型本地不可用，则自动拉取它。

也支持非交互模式：

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

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

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

手动设置

Section titled “手动设置”

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

  2. 如果你想进行本地推理，先拉取一个本地模型：

Terminal window
ollama pull glm-4.7-flash
# 或
ollama pull gpt-oss:20b
# 或
ollama pull llama3.3
  1. 如果你也想使用云端模型，请先登录：
Terminal window
ollama signin
  1. 运行新手引导并选择 Ollama：
Terminal window
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）：
Terminal window
# 设置环境变量
export OLLAMA_API_KEY="ollama-local"


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

模型发现（隐式提供商）

Section titled “模型发现（隐式提供商）”

当你设置 OLLAMA_API_KEY（或凭证配置文件），并且未定义 models.providers.ollama 时，OpenClaw 会从 http://127.0.0.1:11434 上的本地 Ollama 实例发现模型：

  • 查询 /api/tags
  • 在可用时，尽力通过 /api/show 查找 contextWindow
  • 通过模型名称启发式规则标记 reasoning（r1、reasoning、think）
  • 将 maxTokens 设置为 OpenClaw 使用的默认 Ollama 最大 token 上限
  • 将所有成本设置为 0

这样无需手动维护模型条目，同时又能让目录与本地 Ollama 实例保持一致。

查看有哪些可用模型：

Terminal window
ollama list
openclaw models list

添加新模型时，只需通过 Ollama 拉取它：

Terminal window
ollama pull mistral

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

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

配置

Section titled “配置”

基本设置（隐式发现）

Section titled “基本设置（隐式发现）”

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

Terminal window
export OLLAMA_API_KEY="ollama-local"

显式设置（手动模型）

Section titled “显式设置（手动模型）”

以下情况适合使用显式配置：

  • 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 会在可用性检查时自动填充它。

自定义 base URL（显式配置）

Section titled “自定义 base URL（显式配置）”

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

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

模型选择

Section titled “模型选择”

配置完成后，你的所有 Ollama 模型都可用：

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

云端模型

Section titled “云端模型”

云端模型让你可以将云托管模型（例如 kimi-k2.5:cloud、minimax-m2.5:cloud、glm-5:cloud）与本地模型一起使用。

要使用云端模型，请在设置期间选择 Cloud + Local 模式。向导会检查你是否已登录，并在需要时打开浏览器登录流程。如果无法验证认证状态，向导会回退到本地模型默认值。

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

高级用法

Section titled “高级用法”

推理模型

Section titled “推理模型”

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

Terminal window
ollama pull deepseek-r1:32b

模型成本

Section titled “模型成本”

Ollama 是免费的，并且在本地运行，因此所有模型成本都设置为 $0。

流式传输配置

Section titled “流式传输配置”

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

旧版 OpenAI 兼容模式

Section titled “旧版 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 } 禁用流式传输。

当 Ollama 使用 api: "openai-completions" 时，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: [...]
      }
    }
  }
}

上下文窗口

Section titled “上下文窗口”

对于自动发现的模型，OpenClaw 会在 Ollama 提供时使用其报告的上下文窗口，否则回退到 OpenClaw 使用的默认 Ollama 上下文窗口。你可以在显式提供商配置中覆盖 contextWindow 和 maxTokens。

故障排除

Section titled “故障排除”

未检测到 Ollama

Section titled “未检测到 Ollama”

请确认 Ollama 正在运行，并且你已设置 OLLAMA_API_KEY（或凭证配置文件），而且没有定义显式的 models.providers.ollama 条目：

Terminal window
ollama serve

并确认 API 可访问：

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

没有可用模型

Section titled “没有可用模型”

如果没有列出你的模型，可以：

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

添加模型：

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

连接被拒绝

Section titled “连接被拒绝”

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

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


# 或重启 Ollama
ollama serve

另请参阅

Section titled “另请参阅”