1. 长任务跑飞的现场为什么 Claude Code 撑不过 40 分钟先说结论Claude Code 本身能跑长任务但默认配置下它跑不长。我实测过好几轮单会话连续编码超过 40 分钟大概率会遇到三类问题——上下文被塞爆、子 Agent 状态丢失、API 通道抖动导致整条流水线断掉。这三个问题里前两个是 Claude Code 的机制问题第三个是通道问题而通道问题恰恰是最容易被忽略、又最致命的。你想想这个场景主调度派活给程序员 Agent程序员写完代码交给三个质检员并行审查质检员写报告主调度判 PASS/FAILFAIL 就打回去让程序员修。这个循环跑 21 个模块每个模块最多 4 轮开发、3 维测试中间任何一次 API 请求超时或者返回 429整个批次就得重来。如果每次重来都从零开始5 小时根本跑不完。所以这篇要解决的核心问题是怎么让 Claude Code 的 Agent 长任务在无人值守的情况下稳定跑 5 小时不中断。切入点有两个——AGENTS.md 定义角色边界Skill 定义审查标准然后用 TaoToken 统一 Key 和 API 通道让所有 Agent 走同一条稳定的请求链路。下面我把 settings.json 和 config.toml 的骨架、Resume 恢复验证步骤、以及中断后的排查动作全部拆开讲。适合谁看已经在用 Claude Code 跑多 Agent 任务、但总是跑到一半断掉的人想搭一套能自我纠错的编码流水线、但卡在配置环节的人以及想搞清楚 Resume 机制到底怎么用的人。2. TaoToken 前置统一 Key 与 API 通道怎么接Claude Code 默认走 Anthropic 官方通道但多 Agent 并发场景下请求量会瞬间放大。5 个 Agent 同时跑每个 Agent 每轮对话可能触发 3-5 次 API 调用21 个模块跑下来请求数轻松上千。这时候如果通道不稳定中断就是必然的。TaoToken 在这里的作用是提供一个统一的 API 入口把 Claude Code 的所有请求收敛到一条通道上。你只需要在配置里把 base_url 指向https://taotoken.net/api然后用同一个 Key 给所有 Agent 用。这样做的好处是请求链路统一排查问题的时候只需要看一个地方Key 管理集中不用给每个 Agent 单独配通道稳定性由 TaoToken 侧保证你不需要自己维护重试逻辑。具体操作上先去 console 页面创建一个 API Key然后到 API Keys 页面确认 Key 的权限范围。如果你要跑的是长期编码任务建议直接看 Coding Plan 的配置方式它针对 Agent 长任务做了通道优化。模型对话页面可以用来单独验证某个模型是否可用接入文档里有完整的参数说明。这里有个坑要注意Claude Code 的 settings.json 和 config.toml 是两个不同的配置文件前者管 Claude Code 本身的行为后者管底层 API 通道。很多人只改了其中一个结果 Agent 还是走默认通道跑到一半就断。下面我把两个文件的骨架都给出来。3. 可复制配置settings.json 与 config.toml 骨架3.1 settings.jsonAgent 行为与 Resume 开关settings.json 放在项目根目录的.claude/下面主要控制 Claude Code 的会话行为、Agent 调度、以及 Resume 相关的参数。下面是我实测能跑通 5 小时的骨架{ model: claude-opus-4-20250514, maxTokens: 8192, temperature: 0.3, agent: { maxConcurrent: 5, resumeEnabled: true, resumeIdTTL: 18000, contextWindowLimit: 180000, autoCompactThreshold: 0.85 }, tools: { allowed: [Read, Write, Edit, Bash, Glob, Grep], bashTimeout: 120000 }, logging: { level: info, flowLogPath: ./logs/flow-log.jsonl, lessonsPath: ./lessons-learned.md } }几个关键参数解释一下。resumeEnabled打开后子 Agent 可以通过内部 ID 恢复上下文这是长任务不中断的核心。resumeIdTTL设成 18000 秒也就是 5 小时保证 Resume ID 在整个任务周期内有效。autoCompactThreshold设成 0.85意思是上下文用到 85% 的时候自动压缩避免撑爆。maxConcurrent设成 5对应 5 个 Agent 并行。3.2 config.tomlAPI 通道与重试策略config.toml 放在~/.claude/下面控制底层 API 通道。这是接 TaoToken 的关键文件[api] base_url https://taotoken.net/api api_key sk-your-taotoken-key timeout 300 max_retries 5 retry_backoff 2.0 retry_on_status [429, 500, 502, 503, 504] [api.headers] anthropic-version 2023-06-01 content-type application/json [channel] keep_alive true keep_alive_interval 30 connection_pool_size 10 [model_routing] planner claude-opus-4-20250514 developer claude-opus-4-20250514 tester claude-haiku-3-5-20241022max_retries设成 5配合retry_backoff的指数退避能扛住大部分瞬时抖动。retry_on_status里把 429 和 5xx 都列上这些是长任务里最常见的错误码。keep_alive打开后通道会保持长连接避免每次请求都重新握手。model_routing这一段是省钱的关键——规划师和程序员用 Opus质检员用 Haiku因为质检的活是规则匹配不需要推理能力。3.3 AGENTS.md角色边界定义AGENTS.md 是主调度的大脑核心是把三个角色的边界写死。下面是我用的骨架# AGENTS.md ## 角色定义 ### 主调度Orchestrator - 职责派活、判 PASS/FAIL、记日志 - 禁止读代码、读报告正文、替程序员改代码 - 输入质检员的 PASS/FAIL 标记 - 输出下一批任务指令 ### 程序员Developer - 职责读设计指南、写代码、自检、提交 - 禁止碰测试报告以外的东西、自己判 PASS - 输入设计指南、lessons-learned.md - 输出代码文件、提交记录 ### 质检员Tester x3 - 职责读代码、审查、写报告 - 禁止碰输出文件、改代码 - 输入代码文件、Skill 审查标准 - 输出审查报告、PASS/FAIL 标记 ## 流程 Plan - Dev - Test - Fix - Test - PASS - Next Batch ## 铁律 1. 程序员不能说自己过了必须质检员说了算 2. 质检员不能改代码必须程序员来修 3. 主调度不能替程序员改必须程序员自己来 4. 任何一个人越权闭环就破了这份 AGENTS.md 的核心就三条角色能干嘛不能干嘛、信息怎么传、PASS/FAIL 谁说了算。你换成自己的项目时只需要改角色定义里的业务描述流程结构不用动。3.4 Skill 配置审查标准怎么写Skill 文件放在.claude/skills/下面每个质检员对应一个 Skill。下面是一个审查 Skill 的骨架# Skill: 布局质检 ## 零容忍规则M0 - 元素溢出容器边界 - 文本被截断且无省略号 - 重叠元素未设置 z-index ## 一级规则M1 - 间距小于 8px - 颜色对比度低于 4.5:1 - 字体大小小于 12px ## 二级规则M2 - 高度使用 100% 且内容居中导致大面积空白 - flex column 布局未设置 gap ## 三级规则M3 - 动画时长超过 500ms - 过渡曲线非 ease-in-out ## 输出格式 - 命中规则编号 - 文件路径 行号 - 修复建议只写模式不写具体值这里的关键是 M0-M3 的分级思路。M0 是零容忍命中就直接 FAILM1-M3 是递减的严重程度。你把自己最常发现的 bug 写成 M0 规则以后所有页面自动被拦。4. 验证请求Resume 恢复与成功结果确认4.1 先验证通道是否通配置写完后第一步是确认 API 通道能通。用 curl 发一个最小请求curl -X POST https://taotoken.net/api/v1/messages \ -H x-api-key: sk-your-taotoken-key \ -H anthropic-version: 2023-06-01 \ -H content-type: application/json \ -d { model: claude-haiku-3-5-20241022, max_tokens: 100, messages: [{role: user, content: reply with ok}] }如果返回里有content: [{type: text, text: ok}]说明通道没问题。如果返回 401检查 Key 是否正确返回 429说明触发了限流需要调低maxConcurrent。4.2 验证 Resume 机制Resume 是长任务不中断的核心。Claude Code 的子 Agent 可以通过内部 ID 恢复上下文但官方没给直接接口。我的做法是探测文件系统找到最新的 Agent 元数据文件抠出裸 ID。下面是验证步骤# 第一步启动一个测试 Agent claude --agent developer --task 写一个 hello world 函数 # 第二步找到最新的 Agent 元数据文件 ls -lt ~/.claude/agents/metadata/ | head -5 # 第三步从元数据文件里抠出 Resume ID cat ~/.claude/agents/metadata/latest.json | jq -r .resume_id # 第四步用这个 ID 恢复 Agent claude --resume resume_id --task 继续上次的任务如果恢复成功Agent 会带着上次的上下文继续干活你能在日志里看到context_tokens从上次的值继续增长而不是从零开始。实测下来一个页面来回修 3 次程序员的上下文从 1.5 万 token 涨到 6.2 万它不是每次重来而是越修越懂这个页面。4.3 验证长任务稳定性配置全部就绪后跑一个 30 分钟的测试任务观察三个指标# 实时看 flow-log tail -f ./logs/flow-log.jsonl | jq . # 看 Resume 次数 grep -c resume ./logs/flow-log.jsonl # 看 token 消耗 jq -s map(.tokens) | add ./logs/flow-log.jsonl如果 30 分钟内没有中断Resume 次数在合理范围每个模块 1-2 次token 消耗没有异常飙升说明配置没问题可以跑 5 小时的长任务了。5. 本篇常见错排查5.1 跑到一半报 429这是最常见的错误。原因是并发请求太多触发了通道限流。排查动作先看flow-log.jsonl里 429 出现的时间点如果集中在某个批次说明那个批次的 Agent 并发数太高。解决办法是把maxConcurrent从 5 调到 3或者把retry_backoff从 2.0 调到 3.0让重试间隔更长。5.2 Resume 失败Agent 从零开始如果日志里看到resume_id not found或者resume_id expired说明 Resume ID 失效了。检查两个地方resumeIdTTL是否设得够长5 小时任务建议 18000 秒以上元数据文件是否被清理了。如果元数据目录被定时任务清理Resume ID 就找不回来了。解决办法是把元数据目录排除在清理范围外或者把resumeIdTTL设成任务周期的 1.5 倍。5.3 上下文撑爆Agent 卡死如果 Agent 跑到某个点突然不动了日志里没有新记录大概率是上下文撑爆了。检查autoCompactThreshold是否设得太高建议 0.85以及contextWindowLimit是否和模型实际窗口匹配。Opus 的窗口是 200K设成 180000 留出余量。如果还是撑爆说明单个 Agent 的上下文增长太快需要把大文件拆成小块传路径而不是传内容。5.4 质检员误判 PASS如果质检员把有问题的代码判成 PASS检查 Skill 文件里的规则是否写得太模糊。规则要写成可判定的形式比如「间距小于 8px」而不是「间距要合理」。另外质检员用 Haiku 就够了但如果发现 Haiku 判不准可以临时切到 Opus 验证一下是规则问题还是模型问题。5.5 主调度读了报告正文这是架构问题不是配置问题。如果主调度读了报告正文同一份内容会塞进两个 Agent 的上下文主调度先炸转述的内容再炸程序员。检查 AGENTS.md 里主调度的职责定义确保写的是「只读 PASS/FAIL 标记不读报告正文」。如果已经发生了把主调度的上下文清掉重新派活。6. 长任务跑通之后把 Key 和通道固定下来5 小时跑通之后你会发现真正的瓶颈不是 Claude Code 本身而是通道稳定性和 Key 管理。我试过在任务中途换 Key结果所有 Agent 的 Resume ID 全部失效只能从头再来。所以长任务开始之前先把 Key 和通道固定下来。具体做法在 console 里创建一个专门用于长任务的 Key权限只开 messages 接口不要开其他权限。然后在 config.toml 里把这个 Key 写死任务期间不要改。如果任务要跑一整夜建议提前在 API Keys 页面确认 Key 的有效期避免跑到一半 Key 过期。另外Coding Plan 针对长期编码任务做了通道优化如果你要跑的是连续多天的 Agent 任务可以直接用 Coding Plan 的配置方式。接入文档里有完整的参数说明模型对话页面可以用来单独验证某个模型是否可用。最后说一个我踩过的坑长任务跑通之后不要急着加并发。我一开始把maxConcurrent设成 10结果 429 频繁出现Resume 次数飙升反而比 5 并发跑得慢。稳定比快重要5 个 Agent 跑 5 小时比 10 个 Agent 跑 2 小时然后断掉产出高得多。