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 审批文交叉引用；需要套餐对比时打开套餐页与租用彩排成本文。