龙虾连不上模型/API：超时、401、限流怎么排

报错来自云端 API 还是本地模型

分两种情况，排查路子不同：

• 接的是闭源 API（Claude、GPT 等）：查 key、地址、额度、网络。
• 接的是本地模型（Ollama 等本地服务）：查服务有没有起来、地址有没有指错。

云端 API 报错：401、429、404、400、timeout、500 各怎么处理

401：认证失败

现象：请求一发出立刻被拒，日志里写 401 Unauthorized。

原因：API key 填错、过期、首尾带了空格，或者 key 跟模型地址不是同一家（拿 A 家的 key 去连 B 家的接口）。

解决：先找到这把 key 存在哪里，分三种情况：

• 装在本机、key 写在 ~/.openclaw/.env 里的：把对应那一行的 key 整段重新复制一遍，删掉首尾空格。
• 用 Docker 装的：改仓库根目录的 .env，改完跑 docker compose up -d openclaw-gateway，让 Gateway 按新值重建。
• .env 里没有那一行的：用 openclaw models auth list 查已经存下的凭据，再用 openclaw models auth paste-api-key --provider <服务商> 重填。

key 换好以后，再确认它所属的厂商和你填的接口地址一致，没过期、额度没欠费。

日志里是 403 的不归这一条：官方排障文档把上游返回 403 单列成一节，见 Upstream 403 blocked responses。

429：限流 / 额度用尽

现象：偶尔能用，一忙起来就 429 Too Many Requests。

原因：请求太频繁，或免费档额度用光。

解决：是频率超了，就少开同时跑的任务、隔一会儿再发；额度不够就升级账户；某个模型一直报 429，就换一个额度更宽的模型，候选见 模型选型。也可以挂一个备用模型：在 ~/.openclaw/openclaw.json 的 agents.defaults.model.fallbacks 里加一项，配置块的写法在接 API 还是本地模型讲 fallbacks 的那一节。

模型名照 openclaw models list --provider <服务商> 查到的原样填，写完跑 openclaw models fallbacks list 看备用列表里有没有它。

404 / model not found：模型名写错

现象：报 model not found 或 404，但 key 是对的。

原因：配置里的模型名拼错，或用了已经下线的旧模型名。

解决：用 openclaw models list --provider <服务商> 查确切写法，原样填进配置，注意大小写和连字符。Anthropic 一侧，Claude Opus 5、Fable 5、Sonnet 5 已进 Legacy 列表但仍可调用；截至 2026-10-07，官方给 Haiku 4.5 的退役时间是不早于 2026-10-15。

400：请求里带了模型不接受的设置

现象：key 和模型名都对，换到新型号后请求直接被拒，返回 400。

原因：有的新型号不接受旧型号能用的设置，例如 Claude Opus 5.5 的思考不能关闭，强制 tool_choice 会返回 400。

解决：配置里手动写过关闭思考或强制 tool_choice 的，把那一项去掉再试。Opus 5 与 Opus 5.5 的设置对照见龙虾AI 接 Claude Opus 5。

timeout：连接超时，用 curl 测接口地址通不通

现象：请求挂很久，最后 connection timeout 或 read timeout。

原因：跑 Gateway 的那台机器到不了模型接口的地址。

解决：分两步。第一步，在跑 Gateway 的那台机器上（装在服务器上的就登到服务器上）用 curl 测接口地址，域名换成你接的那家：

curl -sS -m 10 -o /dev/null -w "%{http_code}\n" https://<模型接口域名>

Windows 的 PowerShell 里，把开头的 curl 写成 curl.exe，-o /dev/null 换成 -o NUL。10 秒内打出一个状态码（哪怕是 401 或 404），说明网络是通的；报 timed out 或 Could not resolve host，说明这台机器连不到那个地址。

第二步按结果分开处理。curl 也不通的，问题在网络这一层：换一条能访问该地址的线路，或者换到能访问它的机器上跑，直到这条 curl 能打出状态码。curl 通、龙虾还是超时的，跑 openclaw models status 和 openclaw logs --follow，看日志里超时的是哪个地址，和你测的是不是同一个。

500 / 503：对方服务出问题

现象：500 或 503，时好时坏。

原因：这是模型服务端自己的故障或过载，不是你的配置错。

解决：等一会儿重试，或临时切到备用模型。

本地模型报错：connection refused 和 Docker 里连不到宿主机

connection refused：本地服务没起来 / 地址指错

现象：连本地模型时报 connection refused。

原因：本地模型服务根本没启动，或龙虾里填的地址、端口对不上。

解决：在跑 Gateway 的那台机器上直接请求模型服务的地址，以 Ollama 的默认端口为例：

curl http://127.0.0.1:11434
openclaw models list --provider ollama

第一条有响应，说明服务在跑、端口没错；报 connection refused 就是服务没起来或端口不对，把模型服务启动起来再测。第一条通、第二条列不出模型的，看龙虾配置里填的地址和端口是不是这一个。

Docker 里连不到宿主机模型

现象：命令行能连本地模型，把龙虾放进 Docker 后就连不上了。

原因：两个。容器里的 localhost 和 127.0.0.1 指的是容器自己，不是宿主机；宿主机上的模型服务如果只监听本机回环，容器也连不进来。

解决：龙虾配置里的地址改成 host.docker.internal，Ollama 是 http://host.docker.internal:11434。宿主机上的模型服务要监听 Docker 够得着的地址，Ollama 这样起：

OLLAMA_HOST=0.0.0.0:11434 ollama serve

0.0.0.0 是监听所有网卡。机器在云上的，要让安全组或系统防火墙拦住从公网进来的 11434 端口。

容器这边还要有 host.docker.internal 到宿主机的映射，官方 compose 已经带了。自己写 compose 文件的，在 Gateway 那个服务下面加 extra_hosts: ["host.docker.internal:host-gateway"]；用 docker run 起的，加参数 --add-host=host.docker.internal:host-gateway。更多细节见 用 Docker 装 OpenClaw。

分不清是哪一类时，按这个顺序查

1. 跑 openclaw models status 和 openclaw doctor，把输出留下。
2. 看错误码，对照上面找到对应的小节。
3. API 侧：key 和接口地址是不是同一家，额度够不够，curl 测接口地址通不通。
4. 本地侧：服务在不在跑、端口对不对，地址有没有指错（放在 Docker 里的重点看这一项）。
5. 都不行就临时换一个模型试。换了就好，说明问题出在原来那家服务商或那个模型的配置上。

还没接过模型、想搞清楚 API 和本地两条路怎么选，看 接 API 还是本地模型。装本体阶段的报错另见 10 个安装报错对照。

常见问题

在会话里用 /model 选了模型，它连不上时为什么不切到备用模型？

会话里用 /model 手动选的模型是严格的：它连不上时这次回复直接报错，不会顺着 agents.defaults.model.fallbacks 往下切。配置里的默认模型和定时任务的主模型才走备用列表。

Anthropic 报 429 Extra usage is required for long context requests 怎么办？

这条 429 是长上下文请求需要额外用量，官方排障文档把它单列成一节，给的三个方向是改用标准上下文窗口、换一个符合条件的凭证、配备用模型。

本地的 /v1 接口直接 curl 是通的，放进 OpenClaw 却失败？

官方排障文档分三种情况：报错提到 messages[].content 要字符串的，给这个模型设 compat.requiresStringContent: true；只在 OpenClaw 的智能体对话里失败的，设 compat.supportsTools: false 再试；小请求能过、大提示词把后端压垮的，是模型或推理服务自己的上限。这两个开关写在 models.providers 里该模型条目的 compat 下。