企业官网建设流程全解析

1. 长任务跑飞的现场：为什么 Claude Code 撑不过 40 分钟

先说结论：Claude Code 本身能跑长任务，但默认配置下它跑不长。我实测过好几轮，单会话连续编码超过 40 分钟，大概率会遇到三类问题——上下文被塞爆、子 Agent 状态丢失、API 通道抖动导致整条流水线断掉。这三个问题里，前两个是 Claude Code 的机制问题，第三个是通道问题，而通道问题恰恰是最容易被忽略、又最致命的。

你想想这个场景：主调度派活给程序员 Agent，程序员写完代码交给三个质检员并行审查，质检员写报告，主调度判 PASS/FAIL，FAIL 就打回去让程序员修。这个循环跑 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.json：Agent 行为与 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.toml：API 通道与重试策略

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-20241022"

max_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 是零容忍，命中就直接 FAIL；M1-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 小时然后断掉，产出高得多。