工具大全
踩坑实录作者:Coocon2026年9月26日227 次阅读约 8 分钟阅读

Claude Code 报错 Command timed out after 2m 0s 怎么解决:两条超时路径、BASH_DEFAULT_TIMEOUT_MS 与 run_in_background 实测

问题背景

让 Claude Code 跑一个慢命令,比如冷启动的 npm install、整套测试、docker build,或者一段 sleep 轮询,过了两分钟,工具结果变成这样:

Exit code 143
Command timed out after 2m 0s

这是 Claude Code 的 Bash 工具默认超时:120000 ms。常见的处理办法是「把超时调大」,但实际碰到后,至少还有三个问题没回答:

  • 命令被杀后,已经输出的内容还在不在?子进程会不会变成孤儿进程?
  • 用脚本跑 claude -p 时,怎么发现命令其实超时了?
  • BASH_DEFAULT_TIMEOUT_MS、BASH_MAX_TIMEOUT_MS、单条命令的 timeout 参数、run_in_background,分别该在什么场景用?

这篇的所有报错原文和数字,都来自 2026-09-26 在本机 Claude Code 2.1.280 上跑的 19 次真实 claude -p 会话,逐字照抄。

问题分析

先读了一遍 2.1.280 的二进制(claude.exe,217,254,576 字节),相关代码有这几段:

  • 默认值和上限:var p=120000,d=600000。BASH_DEFAULT_TIMEOUT_MS 只有在 !isNaN(o)&&o>0 时才生效,否则回落 120000。BASH_MAX_TIMEOUT_MS 取 Math.max(max, default),所以上限永远不会小于默认值。
  • 报错模板:Command timed out after ${zt(this.#u)}。
  • 单条命令的 timeout 取 Math.min(请求值||默认值, 上限, …)。被夹小时只发一个 timeout_clamped 遥测事件,模型看不到。
  • 超时自动转后台:满足 !or&&Ee===void 0&&kYr(Be) 时,超时的命令不杀,改为转到后台。kYr 会取命令的首词,只要不在 gYr=["sleep"] 里就放行。or 为真的情况包括设置了 CLAUDE_CODE_DISABLE_BACKGROUND_TASKS。

最后一条是这次最意外的发现。2.1.280 里 Bash 超时有两条完全不同的路径:

路径 触发条件 工具结果 is_error
被杀 首词是 sleep,或设了 CLAUDE_CODE_DISABLE_BACKGROUND_TASKS=1 Exit code 143\nCommand timed out after 2m 0s true
转后台 其它命令,例如 echo …; sleep 300、(sleep 301; echo X) | cat Command did not complete within its 120s timeout and was moved to the background (ID: …) false

也就是说,在 2.1.280 里真正会看到「Command timed out after 2m 0s」的,只有第一种情况。标题里这条报错,下面的实验主要用 sleep 300 来稳定复现。

技术方案与选型

默认两分钟不够用时,有三种绕法,它们的代价不一样:

绕法 代价 适用场景
环境变量 BASH_DEFAULT_TIMEOUT_MS(配合 BASH_MAX_TIMEOUT_MS) 对所有命令生效,真卡死的命令也要等满新阈值;0 或非数字会静默回落 120 秒;上限默认 600000 ms,想超过 10 分钟必须同时抬高 MAX 整个会话都在跑长构建,或 CI 类无头任务
单条命令传 timeout 参数(上限是 BASH_MAX_TIMEOUT_MS,默认 600000) 要靠模型主动传参;超过上限会被静默夹取 已知个别命令慢,例如一次长测试
run_in_background 立即返回,但完成通知不带输出,要再读文件;-p 模式下最终回复 5 秒后就会被 kill;实测模型还可能编造完成通知 交互式长任务;在 -p 下必须让模型前台轮询到完成

排除项:

  • 不推荐在命令外面再套一层 timeout 600 …。外层的 GNU timeout 只能让命令提前结束,没法延长 Claude Code 自己的 120 秒计时器(这是按代码逻辑推断的,本轮未实测)。
  • 不推荐靠 nohup … & 把进程甩出去。本轮 sleep 305 & wait 的实验里,& 起的子进程和外层 shell 同属一个进程组,超时时被一起杀掉(见下文 B2c)。就算甩出去了,模型也拿不到结果。
  • 本轮不讨论 CLAUDE_CODE_AUTO_BACKGROUND_TIMEOUT_MS。二进制里有这个变量(会把可转后台命令的超时缩短),但本轮没实测,不给建议。

实测过程

所有会话都用同一种形式调用,每个 run 用独立的 work/ 目录和隔离的 config 目录:

cd <run>/work
CLAUDE_CONFIG_DIR=<lab>/claude-config claude -p '<prompt>' \
  --allowedTools Bash --model haiku --setting-sources user \
  --debug-file <run>/debug.log --output-format text < /dev/null

逐字的工具结果都取自每个会话的 transcript.jsonl。「工具耗时」是 transcript 里 tool_use 到 tool_result 的时间戳差。

A. 默认超时:报错原文、退出码和计时

claude -p 跑 sleep 300:stdout 里是模型转述的报错,stderr 0 字节,退出码 0

A1(text 输出)的读数:

项 读数
墙钟 127.39 s
工具耗时 120.177 s
claude 退出码 0
stderr 0 字节
工具结果(transcript) Exit code 143\nCommand timed out after 2m 0s,is_error=true
  • Exit code 143 = 128 + 15,也就是被 SIGTERM 杀死。
  • 工具结果在 2m 0s 后面没有换行。stdout 里那个代码块是模型自己排版的转述,不是 CLI 打出来的。
  • 在 claude -p 里,这条报错既不在 stdout 也不在 stderr,它是对话内部的 tool_result。stdout 上能不能看到它,完全看模型最后怎么转述。

A2 用 --output-format json 跑同一个 prompt:

字段 值
顶层 is_error / subtype false / success
num_turns 2
duration_ms 126196
duration_api_ms 6021
total_cost_usd 0.0115758

JSON 顶层也看不出命令超时了。duration_ms 包含了 120 秒的工具等待,duration_api_ms 不包含,所以脚本里可以用两者之差来判断时间是不是耗在了 Bash 上。这一点和 MCP 连接超时那篇正好相反:那边的等待发生在第一次 API 请求之前,duration_ms 没算进去。

稳定性:同样跑 sleep 300(B2c 为 sleep 305 & wait)、默认 env 的 6 个 run 都得到同一段工具结果,工具耗时全部落在 120.149–120.189 s,墙钟 125.48–127.39 s,差额是模型两轮推理的时间。另外 A3-r3 的模型把工具结果连同外层的 <error>…</error> 和一段 <system-reminder> 一起抄进了 stdout,由此能看出,模型收到的超时结果外面包着 <error> 标签。

B. 部分输出与进程残留

**B1:echo PARTIAL_OUTPUT_START; sleep 300(默认 env)。**这里没有出现「Command timed out」,因为首词是 echo,走的是转后台路径:

Command did not complete within its 120s timeout and was moved to the background (ID: b1lixbsks). Output is being written to: /private/tmp/claude-501/…/tasks/b1lixbsks.output. You will be notified when it completes. To check interim output, use Read on that file path.

is_error=false,toolUseResult 里 stdout 为 "",同时带有 "timedOutAfterMs": 120000。已经打印的 PARTIAL_OUTPUT_START 没有进工具结果,只写进了后台输出文件。会话结束时这个文件的内容是 PARTIAL_OUTPUT_START\n\n[killed]\n(31 字节)。

**B1b:同一条命令,加上 CLAUDE_CODE_DISABLE_BACKGROUND_TASKS=1 和 BASH_DEFAULT_TIMEOUT_MS=10000,强制走被杀路径。**工具结果:

Exit code 143
Command timed out after 10s
PARTIAL_OUTPUT_START

被杀路径会保留已有的 stdout,追加在报错两行后面。(这次同时改了两个变量;默认 120 秒下的这种组合没有单独跑,未验证。)

**B2:子进程会不会残留。**每条命令都会被包成 /bin/zsh -c source …/shell-snapshots/snapshot-zsh-….sh … && eval '<cmd>' < /dev/null && pwd -P >| /tmp/claude-XXXX-cwd 执行,这个 zsh 是进程组组长。

两条路径的进程树:sleep 首词在超时时整组被杀;管道命令转后台,在收尾时被 kill

run 命令 路径 运行中进程 claude 退出后 +0 / +10 / +60 s
B2-r2 sleep 300 被杀 zsh(64768) → sleep(64772),同一 PGID 无 / 无 / 无
B2c sleep 305 & wait 被杀 zsh(65537) → sleep(65543),同一 PGID 无 / 无 / 无
B2d (sleep 301; echo CHAIN_DONE) | cat 转后台 4 个进程同一 PGID 66172 无 / 无 / 无
  • 被杀路径下,用 & 起的子进程也一起消失了,可以认为杀的是整个进程组。
  • 转后台路径下,命令超时后还在跑,直到 claude -p 收尾才被杀。debug.log 里是 print wind-down: killing background shell bdpcaw0cb ("Run sleep and echo command") after 5000ms grace,时间正好在模型最终回复后 5 秒。CHAIN_DONE 一直没有写出来。
  • 19 个有效 run 的 work/ 目录都没有残留文件。/tmp/claude-XXXX-cwd 抽查 3 个都不存在,因为被杀路径根本走不到 && pwd -P。唯一留下的是 /private/tmp/claude-501/<项目>/…/tasks/*.output,共有 5 个 run 留下了这种文件。

C. 环境变量覆盖

默认值、BASH_DEFAULT_TIMEOUT_MS、BASH_MAX_TIMEOUT_MS 与显式 timeout 的实测工具耗时和报错

设置 命令 工具耗时 工具结果
BASH_DEFAULT_TIMEOUT_MS=8000 sleep 30 8.166 s Command timed out after 8s
BASH_DEFAULT_TIMEOUT_MS=20000 sleep 30 20.167 s Command timed out after 20s
DEFAULT=5000 MAX=15000,模型传 "timeout": 120000 sleep 60 15.119 s Command timed out after 15s
BASH_DEFAULT_TIMEOUT_MS=0 sleep 125 120.334 s Command timed out after 2m 0s
BASH_DEFAULT_TIMEOUT_MS=abc sleep 125 120.167 s Command timed out after 2m 0s

(每行工具结果前面都还有一行 Exit code 143。)

  • 时长的写法是 8s、15s、2m 0s,不是毫秒数。
  • C2 里模型确实传了 {"command": "sleep 60", "timeout": 120000},结果在 15 秒被杀,工具结果里没有任何「被夹取」的提示。
  • 0 和 abc 都静默回落到 120 秒,不报错也不给警告。
  • 默认值大于上限时,上限会被抬到默认值:这一点只从代码 Math.max(max, default) 读出,未实测。

D. 自救路径

**D2:单条命令显式传 timeout。**模型传参 {"command": "sleep 130", "timeout": 300000},工具耗时 130.285 s,结果 (Bash completed with no output),没有在 120 秒被掐断,墙钟 135.34 s。

**D1:只用 run_in_background,prompt 让模型「等通知」。**工具 0.118 s 就返回了,整个会话墙钟只有 18.59 s,sleep 45 根本没跑完。debug.log 显示最终回复 5 秒后后台 shell 被 kill,输出文件内容是 \n[killed]\n。

更麻烦的是,haiku 在最终回复里自己编了一段完成通知:

<task-notification from="bg8oxu8iz" type="completed">
Completed at 2026-09-26T20:51:45Z

它还声称输出是 BG_DONE。transcript 里没有任何真实通知入队,时间戳也是编的。

**D1b:后台启动之后,前台轮询输出文件。**第二次 Bash 调用 while ! grep -q BG_DONE <file>; do sleep 5; done; cat <file>,拿到 BG_DONE\n\n[exited with code 0],墙钟 53.99 s,num_turns 3,cost $0.01930。真实通知的格式如下:

<task-notification>
<task-id>bhotgd0u5</task-id>
<tool-use-id>toolu_01KkFoDKJgtufk46BCyZehk5</tool-use-id>
<output-file>/private/tmp/claude-501/…/tasks/bhotgd0u5.output</output-file>
<status>completed</status>
<summary>Background command "Background sleep and echo task" completed (exit code 0)</summary>
</task-notification>

真实通知不带输出内容,只有状态、退出码和文件路径。

run_in_background:前台轮询拿到 BG_DONE,而只等通知时模型编造了完成通知

实践效果

把上面的读数整理成可以直接照做的结论:

**1. 在脚本里跑 claude -p 时,别指望退出码。**超时时 claude 照样 exit 0、stderr 为空,JSON 顶层是 is_error=false / success。可行的检测方法:

claude -p "$PROMPT" --output-format json < /dev/null > out.json
jq '.duration_ms - .duration_api_ms' out.json

A2 实测差值是 126196 − 6021 = 120175,也就是一次卡满 120 秒的超时。要精确判断,可以解析 transcript 里 is_error=true 的 tool_result,或者找带 timedOutAfterMs 字段的记录(转后台路径)。

**2. 已知整场都慢,就在启动时抬默认值。**本轮所有 env 都是在命令行前缀里传的:

BASH_DEFAULT_TIMEOUT_MS=600000 BASH_MAX_TIMEOUT_MS=1200000 claude

注意值必须是正整数,写 0 或 10m 都会静默回落 120 秒。想超过 600000,要同时抬高 BASH_MAX_TIMEOUT_MS。

**3. 只有个别命令慢,就让模型传 timeout。**实测 timeout: 300000 跑完了 130 秒的命令。超过上限不会报错,只会被悄悄夹小,所以设了上限之后请求值要在上限以内。

**4. -p 模式里用 run_in_background,必须前台轮询到完成。**只「等通知」的话,会话在最终回复 5 秒后就会收尾并 kill 后台任务,模型还可能编一个完成结果。

**5. 看到 moved to the background 而不是 timed out,是正常的。**这是 2.1.280 对首词不是 sleep 的命令的默认行为,命令并没有失败,只是没跑完。在 -p 下它同样会在收尾时被 kill。

本轮 19 个有效会话的 API 花费合计 $0.4152。

踩坑

  • **本机 grep 是 ugrep 的别名。**静态复核时用带 .{0,N} 的正则搜 217 MB 的二进制,直接报 exceeds complexity limits。换成 /usr/bin/grep 后,前导 .{0,255} 又跑了超过 600 秒,连我自己驱动实验的那个 Bash 命令也因此被自动转后台,算是先亲身体验了一次本文要测的东西。最后改用 python mmap 按偏移切片。
  • **API 网关 503。**第一批 6 个 run 并发跑,全部撞上 503 No available accounts,11 次重试耗尽,cost 为 0。这些 run 移到 _invalid_503/ 作废,之后把并发降到 2–3 重跑。B2 首跑的「运行中进程快照」因为 503 延迟没采到。
  • **仓库 hook 误捕获。**我查看读数的命令输出里有 Exit code 143 / timed out,仓库的 PostToolUse hook 把它们当成失败命令,往 tasks/lessons-inbox.md 追加了 10 行(18→28)。确认只是尾部追加后,截回了前 18 行。在写「超时」主题的仓库里跑实验,要记得这件事。
  • 模型编造后台完成通知(D1),只在 haiku 上见过 1 次,其它模型和重复率未测。结论照样成立:别信回复里的「完成通知」,去读输出文件。
  • **进程轮询精度有限。**用 lsof 按 cwd 归属进程很慢,实际轮询间隔 8–25 秒,所以「超时那一刻进程就消失了」只能精确到「claude 退出时已经不在了」。

未验证清单:zt() 格式化函数的源码没有定位到(格式只按实测);CLAUDE_CODE_AUTO_BACKGROUND_TIMEOUT_MS 和 sleep≥25 检测只读了代码;默认 120 秒下「非 sleep 首词 + 关后台」的被杀路径;交互式(非 -p)会话里转后台之后的行为;DEFAULT 大于 MAX 时上限被抬高。

相关阅读

这类实测,每周六汇总一封

订阅码农早餐:每天 8:00 一封 AI 编程早报,每周六另附本周 Claude Code / Codex / 本地模型的实测和踩坑汇总。

相关文章

Claude Code 禁止 rm -rf 怎么配:deny 规则两周拦下 14 次,实测还有 7 种写法照样能删,一个 hook 补齐

为了防 Claude Code 误删文件,我在全局 settings 里加了一条 deny 规则 Bash(rm -rf *)。翻本机 10 月 7 日到 21 日的会话记录:这条规则拦下 14 次删除,模型被拒后 8 次换新目录名、6 次直接放弃删除,一次都没换写法绕过。但在 Claude Code 2.1.285 上用 stub 逐字回放 22 种删除写法后发现:rm -fr、rm -r -f、rm -Rf、rm -r 在手动、auto、bypass 三种模式下都照删不误,/bin/rm、find -delete、bash -c 在手动和 bypass 模式下也能删。auto 模式下,工作目录内的 rm -fr 会被当成「acceptEdits 也会放行」的操作,连分类器都不过。另一道闸是内置的 dangerous-rm 检查,目标是 $D/* 这类变量展开时触发,bypass 模式也拦;多行命令里前面有 heredoc,它就跟不上同一条命令里的变量赋值。文末给出一个 PreToolUse hook,三种模式下补齐全部递归删除写法,并告诉模型被拒后该怎么做。

claude-codehooks+5
pitfalls2026年10月21日7 min
920

Claude Code 接 DeepSeek / GLM / Kimi 开 auto 模式:temporarily unavailable 括号里的原因怎么看,哪些重试没用(故障注入实测)

用第三方模型跑 Claude Code auto 模式,每个有副作用的动作都会用你的会话模型向同一个后端多发一次判定请求:系统提示词 132,470 字符,单次约 2.97 万输入 token,比主循环那一步还多。判定请求一失败,就出现「xxx is temporarily unavailable, so auto mode cannot determine the safety of Bash」。本文用故障注入代理把每种失败对应的报错原文测了一遍:500 → (server error)、429 → (rate-limited)、529 → (overloaded)、断连 → (connection failed),这几种会自动重试 5 次;超过 60 秒没回 → (timed out);**没有括号 = 后端拒收(4xx),只试 1 次,重试多少遍都一样**;后端回了但模型没给判定 → could not evaluate,连续 3 次就退回人工确认。另外实测 CLAUDE_CODE_AUTO_MODE_MODEL 不生效,判定器只能跟着会话模型换。Claude Code 2.1.285,真实后端 DeepSeek v4-pro 与小米 MiMo v2.5。

claude-codedeepseek+7
pitfalls2026年10月11日11 min
1865

Claude Code 上下文太长怎么办:Prompt is too long 会自动压缩,中转站 / DeepSeek 的 maximum context length 却不会(实测)

Claude Code 靠报错文案判断「上下文太长」:后端说 prompt is too long 或 input is too long for requested model,它会自动压缩对话后重发,用户无感;DeepSeek 和 OpenAI 风格中转返回的 This model's maximum context length is …,它不认识,直接报 API Error: 400,每轮都失败。手动 /compact 有效;更好的办法是用 CLAUDE_CODE_MAX_CONTEXT_TOKENS(非 claude- 模型 ID)或 CLAUDE_CODE_AUTO_COMPACT_WINDOW(claude- 模型 ID)告诉它真实上限,让它提前压缩。Claude Code 2.1.285 + 本地 stub 实测。

claude-codedeepseek+6
pitfalls2026年10月5日8 min
1464

Claude Code 一直卡住、转圈没反应怎么办:后端不回时它要等 6 分钟,重试满 10 次可能卡一个多小时(实测)

Claude Code 转圈不动、或者停在 Retrying in 0s,多半是后端没有回数据。实测 2.1.285(API key + ANTHROPIC_BASE_URL):后端不回响应头时每次等 6 分钟(360 秒)才判超时,把 API_TIMEOUT_MS 调到 60 万、90 万也不变,只能调小;默认重试 10 次,总共可能卡一个多小时。中转站如果把回复缓冲到生成完才返回,超过 6 分钟的回复永远拿不到。按 Esc 可以随时中断。全部在本地 stub 上实测。

claude-code中转站+6
pitfalls2026年10月5日10 min
1275