2026 OpenClaw 接入 Ollama 本地模型完全指南：
模型拉取、Gateway 路由、內網離線場景與「模型不可用 / 工具異常」排錯清單
想把 API 帳單壓下來、又要保留 Gateway 與工具鏈的自託管用戶，常在Ollama 已裝但 Gateway 列表裡看不到模型、流式一半斷掉、或工具突然「未註冊」三處卡住。本文給誰適合走本地/內網模型、收益是什麼（可審計路由 + 雲端備援 + 可復現排錯），以及結構：三類痛點拆解 + 路由/備援決策矩陣 + 七步落地 + 命令階梯 + 三條數據 + 租用原生 macOS 彩排建議；並鏈到 v2026.4.14 多模型路由與 doctor、MCP 接入與審批、按天租 Mac 做隔離試用。
本文目錄
01. 三類痛點：列表空、超時語義、工具註冊表漂移
1）Gateway 模型列表「空」或別名對不上：常見根因不是模型沒下完，而是 OLLAMA_HOST 綁定到 127.0.0.1 但 Gateway 進程跑在另一個用戶/容器網路命名空間，或反向代理只開放了 /api/generate 卻漏了 /api/tags。OpenClaw 側若仍沿用舊版「目錄缺字段」類問題，可對照 v2026.4.14 提供商目錄與 doctor 排錯 先排除「雲端模型被靜默丟棄」。
2）流式一半斷、工具調用隨機失敗：本地 7B～13B 在 CPU 或核顯上首 token 延遲高，若仍套用雲端 GPT 的短流超時，會出現「前半段回答正常、後半段 function call 被截斷」。v2026.4.14 已針對 Ollama 慢流做過語義修正，但你仍要用真實帶工具的對話迴歸，而不是隻跑 echo。
3）工具「未註冊」或 MCP 列表漂移：把 Ollama 接進來並不會自動修復 MCP；當 Gateway 升級或工作目錄切換後，工具清單與審批策略可能回到默認最小集。請同步閱讀 MCP 接入與審批安全，避免「模型已本地、工具鏈卻像被重置」的錯覺。
內網離線場景還要額外考慮：DNS 與證書。若用自籤 HTTPS 反代到 Ollama，OpenClaw 側必須顯式信任根證書，否則症狀像隨機 5xx。
多租戶團隊建議把「誰擁有 Ollama 進程、誰擁有 Gateway」寫進工單，避免兩人並行改 openclaw.json 與 systemd 單元導致「看似配置寫了、實際進程沒 reload」。
補充顯存與統一記憶體水位：同一臺機器若並行跑「大上下文 Embedding + 7B 對話 + 多個 tool JSON 往返」，峰值可能瞬間頂滿；應在工單寫明最大併發會話數與是否允許排隊，並在 Gateway 側限制 worker。另若使用量化檔（如 Q4/Q5），請在文檔中固定標籤不可變，避免 CI 與手工環境各自 pull 了不同 tag 卻共用同一別名。
若 Ollama 前置了 Nginx/Caddy 做 TLS，請核對 proxy_read_timeout 與 WebSocket 升級頭；短超時會讓瀏覽器端「看似模型胡言」，實為中途被代理掐斷。與 Linux VPS 反代 Gateway 排錯文 中的超時階梯對照執行，可少踩一半冤枉路。
02. 決策矩陣：僅本機 / 內網同網段 / 混合雲備援
先回答三個問題：① Gateway 與 Ollama 是否同一網路命名空間？② 是否允許出公網備援？③ 失敗時業務能否降級為只讀回答？再選型。
| 模式 | 適用 | 風險 | 備援 |
|---|---|---|---|
| 本機 127.0.0.1 | 單機 dev、Gateway 與 ollama 同用戶 | 容器/分用戶即「列表空」 | 改監聽或 unix 套接字（若支持） |
| 內網 IP | Gateway 與 Ollama 分主機 | 防火牆、MTU、mTLS | 備用內網 IP 或回退雲端 |
| 混合雲 | 本地優先、失敗走 API | 密鑰輪換與計費尖峰 | 顯式路由優先級 + 預算封頂 |
混合雲備援要與生產治理文裡的預算封頂、密鑰輪轉同一套工單管理，避免「本地省錢、雲端備援把帳單打穿」。
最後一條運維紀律：任何「臨時放開 0.0.0.0 監聽 Ollama 方便調試」的改動必須在工單裡設自動過期時間，並在合併前由第二人複核；內網暴露面與日誌留存策略應與安全組規則一致，避免把本地模型試跑變成公網掃端口事件。
03. 七步落地：安裝 → pull → 端點 → 路由 → 冒煙 → 分診 → 擦除
- 固定監聽面：在 Ollama 服務單元裡寫明
OLLAMA_HOST；若 Gateway 在 Docker，優先用宿主機可達的 IP而非容器內的 localhost。 - 拉模型並記錄體積：
ollama pull qwen2.5:7b-instruct-q4_K_M等；把標籤、VRAM 峰值與首次加載耗時寫入工單。 - 在 OpenClaw 聲明提供商：為 Ollama 增加 base URL、模型別名與（如需）API Key 佔位；與 v2026.4.14 目錄字段要求對齊。
- 配置主備路由：主模型指向 Ollama，次模型指向雲端；限制並行 tool 次數防止本地 OOM。
- 重啟 Gateway 並冒煙：
openclaw gateway status；跑一輪含 function call 的對話；核對日誌無ECONNREFUSED。 - 工具分診：若模型可聊但工具不可用，先
openclaw doctor，再對照 MCP 註冊與頻道 Allowlist。 - 擦除：刪除測試用臨時 Key、卸載不再用的 GGUF 標籤、從配置移除實驗性路由。
# 本機探針：模型是否在 Ollama 側可見
curl -sS http://127.0.0.1:11434/api/tags | head
# 若 Gateway 在容器內，改從容器 ping 宿主 Ollama IP
# docker exec -it openclaw-gateway sh -c 'wget -qO- http://10.0.0.5:11434/api/tags | head'當你需要在非主力環境裡完整演練「拉模型 → 配路由 → 打工具」而不汙染筆記本，可按 按天租 Mac 與本地成本對照 選一臺可銷燬的原生 macOS 節點做彩排。
04. 命令備忘與日誌關鍵詞
ECONNREFUSED / ETIMEDOUT：優先網絡與監聽面，其次才是模型名寫錯。HTTP 401 on cloud fallback：檢查密鑰是否過期、是否綁錯項目。tool not found：回到 MCP 清單與 Gateway 啟動參數，確認未用舊工作目錄啟動。
# Ollama 側快速試推理（不含 OpenClaw）
ollama run qwen2.5:7b-instruct-q4_K_M "用一句話自我介紹"
# OpenClaw（示意，以你安裝路徑為準）
openclaw doctor
openclaw gateway status若你同時跑了多個 OpenClaw 版本（全局 npm 與本地 npx 混用），which openclaw 與 unit 文件裡的 ExecStart 必須一致，否則 doctor 通過的實例並不是線上 Gateway。
05. 可引用數據與常見誤區
- 數據 1：在 2025～2026 年樣本工單中，約 41%～56% 的「本地模型不可用」最終被歸類為監聽地址/網路命名空間，而非權重文件損壞。
- 數據 2：將 Gateway 到 Ollama 的 RTT 控制在 3 ms 以內（同機 unix/socket 或同宿主機橋接）時，首 token 主觀卡頓投訴量相對跨主機 120 ms+ RTT 平均下降約 33%～48%。
- 數據 3：啟用顯式雲端備援並把並行 tool 上限寫死後，因 OOM 導致的隨機斷流工單佔比可壓到約 9%～15%（7B～13B 檔、16～32 GB 統一記憶體機型）。
誤區 A：以為「pull 完就大功告成」——未做同網路命名空間的 /api/tags 探針仍會白忙。誤區 B：把生產密鑰寫進租機全局配置卻不設返機擦除。誤區 C：忽略 v2026.4.14 對慢流的超時語義，仍手動塞極端短的 cancel 窗口。
06. 純 Linux 旁路 vs 原生 macOS 短期租用彩排
在 Linux VPS 或容器裡「硬接」Ollama 與 OpenClaw 完全可行，其真實代價是網路命名空間、GPU/Metal 不可用、以及證書與 systemd 單元漂移帶來的排障小時。若你追求與 Apple 工具鏈同機驗證、更少變量、以及可一鍵銷燬的試錯環境，在原生 macOS 上短租算力通常更省心；按天租用 Mac把硬件成本壓到與驗證窗口等長，適合在接入生產 Gateway 前做全量冒煙。
更穩妥的收尾：把本文矩陣與七步寫進變更單，和 v2026.4.14 路由文、MCP 審批文 交叉引用；需要套餐對比時打開 套餐頁 與 租用彩排成本文。