OpenClaw使用Ollama本地模型实现工具调用

Ollama 的出现，让在本地运行大模型变得前所未有的简便。而 OpenClaw 工具链可以通过 Ollama 提供的 OpenAI 兼容 API 实现无缝对接。最巧妙的是，只要配置好 OLLAMA_API_KEY（或完成认证），且未在配置文件中显式定义 models.providers.ollama 条目，OpenClaw 便能自动发现本地所有支持工具调用的模型，省去大量手动配置的繁琐步骤。

快速开始

想立刻上手？只需按以下步骤操作即可：

1. 首先安装 Ollama，下载地址：https://ollama.ai
2. 然后拉取所需的模型：

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

• 接下来，为 OpenClaw 启用 Ollama 支持。这里有个技巧：任意填写一个值即可，因为本地运行 Ollama 并不需要真实的 API 密钥。

# 设置环境变量
export OLLAMA_API_KEY="ollama-local"
# 或在配置文件中设置
openclaw config set models.providers.ollama.apiKey "ollama-local"

• 最后，直接在配置中引用 Ollama 下的模型：

{
  agents: {
    defaults: {
      model: { primary: "ollama/llama3.3" },
    },
  },
}

模型发现（隐式提供商）

当你设置了 OLLAMA_API_KEY 但未定义 models.providers.ollama 时，精彩之处就展现出来：OpenClaw 会自动连接本地 Ollama 实例（默认地址 http://127.0.0.1:11434），并自动发现可用模型。具体流程如下：

• 首先查询 /api/tags 和 /api/show 这两个接口。
• 然后从返回结果中，仅筛选出那些报告具备 tools 能力的模型。
• 如果某个模型报告了 thinking 能力，它会被自动标记为 reasoning 类型（即具备推理能力）。
• 上下文窗口大小（contextWindow）从 model_info[".context_length"] 读取；若读取不到，则使用默认值。
• maxTokens 被设置为上下文窗口值的10倍。
• 所有费用均设为 0，毕竟是本地运行。

通过这套自动化机制，你完全无需手动配置每个模型，OpenClaw 会持续维护一个与 Ollama 能力同步的模型目录。想查看当前可用模型？非常简单：

ollama list
openclaw models list

若想使用新模型，只需通过 Ollama 拉取即可：

ollama pull mistral

拉取完成后，该模型会被 OpenClaw 自动发现并纳入使用。请注意：如果你在配置中显式设置了 models.providers.ollama，自动发现功能将被禁用，届时需要手动定义每个模型（具体方法参考下一节）。

配置

基本设置（隐式发现）

想要快速启用 Ollama？环境变量是最直接的方式：

export OLLAMA_API_KEY="ollama-local"

显式设置（手动模型）

什么情况下需要显式配置呢？常见场景包括：

• Ollama 运行在其他主机或非默认端口上。
• 你想手动指定上下文窗口大小，或精确控制模型列表。
• 你想将那些未报告工具支持能力的模型也纳入进来。

此时，你需要在配置文件中完整定义所有参数：

{
  models: {
    providers: {
      ollama: {
        // 注意：地址需包含 /v1，以兼容 OpenAI API 格式
        baseUrl: "http://ollama-host:11434/v1",
        apiKey: "ollama-local",
        api: "openai-completions",
        models: [
          {
            id: "llama3.3",
            name: "Llama 3.3",
            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 下的模型即可直接调用。例如，可以这样配置一个主模型和一个备用模型：

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

高级用法

推理模型

当 Ollama 在 /api/show 接口中报告模型具备 thinking 能力时，OpenClaw 会自动将其标记为推理模型。例如拉取 DeepSeek-R1 模型后，它就会自动拥有这一属性：

ollama pull deepseek-r1:32b

模型费用

这一点无需多言：Ollama 完全免费，所有费用均为 $0。

上下文窗口

对于自动发现的模型，OpenClaw 优先使用 Ollama 报告的上下文窗口值。若报告中没有该值，则默认回退为 8192。当然，你也可以在显式提供商配置中，通过覆盖 contextWindow 和 maxTokens 来获得完全控制权。

故障排除

如果一切顺利，Ollama 将很快成为你工具箱中的利器——但如果遇到问题，可以参考以下方案：

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 llama3.3  # 拉取一个新模型

连接被拒绝

这通常意味着 Ollama 未在预期端口上运行。请检查：

# 查看 Ollama 进程是否存在
ps aux | grep ollama
# 或者直接重启 Ollama
ollama serve

另请参阅

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