OpenClaw 只配了一个模型,超时不重试怎么办?一个补丁搞定

前几天我遇到了一个很烦的问题。

我的 OpenClaw 只配了一个模型——GPT-5.4，没有配 fallback。

原因很简单：我试过几轮之后，觉得这个模型目前最适合我的 Agent 系统，不想配一堆次优的模型来"凑数"。

结果就出事了。

偶尔模型请求超时的时候，OpenClaw 不会自动重试，直接把错误抛给用户，对话就断了。

如果当时恰好是通过 Telegram 在用，你收到的就是一条冷冰冰的错误提示，然后需要手动重新发一遍消息。

这在日常使用里其实挺破坏体验的。

先搞清楚为什么不重试

我让 Agent 自己去查了日志，结论很直接：

每次超时，日志里都会出现这样一条记录：

embedded_run_failover_decision
decision = surface_error
failoverReason = timeout
fallbackConfigured = false

翻译成人话就是：

1. 模型请求超时了
2. 框架去查了一下：有没有配备用模型？
3. 没有
4. 那就直接报错，不重试

这里的问题在于，OpenClaw 把两件事绑在了一起：

• 模型回落（fallback）：有备用模型可以切换
• 瞬时重试（transient retry）：同一个模型再试一次

如果你配了多个模型，超时后框架会尝试切换到下一个模型，这条路是通的。

但如果你只配了一个模型，框架发现"没有 fallback 可用"，就直接走到了 surface_error，连"用同一个模型再试一次"的机会都没给。

"没有备用模型"被错误地等同于了"不能重试"。

这两件事本来不应该绑在一起。超时是瞬时错误，网络抖一下、上游服务卡一下，过几秒再请求很可能就通了。这种情况下，即使没有 fallback 模型，也完全应该允许同模型重试。

问题出在哪一段代码

OpenClaw 的模型请求失败处理链路，核心在这个文件里：

~/.npm-global/lib/node_modules/openclaw/dist/pi-embedded-DWASRjxE.js

如果你是通过其他方式安装的 OpenClaw（比如全局 npm、1Panel 等），路径可能不同，但文件名是一样的。可以用 find / -name "pi-embedded-DWASRjxE.js" 2>/dev/null 找到它。

关键函数有两个：

1. resolveRunFailoverDecision()

这个函数决定"失败后该干什么"。它的 assistant 阶段逻辑大致是：

// 简化后的逻辑
const assistantShouldRotate = shouldRotateAssistant(params);

// 第一步：尝试切换 profile
if (!params.profileRotated && assistantShouldRotate) {
 return { action: "rotate_profile" };
}

// 第二步：尝试切换到 fallback 模型
if (assistantShouldRotate && params.fallbackConfigured) {
 return { action: "fallback_model" };
}

// 第三步：如果不需要轮转，正常继续
if (!assistantShouldRotate) {
 return { action: "continue_normal" };
}

// 兜底：直接报错
return { action: "surface_error" };

问题就在最后那个兜底：只要 shouldRotateAssistant 为 true（超时会触发这个），又没有 fallback 模型，就直接 surface_error。

没有"用同一个模型重试"这条出口。

2. handleAssistantFailover()

这个函数执行具体的失败处理动作。它本身是支持 retry 这个 outcome 的：

// 它可以返回这三种结果
{ action: "retry" }          // 重试
{ action: "throw" }          // 抛出错误，触发 fallback
{ action: "continue_normal" } // 正常继续（实际上就是放弃了）

也就是说，执行层有重试的能力，但决策层没给它机会。

补丁怎么打

思路很简单：在 handleAssistantFailover() 函数里，当决策是 surface_error 时，加一层判断——如果错误类型是瞬时可重试的（timeout、rate_limit 等），就不要直接放弃，而是允许同模型重试，最多重试 2 次。

第一步：备份原文件

cp ~/.npm-global/lib/node_modules/openclaw/dist/pi-embedded-DWASRjxE.js \
  ~/.npm-global/lib/node_modules/openclaw/dist/pi-embedded-DWASRjxE.js.bak

第二步：找到需要修改的位置

在文件中搜索这段代码（大约在第 27256 行附近）：

if (decision.action === "surface_error") params.logAssistantFailoverDecision("surface_error");
return {
   action: "continue_normal",
   overloadProfileRotations
};

注意这段代码在 handleAssistantFailover() 函数的末尾，紧接在 fallback_model 分支之后、//#endregion 之前。

第三步：替换为以下代码

if (decision.action === "surface_error") {
   const isTransientError = params.timedOut === true
       || params.failoverReason === "timeout"
       || params.failoverReason === "rate_limit"
       || params.failoverReason === "overloaded"
       || params.failoverReason === "upstream_error"
       || params.failoverReason === "network_error"
       || params.failoverReason === "connection_error";
   const transientRetryCount = params.transientRetryCount ?? 0;
   if (isTransientError && !params.fallbackConfigured && transientRetryCount < 2) {
       log$16.warn(`[transient-retry-patch] retrying: failoverReason=${params.failoverReason} timedOut=${params.timedOut} attempt=${transientRetryCount + 1}/2`);
       params.logAssistantFailoverDecision("transient_retry");
       const backoffMs = transientRetryCount === 0 ? 1000 : 3000;
       if (backoffMs > 0) await new Promise(r => setTimeout(r, backoffMs));
       return {
           action: "retry",
           overloadProfileRotations,
           transientRetryCount: transientRetryCount + 1,
           lastRetryFailoverReason: mergeRetryFailoverReason({
               previous: params.previousRetryFailoverReason,
               failoverReason: params.failoverReason,
               timedOut: params.timedOut
           })
       };
   }
   params.logAssistantFailoverDecision("surface_error");
}
return {
   action: "continue_normal",
   overloadProfileRotations
};

关于 isTransientError 的判断条件：这里我特意把条件写得比较宽。一开始我只判断了 failoverReason === "timeout"，结果在实际测试中发现补丁没生效。通过加调试日志才看到，当网络层面发生 connection error 时，failoverReason 实际是 null，而 timedOut 也可能是 false——但这种情况本质上就是瞬时故障，应该重试。所以最终的条件里，只要 timedOut === true、或者 failoverReason 落在常见的瞬时错误类型里，都走重试分支。

另外，log$16 是这个文件内部的 logger 实例，直接复用就好。如果你的文件里变量名不同，搜索 log.warn 就能找到对应的 logger。

第四步：添加重试计数器

在文件中搜索这行（大约在第 35659 行附近）：

let overloadProfileRotations = 0;
let planningOnlyRetryAttempts = 0;

在它们之间加一行：

let overloadProfileRotations = 0;
let transientRetryCount = 0;
let planningOnlyRetryAttempts = 0;

第五步：传入和回收计数器

搜索调用 handleAssistantFailover 的地方，找到参数列表中的：

overloadProfileRotations,
overloadProfileRotationLimit,

在它们之间加一行：

overloadProfileRotations,
transientRetryCount,
overloadProfileRotationLimit,

然后找到结果回收的地方：

overloadProfileRotations = assistantFailoverOutcome.overloadProfileRotations;
if (assistantFailoverOutcome.action === "retry") {

在它们之间加一行：

overloadProfileRotations = assistantFailoverOutcome.overloadProfileRotations;
if (assistantFailoverOutcome.transientRetryCount != null) transientRetryCount = assistantFailoverOutcome.transientRetryCount;
if (assistantFailoverOutcome.action === "retry") {

第六步：重启 gateway

systemctl --user restart openclaw-gateway.service

验证：

systemctl --user status openclaw-gateway.service

看到 active (running) 就说明补丁没有语法错误，已经生效了。

第七步：验证补丁真的生效（很重要）

这一步我第一次没做，结果踩了坑。

补丁加载成功 ≠ 补丁逻辑真的进入了重试分支。最稳的验证办法是主动制造一次模型请求失败，然后看日志有没有打印 [transient-retry-patch] retrying 这行。

我的做法是直接用 iptables 临时封禁模型服务器的 IP：

# 假设你的模型服务器 IP 是 X.X.X.X
sudo iptables -I OUTPUT -d X.X.X.X -j DROP

# 发起一次 agent 请求（可以通过 Telegram 发消息，或者用 openclaw agent 命令）
openclaw agent --agent general-agent -m "test retry" --session-id test-retry --timeout 90

# 观察日志
journalctl --user -u openclaw-gateway.service --since "1 min ago" | grep -E "transient-retry-patch|failover"

# 测试完立刻解除封禁
sudo iptables -D OUTPUT -d X.X.X.X -j DROP

如果看到日志里出现：

[transient-retry-patch] retrying: failoverReason=... timedOut=... attempt=1/2
embedded run failover decision: ... decision=transient_retry

就说明补丁真的生效了。

如果只看到 decision=surface_error，说明某个条件没满足，需要回到补丁里把 log$16.warn 的日志打开，看 failoverReason、timedOut、fallbackConfigured 的实际值，再调整 isTransientError 的判断条件。

我踩过的那个坑就是：我最早只判断 failoverReason === "timeout"，结果实际触发时 failoverReason=null、timedOut=false（因为请求在更高层被判定为 connection error 而不是 timeout），条件不满足，补丁没进入重试分支。加上了 timedOut === true 和更宽的 failoverReason 判断后才真正跑通。

这个补丁具体做了什么

用一张表说清楚：

重试策略：

• 第 1 次重试：等 1 秒后发起
• 第 2 次重试：等 3 秒后发起
• 超过 2 次：正常报错，和原来行为一致

只对瞬时错误生效，不会对鉴权失败、参数错误、格式错误这类"重试也没用"的错误做无意义的重试。

什么人需要这个补丁

说实话，大部分人可能不需要。

如果你给 OpenClaw 配了多个模型，框架本身的 fallback 机制就能覆盖超时场景——A 模型超时了，自动切到 B，B 再超时切到 C，这条路是通的。

需要这个补丁的，是像我这样的用法：

• 只配了一个模型（因为觉得它最好，不想用次优的凑数）
• 或者配了多个模型但它们都指向同一个 provider（本质上还是一个）
• 偶尔会遇到网络抖动、上游短暂不可用的情况
• 希望框架能自己重试，而不是每次都需要手动重发

如果你恰好是这种情况，这个补丁应该能帮到你。

升级后怎么办

这是打补丁不可避免的问题：OpenClaw 升级会覆盖掉这个文件。

几个建议：

1. 升级前先检查：看看新版本是否已经修复了这个问题。搜索 surface_error 附近的代码，看有没有 transientRetry 相关的逻辑。
2. 保留备份：升级前把打过补丁的文件也备份一份，方便对照重新打。
3. 补丁本身很小：总共改动 4 个位置，熟练了 5 分钟就能打完。
4. 关注官方更新：这个行为更像是设计上的遗漏而非刻意为之，后续版本有可能会官方修复。

如果你想用脚本自动化这个过程，核心就是 sed 替换那 4 个位置。但考虑到每个版本的行号和上下文可能略有变化，建议还是手动搜索定位更稳妥。

最后

这个问题本身不大，但它很典型。

很多 Agent 框架在设计 failover 机制时，会把"切换模型"和"重试请求"混在一起处理。当你的使用方式恰好不在主流路径上（比如只用一个模型），就会撞上这种"明明应该重试但框架不让重试"的边界情况。

还有一件事我想单独拎出来说：

补丁"代码加进去了"和"补丁真的生效了"，是两件事。

我第一次改完重启服务，看日志没报错，就以为搞定了。直到实际撞上一次超时，发现日志里还是 decision=surface_error，才意识到我的条件判断写窄了——真实的失败场景里，failoverReason 可能是 null，timedOut 也可能是 false，而我原本只判断 failoverReason === "timeout"。

后来我加了一行调试日志，主动用 iptables 封禁模型服务器 IP 触发一次真实超时，才看清楚各个字段的实际值，把条件改宽才跑通。

所以如果你也在打这类运行时补丁，别省验证这一步。

主动触发一次失败场景，看到日志里那行"补丁真的被执行了"，才算完事。

如果你也在用 OpenClaw，也遇到过"超时后没反应需要手动重发"的问题，可以试试这个补丁。

文件改动不大，风险可控，最坏情况也就是恢复备份重启一下。