Ollama

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

远程 Ollama 用户：不要将 /v1 OpenAI 兼容 URL（http://host:11434/v1）与 OpenClaw 一起使用。这会破坏工具调用，模型可能会将原始工具 JSON 输出为纯文本。请改用原生 Ollama API URL：baseUrl: "http://host:11434"（不带 /v1）。

快速开始

安装 Ollama：https://ollama.ai
拉取模型：

ollama pull gpt-oss:20b
# 或
ollama pull llama3.3
# 或
ollama pull qwen2.5-coder:32b
# 或
ollama pull deepseek-r1:32b

为 OpenClaw 启用 Ollama（任何值都可以；Ollama 不需要真实的密钥）：

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

# 或在配置文件中配置
openclaw config set models.providers.ollama.apiKey "ollama-local"

使用 Ollama 模型：

{
  agents: {
    defaults: {
      model: { primary: "ollama/gpt-oss:20b" },
    },
  },
}

模型发现（隐式提供者）

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

查询 /api/tags 和 /api/show
仅保留报告 tools 能力的模型
当模型报告 thinking 时标记 reasoning
从 model_info["<arch>.context_length"] 读取 contextWindow（如果可用）
将 maxTokens 设置为上下文窗口的 10 倍
将所有成本设置为 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 会填充它以进行可用性检查。

自定义基础 URL（显式配置）

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

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

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

模型选择

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

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

高级

推理模型

当 Ollama 在 /api/show 中报告 thinking 时，OpenClaw 会将模型标记为支持推理：

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 } 禁用流式传输。

当 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: [...]
      }
    }
  }
}

上下文窗口

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

故障排除

未检测到 Ollama

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

ollama serve

并确保 API 可访问：

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

没有可用模型

OpenClaw 仅自动发现报告工具支持的模型。如果你的模型未列出，要么：

拉取支持工具的模型，或
在 models.providers.ollama 中显式定义模型。

添加模型：

ollama list  # 查看已安装的内容
ollama pull gpt-oss:20b  # 拉取支持工具的模型
ollama pull llama3.3     # 或其他模型

连接被拒绝

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

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

# 或重启 Ollama
ollama serve

另请参阅

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