LLM request timed out 这个报错接第三方 API 的朋友应该不陌生。OpenClaw 本身是个开源智能体框架跑起来很轻但一旦把模型源切到第三方兼容接口超时就像定时炸弹一样时不时爆一下。这篇文章把我自己调通的全过程写出来包括怎么定位、怎么调参数、怎么防复发给同样在坑里的朋友一个完整参考。先说结论这个报错绝大多数时候不是 OpenClaw 坏了而是整个请求链路里某个环节的响应速度超过了客户端等待上限。你可以把它理解成点外卖你下单之后商家迟迟不接单或者骑手迟迟不取货平台等得不耐烦了就告诉你“超时”。但具体是商家漏单、骑手堵车、还是平台自己网络不好得一层层看。下面我就按排查顺序把每个环节拆开讲。1. 先说清楚这个超时到底卡在哪一环想解决问题第一步不是改配置而是搞清楚 OpenClaw 从发起一次 LLM 请求到拿到结果中间到底经过哪些环节。很多人上来就调超时时间结果调了还是超时就是因为没定位准卡点。1.1 OpenClaw 调用第三方 API 的完整链路OpenClaw 作为一个开源智能体运行时核心工作是把用户的指令转换成对大模型 API 的调用。当模型源指向第三方兼容接口时一次请求大致经过以下几个环节OpenClaw 内部配置解析与模型客户端初始化模型 SDK 组装 HTTP 请求包括 headers、body、认证信息建立 TCP 连接完成 TLS 握手发送请求体等待第三方 API 网关响应第三方 API 网关转发请求到上游模型推理服务上游模型完成推理把结果逐段或一次性返回OpenClaw 收到响应解析并交给上层逻辑这里的任何一个环节拖延都可能表现为 LLM request timed out。我见过最离谱的情况是上游模型服务要排队第三方网关没设置合理的排队上限结果请求挂在网关内部十几秒才返回错误OpenClaw 这边早就超时放弃了。从超时类型上分客户端通常要区分两个阶段连接超时和读取超时。连接超时指的是 TCP 建连和 TLS 握手阶段如果第三方服务 IP 不通、端口被墙、TLS 握手慢这一阶段就会触发。读取超时则是指请求已经发出去但迟迟等不到响应数据常见于上游模型推理慢、网关排队、或者返回的数据量过大。用生活化类比就是连接超时是“你拨电话对方一直不接”读取超时是“电话接通了但对方半天不说话”。两种超时的排查方向完全不同前者偏向网络层面后者偏向服务处理能力。1.2 超时出现的三类典型场景我实际接触过的案例里出现超时的场景基本可以归成三类你先对号入座能省掉大量无用排查第一类是 OpenClaw 直连第三方聚合接口。这是最普遍的场景用户配置了某个第三方兼容服务作为模型源日常对话偶尔正常但请求一长或者并发一高就超时。这种问题多半出在第三方网关的稳定性或者配的模型名称对应的上游服务负载过高。第二类是第三方系统通过 API 调用 OpenClawOpenClaw 内部再去请求 LLM。这种情况下外部调用方可能设置了自己的超时阈值比如 30 秒而 OpenClaw 内部请求 LLM 就要花 40 秒外部系统先炸了。表面看是 OpenClaw 的问题实际上是整体调用链路的超时阈值没有对齐。第三类是批处理或者自动化任务场景。OpenClaw 在无人值守状态下跑批量任务多个请求几乎同时发出第三方网关的限流策略触发了排队部分请求等待时间超过阈值。这种往往是间歇性的问题复现全靠运气排查难度最大。区分这三类场景的意义在于第一类重点调 OpenClaw 到第三方之间的参数第二类要协调第三方系统那边的超时配置第三类要处理并发和限流。后面讲的排查步骤我会反复提到这个区分。2. 动手排查三步定位超时的真正原因定位问题讲究先易后难。我习惯的顺序是先查配置再做网络基准测试最后看日志。这三步走完90% 的超时问题都能锁到具体环节。2.1 先从最容易混淆的配置开始检查很多超时其实是配置错误导致的连锁反应。比如 Base URL 填错了请求打到了不存在的路径上第三方网关可能返回一个 404但 SDK 却在那里反复重试最终表现为超时。再比如模型名称填了一个第三方平台没有接入的模型网关内部查询模型路由表超时也会直接拖垮响应。我整理了几个高频配置错误你在排查时先对着过一遍配置项典型错误后果Base URL末尾多了/v1后又拼接了/v1请求路径 404反复重试直至超时API Key复制时带了空格或换行认证失败某些网关延迟返回 401模型名称大小写不对或版本号不匹配网关内部路由查询超时超时参数设了 10 秒但接口 P95 就要 15 秒正常请求也频繁超时Stream 参数请求未开启流式但期待快速首包等待完整响应时间过长这里要注意一个细节OpenClaw 的配置通常是 YAML 文件配合环境变量一起生效。如果你同时设置了环境变量和配置文件里的字段环境变量优先级更高。我遇到过一位开发者配置文件里超时设置得很合理但环境变量里残留了一个旧的超时值导致每次请求都在同一时间点被掐断。排查时要把两处都看一遍别只盯着配置文件。2.2 用 curl 直连第三方 API 做基准测试配置确认无误后下一步是把 OpenClaw 隔离掉直接用 curl 请求第三方 API看它的真实响应能力。这一步能快速判断问题到底在 OpenClaw 侧还是第三方服务侧。我常用的命令是这样的curl -v -X POST https://your-api-gateway.example.com/v1/chat/completions \ -H Content-Type: application/json \ -H Authorization: Bearer sk-xxx \ -d { model: your-model-name, messages: [{role: user, content: ping}], max_tokens: 16, stream: false } \ -w \n时间分解\n -w DNS解析: %{time_namelookup}s\n -w TCP连接: %{time_connect}s\n -w TLS握手: %{time_appconnect}s\n -w 首字节: %{time_starttransfer}s\n -w 总耗时: %{time_total}s\n关键要看三组数据TCP 连接时间、首字节时间TTFB、总耗时。如果 TCP 连接时间本身就超过 1 秒说明网络链路有问题如果 TCP 很快但 TTFB 很长说明第三方网关或上游模型推理慢如果总耗时比 TTFB 长很多说明响应体下载慢可能是返回内容太多或者网络带宽受限。光测一次不够。第三方 API 的响应时间是有波动的我建议至少测 10 到 20 次记录每次的耗时分布重点观察两个指标平均耗时和 P95 耗时。P95 的意思是最慢的 5% 请求的耗时临界值如果 P95 是 20 秒那你的超时时间至少要设到 25 秒以上否则 20 个请求里就有一个会挂。2.3 看 OpenClaw 日志里的关键时间戳curl 测试能确认第三方服务的基准能力但没法看到 OpenClaw 内部的调度逻辑。这个时候日志就是你最好的朋友。先把 OpenClaw 的日志级别调到 debug 或者 trace。不同版本的 OpenClaw 日志配置方式略有差异但一般都在配置文件里有个 log_level 字段。调完之后发起一次会超时的请求然后重点看日志里的几个时间点请求发起时间OpenClaw 开始组装请求的时刻HTTP 调用开始时间SDK 真正发出请求的时刻第三方响应时间第一批响应数据到达的时刻OpenClaw 抛错时间LLM request timed out 出现的时刻用这四个时间点做减法就能算出各阶段的耗时。如果从请求发起到 HTTP 调用开始就隔了好几秒说明问题出在 OpenClaw 内部可能是前置处理逻辑、插件机制或者上下文压缩占用了太多时间。如果 HTTP 调用开始到抛错之间正好等于你配置的超时时间那说明是第三方响应太慢OpenClaw 等不起。还有一种容易被忽略的情况系统时间不同步。如果 OpenClaw 所在机器的时间和第三方网关的时间偏差过大某些基于时间戳校验的 API 可能直接拒绝请求而表现就是请求被挂起直到超时。排查时顺手执行一下时间同步命令成本很低但收益明显。3. 核心解决手段参数调整与重试机制定位到问题之后接下来就是动手改参数了。这一部分我重点讲两个东西超时时间怎么调才科学以及重试机制怎么设计才不容易把问题放大。3.1 超时参数怎么调才不算乱调大多数 OpenClaw 部署在调用第三方 API 时超时配置会涉及两个字段连接超时和读取超时。连接超时对应的是建连阶段读取超时对应的是发出请求后等待响应的阶段。连接超时不建议设得太大5 到 10 秒足够。因为正常网络环境下TCP 建连加 TLS 握手通常在 1 到 2 秒内完成超过 10 秒还连不上说明网络链路大概率有问题继续等没有意义。读取超时则要看基准测试的结果。我的经验公式是读取超时 P95 响应耗时 × 1.5再往上取整到 10 的倍数。比如 curl 测试显示 P95 是 18 秒那读取超时就设为 30 秒如果 P95 是 7 秒就设为 15 秒。这个系数的意义在于给波动留出缓冲又不至于让单次请求占住线程太久。这里要特别提醒超时时间不是越长越好。很多人的第一个反应是把超时调到 300 秒觉得这样总不会超了。但超时时间过长会带来两个新问题一是 OpenClaw 内部线程被长时间占住并发能力下降二是第三方接口如果真的挂了你要等满 5 分钟才能感知到严重拖慢故障恢复速度。合理的做法是留足缓冲但不放纵。在 OpenClaw 的配置里常见的写法是model: provider: openai_compatible model_name: your-model-name api_base: https://your-api-gateway.example.com/v1 api_key: ${OPENCLAW_API_KEY} timeout: connect: 10s read: 30s如果你的 OpenClaw 版本采用的是环境变量方式那就是类似OPENCLAW_TIMEOUT_CONNECT10和OPENCLAW_TIMEOUT_READ30这种命名。具体字段名以你实际使用的版本文档为准但思路是一样的连接超时管建连读取超时管响应等待。3.2 流式响应是解决首包超时的关键很多第三方 API 默认非流式返回也就是说要等完整响应生成完才一次性返回。对于长文本场景整个生成过程可能要几十秒甚至几分钟客户端只能干等着超时几乎无法避免。流式响应Streaming能从根本上改变这个局面。开启流式后第三方 API 每生成一段 token 就立刻推送出来客户端第一时间就能收到数据不需要等完整响应。对 OpenClaw 来说收到第一批数据就代表请求活着读取超时也就不会那么容易被触发。流式响应的原理是 SSE也就是服务端推送事件。HTTP 连接会保持打开服务端不断往同一个连接里写数据块每个数据块以data: {choices: [...]}的形式出现。OpenClaw 收到后逐渐拼装出完整回复。但开了流式不等于万事大吉。这里有一个坑流式模式下服务端生成 token 的速度可能很不均匀有时候两批 token 之间的间隔会超过你设置的读超时。比如你设了 30 秒读超时但模型思考了 40 秒才输出第一个 token照样超时。所以流式模式下读取超时应该以“相邻数据块之间的最大间隔”为基准来设置而不是以完整响应的总耗时。如果你发现第三方 API 的流式输出经常出现长间隔可以考虑在 OpenClaw 侧开启“流式超时保护”机制。有些版本支持配置空闲超时idle timeout专门控制相邻数据块的最大间隔这个值可以比整体读取超时小很多比如 15 秒。3.3 重试与退避策略的合理设计超时之后再重试是很多人下意识的做法但盲目重试会让情况更糟。如果第三方服务已经过载你的重试请求等于又在排队末尾追加任务可能越试越慢最终把 OpenClaw 的请求队列全部堵死。正确的重试策略要看错误类型。HTTP 状态码 429 表示限流503 表示服务不可用超时类错误通常对应网关响应超时或连接被断开。这些属于可重试的错误。而 400、401、403 这类错误代表请求本身有问题重试 100 次也是同样的结果不要重试。重试间隔要用指数退避加抖动。指数退避的意思是每次重试的等待时间按指数增长比如第一次等 1 秒、第二次等 2 秒、第三次等 4 秒、第四次等 8 秒。抖动是在这个基础上加一个随机偏移避免多个客户端同时重试形成惊群效应。公式可以写成import random def backoff_delay(attempt: int, base: float 1.0, cap: float 30.0) - float: delay min(cap, base * (2 ** attempt)) jitter random.uniform(0, delay * 0.3) return delay jitter在 OpenClaw 中如果要实现重试优先看框架本身有没有内置的重试配置。有些第三方 SDK 自带自动重试但默认重试次数可能过多或过少。我建议把重试次数控制在 2 到 3 次超过这个数字之后再重试的成功率很低反而白白消耗资源。另一个值得注意的点重试时要不要重新构造请求体对于 LLM 调用如果上下文里带有时间戳或者随机采样参数重新构造请求可能导致生成结果不一致。OpenClaw 内部一般会保存原始请求的不可变快照重试时直接复用这个设计是合理的不需要你自己处理。4. 针对第三方 API 的专项优化前面讲的都是 OpenClaw 侧的参数调整。但第三方 API 本身的不稳定性才是超时的根本来源这一节专门讲怎么应对第三方服务的各种异常表现。4.1 第三方 API 网关响应的不稳定因素第三方兼容接口本质上是一个或多或少的聚合网关它自身的稳定性取决于上游模型服务的负载、网关的队列设计、以及限流策略。我实测过一家聚合服务的耗时数据同样一个请求凌晨 2 点的 P95 是 6 秒下午 3 点的 P95 直接飙到 25 秒。这说明单纯调大超时并不能根治问题高峰期还是会触发超时。网关的不稳定主要来自几个方面上游模型推理服务的排队时间、网关自身的 CPU 和内存瓶颈、限流策略触发的排队等待、以及跨地域网络链路的抖动。你可以通过长期监控来掌握它的规律比如每天固定时间跑一次 curl 基准测试积累一周数据基本就能看出高峰期分布。如果第三方网关的 P95 和 P99 差距特别大说明它的服务质量很不稳定。这种情况下我会考虑两个方向一是寻找备用的第三方服务二是降低对它的依赖比如把一些固定模式的请求改成本地规则处理。4.2 请求体瘦身与上下文管理请求体大小是影响超时的一个隐蔽因素。LLM 请求的耗时和总 token 数呈正相关上下文越长模型处理的时间越长第三方网关转发的数据量也越大。如果你发给第三方 API 的请求动辄几万 token超时几乎是必然的。我处理过一个案例某开发者给 OpenClaw 配置了很长的 system prompt又开了长期记忆功能每次请求都把历史消息完整带上token 数经常到两万以上。第三方 API 处理这样的请求需要将近 30 秒远超默认超时时间。解决方案是上下文瘦身。OpenClaw 通常支持上下文压缩机制把历史消息做摘要只保留最近几轮完整消息再往前的用摘要代替。你也可以手动调小单次请求携带的最大 token 数或者对 system prompt 做精简。瘦身之后请求耗时能下降 50% 以上。另外一个参数是max_tokens它决定了模型最多生成多少 token。如果这个值设得很大模型生成时间就长。在需要快速响应的场景下适当限制输出长度能显著降低总耗时。比如客服机器人回复一般不会超过 200 字max_tokens设 300 就够没必要给 2000。4.3 多路回退与本地兜底方案单点依赖第三方 API 永远是风险最大的方案因为它一挂你的整个 OpenClaw 服务都跟着挂。我的建议是至少配置两个可用的模型来源做好故障切换。OpenClaw 支持配置多个 provider某些版本还支持自动故障切换。配置思路是主 provider 指向稳定的第三方服务备用 provider 可以指向另一家服务或者本地部署的模型。当主 provider 连续超时达到阈值时自动把请求切换到备用 provider。这样即便第三方 API 高峰期不稳定你的服务也能兜底。还有一种更轻量的兜底方案适用于一些固定场景的问答。比如你跑的是智能客服常见问题的高频回复完全可以做成模板或者本地规则。OpenClaw 收到请求后先走本地匹配匹配不到再走 LLM。这虽然不是 AI 优先的做法但能大幅降低对第三方 API 的依赖减少被超时影响的概率。5. 实操记录一次完整的排障过程理论讲再多也不如一次实操来得直观。这个案例是我帮一位开发者处理的症状就是间歇性 LLM request timed out非常典型。5.1 问题复现那位开发者的环境是 OpenClaw 部署在一台云服务器上模型源指向某第三方兼容 API。现象是对话偶尔正常有时候连续几次请求都报 LLM request timed out过一会儿又自己恢复。出错频率大约每 10 次请求出现 1 到 2 次完全没有规律可循。我让他做了一件事把报错前后 10 分钟的 OpenClaw 日志完整保留下来同时用 curl 手动测同一个第三方 API 的响应时间。结果很说明问题手动 curl 测试偶尔也会超时但比 OpenClaw 的频率低很多。这一步基本确认了第三方 API 本身就不稳定但 OpenClaw 的某些配置放大了这种不稳定性。5.2 逐步验证我让他按步骤验证了几个点第一步检查配置文件里的超时设置。发现他设置的是 20 秒读取超时但 curl 测试显示第三方 API 的 P95 响应时间是 22 秒。也就是说每 20 个请求至少有 1 个的响应时间超过他的超时阈值超时当然会发生。第二步查看日志里每次超时前的请求特征。发现超时的请求全部集中在上下文长度超过 8000 token 的场景。而短对话请求很少超时。这说明问题不仅和第三方 API 的负载有关还和请求体大小有关。第三步检查并发情况。日志显示他的 OpenClaw 配置了多个会话同时运行高峰期会有 5 个请求同时打到第三方 API。第三方网关在并发请求到来时出现了明显的排队个别请求的响应时间被拉长到 30 秒以上。三个因素叠加在一起第三方 API 本身 P95 偏高、请求体过大、并发触发排队。任何一个单独拿出来都不是致命问题但合在一起就把 20 秒超时时间打穿了。5.3 最终配置针对这个案例我们做的调整如下读取超时从 20 秒调到 45 秒缓冲区间按 P95 乘以 1.5 再加余量开启上下文压缩把超长历史会话的消息进行摘要控制单次请求在 6000 token 以内最大并发数限制到 3避免同时太多请求打向第三方 API重试次数设为 2 次采用指数退避第一次等 1 秒、第二次等 2 秒增加了一个备用 provider主 provider 连续超时 3 次后自动切换调整之后稳定跑了两周没有再出现过一次 LLM request timed out。配置大概长这样model: provider: openai_compatible model_name: your-model-name api_base: https://your-api-gateway.example.com/v1 api_key: ${OPENCLAW_API_KEY} max_tokens: 1024 stream: true timeout: connect: 10s read: 45s advanced: max_concurrency: 3 context_compression: true context_target_tokens: 6000 retry: max_attempts: 2 backoff_base: 1s backoff_multiplier: 2 retry_on_http: [429, 503]这个配置不是标准答案但它反映了真实世界里解决超时问题需要的几个必要动作给足缓冲、降低负载、控制并发、设置兜底。6. 常见问题速查表与避坑心得最后整理一个速查表方便你遇到问题时快速对照。同时分享几个写文档的人通常不会写进文档里的经验。6.1 快速对照表现象可能原因解决方向每次都在相同时间点超时环境变量覆盖了配置文件的超时值检查环境变量和配置文件优先级请求偶尔超时手动 curl 正常并发请求触发第三方网关限流降低 OpenClaw 最大并发数长对话必超时短对话正常上下文 token 过多导致处理变慢开启上下文压缩或裁剪历史消息流式模式下仍超时相邻 token 间隔超过读超时配置独立的空闲超时参数切换模型后开始超时模型名称不匹配或模型负载过高核对模型名或更换备用模型重启后超时消失运行几小时后复发第三方网关或本机连接被逐步耗尽检查连接复用配置和资源泄漏使用第三方聚合服务超时聚合网关排队机制不合理更换服务、配置备用 provider 或本地兜底6.2 几个写文档的人不会告诉你的坑第一个坑健康检查比超时调优更重要。很多人只盯着超时参数改来改去却忘了给第三方 API 加健康检查。我建议在 OpenClaw 侧配置定期探测比如每 30 秒发一次极简请求连续失败就标记服务不可用并切换。这样能把故障发现时间从几分钟缩短到几十秒。第二个坑不要把重试做成放大器。如果你的重试间隔很短比如 100 毫秒第三方服务还在过载中你的重试请求会加剧排队形成恶性循环。我见过一个案例OpenClaw 默认重试 3 次且间隔很短结果每次超时后第三方服务的负载反而更高。重试间隔一定要按指数退避来设必要时加随机抖动。第三个坑流式响应不是万能的。有些第三方 API 对流式支持得并不好或者流式模式下 TTFB 反而更长。开启流式之前先用 curl 对比流式和非流式的首包时间。如果流式的 TTFB 更长说明网关对流式处理有额外开销这时候流式并不能解决超时问题。第四个坑版本升级要慎重。OpenClaw 本身迭代很快新版本可能改动了超时字段名、重试逻辑或者线程模型。升级前先看 changelog重点看有没有涉及网络层和请求调度的改动。我曾经在升级后遇到超时行为完全变化的情况最后发现是新版本重写了连接池的复用逻辑导致部分请求排队等待空闲连接而旧版本没有这个问题。第五个坑不要忽略时区问题。如果你的日志和第三方 API 的响应头里都有时间戳而两边时区不一致排查超时时对不上时间线会非常痛苦。统一使用 UTC 记录日志能省去大量对时间的精力。我个人在实际操作中的体会是LLM request timed out 这种问题八成都不是代码 bug而是资源和使用方式的错配。只要你能接受“第三方 API 就是会慢”这个现实然后从超时阈值、请求体大小、并发数三个维度去做合理设计绝大部分超时都能在配置层面解决。剩下那部分解决不了的多半是第三方服务本身的稳定性问题那就不是调参能解决的了该换服务就换服务该做兜底就做兜底。希望这篇排障记录能帮你少走几天弯路。