Ollama

Ollama 是一个本地 LLM 运行时,让你可以轻松在自己的机器上运行开源模型。OpenClaw 集成了 Ollama 的 OpenAI 兼容 API,当你设置 OLLAMA_API_KEY(或认证配置)且没有显式定义 models.providers.ollama 时,可以自动发现支持工具调用的模型。

快速开始

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

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/llama3.3" },
    },
  },
}

模型自动发现(隐式 Provider)

当你设置了 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
openclaw models list

添加新模型,只需用 Ollama 拉取:

ollama pull mistral

新模型会自动被发现并可以使用。

如果你显式设置了 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,你可以在 provider 配置中省略 apiKey,OpenClaw 会自动填充它用于可用性检查。

自定义基础 URL(显式配置)

如果 Ollama 运行在不同的主机或端口(显式配置会禁用自动发现,所以需要手动定义模型):

{
  models: {
    providers: {
      ollama: {
        apiKey: "ollama-local",
        baseUrl: "http://ollama-host:11434/v1",
      },
    },
  },
}

模型选择

配置完成后,所有 Ollama 模型都可以使用:

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

高级功能

推理模型

当 Ollama 在 /api/show 中报告 thinking 时,OpenClaw 会将模型标记为具有推理能力:

ollama pull deepseek-r1:32b

模型成本

Ollama 是免费的且在本地运行,所以所有模型成本都设置为 $0。

上下文窗口

对于自动发现的模型,OpenClaw 使用 Ollama 报告的上下文窗口(如果可用),否则默认为 8192。你可以在显式 provider 配置中覆盖 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 llama3.3  # 拉取一个模型

连接被拒绝

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

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

# 或重启 Ollama
ollama serve