排错 · 模型连接

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

钳叔 · 龙虾AI 编辑部 · 2026-06 · 约 8 分钟

本体明明装好了，一让它干活就蹦出「连不上模型」——这一步把不少人挡在了门外。所幸这类问题有个好处：错误码会替你说话，401、429、timeout 各对应一种病因，认得它就不用瞎猜。下面按错误码和现象分节，每节给一条最快的定位顺序，照着走，不必逐行试。

先做一个 30 秒判断

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

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

先认清自己是哪种，再往下看对应的节。

按错误码排：API 这一侧

401 / 403：认证失败

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

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

解决：把 key 整段重新复制一遍，删掉首尾空格；确认 key 所属厂商和你填的接口地址一致；确认 key 还没过期、额度没欠费。

429：限流 / 额度用尽

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

原因：请求太频繁，或免费档额度用光。智能体跑长任务时一连串调用很容易撞上。

解决：给龙虾设置重试间隔、降低并发；额度不够就升级账户；如果某个模型长期撞 429，换一个额度更宽松的模型当大脑更省心，可参考 AI 模型榜。

404 / model not found：模型名写错

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

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

解决：对照厂商当前支持的模型名，原样填进配置，注意大小写和连字符。

timeout：连接超时

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

原因：网络到不了接口，或代理没配好。境外接口在国内网络下尤其常见。

解决：先确认本机能不能访问那个接口地址；该走代理就给龙虾进程也配上代理；如果是大任务返回慢，把超时时间调长一点。

500 / 503：对方服务出问题

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

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

解决：等一会儿重试，或临时切到备用模型。配了自动重试的话，龙虾通常能自己缓过来。

本地模型这一侧

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

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

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

解决：分两步查——先确认本地模型服务进程在跑、端口正确；再确认龙虾配置里的地址指向 http://localhost:端口 且端口一致。

Docker 里连不到宿主机模型

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

原因：容器里的 localhost 指的是容器自己，不是宿主机。

解决：容器里连宿主机服务，地址不能写 localhost，要用宿主机映射地址（很多环境下是 host.docker.internal）。Docker 相关细节见 用 Docker 装 OpenClaw。

一条万能排查顺序

1. 看错误码，对照上面找到对应节。
2. API 侧先验 key 和地址是不是一家，再看额度和网络。
3. 本地侧先确认服务在跑、端口对，再看地址有没有指错（尤其 Docker）。
4. 都不行就临时换一个模型试——如果换了就好，说明问题在原来那家而不在你。

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

常见问题

看到 401 是什么意思？

认证失败，几乎都是 API key 的问题：填错、过期、首尾带空格，或 key 跟模型地址不是同一家。重新复制 key、去掉首尾空格再试。

429 限流怎么办？

请求太频繁或额度用尽。放慢并发、设重试间隔，或升级额度。长任务一直撞 429 就换一个额度更宽的模型。

本地模型连不上怎么查？

先确认本地模型服务起来了、端口对，再确认龙虾里填的地址指向本机。Docker 里的龙虾连宿主机模型，地址不能写 localhost，要用宿主机映射地址。