跳转到主要内容

​
Ollama

OpenClaw 集成了 Ollama 的原生 API（/api/chat），可用于托管云模型以及本地/自托管的 Ollama 服务器。你可以通过三种模式使用 Ollama：通过可访问的 Ollama 主机实现的 Cloud + Local、直接连接 https://ollama.com 的 Cloud only，或连接可访问的 Ollama 主机的 Local only。
远程 Ollama 用户：不要在 OpenClaw 中使用 /v1 的 OpenAI 兼容 URL（http://host:11434/v1）。这会破坏工具调用，模型还可能将原始工具 JSON 作为纯文本输出。请改用原生 Ollama API URL：baseUrl: "http://host:11434"（不要加 /v1）。

​
入门指南

选择你偏好的设置方法和模式。
最适合： 以最快路径完成可用的 Ollama 云端或本地设置。
1

运行新手引导

openclaw onboard
在提供商列表中选择 Ollama。
2

选择你的模式

  • Cloud + Local — 本地 Ollama 主机加上通过该主机路由的云模型
  • Cloud only — 通过 https://ollama.com 使用托管的 Ollama 模型
  • Local only — 仅使用本地模型
3

选择模型

Cloud only 会提示输入 OLLAMA_API_KEY，并推荐托管云模型的默认值。Cloud + Local 和 Local only 会要求提供 Ollama 基础 URL、发现可用模型，并在所选本地模型尚不可用时自动拉取。Cloud + Local 还会检查该 Ollama 主机是否已登录以启用云访问。
4

验证模型可用

openclaw models list --provider ollama

​
非交互模式

openclaw onboard --non-interactive \
  --auth-choice ollama \
  --accept-risk
也可以选择指定自定义基础 URL 或模型：
openclaw onboard --non-interactive \
  --auth-choice ollama \
  --custom-base-url "http://ollama-host:11434" \
  --custom-model-id "qwen3.5:27b" \
  --accept-risk

​
云模型

Cloud + Local 使用可访问的 Ollama 主机作为本地模型和云模型的统一控制点。这是 Ollama 推荐的混合流程。在设置时使用 Cloud + Local。OpenClaw 会提示输入 Ollama 基础 URL，从该主机发现本地模型，并检查该主机是否已通过 ollama signin 登录以启用云访问。当主机已登录时，OpenClaw 还会推荐托管云模型默认值，例如 kimi-k2.5:cloud、minimax-m2.7:cloud 和 glm-5.1:cloud。如果该主机尚未登录，OpenClaw 会将设置保持为仅本地模式，直到你运行 ollama signin。

​
模型发现（隐式 provider）

当你设置了 OLLAMA_API_KEY（或身份验证配置）且没有定义 models.providers.ollama 时，OpenClaw 会从位于 http://127.0.0.1:11434 的本地 Ollama 实例中发现模型。
行为详细信息
目录查询查询 /api/tags
能力检测使用尽力而为的 /api/show 查询来读取 contextWindow 并检测能力（包括视觉）
视觉模型由 /api/show 报告具有 vision 能力的模型会被标记为支持图像输入（input: ["text", "image"]），因此 OpenClaw 会自动将图片注入到提示中
推理检测使用模型名称启发式规则（r1、reasoning、think）标记 reasoning
Token 限制将 maxTokens 设置为 OpenClaw 使用的默认 Ollama 最大 token 上限
费用将所有费用设置为 0
这样可以避免手动录入模型，同时让目录与本地 Ollama 实例保持一致。 
# 查看有哪些模型可用
ollama list
openclaw models list
要添加新模型，只需使用 Ollama 拉取它： 
ollama pull mistral
新模型会被自动发现并可立即使用。
如果你显式设置了 models.providers.ollama，则会跳过自动发现，你必须手动定义模型。参见下面的显式配置部分。

​
配置

最简单的仅本地启用方式是通过环境变量：
export OLLAMA_API_KEY="ollama-local"
如果设置了 OLLAMA_API_KEY，你可以在 provider 条目中省略 apiKey，OpenClaw 会在可用性检查时自动补齐它。

​
模型选择

完成配置后，你的所有 Ollama 模型都可用： 
{
  agents: {
    defaults: {
      model: {
        primary: "ollama/gpt-oss:20b",
        fallbacks: ["ollama/llama3.3", "ollama/qwen2.5-coder:32b"],
      },
    },
  },
}

​
Ollama Web 搜索

OpenClaw 支持将 Ollama Web 搜索 作为内置的 web_search provider 使用。
属性详细信息
主机使用你配置的 Ollama 主机（设置了 models.providers.ollama.baseUrl 时使用该值，否则为 http://127.0.0.1:11434）
认证无需密钥
要求Ollama 必须正在运行，并且已通过 ollama signin 登录
在 openclaw onboard 或 openclaw configure --section web 中选择 Ollama Web 搜索，或设置： 
{
  tools: {
    web: {
      search: {
        provider: "ollama",
      },
    },
  },
}
完整的设置和行为细节，请参见 Ollama Web 搜索。

​
高级配置

在 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 报告的上下文窗口；否则，会回退到 OpenClaw 使用的默认 Ollama 上下文窗口。你可以在显式 provider 配置中覆盖 contextWindow 和 maxTokens：
{
  models: {
    providers: {
      ollama: {
        models: [
          {
            id: "llama3.3",
            contextWindow: 131072,
            maxTokens: 65536,
          }
        ]
      }
    }
  }
}
OpenClaw 默认会将名称中包含 deepseek-r1、reasoning 或 think 的模型视为支持推理的模型。
ollama pull deepseek-r1:32b
无需额外配置——OpenClaw 会自动标记它们。
Ollama 可免费使用并在本地运行，因此所有模型费用都设置为 $0。这同时适用于自动发现的模型和手动定义的模型。
内置的 Ollama 插件会为 memory search 注册一个 memory embedding provider。它使用已配置的 Ollama 基础 URL 和 API 密钥。
属性值
默认模型nomic-embed-text
自动拉取是——如果 embedding 模型在本地不存在，则会自动拉取
要将 Ollama 选为 memory search 的 embedding provider：
{
  agents: {
    defaults: {
      memorySearch: { provider: "ollama" },
    },
  },
}
OpenClaw 的 Ollama 集成默认使用原生 Ollama API（/api/chat），可同时完整支持流式传输和工具调用。无需任何特殊配置。
如果你需要使用 OpenAI 兼容端点，请参阅上面的“旧版 OpenAI 兼容模式”部分。在该模式下，流式传输和工具调用可能无法同时工作。

​
故障排除

请确保 Ollama 正在运行，并且你已设置 OLLAMA_API_KEY（或身份验证配置），同时没有定义显式的 models.providers.ollama 条目：
ollama serve
验证 API 可访问：
curl http://localhost:11434/api/tags
如果列表中没有你的模型，请在本地拉取该模型，或在 models.providers.ollama 中显式定义它。
ollama list  # 查看已安装的模型
ollama pull gemma4
ollama pull gpt-oss:20b
ollama pull llama3.3     # 或其他模型
检查 Ollama 是否在正确的端口上运行：
# 检查 Ollama 是否正在运行
ps aux | grep ollama

# 或重启 Ollama
ollama serve
更多帮助：故障排除 和 常见问题。

​
相关内容

模型提供商

所有提供商、模型引用和故障切换行为的概览。

模型选择

如何选择和配置模型。

Ollama Web 搜索

了解 Ollama 驱动的网页搜索的完整设置和行为细节。

配置

完整的配置参考。