Ollama

Ollama 是一个本地 LLM 运行时，能够让您轻松在本机运行开源模型。OpenClaw 与 Ollama 的原生 API (/api/chat) 深度集成，支持流式输出和工具调用，并且可以自动发现支持工具调用的模型。

远程 Ollama 用户注意： 不要使用带有 /v1 的 OpenAI 兼容 URL（例如 http://host:11434/v1）。这会导致工具调用失效，模型可能会以纯文本形式输出原始的工具 JSON。应使用 Ollama 的原生 API URL：baseUrl: "http://host:11434"（不要加 /v1）。

快速开始

安装 Ollama

访问 Ollama 官网下载并安装 Ollama。

brew install ollama

拉取模型

# GPT-OSS 20B（支持工具调用）
ollama pull gpt-oss:20b

# 或其他推荐模型
ollama pull llama3.3
ollama pull qwen2.5-coder:32b
ollama pull deepseek-r1:32b

启用 OpenClaw 的 Ollama

设置任意值作为 API 密钥（Ollama 不需要真实密钥）：

export OLLAMA_API_KEY="ollama-local"

使用 Ollama 模型

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

模型自动发现

OpenClaw 提供智能的模型自动发现功能，无需手动配置模型列表。

工作原理

当您设置了 OLLAMA_API_KEY（或认证配置），且没有定义 models.providers.ollama 时，OpenClaw 会：

连接到本地 Ollama 实例（默认 http://127.0.0.1:11434）
请求 /api/tags 和 /api/show 获取模型信息
仅保留报告支持 tools 功能的模型
如果模型报告了 thinking，则标记为 reasoning
从 model_info["<arch>.context_length"] 读取 contextWindow
将 maxTokens 设置为上下文窗口的 10 倍
所有费用均设为 0（本地运行免费）

这样避免了手动维护模型条目，同时目录与 Ollama 的实际能力保持一致。

查看可用模型

ollama list

添加新模型

只需使用 Ollama 拉取模型，OpenClaw 会自动发现：

# 拉取新模型
ollama pull mistral

# 自动发现并可用
openclaw models list | grep mistral

如果您显式设置了 models.providers.ollama，自动发现将被跳过，您必须手动定义模型。

配置方式

隐式发现（推荐）
显式配置
远程 Ollama

基础设置（自动发现）

最简单的配置方式，适合大多数用户：

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

配置文件：

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

OpenClaw 会自动：

发现本地 Ollama 实例
列出所有支持工具调用的模型
配置正确的上下文窗口和参数

显式设置（手动定义）

适用于以下场景：

Ollama 运行在不同的主机或端口
需要强制指定上下文窗口或模型列表
想包含未报告工具支持的模型

{
  "agents": {
    "defaults": {
      "model": {
        "primary": "ollama/gpt-oss:20b"
      }
    }
  },
  "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": 81920
          }
        ]
      }
    }
  }
}

显式配置会禁用自动发现，需要手动维护模型列表。

自定义基础 URL

如果 Ollama 运行在其他主机或端口：

{
  "models": {
    "providers": {
      "ollama": {
        "apiKey": "ollama-local",
        "baseUrl": "http://ollama-host:11434",
        "api": "ollama",
        "models": [
          {
            "id": "llama3.3",
            "name": "Llama 3.3"
          }
        ]
      }
    }
  }
}

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

GPT-OSS 20B

高质量开源模型，支持工具调用

ollama pull gpt-oss:20b

Llama 3.3

Meta 最新开源模型

ollama pull llama3.3

Qwen 2.5 Coder

专为编码优化的模型

ollama pull qwen2.5-coder:32b

Mistral

快速且强大的通用模型

ollama pull mistral

推理模型

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

# DeepSeek R1 推理模型
ollama pull deepseek-r1:32b

{
  "agents": {
    "defaults": {
      "model": {
        "primary": "ollama/deepseek-r1:32b"
      }
    }
  }
}

高级配置

多模型故障切换

配置多个 Ollama 模型作为故障切换选项：

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

流式配置

OpenClaw 默认使用 Ollama 原生 API（/api/chat），完全支持流式输出和工具调用同时进行，无需额外配置。

OpenAI 兼容模式（不推荐）

OpenAI 兼容模式下，工具调用不可靠。 仅当您需要使用 OpenAI 格式代理且不依赖原生工具调用时使用本模式。

如果需要使用 OpenAI 兼容端点：

{
  "models": {
    "providers": {
      "ollama": {
        "baseUrl": "http://ollama-host:11434/v1",
        "api": "openai-completions",
        "injectNumCtxForOpenAICompat": true,
        "apiKey": "ollama-local",
        "models": [
          {
            "id": "llama3.3",
            "name": "Llama 3.3",
            "params": {
              "streaming": false
            }
          }
        ]
      }
    }
  }
}

此模式可能无法同时支持流式和工具调用。您可能需要通过 params: { streaming: false } 禁用流式输出。

num_ctx 注入

当使用 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"
      }
    }
  }
}

上下文窗口

对于自动发现的模型，OpenClaw 使用 Ollama 报告的上下文窗口（如有），否则默认 8192。显式配置时可覆盖 contextWindow 和 maxTokens：

{
  "models": {
    "providers": {
      "ollama": {
        "models": [
          {
            "id": "custom-model",
            "contextWindow": 32768,
            "maxTokens": 327680
          }
        ]
      }
    }
  }
}

故障排除

Ollama 未检测到

问题： OpenClaw 无法连接到 Ollama。 解决方案：

确认 Ollama 运行

# 启动 Ollama 服务
ollama serve

验证 API 可访问

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

设置环境变量

export OLLAMA_API_KEY="ollama-local"

确认未定义显式配置

检查配置文件中是否定义了 models.providers.ollama。如果有，移除它以启用自动发现。

没有可用模型

问题： OpenClaw 没有发现任何模型。 原因： OpenClaw 仅自动发现报告支持工具调用的模型。 解决方案：

拉取支持工具调用的模型
显式定义模型

# 推荐的工具调用模型
ollama pull gpt-oss:20b
ollama pull llama3.3
ollama pull qwen2.5-coder:32b

# 验证
ollama list
openclaw models list

如果您的模型不报告工具支持，可以在配置中显式定义：

{
  "models": {
    "providers": {
      "ollama": {
        "apiKey": "ollama-local",
        "api": "ollama",
        "models": [
          {
            "id": "your-model-name",
            "name": "Your Model"
          }
        ]
      }
    }
  }
}

连接被拒绝

问题： 无法连接到 Ollama API。 解决方案：

检查 Ollama 进程

ps aux | grep ollama

重启 Ollama

# 停止
killall ollama

# 启动
ollama serve

验证端口

# 检查端口 11434 是否监听
lsof -i :11434
# 或
netstat -an | grep 11434

检查防火墙

如果 Ollama 在远程主机，确保防火墙允许访问端口 11434。

工具调用失效

问题： 模型以纯文本输出 JSON，而不是调用工具。 原因： 使用了 OpenAI 兼容模式（/v1 路径）。 解决方案：

移除 URL 中的 /v1 后缀：

{
  "models": {
    "providers": {
      "ollama": {
        "baseUrl": "http://localhost:11434",
        "api": "ollama"
      }
    }
  }
}

或使用隐式发现（推荐）

上下文窗口太小

问题： 模型上下文窗口限制为 4096。 原因： Ollama 使用默认上下文窗口。 解决方案：

使用原生 API（推荐）
OpenAI 兼容模式

使用 Ollama 原生 API 会自动使用正确的上下文窗口：

{
  "models": {
    "providers": {
      "ollama": {
        "api": "ollama"
      }
    }
  }
}

如果必须使用 OpenAI 兼容模式，确保启用 injectNumCtxForOpenAICompat：

{
  "models": {
    "providers": {
      "ollama": {
        "api": "openai-completions",
        "injectNumCtxForOpenAICompat": true
      }
    }
  }
}

完整配置示例

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

性能优化

硬件要求

根据模型大小选择合适的硬件：

模型大小	最小 RAM	推荐 RAM	GPU
7B	8 GB	16 GB	可选
13B	16 GB	32 GB	推荐
20B+	32 GB	64 GB	推荐
70B+	64 GB	128 GB	必需

GPU 加速

Ollama 自动检测并使用可用的 GPU：

NVIDIA GPU: 自动使用 CUDA
Apple Silicon: 自动使用 Metal
AMD GPU: 自动使用 ROCm（Linux）

验证 GPU 使用：

# 运行模型时查看日志
ollama run gpt-oss:20b
# 应该显示 GPU 信息

并发请求

Ollama 支持并发处理多个请求，但需要足够的内存：

# 设置最大并发数（默认为 1）
export OLLAMA_NUM_PARALLEL=4

# 重启 Ollama
ollama serve

开始使用

核心概念

安装与配置

消息渠道

AI 提供商

​Ollama

​快速开始

​模型自动发现

​工作原理

​查看可用模型

​添加新模型

​配置方式

​基础设置（自动发现）

​显式设置（手动定义）

​自定义基础 URL

​推荐模型

​通用编码模型

GPT-OSS 20B

Llama 3.3

Qwen 2.5 Coder

Mistral

​推理模型

​高级配置

​多模型故障切换

​流式配置

​OpenAI 兼容模式（不推荐）

​num_ctx 注入

​上下文窗口

​故障排除

​Ollama 未检测到

​没有可用模型

​连接被拒绝

​工具调用失效

​上下文窗口太小

​完整配置示例

​性能优化

​硬件要求

​GPU 加速

​并发请求

​相关资源

Ollama

快速开始

模型自动发现

工作原理

查看可用模型

添加新模型

配置方式

基础设置（自动发现）

显式设置（手动定义）

自定义基础 URL

推荐模型

通用编码模型

推理模型

高级配置

多模型故障切换

流式配置

OpenAI 兼容模式（不推荐）

num_ctx 注入

上下文窗口

故障排除

Ollama 未检测到

没有可用模型

连接被拒绝

工具调用失效

上下文窗口太小

完整配置示例

性能优化

硬件要求

GPU 加速

并发请求

相关资源