必须逐段验证链路：先用lsof或netstat确认模型端口监听状态，再用curl测试服务可用性，接着检查openclaw gateway状态及日志中的转发地址是否匹配，最后严格核对openclaw.json中baseurl、model.id和api字段的一致性。
☞☞☞AI 智能聊天, 问答助手, AI 智能搜索, 多模态理解力帮你轻松跨越从0到1的创作门槛☜☜☜
OpenClaw调用本地部署的Qwen3.5-9B等模型时突然报“Connection refused”或“ETIMEDOUT”，不是模型没跑起来，就是网关没对上地址——这类错误必须按链路逐段验证，跳过任何一环都可能白忙两小时。
确认模型服务真实运行中
别信进程列表里的“python app.py”，要亲眼看到服务在监听端口：
执行 lsof -i :5000（macOS/Linux）或 netstat -ano | findstr :5000（Windows），检查是否有 LISTEN 状态的进程绑定到目标端口。
如果端口空闲，立刻启动模型服务；如果端口被占但不是你的模型进程，【kill掉冲突进程，否则curl测试永远返回connection refused】。
接着用 curl 直接发请求验证服务可用性：curl -X POST http://localhost:5000/v1/chat/completions -H "Content-Type: application/json" -d '{"model":"qwen3-9b","messages":[{"role":"user","content":"test"}]}'
这一步必须成功返回 JSON 响应。若返回 404，说明 API 路由不对（比如你用的是 vllm 启动但配置了 openai-completions 协议）；若返回 502，大概率是模型服务崩溃或 OOM 退出了。
检查 OpenClaw 网关是否正常转发
网关不等于模型服务，它是独立进程，负责把 OpenClaw 请求转给后端模型。先查状态：openclaw gateway status
如果显示 inactive 或 crashed，直接重启：openclaw gateway restart
重启后立即看日志流：openclaw gateway logs --follow
重点盯三类输出：① “Forwarding to http://…” 是否和你模型的 baseUrl 完全一致；② 出现 “ECONNREFUSED” 表示网关连不上模型；③ 出现 “timeout” 则说明网络通但模型响应太慢或卡死。
注意：网关重启后，OpenClaw 客户端不会自动重连，必须手动刷新页面或重启 CLI。
核对模型配置文件中的关键字段
打开 ~/.openclaw/openclaw.json，定位到 models.providers.qwen-local 段落。
方法一：baseUrl 必须与 curl 测试时的地址一字不差
比如模型实际运行在 http://127.0.0.1:5000，配置里却写了 http://localhost:5000，某些系统 DNS 解析会失败；更隐蔽的是写成 http://0.0.0.0:5000——这个地址只能被本机其他进程访问，网关无法绑定。
方法二：model.id 必须和模型实际声明的 ID 严格匹配
例如 vllm 启动命令中用了 --model Qwen/Qwen3.5-9B，那配置里 "id": "Qwen/Qwen3.5-9B" 才有效；写成 "qwen3-9b" 就会触发 modelnotfound 错误。
方法三：api 字段必须与模型服务协议对齐
本地 FastAPI 服务用 openai-completions 协议就填 "openai-completions"；若用的是 Ollama 格式，就得改成 "ollama-chat"。填错会导致网关解析 action 失败，日志里出现 “unknown api type”。
快速复位操作路径
第一步：停掉所有相关进程pkill -f "uvicorn\|vllm\|openclaw"（macOS/Linux）或任务管理器结束 python.exe、openclaw.exe 进程（Windows）
第二步：清空网关缓存rm -rf ~/.openclaw/gateway/cache/（macOS/Linux）或删除 %USERPROFILE%\.openclaw\gateway\cache\（Windows）
第三步：重新启动模型服务→等待 5 秒→执行 openclaw gateway restart→等待 3 秒→在 OpenClaw UI 中点击「Test Connection」按钮
