Agent Harness 长任务中断最常见的排障现场是这样的两个市场研究 Agent 跑同一个选题第五步抓取超时后重启前四步的产物到底能不能复用说不清于是要么重复创建要么直接覆盖。遇到这种局面把模型调用通道单独拎出来处理会省事很多——打开 TaoToken 官网 https://taotoken.net/?utm_sourcetaotoken_aicg_blog_end 注册并创建 API Key把 Harness 里的 Base URL 统一改成 https://taotoken.net/api再回头补第三层规划与第七层恢复的检查点。通道的归通道状态的归状态两件事分开做中断恢复时才不用一边猜 Key 一边猜逻辑。这篇按排障视角来走先复现「第五步超时」这个失败再拆开看为什么断点续跑会被凭证和入口拖累然后把 Harness 里模型调用的接入点改到统一通道上最后回到检查点与工作区验证一次真实的续跑。技术主线仍然贴着原文的七层结构只是把 Level 3 / Level 4 的模型调用单独提到前面处理。1. 第五步超时之后两个市场研究 Agent 为什么开始重复劳动1.1 把 timeout 打在第五步一次可重复的复现找两个市场研究 Agent 做对照最省事的做法是只改结构、不改任务。任务都给同一句话调研某个细分行业的规模、主要玩家和近一年的融资情况。Agent A 用一条长 prompt 一把梭把检索、抓正文、抽取要点、成稿全塞在一次调用里Agent B 显式拆成八步每一步的输入输出都落盘到工作区目录规划、执行、观测分层写在代码里。这个对照不是比谁写得漂亮而是看第五步挂掉之后谁还能接着跑。复现的关键在第五步。把这一步定义成「批量抓取候选来源正文并抽取要点」同时把 HTTP 超时压到 5 秒候选源里必然有几个响应慢的站点于是第五步稳定抛超时。这时候你会看到 A 的表现是整段重来因为它的中间状态全在上下文里B 的表现取决于它有没有把前四步的结果写入可被重新读到的位置。原文把这个现象归到失败四任务在第五步中断、重新运行之后Agent 无法判断前四步产物能否复用结果就是重复创建文件或者把上一轮已经修好的中间产物直接覆盖掉。这里要强调一点超时本身不是病超时之后「谁拥有这些中间产物」没有记录才是病。很多 Harness 把工作区当成一个临时目录跑完就删或者用同一套文件名反复写。一旦第五步崩掉第七层的恢复逻辑拿不到任何指纹信息只能选择最安全的策略全部重跑。安全是安全了代价是钱和时间还有可能把上一轮已经人工修过的内容冲掉。1.2 失败四的成本不在超时在产物归属没人记录把「重复劳动」拆开看其实分成三种不同的问题。第一种是重复调用模型前四步的抽取结果明明还在磁盘上恢复时却重新发起了一遍第二种是重复创建产物工作区里出现step3_result.json、step3_result_v2.json、step3_result_final.json这种命名失控的现场第三种最麻烦是覆盖写新的一轮把旧的一轮盖掉而旧的那一轮里可能包含着人工修正过的字段。这三种问题的共同点是它们都发生在恢复阶段但根因分散在三个层。第三层规划没有给每一步一个稳定的step_id第五层执行没有约定工作区路径和写入语义第七层观测没有记录「这一步上一次跑到哪里、产物的指纹是什么」。原文用两个 Agent 对比其实就是在说明一件事光有分层这个形式不够每一层还得留下可被恢复逻辑读取的痕迹。所以排障顺序建议反过来。不要一上来就改 Prompt也不要一上来就加 retry而是先确认恢复逻辑依赖哪些字段、这些字段有没有真的落盘。确认完再动手改模型调用通道这样即使改通道过程中出现新的报错你也能分清是接入问题还是状态问题。1.3 模型调用是所有层的公共依赖先把它固定下来第三层的 Planner 要调模型做任务拆解第四层的工具选择要调模型做路由判断第五层执行之后的摘要、抽取、交叉验证同样要调模型。也就是说模型调用不是某一层的能力而是贯穿整个 Harness 的公共依赖。公共依赖最容易出的事就是今天这里写死一家明天那里改成另一家恢复阶段两边对不上。固定它的方式很简单只统一两样东西Base URL 和 API Key。Agent 代码里所有发起模型请求的地方都从一个配置源读取这两个值不允许多处硬编码。至于模型 ID建议也走配置并且以 https://taotoken.net/?utm_sourcetaotoken_aicg_blog_end 上的模型广场当时列表为准不要凭记忆写一个带日期后缀的名字那种 ID 往往在恢复的那一天已经不存在了。固定好之后恢复流程会变得清爽检查点校验的是任务状态不是连接参数日志里记录的是模型 ID 和通道标识而不是某一次临时复制进来的 Key。后面几节就按这个顺序来先把通道改好再把检查点补齐。2. 断点恢复最怕通道乱Key 和 Base URL 不统一会吃掉半天2.1 一个 Harness 里塞三套凭证的现场做过一段时间 Agent 的人多半有过这种目录根目录一个.env工具目录一个config.yaml某个实验脚本里还夹着一行硬编码的 Key。平时跑短任务没事因为失败了重跑一次就完事一旦任务长度拉到十几步、单次要跑几十分钟问题就来了。第五步超时之后你重启进程读到的可能是第三套凭证模型 ID 也换了个版本于是恢复逻辑虽然触发了但发出的请求和上一轮根本不是同一条路径。更麻烦的是排查成本。日志里写着「模型返回 400」你第一反应是 Prompt 太长第二反应是模型不支持这个参数第三才会想到是不是请求打到了另一个入口。中间这段时间都在做无效推理。把 Base URL 和 Key 收敛成一份配置最大的收益不是省钱而是把排障范围从「三条路径」压缩到「一条路径」。原文在讲第五层执行与工作区时提到过工作区要能被人和 Agent 同时看懂。这条经验对配置同样成立配置项也要能让人一眼看懂「这次跑的是谁的模型、走的哪个入口」。2.2 TaoToken 兼容通道统一 Base URL 与 Key 两件事TaoToken 在这里的角色是统一接入层不是一个需要额外学习的协议。你仍然用 OpenAI 兼容的客户端、Anthropic 兼容的客户端或者任何支持自定义 Base URL 的框架只把入口地址换成 https://taotoken.net/apiKey 换成从控制台创建的那一把。注意这个地址末尾不带/v1很多 404 就是这么来的客户端自己会拼路径你再补一层/v1就变成/v1/v1/...。对断点续跑来说统一入口带来的实际好处是无论恢复时是 Planner 在发请求还是执行层在发请求日志里记录的都是同一个 base_url 前缀。对比两轮运行日志时只要看到这个前缀不一致就能立刻定位到「换过通道」而不是去翻 prompt 差异。模型 ID 同样集中管理。写代码时用一个环境变量占位实际值去 https://taotoken.net/?utm_sourcetaotoken_aicg_blog_end 的模型广场挑挑完填进去。不要在任务状态里存一个「模型显示名」那是给日志看的不是给请求用的。2.3 拿 Key 的动作放进准备材料里动手改代码之前先把材料准备齐。打开 TaoToken 完成注册并登录然后在控制台里创建一把 API Key妥善保存代码里统一用YOUR_API_KEY这个占位符代替不要真的把明文提交进仓库。Key 的权限和额度信息在控制台都能看到长任务跑之前顺手确认一下额度是否够用可以避免跑到第七步才因为额度耗尽而中断。准备清单只有三项一把 API Key、一个确定的 Base URLhttps://taotoken.net/api、一个从模型广场选出来的模型 ID。把这三项写进.env然后让 Harness 里的所有模型调用都只读这份配置。做完这一步再去看检查点的代码思路会清晰很多。3. Harness 的模型接入点.env、settings.json、config.toml 分别怎么改3.1 Python 版 Harnessopenai 客户端指向 https://taotoken.net/api多数自研 Harness 是 Python 写的模型调用集中在少数几个函数里。先建一份.envTAOTOKEN_API_KEYYOUR_API_KEY TAOTOKEN_BASE_URLhttps://taotoken.net/api TAOTOKEN_MODEL_IDYOUR_MODEL_ID然后在客户端初始化处统一读取不要在业务函数里再写一遍地址import os from openai import OpenAI client OpenAI( api_keyos.environ[TAOTOKEN_API_KEY], base_urlos.environ[TAOTOKEN_BASE_URL], # https://taotoken.net/api ) def call_model(prompt: str) - str: resp client.chat.completions.create( modelos.environ[TAOTOKEN_MODEL_ID], messages[{role: user, content: prompt}], ) return resp.choices[0].message.content关键点有三个。base_url末尾不要加/v1模型 ID 从环境变量读方便中断恢复时对比日志所有层Planner、工具路由、摘要都调用同一个call_model不要在某一层单独 new 一个客户端。第三点看着琐碎但它直接决定了恢复阶段能不能只改一处配置就切换通道。如果你的 Harness 里同时存在异步客户端做法一样只是把AsyncOpenAI也指向同一个base_url。两套客户端指向同一份配置日志里就能对齐。3.2 执行环节交给 Claude Code 时改 ~/.claude/settings.json 的 env有些 Harness 把「写脚本、改配置、跑一次校验」这类执行环节交给 Claude Code 来做。这种情况下要改的是 Claude Code 的配置而不是 Harness 的.env。在~/.claude/settings.json里写{ env: { ANTHROPIC_BASE_URL: https://taotoken.net/api, ANTHROPIC_AUTH_TOKEN: YOUR_API_KEY, ANTHROPIC_MODEL: YOUR_MODEL_ID } }三个字段都要对。ANTHROPIC_BASE_URL填接口地址 https://taotoken.net/api不带/v1也不要附任何查询参数ANTHROPIC_AUTH_TOKEN用YOUR_API_KEY占位真实值从控制台取ANTHROPIC_MODEL填模型广场里选定的 ID。改完之后重新打开终端会话让环境变量生效再启动 Claude Code。要提醒一句边界Claude Code 在这条链路里只负责生成和解释代码、比对配置不会替你去连生产库、也不会替你在生产机器上执行命令。凡是需要真实执行的诊断脚本、校验命令都由你在本地跑完之后把输出贴回对话里让它继续分析。Harness 的检查点逻辑也一样Claude Code 可以帮你写、帮你审但跑不跑、在哪跑决定权在你手上。3.3 复核脚本交给 Codex 时改 ~/.codex/config.toml 的 model_provider另一条常见链路是用 Codex 复核恢复逻辑、审查 SQL 或者对账脚本。Codex 的配置文件是~/.codex/config.toml注意别把 Anthropic 那套变量名套上来两者不通用model YOUR_MODEL_ID model_provider taotoken [model_providers.taotoken] name TaoToken base_url https://taotoken.net/api env_key TAOTOKEN_API_KEY这里model_provider指向自定义 provider 段base_url同样填 https://taotoken.net/apienv_key写的是保存 Key 的环境变量名。改完保存重启 Codex 会话。如果你的 Codex 版本对 provider 字段有额外要求以版本自带说明和接入文档为准不要凭印象补字段多一个键有时候会直接导致启动失败。如果 Harness 同时用到 Claude Code 和 Codex最好在项目 README 里写清楚「哪一步用哪个工具、各自读哪份配置」避免恢复时两边模型 ID 不一致日志对不上。4. 第三层 Planner 的 State 里到底要落盘什么才能让第五步挂掉不重来4.1 每一步都要有 step_id、输入指纹、产物指纹第三层规划最容易犯的错是把计划写成一个字符串数组跑完就丢。正确的做法是每一步一条结构化记录至少有这几个字段稳定的step_id比如s05_fetch_and_extract不用数组下标因为你以后会插步骤、输入指纹上游产物的哈希或者版本号、产物路径、产物指纹、状态pending / running / done / failed、最后一次错误摘要。有了这几个字段第五步超时之后恢复逻辑的判断就变成一行确定性的检查step_id为 done 且产物指纹没变的步骤直接跳过状态是 running 但超时的步骤重新执行并且写入新版本而不是覆盖旧版本状态是 failed 的步骤按策略重试超过次数就停下来等人。这条规则写起来简单但它把「能不能复用」从一个猜测变成了一个查表动作。指纹怎么算不用复杂对产物文件做一次内容哈希就行。关键是算完要落盘。只算不存下次启动照样要重跑第一步来重新计算等于白算。4.2 第五层工作区路径约定 不覆盖写工作区的目录约定要跟step_id对齐例如每步一个子目录产物带步号和轮次workspace/ run_20250601_101500/ s01_plan/ s02_sources/ s05_fetch_and_extract/ result.r1.json result.r2.json轮次编号是重点。第二次执行第五步时写入result.r2.json同时把state.json里的产物指针指向 r2上一轮的 r1 保留在原地。这样即使新的一轮结果更差你也能回退不会出现「上一版被人改好过现在找不到了」的情况。对应的写入代码要显式禁止覆盖def save_step_output(workspace, step_id, run_id, payload): step_dir workspace / step_id step_dir.mkdir(parentsTrue, exist_okTrue) target step_dir / fresult.{run_id}.json if target.exists(): raise FileExistsError(f{target} already exists) target.write_text(payload, encodingutf-8) return target抛异常看起来粗暴但它能在开发阶段就把覆盖写的问题暴露出来而不是等到线上跑了几十分钟之后才发现中间产物被冲掉了。4.3 第七层观测恢复日志的最小字段集恢复日志不需要很花哨但必须包含能回答三个问题的信息这次是第几轮、从哪一步继续、用的是哪条通道和哪个模型。建议每条日志固定带上step_id、run_id、resumed_from、base_url_prefix、model_id、耗时、token 用量。其中base_url_prefix只记前缀就行不要记完整地址带参数更不要记 Key。有了这组字段验证阶段就很好做对照第一轮和第二轮的base_url_prefix应该一致model_id应该一致resumed_from应该指向第五步而不是从第一步开始。三项里任意一项对不上都能立刻定位到具体原因。5. 验证跑一轮市场研究任务看它是续跑还是重跑5.1 三种人为打断方式不要等真实超时那样太随机。三种可控的打断方式更实用。第一种是在第五步里插入一个if len(items) 3: raise TimeoutError让它在固定位置挂第二种是直接用系统的进程终止信号在日志输出到第五步时手动结束进程第三种是临时把网络超时改成极小的值让所有抓取都失败。第一种最推荐因为位置确定恢复时的行为最好观察。打断之后不要清理工作区。直接重启 Harness观察它第一件事做了什么。如果它先读了state.json并打印出resumed_froms05_fetch_and_extract说明恢复逻辑生效了如果它从s01_plan开始重新执行那就去第三节的配置和第四节的检查点里找原因。5.2 日志对照续跑与重跑的判别把两轮日志并排看续跑应该长这样第一轮有 s01 到 s04 的完成记录第五步开始后中断第二轮启动时只有 s05 及之后的记录前面的步骤被标记为 reused。重跑则相反第二轮里 s01 到 s04 又完整出现了一遍而且run_id换了新的一轮说明状态没有被读到。这时候可以顺手确认一件事这些复用的步骤有没有产生新的模型调用。如果日志里 s02、s03 又出现了 token 消耗记录那就是典型的重复劳动即使产物没被覆盖钱也已经花了。这一步的检查直接对应失败四里的第一种成本。5.3 容易误判的两种情况第一种误判是「看起来续跑了其实只是跳过了缓存」。有些框架会在同一进程内做内存缓存进程重启之后就没了表现为第一次恢复像续跑、第二次恢复又变成重跑。判断方法是彻底重启环境包括清掉内存状态看行为是否稳定。第二种误判是「产物文件名相同就认为可复用」。文件名相同不代表内容一致如果第五步的输入变了比如上游来源列表更新了旧产物就不能直接复用。这就是输入指纹存在的意义。对照state.json里记录的输入指纹和当前实际输入不一致就必须重跑该步而不是盲目复用。6. 排障对照表401、模型 not found、多了 /v1、产物重复创建6.1 凭证与地址类报错现象常见原因处理方式401 / invalid api keyKey 未生效、复制时带了空格、环境变量没被读到重新确认YOUR_API_KEY的注入方式打印一次base_url前缀确认通道连接被拒或域名解析失败Base URL 写成了别的地址或者误加了查询参数统一改回 https://taotoken.net/api404 not foundBase URL 末尾多写了/v1去掉多余的路径段地址保持原样这三类错误里404 最常见也最容易被忽略。因为很多客户端示例里默认就带/v1复制过来不删请求路径就多了一层。判断方法很简单把实际发出的完整 URL 打印出来看一眼。6.2 模型 ID 类报错模型相关报错通常提示model not found或者权限不足。出现这类提示第一件事是回到 https://taotoken.net/?utm_sourcetaotoken_aicg_blog_end 的模型广场核对当前可用的模型 ID把.env里的值替换掉。不要靠猜也不要把某个带日期后缀的名字当成通用别名这类 ID 的可用性会随时间变化。第二件事是确认 Harness 的每一层读的是同一份配置。常见情况是 Planner 读.env摘要层读的是配置文件里另一处写死的旧 ID结果第五步正常、第七步报错看起来像恢复逻辑的问题其实是模型 ID 不一致。6.3 恢复逻辑类问题如果日志显示续跑但你发现有些步骤还是重复执行了重点检查三处step_id是否稳定用了数组下标就会随插入步骤而漂移、产物指纹是否真的写进了state.json、读取状态时是否用了最新的那一轮run_id。这三处任意一处出问题都会让恢复逻辑退化成重跑。如果确认是重复创建而不是覆盖说明你的写入保护起作用了只是复用判断没生效。这种情况下先把resumed_from打到日志里再对照状态文件逐条排查通常很快就能定位。7. 跑通之后回控制台对一下这次长任务的调用验证跑完之后最好回控制台对一下账这次长任务一共消耗了多少、中断重跑带来的额外消耗是多少、哪些步骤被正确复用了。这些数字比任何主观感受都更能说明检查点有没有起作用。如果发现额外消耗偏高回到第四节的指纹和轮次编号上去找原因。需要长期跑 Agent 任务的话可以先在 TaoToken 模型对话 里用同一把 Key 发一条测试消息确认模型 ID 和 Base URL 没有填错接着看 Coding Plan 的额度是否够覆盖你的任务频率Key 本身在 控制台 API Keys 里创建和管理。如果你的执行环节用的是 Claude Code环境变量字段对照可以看 Claude Code 接入文档。最后留一个顺序上的建议先领 Key、把通道固定成一处配置再按第三层和第七层的结构补检查点。顺序反过来的话你会同时面对「请求打不通」和「状态读不到」两类问题日志里混在一起排查时间会长出一大截。