OpenClaw调用Ollama本地模型：工具调用配置指南

2026-06-02阅读 0热度 0

OpenClaw

Ollama 显著简化了本地大模型的部署流程。通过其提供与 OpenAI 兼容的 API，工具链 OpenClaw 能够直接对接。只需正确设置 OLLAMA_API_KEY（或完成认证），且未在配置文件中明确定义 models.providers.ollama，OpenClaw 便会自动探测并加载支持工具调用的本地模型，大幅减少手动配置工作量。

快速上手

只需以下步骤即可启动运行：

安装 Ollama，官方下载地址：https://ollama.ai
拉取所需模型：

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

为 OpenClaw 启用 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，自动发现将被禁用，需手动定义每个模型（详见下节）。

配置方式

基本设置（隐式发现）

最快捷的方式是使用环境变量：

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。

上下文窗口

自动发现的模型优先使用 Ollama 报告的值。若无，默认回退至 8192。在显式提供商配置中可通过覆盖 contextWindow 和 maxTokens 实现完全控制。

故障排查

若遇到问题，按以下步骤诊断：

Ollama 未被检测到

首先确保 Ollama 正在运行，已设置 OLLAMA_API_KEY，且未定义显式的 models.providers.ollama。启动服务：

ollama serve

验证 API 是否可访问：

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

无可用模型

自动发现仅对报告工具支持的模型有效。若模型未列出：

拉取明确支持工具调用的模型。
或在 models.providers.ollama 中显式定义模型参数。

添加模型操作：

ollama list  # 查看已安装模型
ollama pull llama3.3  # 拉取新模型

连接被拒绝

通常由 Ollama 未在预期端口运行导致。检查：

# 查看 Ollama 进程
ps aux | grep ollama
# 或重启 Ollama
ollama serve

参考文档

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