openclaw接口请求失败需四步排查：一查服务是否监听0.0.0.0:3000（非仅127.0.0.1）；二看日志是否卡在模型加载；三验api请求是否携带正确authorization头；四检防火墙及云安全组是否放行3000端口。
☞☞☞AI 智能聊天, 问答助手, AI 智能搜索, 多模态理解力帮你轻松跨越从0到1的创作门槛☜☜☜
OpenClaw部署后接口请求失败，说明服务虽已启动但无法正常响应外部调用，常见于端口未暴露、认证配置缺失、模型加载卡住或网络策略拦截等具体环节，需逐层验证。
确认服务是否真正监听在预期端口
执行 netstat -tuln | grep :3000（或你配置的端口），检查是否有 LISTEN 状态条目。没有输出，代表服务根本没绑定成功——此时不是接口“失败”，而是压根没起来。
若看到 127.0.0.1:3000 但看不到 0.0.0.0:3000，说明服务只绑定了本地回环，外部请求会被拒绝。必须确认启动命令中明确指定了 --host 0.0.0.0 或等效参数（如 FastAPI 的 host="0.0.0.0"）。
这一步漏掉，所有远程请求都会直接超时，连错误响应都收不到。
检查容器内服务日志是否卡在模型加载阶段
运行 docker logs openclaw-app --tail 50，重点观察最后几行是否停留在类似 Loading model 'Qwen2.5-7B-Instruct'... 或长时间无新日志输出。
模型体积大（常 >4GB）、磁盘 IO 慢、或显存不足时，加载可能耗时 3～10 分钟。此时接口返回 503 Service Unavailable 属正常现象，等待即可。
【注意：不要在加载完成前反复重启容器，否则会重复耗时】
若超过 15 分钟仍无 Uvicorn running on http://0.0.0.0:3000 类似日志，则大概率是模型路径错误或权重文件损坏，需重新挂载或校验 SHA256。
验证 API 认证头是否被强制启用
方法一：用 curl 直接绕过前端，测试裸接口
curl -X POST http://localhost:3000/v1/chat/completions -H "Content-Type: application/json" -d '{"model":"qwen","messages":[{"role":"user","content":"hi"}]}'
若返回 401 Unauthorized，说明 OpenClaw 启用了 API Key 校验但未传入。此时必须在请求头中添加 -H "Authorization: Bearer sk-xxx"，且该密钥需与启动时设置的 OPENCLAW_API_KEY 环境变量完全一致。
方法二：检查启动命令是否遗漏了认证开关
若使用 Docker 运行，确认命令中包含 -e OPENCLAW_API_KEY=your_secret_key。漏设该变量，服务会默认开启认证但无有效密钥，所有请求均被拒。
排查宿主机防火墙或云服务器安全组拦截
第一步：在部署机器上执行 telnet localhost 3000，能连上说明服务本地可达；
第二步：从另一台局域网机器执行 telnet your-server-ip 3000，失败则说明流量被中间层拦截；
第三步：Ubuntu 系统运行 sudo ufw status，若显示 Status: active 且无 3000 端口放行规则，执行 sudo ufw allow 3000；
阿里云/腾讯云用户，必须登录控制台，在对应 ECS 实例的“安全组”中手动添加入方向规则：协议类型 TCP，端口范围 3000，授权对象 0.0.0.0/0（或限定 IP 段）。
