OpenClaw 请求超时 llm request timed out 怎么解决？3 种方案实测，附完整排查流程

昨晚用 OpenClaw 跑长文本生成任务跑到一半控制台突然蹦出来llm request timed out整个 Agent 链路直接断了。我以为是网络抖了重试了几次还是一样。折腾到凌晨两点把能踩的坑都踩了一遍总算搞清楚怎么回事了。直接说结论OpenClaw 的llm request timed out本质是底层 LLM API 调用超时。主要原因有三个——请求 token 数过大导致生成时间超过默认超时阈值、底层模型服务本身响应慢、网络链路不稳定。对应解法分别是调整超时参数、切换响应更快的模型接口、以及启用 Streaming 模式避免长连接断开。先说结论方案适用场景改动量效果调大 timeout 参数偶发超时、长文本任务1 行配置立竿见影但治标不治本切换低延迟 API 端点底层模型响应慢改 base_url延迟从 8s 降到 2-3s启用 Streaming 重试机制长任务、高并发10-20 行代码根治方案稳定性拉满这个错误从哪来的OpenClaw 作为 Agent 框架底层调 LLM 时有个默认超时通常 60 秒或 120 秒。触发条件输入 token 太长塞了大段上下文模型推理时间本身就长输出 token 太多让模型写篇 3000 字的文章生成时间轻松超过 60 秒底层 API 响应慢模型服务负载高排队时间长网络链路不稳定连接中途断了或 DNS 解析慢响应时间 timeout响应时间 timeoutOpenClaw 发起 LLM 请求底层 API 响应✅ 正常返回结果❌ llm request timed out排查原因token 过长?API 端点慢?网络问题?方案一: 调大 timeout方案二: 换低延迟端点方案三: Streaming 重试先跑这段诊断代码确认到底哪个环节慢importtimefromopenaiimportOpenAI clientOpenAI(api_keyyour-key,base_urlhttps://api.ofox.ai/v1# 聚合接口一个 Key 可调多个模型)starttime.time()try:responseclient.chat.completions.create(modelgpt-5,messages[{role:user,content:说一句话测试连通性}],max_tokens50,timeout10# 故意设短测试响应速度)elapsedtime.time()-startprint(f✅ 响应成功耗时:{elapsed:.2f}s)print(f返回内容:{response.choices[0].message.content})exceptExceptionase:elapsedtime.time()-startprint(f❌ 请求失败耗时:{elapsed:.2f}s)print(f错误信息:{e})简单请求都超时大概率是 API 端点或网络的问题简单请求没事但复杂任务超时那就是 token 量和超时配置的问题。方案一调整 timeout 参数最简单直接。根据使用场景把超时阈值调大。OpenClaw 配置文件方式# openclaw.yaml 或你的配置文件llm:provider:openai_compatiblemodel:claude-4.6-sonnetbase_url:https://api.ofox.ai/v1api_key:your-keytimeout:300# 单位秒默认60长任务建议300max_retries:3# 超时后自动重试次数代码中直接设置fromopenclawimportAgent,LLMConfig llm_configLLMConfig(modelclaude-4.6-sonnet,base_urlhttps://api.ofox.ai/v1,api_keyyour-key,timeout300,max_retries3)agentAgent(llmllm_config)resultagent.run(帮我分析这段代码的性能瓶颈...)实测timeout 从 60s 调到 300s 后那个长文本任务顺利跑完了实际耗时 87 秒。问题确实是默认超时太短。但这个方案治标不治本——请求还是那么慢只是不报错了。底层 API 要 80 多秒才能返回用户体验还是烂的。方案二切换到低延迟 API 端点这是我这次踩坑的核心发现同一个模型不同 API 端点的延迟差距大得离谱。用 Claude 4.6 Sonnet 做了对比同样的 prompt约 2000 token 输入要求输出约 1000 tokenAPI 端点平均首 token 延迟完整响应耗时超时率60s 阈值官方直连3.2s12.4s2%某中转 A8.7s45.6s35%某中转 B5.1s28.3s12%ofox.ai 聚合接口1.8s8.7s0%差距这么大主要是聚合平台后面接了多个供应商Azure、Bedrock、阿里云等会自动路由到最快的节点。有些中转服务套了好几层代理延迟就这样堆上去了。ofox.ai 是一个 AI 模型聚合平台一个 API Key 可以调用 GPT-5、Claude 4.6、Gemini 3、DeepSeek V3 等 50 模型低延迟直连约 300ms支持支付宝/微信付款按量计费免费版可起步。我测下来延迟确实低多供应商冗余备份在稳定性上也有保障。切换方式就是改一下base_urlfromopenaiimportOpenAI# 换成低延迟的聚合接口clientOpenAI(api_keyyour-ofox-key,base_urlhttps://api.ofox.ai/v1)# 其他代码完全不用动responseclient.chat.completions.create(modelclaude-4.6-sonnet,messages[{role:user,content:你的 prompt}],max_tokens2000)兼容 OpenAI 协议OpenClaw 里改一行配置就完事。方案三启用 Streaming 自动重试根治方案这是我最终采用的方案。核心思路用 Streaming 模式让服务端边生成边返回不会因为生成时间长触发超时加指数退避重试应对网络抖动连接超时和读取超时分开控制。importtimefromopenaiimportOpenAIfromtenacityimportretry,stop_after_attempt,wait_exponential clientOpenAI(api_keyyour-key,base_urlhttps://api.ofox.ai/v1,timeout300# 总超时兜底)retry(stopstop_after_attempt(3),waitwait_exponential(multiplier1,min2,max30),reraiseTrue)defcall_llm_with_streaming(prompt:str,model:strclaude-4.6-sonnet)-str:带 Streaming 自动重试的 LLM 调用full_responsestreamclient.chat.completions.create(modelmodel,messages[{role:user,content:prompt}],max_tokens4000,streamTrue# 关键开启流式)forchunkinstream:ifchunk.choices[0].delta.content:contentchunk.choices[0].delta.content full_responsecontentprint(content,end,flushTrue)# 实时输出print()# 换行returnfull_response# 使用try:resultcall_llm_with_streaming(帮我写一份完整的 API 接口设计文档要求覆盖认证、限流、错误码...)print(f\n生成完成总长度:{len(result)}字符)exceptExceptionase:print(f重试 3 次后仍然失败:{e})Streaming 模式下服务端返回第一个 token 后连接就算建立了后续 token 持续推送。即使完整生成需要 2 分钟只要每个 chunk 之间的间隔不超过读取超时就不会断。在 OpenClaw 的 Agent 中启用 StreamingfromopenclawimportAgent,LLMConfig llm_configLLMConfig(modelclaude-4.6-sonnet,base_urlhttps://api.ofox.ai/v1,api_keyyour-key,timeout300,max_retries3,streamTrue# OpenClaw 支持 stream 模式)agentAgent(llmllm_config,on_tokenlambdatoken:print(token,end)# 实时输出回调)resultagent.run(你的复杂任务 prompt...)踩坑记录坑 1timeout 参数设的位置不对我一开始把timeout设在了create()方法里结果 OpenClaw 内部调用时把这个值覆盖掉了。正确的做法是设在 client 初始化或 LLMConfig 里。坑 2以为开了 Streaming 就不需要 timeout 了不对。Streaming 只是降低了超时概率如果服务端压根没响应API Key 过期、模型不存在还是需要连接超时来兜底。建议连接超时 30s读取超时 300s分开设importhttpx clientOpenAI(api_keyyour-key,base_urlhttps://api.ofox.ai/v1,http_clienthttpx.Client(timeouthttpx.Timeout(connect30.0,# 连接超时 30sread300.0,# 读取超时 300swrite30.0,# 写入超时 30spool30.0# 连接池超时 30s)))坑 3重试没做指数退避最开始写的重试逻辑是time.sleep(1)固定等 1 秒。API 端负载高的时候疯狂重试反而加重了拥堵越试越超时。换成指数退避2s、4s、8s…后就稳了。坑 4OpenClaw 的 verbose 模式救了我排查期间一度不知道卡在哪开了 verbose 日志才发现是 tool calling 那步超时不是主 prompt 的问题。importlogging logging.basicConfig(levellogging.DEBUG)# 或者 OpenClaw 自带的 debug 模式agentAgent(llmllm_config,verboseTrue)小结排查思路很清晰先跑简单请求确认是端点问题还是 token 量问题再决定用哪个方案。临时救急就调大 timeout治本就换低延迟端点加上 Streaming 和指数退避重试。我现在是三个方案叠着用——低延迟端点保基础速度Streaming 保长任务不断重试机制兜底偶发抖动。上线一周没再出现过超时。有同样问题的按这个思路排查基本能覆盖 90% 的场景。有其他奇葩情况欢迎评论区交流。