高级 12 分钟智能体

使用 Ollama 的 OpenClaw：接入一个模型 本地

本指南介绍如何将 OpenClaw 连接到 Ollama，让助手运行在本地模型上：声明供应商、设置服务器地址、规划上下文窗口，以及选择能够调用工具的模型。工作量有一半在于避免那些不会显示任何错误的故障：上下文被截断、工具从未被调用、模型不在列表中。命令取自 Ollama 和 OpenClaw 的文档；由于两者更新很快，粘贴命令前应重新阅读文档；本页不包含自测、速度测量或模型排名。

作者： Thomas P.·更新于 2026-10-05·已在 Windows、macOS 和 Linux 上测试

#OpenClaw 与 Ollama：各自负责什么

OpenClaw 是一个网关：它从消息应用接收你的消息，将其传递给语言模型，并执行该模型请求的操作。Ollama 是模型服务器：它将模型加载到内存中，并在机器的 11434 端口上响应，默认地址为 http://localhost:11434。将两者连接起来，就是在 OpenClaw 中将 Ollama 声明为提供商，然后指定一个本地模型作为代理的主模型。

根据 OpenClaw 文档，这种连接通过 Ollama 的原生 API（端点 /api/chat）实现，该 API 支持流式响应和工具调用。这个细节比看起来更重要：后文会看到，地址写错一个地方，就足以让网关切换到另一种模式，在该模式下工具将无法运行。

Ollama
加载模型，为其分配上下文窗口并生成文本。消耗多少内存由它决定。
OpenClaw
每轮都会发送系统指令、可用工具的描述和对话历史，然后执行模型请求的工具。
该模型
必须能够记住长指令，并知道如何以预期格式请求工具。并非所有本地模型都具备这种能力。
不变的部分
无论模型供应商是谁，消息系统、助手记忆、令牌和网关安全性仍在 OpenClaw 侧配置。

这种连接方式比聊天界面的连接更复杂。聊天只会向模型发送几行内容；而代理从一开始就会向模型发送数千个 token 的指令和工具定义，甚至早于您的第一条消息。Ollama 的默认设置是为前一种情况设计的，而不是后一种。

i
本地运行不代表没有风险
本地模型可以避免将您的对话发送给在线供应商。但它不会消除代理自身的风险：OpenClaw 会读取来自外部的内容，并且可能执行命令。与大型模型相比，小型模型通常更容易被诱导文本劫持，项目的安全文档也提醒用户对此保持谨慎。请将网关保留在专用机器上，尽可能少启用工具，并在更换模型后再次运行 openclaw security audit --deep。

#先决条件

本地智能体套件

在你的机器上执行操作的智能体：具备智能体能力的 Cline、MCP、n8n + Ollama、本地自动化。

  • 在线空间，终身可用
  • PDF + 文件
  • 终身更新
本地智能体套件 →或 所有套件终身使用权 — 49 € →
OpenClaw 已安装
网关能够启动，诊断也能通过。这里不重复介绍安装过程：请参阅我们的指南《使用 Docker 安装 OpenClaw》。
已安装并更新至最新版本的 Ollama
下面使用的 ollama launch 命令仅存在于较新的版本中。安装过程请参阅我们的《安装 Ollama》指南。
为模型及其上下文提供的内存
仅计算权重时，Q4_K_M 的参考值为：70 亿参数模型约 5 GB，140 亿参数约 9 GB，320 亿参数约 19 GB。智能体要求的上下文窗口还要在此基础上增加。
访问终端
在托管网关的机器上；如果托管Ollama的机器不是同一台，也要在那台机器上。
终端——检查这两个工具
ollama --version
openclaw --version

# Le serveur Ollama répond-il ?
curl http://localhost:11434/api/tags

最后一条命令应以 JSON 格式返回已安装模型的列表。连接被拒绝意味着 Ollama 尚未启动：请启动应用，或在终端中运行 ollama serve。在得到这一响应之前，无需继续进行。

#第 1 步：预留 64 000 个 token 的上下文

这是导致安装失败最多的设置，而且它是在 Ollama 侧完成的，不是在 OpenClaw 侧。Ollama 关于 OpenClaw 的页面指出，助手需要较大的上下文窗口，并建议本地模型至少使用 64 000 个 token。该页面关于上下文长度的说明，也为代理、网页搜索和代码工具给出了相同数值。

不过，Ollama 会根据可用显存默认选择上下文窗口：根据同一份文档，在 24 GiB VRAM 以下约为 4 000 tokens，24 至 48 GiB 之间为 32 000，从 48 GiB 起为 256 000。因此，在 12 或 16 GB 显存的显卡上，服务器启动时的窗口会比建议值小十六倍。系统不会对此发出提示：Ollama 会直接截断超出的内容，不显示错误消息。

终端 — 手动启动的 Ollama（Linux、macOS）
OLLAMA_CONTEXT_LENGTH=64000 ollama serve

如果 Ollama 已经作为应用程序运行（macOS、Windows），请不要运行此命令：第二个服务器会与端口 11434 发生冲突。请在应用程序设置中调整上下文长度。在 Linux 下，如果 Ollama 是作为 systemd 服务安装的，则应在服务本身中声明该变量。

终端 — 已作为服务安装的 Ollama（Linux）
sudo systemctl edit ollama.service

# Dans l'éditeur qui s'ouvre, ajouter ces deux lignes :
# [Service]
# Environment="OLLAMA_CONTEXT_LENGTH=64000"

sudo systemctl daemon-reload
sudo systemctl restart ollama
!
64 000 个 token 需要占用内存
上下文窗口会在模型权重之外额外占用内存。一个在对话中运行自如的模型，在提高上下文后可能会溢出到处理器，此时代理会变得非常缓慢。我们不提供具体数值，因为它取决于模型：第 4 步中介绍的 ollama ps 命令会显示实际分配的资源。如果发生溢出，应选择更小的模型，而不是削减上下文。Ollama 的 FAQ 中记录了两个可以降低开销的变量：OLLAMA_FLASH_ATTENTION=1 和 OLLAMA_KV_CACHE_TYPE=q8_0。

#步骤 2：选择支持工具调用的模型

智能体只能通过工具行动：读取文件、运行命令、搜索网页。不会构造工具请求的模型只会礼貌地回复你的消息，却永远不会真正执行任何操作。本页面不对模型进行排名；它列出的是在接入模型前需要核查的标准。

“tools”能力
命令 ollama show affiche 包含一个 Capabilities 部分。该部分必须包含 tools。在 Ollama 的库中，相应的筛选器位于地址 https://ollama.com/search?c=tools。
足够大的原生窗口
同一个命令会显示模型的最大上下文长度。为 8 000 或 32 000 个 tokens 设计的模型，无论服务器如何设置，都无法遵循 64 000 的建议。
现实可行的内存预算
模型权重和上下文必须共同容纳在 VRAM 中，或容纳在 Mac 的统一内存中。在一张 12 GB 的显卡上（RTX 3060、RTX 4070），这意味着只能选择明显小于该显卡在简单对话中可接受范围的模型；16 GB（RTX 4080）和 24 GB（RTX 4090）则留有更多余量。
长时间运行的稳定性
一个智能体会针对每个请求连续调用多个工具。极小型模型更容易弄错格式或工具。任何规格页都无法替代使用你自己的请求进行测试，首先应从低风险请求开始。
终端 — 下载模型，然后进行检查
ollama pull gpt-oss:20b
ollama show gpt-oss:20b

gpt-oss:20b 这个名称将在本指南后文作为示例使用：请将其替换为你选定的模型。Ollama 的集成页面会持续更新适用于 OpenClaw 的推荐模型列表，该列表会随着新版本发布而变化；与其依赖这里固定不变的列表，不如查看该页面。

i
“云端”模型不是本地模型
Ollama 的模型库以及 ollama launch 命令的选择器，也会提供标签以 cloud 结尾的模型。这些模型运行在 Ollama 的服务器上，而不是您的机器上：您的消息会离开本地。若要真正进行本地安装，请选择已下载且能在 ollama list 中看到的模型。

#步骤 3：在 OpenClaw 中配置供应商 Ollama

有两种方式。第一种是执行一条Ollama命令，由它代您写入配置。第二种是在 OpenClaw 的配置中自行声明提供商；只要网关运行在 Docker 中，或Ollama位于另一台机器上，这种方式就是必需的。

#快速路径：ollama launch openclaw

终端
# Configurer OpenClaw pour Ollama et démarrer la passerelle
ollama launch openclaw

# Configurer sans rien lancer
ollama launch openclaw --config

根据 Ollama 的文档，此命令会选择一个模型，将 OpenClaw 配置为使用 Ollama，并启动网关；如果网关已经运行，它会自行加载新配置。项目的旧名称仍然可用：ollama launch clawdbot 是一个别名。该命令适用于直接安装在机器上的 OpenClaw，并且终端中可用 openclaw 命令。它并不能免除第 1 步：同一页面要求记录服务器的上下文。

#手动方式：自行声明供应商

OpenClaw 的文档首先介绍自动发现模式。我们提供一个伪造的密钥，因为Ollama不需要密钥；OpenClaw 会通过地址http://127.0.0.1:11434查询本地实例，以查找已安装的模型。

终端 — 启用提供商并选择模型
# N'importe quelle valeur convient : Ollama ne vérifie pas de clé
export OLLAMA_API_KEY="ollama-local"

# Ou l'inscrire dans la configuration d'OpenClaw
openclaw config set models.providers.ollama.apiKey "ollama-local"

# Lister les modèles vus par OpenClaw, puis fixer le modèle principal
openclaw models list
openclaw models set ollama/gpt-oss:20b

模型应写成 ollama/ 加上 ollama list 显示的确切名称，包括标签。网关作为服务运行时，优先将其写入配置，而不是使用环境变量：在终端中导出的变量不会传递给系统启动的进程。使用 Docker 安装时，每条 openclaw 命令前都要加上 docker compose run --rm openclaw-cli。

第二种方式是在采用 JSON5 编写的 ~/.openclaw/openclaw.json 文件中进行显式声明。当 Ollama 运行在网关机器之外、模型未出现在列表中，或者你想自行固定向智能体公布的窗口时，这种方式便派上用场。

~/.openclaw/openclaw.json — 明确声明（JSON5）
{
  models: {
    providers: {
      ollama: {
        baseUrl: "http://127.0.0.1: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: 64000,
            maxTokens: 8192
          }
        ]
      }
    }
  },
  agents: {
    defaults: {
      model: { primary: "ollama/gpt-oss:20b" }
    }
  }
}
baseUrl
服务器 Ollama 的地址，包括端口，后面不要添加任何内容。Ollama 在另一台机器上运行时，只需修改这一行。
api: "ollama"
明确要求使用 Ollama 的原生 API，即支持工具调用的那个 API。
apiKey
一个虚假值。它仅用于激活供应商。
contextWindow
向 OpenClaw 声明的窗口，OpenClaw 用它来管理历史记录的长度。它必须与 Ollama 实际加载的内容相符，而不是与模型理论上能够接受的长度相符。
maxTokens
回答的长度上限。
cost
一分钱都不用花：本地模型不会按 token 计费。
agents.defaults.model.primary
代理默认使用的模型，格式为 ollama/模型名称。

此示例沿用了 OpenClaw 文档提供的结构；contextWindow 和 maxTokens 的值是我们设置的，需要根据你的模型进行调整。有两点需要记住。首先，对于推理模型，将 reasoning 设置为 true。其次，根据同一份文档，只要明确存在 models.providers.ollama 条目，自动发现就会被禁用：此时你想使用的每个模型都必须列在 models 中。

!
地址末尾不要加 /v1
许多工具通过兼容 OpenAI 的接口连接到 Ollama，地址为 http://localhost:11434/v1。OpenClaw 文档明确要求不要这样使用：在这种模式下，工具调用不再可靠，模型可能会以纯文本形式返回工具 JSON。正确的地址应在端口处结束：http://localhost:11434。
终端 — 应用并检查
openclaw gateway restart
openclaw doctor

#在 Docker 中运行网关，或在另一台机器上运行 Ollama

在容器内部，localhost 指的是容器自身。因此，使用 Docker 启动的 OpenClaw 网关无法在地址 http://localhost:11434 看到主机的 Ollama：连接会被拒绝，尽管从你的终端上一切正常。解决方案取决于 Ollama 运行的位置。

Docker Desktop（macOS、Windows）
host.docker.internal 这个名称表示从容器访问宿主机。将 http://host.docker.internal:11434 指定为显式声明中的 baseUrl。
Linux 下的 Docker Engine
这个名称默认不存在：必须像下面这样，使用 extra_hosts 将其添加到服务中。除此之外，Ollama还必须监听容器能够连接的接口；其原始设置仅限于环回接口，无法满足这一点。
Ollama 在另一台机器上运行
将这台机器在本地网络或 VPN 中的地址填入 baseUrl，并以同样方式设置 Ollama 在这台机器上的监听。
docker-compose.override.yml — 待调整示例（Linux）
services:
  openclaw-gateway:
    extra_hosts:
      - "host.docker.internal:host-gateway"
终端——让 Ollama 在本地回环接口之外监听（Linux 服务）
sudo systemctl edit ollama.service

# Dans l'éditeur qui s'ouvre, ajouter ces deux lignes :
# [Service]
# Environment="OLLAMA_HOST=0.0.0.0:11434"

sudo systemctl daemon-reload
sudo systemctl restart ollama

Compose 文件是我们提供的示例，并非 OpenClaw 文档中的摘录：请将服务名称与您所用版本的 docker-compose.yml 进行比较。至于变量 OLLAMA_HOST，Ollama 的常见问题中对此有说明。请评估它的影响：使用 0.0.0.0 时，服务器会监听机器的所有接口，而 Ollama 的 API 不要求身份验证。防火墙必须将端口 11434 限制在 Docker 网络或本地网络内，该端口绝不能从互联网访问。我们的 Ollama 服务器安全指南详细说明了这些规则。

#步骤 4：验证端到端连接

一个只会回答“你好”的代理什么也证明不了：这个回答既不需要工具，也不需要上下文。有用的验证应逐层推进，从模型服务器一直检查到消息系统。

  1. 01
    仅在 Ollama 上测试工具调用
    使用下面的命令，向服务器发送一个附带虚构工具的问题。响应必须包含一个 tool_calls 字段，指出工具名称并传入一个参数。如果模型只用一句话回答，就不适合作为智能体。
  2. 02
    检查 OpenClaw 能看到什么
    命令 openclaw models list 应显示采用 ollama/模型名称 格式的模型，而 openclaw doctor 不应报告供应商错误。
  3. 03
    请求执行操作，而不是回答
    从控制界面或您的消息应用中发送一条要求代理使用工具的请求，例如列出其工作区中的文件。它必须真正执行，而不是描述自己会怎么做。
  4. 04
    查看 Ollama 加载了什么
    就在这次交流之后，在服务器机器上运行 ollama ps，并查看 CONTEXT 和 PROCESSOR 列。
终端 — 1. 直接在 Ollama 上调用工具
curl http://localhost:11434/api/chat -d '{
  "model": "gpt-oss:20b",
  "stream": false,
  "messages": [{"role": "user", "content": "Quel temps fait-il à Lyon ?"}],
  "tools": [{
    "type": "function",
    "function": {
      "name": "get_weather",
      "description": "Donne la météo actuelle pour une ville",
      "parameters": {
        "type": "object",
        "properties": {"city": {"type": "string"}},
        "required": ["city"]
      }
    }
  }]
}'
终端 — 2 和 4。在 OpenClaw 一侧，然后在 Ollama 一侧
openclaw models list
openclaw doctor

# Après un échange avec l'agent
ollama ps

在 ollama ps 的输出中，CONTEXT 列给出已加载模型实际分配到的窗口。如果它显示 4096，而你的目标是 64 000，那么第 1 步的设置并未生效，无论 OpenClaw 的配置显示什么。PROCESSOR 列给出显卡与处理器之间的分配情况：我们需要看到的是 100% GPU；混合分配表示模型及其上下文超出了显存。

→
隔离故障层
如果直接在 Ollama 上进行的测试（四项检查中的第一项）失败，问题来自模型或 Ollama，OpenClaw 的任何设置都无法修复它。如果测试成功但代理没有行动，请从连接方面查找原因：服务器地址、API 模式、上下文窗口。这种排查可以避免随意修改配置。

#无声故障：症状及其原因

明确的错误（连接被拒绝、找不到模型）会出现在日志中。下面这些故障代价更高，因为助手仍会继续回答：只是回答得不对。

助手忽略其指令，或答非所问
最可能的原因：上下文被截断。系统指令和工具定义超出了 Ollama 加载的窗口，后者会在不提示的情况下截去其中一部分。请检查 ollama ps 的 CONTEXT 列，然后重新执行第 1 步。
显示的是 JSON，而不是操作
模型确实生成了工具调用，但网关将其作为文本接收。这表明地址使用了 /v1，或者供应商被声明为 OpenAI 兼容模式。请改回原生地址，并将 api 设置为 "ollama"。
它描述自己会做什么，却什么也没做
该模型没有声明 tools 能力，或者能力太有限，无法在较长指令中途使用。请重新执行第 4 步所述的 Ollama 直接测试；如果失败，请更换模型。
模型没有出现在 openclaw models list 中
有三种可能。供应商未启用（缺少虚假密钥，或变量未传递给服务）。存在明确的 models.providers.ollama 条目，但其中没有列出该模型。或者模型没有声明工具调用：根据我们所了解的文档，自动发现只会保留声明了工具调用的模型；这一行为可能会随版本变化。
上下文设置仍然没有效果
变量 OLLAMA_CONTEXT_LENGTH 已在终端中导出，但 Ollama 是作为服务或应用运行的：服务器从未看到这个变量。请在服务中或应用设置中声明它，然后重启 Ollama。
响应耗时很长，或者根本不会出现
要么模型溢出到处理器上（ollama ps 的 PROCESSOR 列），要么模型在一段时间不活动后被卸载，并在每条消息到来时重新加载：默认情况下，Ollama 会将模型保留在内存中五分钟。OLLAMA_KEEP_ALIVE 变量可以延长这一时间。
终端上一切正常，网关却什么也做不了
网关在容器中运行，并在自己的 localhost 上查找 Ollama。请参阅 Docker 相关章节。
“Model context window too small”
这并非无声无息，而是令人困惑：我们所知的 OpenClaw 版本拒绝使用上下文窗口声明得过小的模型。请在明确声明中调整 contextWindow，并相应调整 Ollama 的上下文。
终端 — 跟踪两端的日志
# Passerelle OpenClaw
openclaw logs --follow

# Serveur Ollama installé comme service (Linux)
journalctl -u ollama -f

建立连接后需要牢记的一点限制是：正确接入的本地模型，在处理较长或含糊的任务时，未必会表现得像大型在线模型。本文不发布任何对比结果或吞吐量数据。请先从简单且无风险的请求开始，观察模型在哪些地方开始失效；如果助手是日常工作的一部分，请保留一家在线供应商作为备用方案。

#随手备查的官方资料

本指南不依赖任何自有测试：不包含时长、吞吐量或分数。命令和字段名称均取自两个项目的文档，而文档会随版本变化：ollama launch 选项、自动发现行为、默认值。如果本页面与文档存在差异，以文档为准。

Ollama：OpenClaw 集成
https://docs.ollama.com/integrations/openclaw
OpenClaw：Ollama 提供商
https://docs.openclaw.ai/providers/ollama
Ollama：上下文长度
https://docs.ollama.com/context-length
Ollama：常见问题（服务器变量）
https://docs.ollama.com/faq
OpenClaw：网关安全
https://docs.openclaw.ai/gateway/security

#深入了解

连接建立在网站其他地方详细介绍的三个概念之上：Ollama 服务器、上下文窗口和工具调用。

安装 Ollama
模型服务器的安装、基本设置，以及可能离开机器的内容。https://quelllm.fr/guide/installer-ollama
理解上下文窗口
token 衡量的是什么、上下文为何会消耗内存，以及如何确定其大小。https://quelllm.fr/guide/comprendre-fenetre-contexte
使用 Ollama 调用工具
工具请求的格式，以及在完全脱离代理的情况下测试工具的方法。https://quelllm.fr/guide/appel-outil-ollama-tutoriel
Hermes Agent 搭配 Ollama
另一个连接到本地模型的自托管代理，用于比较不同方案。https://quelllm.fr/guide/hermes-agent-ollama-guide
使用 Docker 安装 OpenClaw
网关的安装、更新以及在 VPS 上的暴露规则。https://quelllm.fr/guide/installer-openclaw-docker
这份指南对您有帮助吗？

有反馈、发现了错误，或想补充说明？请告诉我们，让这份指南对每个人都更有帮助。