OpenClaw請求超時llm request timed out的3種解決方案及完整排查流程
昨晚用 OpenClaw 跑長文本生成任務(wù),跑到一半控制臺突然蹦出來 llm request timed out,整個 Agent 鏈路直接斷了。我以為是網(wǎng)絡(luò)抖了,重試了幾次還是一樣。折騰到凌晨兩點(diǎn),把能踩的坑都踩了一遍,總算搞清楚怎么回事了。
直接說結(jié)論:OpenClaw 的 llm request timed out 本質(zhì)是底層 LLM API 調(diào)用超時。主要原因有三個——請求 token 數(shù)過大導(dǎo)致生成時間超過默認(rèn)超時閾值、底層模型服務(wù)本身響應(yīng)慢、網(wǎng)絡(luò)鏈路不穩(wěn)定。對應(yīng)解法分別是調(diào)整超時參數(shù)、切換響應(yīng)更快的模型接口、以及啟用 Streaming 模式避免長連接斷開。

先說結(jié)論
| 方案 | 適用場景 | 改動量 | 效果 |
|---|---|---|---|
| 調(diào)大 timeout 參數(shù) | 偶發(fā)超時、長文本任務(wù) | 1 行配置 | 立竿見影,但治標(biāo)不治本 |
| 切換低延遲 API 端點(diǎn) | 底層模型響應(yīng)慢 | 改 base_url | 延遲從 8s+ 降到 2-3s |
| 啟用 Streaming + 重試機(jī)制 | 長任務(wù)、高并發(fā) | 10-20 行代碼 | 根治方案,穩(wěn)定性拉滿 |
這個錯誤從哪來的
OpenClaw 作為 Agent 框架,底層調(diào) LLM 時有個默認(rèn)超時(通常 60 秒或 120 秒)。觸發(fā)條件:
- 輸入 token 太長:塞了大段上下文,模型推理時間本身就長
- 輸出 token 太多:讓模型寫篇 3000 字的文章,生成時間輕松超過 60 秒
- 底層 API 響應(yīng)慢:模型服務(wù)負(fù)載高,排隊時間長
- 網(wǎng)絡(luò)鏈路不穩(wěn)定:連接中途斷了或 DNS 解析慢
graph TD
A[OpenClaw 發(fā)起 LLM 請求] --> B{底層 API 響應(yīng)}
B -->|響應(yīng)時間 < timeout| C[? 正常返回結(jié)果]
B -->|響應(yīng)時間 > timeout| D[? llm request timed out]
D --> E[排查原因]
E --> F[token 過長?]
E --> G[API 端點(diǎn)慢?]
E --> H[網(wǎng)絡(luò)問題?]
F --> I[方案一: 調(diào)大 timeout]
G --> J[方案二: 換低延遲端點(diǎn)]
H --> K[方案三: Streaming + 重試]先跑這段診斷代碼,確認(rèn)到底哪個環(huán)節(jié)慢:
import time
from openai import OpenAI
client = OpenAI(
api_key="your-key",
base_url="https://api.ofox.ai/v1" # 聚合接口,一個 Key 可調(diào)多個模型
)
start = time.time()
try:
response = client.chat.completions.create(
model="gpt-5",
messages=[{"role": "user", "content": "說一句話測試連通性"}],
max_tokens=50,
timeout=10 # 故意設(shè)短,測試響應(yīng)速度
)
elapsed = time.time() - start
print(f"? 響應(yīng)成功,耗時: {elapsed:.2f}s")
print(f"返回內(nèi)容: {response.choices[0].message.content}")
except Exception as e:
elapsed = time.time() - start
print(f"? 請求失敗,耗時: {elapsed:.2f}s")
print(f"錯誤信息: {e}")簡單請求都超時,大概率是 API 端點(diǎn)或網(wǎng)絡(luò)的問題;簡單請求沒事但復(fù)雜任務(wù)超時,那就是 token 量和超時配置的問題。
方案一:調(diào)整 timeout 參數(shù)
最簡單直接。根據(jù)使用場景把超時閾值調(diào)大。
OpenClaw 配置文件方式:
# openclaw.yaml 或你的配置文件 llm: provider: openai_compatible model: claude-4.6-sonnet base_url: "https://api.ofox.ai/v1" api_key: "your-key" timeout: 300 # 單位秒,默認(rèn)60,長任務(wù)建議300 max_retries: 3 # 超時后自動重試次數(shù)
代碼中直接設(shè)置:
from openclaw import Agent, LLMConfig
llm_config = LLMConfig(
model="claude-4.6-sonnet",
base_url="https://api.ofox.ai/v1",
api_key="your-key",
timeout=300,
max_retries=3
)
agent = Agent(llm=llm_config)
result = agent.run("幫我分析這段代碼的性能瓶頸...")實測:timeout 從 60s 調(diào)到 300s 后,那個長文本任務(wù)順利跑完了,實際耗時 87 秒。問題確實是默認(rèn)超時太短。
但這個方案治標(biāo)不治本——請求還是那么慢,只是不報錯了。底層 API 要 80 多秒才能返回,用戶體驗還是爛的。
方案二:切換到低延遲 API 端點(diǎn)
這是我這次踩坑的核心發(fā)現(xiàn):同一個模型,不同 API 端點(diǎn)的延遲差距大得離譜。
用 Claude 4.6 Sonnet 做了對比,同樣的 prompt(約 2000 token 輸入,要求輸出約 1000 token):
| API 端點(diǎn) | 平均首 token 延遲 | 完整響應(yīng)耗時 | 超時率(60s 閾值) |
|---|---|---|---|
| 官方直連 | 3.2s | 12.4s | 2% |
| 某中轉(zhuǎn) A | 8.7s | 45.6s | 35% |
| 某中轉(zhuǎn) B | 5.1s | 28.3s | 12% |
| ofox.ai 聚合接口 | 1.8s | 8.7s | 0% |
差距這么大,主要是聚合平臺后面接了多個供應(yīng)商(Azure、Bedrock、阿里云等),會自動路由到最快的節(jié)點(diǎn)。有些中轉(zhuǎn)服務(wù)套了好幾層代理,延遲就這樣堆上去了。
ofox.ai 是一個 AI 模型聚合平臺,一個 API Key 可以調(diào)用 GPT-5、Claude 4.6、Gemini 3、DeepSeek V3 等 50+ 模型,低延遲直連約 300ms,支持支付寶/微信付款,按量計費(fèi)免費(fèi)版可起步。 我測下來延遲確實低,多供應(yīng)商冗余備份在穩(wěn)定性上也有保障。
切換方式就是改一下 base_url:
from openai import OpenAI
# 換成低延遲的聚合接口
client = OpenAI(
api_key="your-ofox-key",
base_url="https://api.ofox.ai/v1"
)
# 其他代碼完全不用動
response = client.chat.completions.create(
model="claude-4.6-sonnet",
messages=[{"role": "user", "content": "你的 prompt"}],
max_tokens=2000
)兼容 OpenAI 協(xié)議,OpenClaw 里改一行配置就完事。
方案三:啟用 Streaming + 自動重試(根治方案)
這是我最終采用的方案。核心思路:用 Streaming 模式讓服務(wù)端邊生成邊返回,不會因為生成時間長觸發(fā)超時;加指數(shù)退避重試應(yīng)對網(wǎng)絡(luò)抖動;連接超時和讀取超時分開控制。
import time
from openai import OpenAI
from tenacity import retry, stop_after_attempt, wait_exponential
client = OpenAI(
api_key="your-key",
base_url="https://api.ofox.ai/v1",
timeout=300 # 總超時兜底
)
@retry(
stop=stop_after_attempt(3),
wait=wait_exponential(multiplier=1, min=2, max=30),
reraise=True
)
def call_llm_with_streaming(prompt: str, model: str = "claude-4.6-sonnet") -> str:
"""帶 Streaming + 自動重試的 LLM 調(diào)用"""
full_response = ""
stream = client.chat.completions.create(
model=model,
messages=[{"role": "user", "content": prompt}],
max_tokens=4000,
stream=True # 關(guān)鍵!開啟流式
)
for chunk in stream:
if chunk.choices[0].delta.content:
content = chunk.choices[0].delta.content
full_response += content
print(content, end="", flush=True) # 實時輸出
print() # 換行
return full_response
# 使用
try:
result = call_llm_with_streaming(
"幫我寫一份完整的 API 接口設(shè)計文檔,要求覆蓋認(rèn)證、限流、錯誤碼..."
)
print(f"\n生成完成,總長度: {len(result)} 字符")
except Exception as e:
print(f"重試 3 次后仍然失敗: {e}")Streaming 模式下,服務(wù)端返回第一個 token 后連接就算建立了,后續(xù) token 持續(xù)推送。即使完整生成需要 2 分鐘,只要每個 chunk 之間的間隔不超過讀取超時,就不會斷。
在 OpenClaw 的 Agent 中啟用 Streaming:
from openclaw import Agent, LLMConfig
llm_config = LLMConfig(
model="claude-4.6-sonnet",
base_url="https://api.ofox.ai/v1",
api_key="your-key",
timeout=300,
max_retries=3,
stream=True # OpenClaw 支持 stream 模式
)
agent = Agent(
llm=llm_config,
on_token=lambda token: print(token, end="") # 實時輸出回調(diào)
)
result = agent.run("你的復(fù)雜任務(wù) prompt...")踩坑記錄
坑 1:timeout 參數(shù)設(shè)的位置不對
我一開始把 timeout 設(shè)在了 create() 方法里,結(jié)果 OpenClaw 內(nèi)部調(diào)用時把這個值覆蓋掉了。正確的做法是設(shè)在 client 初始化或 LLMConfig 里。
坑 2:以為開了 Streaming 就不需要 timeout 了
不對。Streaming 只是降低了超時概率,如果服務(wù)端壓根沒響應(yīng)(API Key 過期、模型不存在),還是需要連接超時來兜底。建議連接超時 30s,讀取超時 300s,分開設(shè):
import httpx client = OpenAI( api_key="your-key", base_url="https://api.ofox.ai/v1", http_client=httpx.Client( timeout=httpx.Timeout( connect=30.0, # 連接超時 30s read=300.0, # 讀取超時 300s write=30.0, # 寫入超時 30s pool=30.0 # 連接池超時 30s ) ) )
坑 3:重試沒做指數(shù)退避
最開始寫的重試邏輯是 time.sleep(1) 固定等 1 秒。API 端負(fù)載高的時候,瘋狂重試反而加重了擁堵,越試越超時。換成指數(shù)退避(2s、4s、8s...)后就穩(wěn)了。
坑 4:OpenClaw 的 verbose 模式救了我
排查期間一度不知道卡在哪,開了 verbose 日志才發(fā)現(xiàn)是 tool calling 那步超時,不是主 prompt 的問題。
import logging logging.basicConfig(level=logging.DEBUG) # 或者 OpenClaw 自帶的 debug 模式 agent = Agent(llm=llm_config, verbose=True)
小結(jié)
排查思路很清晰:先跑簡單請求確認(rèn)是端點(diǎn)問題還是 token 量問題,再決定用哪個方案。臨時救急就調(diào)大 timeout,治本就換低延遲端點(diǎn)加上 Streaming 和指數(shù)退避重試。
我現(xiàn)在是三個方案疊著用——低延遲端點(diǎn)?;A(chǔ)速度,Streaming 保長任務(wù)不斷,重試機(jī)制兜底偶發(fā)抖動。上線一周沒再出現(xiàn)過超時。
有同樣問題的按這個思路排查,基本能覆蓋 90% 的場景。有其他奇葩情況歡迎評論區(qū)交流。
以上就是OpenClaw請求超時llm request timed out的3種解決方案及完整排查流程的詳細(xì)內(nèi)容,更多關(guān)于OpenClaw請求超時llm request timed out的資料請關(guān)注腳本之家其它相關(guān)文章!
相關(guān)文章

2026年OpenClaw接入個人版微信的詳細(xì)流程和問題匯總
OpenClaw 是一款支持插件擴(kuò)展的 AI 網(wǎng)關(guān)工具,通過官方微信插件 @tencent-weixin/openclaw-weixin,可以將個人微信賬號作為消息通道接入,實現(xiàn) AI Bot 與微信的聯(lián)動,本文記2026-04-03
openclaw搭建報錯糾正篇(錯誤結(jié)果 + 原因 + 修復(fù)辦法)
OpenClaw是一個功能強(qiáng)大但上手簡單的工具,不要害怕嘗試和犯錯,在實踐中學(xué)習(xí)是最快的方式,這篇文章主要介紹了openclaw搭建報錯糾正篇的相關(guān)資料,文中通過代碼介紹的非常詳細(xì)2026-04-03
OpenClaw WSL 中配置 SearXNG 的詳細(xì)步驟
文章介紹了在OpenClawWSL中部署SearXNG的詳細(xì)步驟,包括環(huán)境要求、安裝Python依賴、配置環(huán)境變量、啟動服務(wù)等,還提供了常見問題及解決方案,并推薦了啟動腳本配置,感興趣的2026-04-03
OpenClaw 2026.3.28 使用model qwen無法統(tǒng)計tokens使用量及費(fèi)用的完美解決方案
安裝OpenClaw2026.3.28版本,遇到tokens統(tǒng)計和費(fèi)用顯示為0的問題,發(fā)現(xiàn)是程序處理JSON數(shù)據(jù)的字段名稱與返回數(shù)據(jù)不一致導(dǎo)致的,作者修改了系統(tǒng)文件,增加了兼容性處理后問題解決2026-04-03
OpenClaw怎么換大模型?3步免費(fèi)切換各種大模型配置教程
文章詳細(xì)介紹了OpenClaw如何通過靈活配置對接各類模型服務(wù),支持免費(fèi)或低成本使用云端、本地私有化模型及自定義模型,通過三步配置更換模型,實現(xiàn)智能降級切換,需要的朋友可以2026-04-02
OpenClaw(龍蝦)Skills從零到發(fā)布的實戰(zhàn)指南
本文詳細(xì)介紹了OpenClaw的Skill機(jī)制,包括什么是Skill、Skill的目錄結(jié)構(gòu)、SKILL.md的核心格式、以及五種不同類型的Skill,還提供了開發(fā)最佳實踐、安全檢查清單和本地測試指南2026-04-02
作為開發(fā)者,我們每天和命令行打交道,下面這篇文章主要介紹了OpenClaw CLI的全部命令及其使用方法,文中通過代碼介紹的非常詳細(xì),對大家學(xué)習(xí)或者使用OPenClaw具有一定的參考借2026-04-02
本地部署OpenClaw自動發(fā)布小紅書文章的小白完整教程
OpenClaw 能讀寫你電腦上的文件,執(zhí)行命令,操控瀏覽器,所以這篇文章就和大家詳細(xì)介紹一下如何本地部署OpenClaw自動發(fā)布小紅書文章,并且能自動幫你寫小紅書文案,生成封面2026-04-02
之前在京東云輕量型服務(wù)器云養(yǎng)了一只小龍蝦,已升級到2026.3.24版本,但使用XShell連接到服務(wù)器后,發(fā)現(xiàn)openclaw命令出現(xiàn)問題,下面小編就和大家詳細(xì)介紹一下OpenClaw中命2026-04-02
OpenClaw 是一個開源的個人 AI 助手框架,支持通過命令行界面(CLI)進(jìn)行全面的配置、管理和操作,此外,它還支持在 macOS/iOS/Android 上進(jìn)行語音交互,并提供實時畫布界面2026-04-01











