1. 从京东二面那道题说起137 份任务挂掉之后怎么办先把场景摆出来。你写了一个批处理 Agent要处理 200 份合同文档每份都要走一遍「读取 → 抽取字段 → 校验 → 写库」。跑到第 137 份的时候进程被 OOM 杀了或者 API 连续超时把重试次数耗光任务直接退出。第二天你重启脚本它老老实实从第 1 份开始跑。前面 136 份的时间和 token全白烧了。这就是「Agent 断点续跑」要解决的问题。它不是一个 API 重试的小技巧而是一套让长任务在任意时刻挂掉之后都能从干净、可信的状态接续下去的工程方法。适合谁适合所有在跑批处理 Agent、长链路工作流、文档抽取、数据清洗、代码批量改造的人。只要你的任务单次运行超过 5 分钟或者单次成本超过几块钱这套东西就值得做。我先把核心结论放前面不要保存整段对话历史要保存任务的「进度快照」。对话历史会越来越臃肿、越来越不可靠而进度快照是精简的、可独立检查的、能直接决定「从哪继续」的。一个健壮的检查点通常包含三样东西第一是任务目标。这一步要完成的最终结果是什么一句话说清楚而且这个目标不随任务进行而漂移。比如「把 200 份合同里的甲乙方、金额、签署日期抽成结构化 JSON 并写入 contracts 表」。第二是检查点清单。已经完成的最小单元有哪些正在处理第几个剩下的还有哪些。这份清单是续跑的核心它决定了重启后从哪个 index 开始。第三是当前工作区状态。文件改了没改、数据库写到哪一行、生成了哪些中间产物。这部分必须能被独立检查而不是只存在于模型的「记忆」里。有一个判断标准很实用如果从这一点续跑能省下 5 分钟以上的算力或者能省下几块钱的 token这个检查点就值得存。检查点不是越多越好是「划算」才做。还有一个特别容易被忽略的细节检查点要在一个工作单元真正成功之后再写而不是提前写。如果你提前写可能会把一个「看起来做完了、其实执行到一半失败了」的步骤记成「已完成」续跑的时候反而会跳过一个坏掉的结果后面全错。这个坑我在实际项目里踩过排查了半天才发现是检查点写早了。2. 用 TaoToken 统一 Key 打通检查点恢复的接入准备断点续跑要落地除了检查点逻辑还有一个绕不开的问题认证和通道的稳定性。批处理任务动辄跑几小时如果中途因为 key 额度、通道切换、endpoint 配置不一致导致请求失败那检查点做得再好也白搭。所以这一步我们把 endpoint 和认证统一到 TaoToken 的 API 通道上让整个任务只认一套 Key。TaoToken 在这里扮演的角色是「统一的模型调用入口」。你不需要在代码里散落多个厂商的 key也不需要为不同模型维护不同的 base_url。把 endpoint 指向https://taotoken.net/api用一套 Key 就能覆盖任务里用到的模型调用。对于断点续跑这种长任务来说通道统一意味着重启之后不用重新配环境auth.json 里那一份配置就是全部。先说清楚要准备什么一个 TaoToken 账号登录后在控制台创建 API Key。控制台地址是https://taotoken.net/console?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content进去之后在 API Keys 页面新建一个 key复制出来保存好。确认你要用的模型 ID。比如做文档抽取选一个支持长上下文、结构化输出稳定的模型。模型 ID 要写进配置不能靠猜。一个能持久化检查点的地方。简单场景用 JSON 文件就够复杂场景用 SQLite 或 Postgres 的一张进度表。这里要强调「三件套」的概念Base URL Key Model ID。这三样必须同时正确缺一个都会报错。Base URL 是https://taotoken.net/apiKey 是你刚创建的那串Model ID 是你选定的模型标识。后面所有的配置文件本质上都是在填这三样。如果你用的是 Claude Code 这类工具它的配置入口和直接写脚本不太一样但底层还是这三件套。Claude Code 的接入文档在https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content里面有针对不同客户端的配置说明照着填就行。还有一个概念要提前建立检查点的持久化和认证配置是两件独立的事但必须一起设计。检查点决定「从哪继续」认证配置决定「能不能继续」。如果重启之后 key 失效了检查点再准也跑不起来。所以下面我会把两者放在同一套配置里讲。3. 可复制的检查点配置与 auth.json 改造这一节是全文最核心的部分直接给可复制的东西。我按「检查点文件 auth.json 任务脚本」三层来组织。3.1 检查点文件长什么样先定义一个 checkpoint.json放在任务工作目录下。它的结构要能回答三个问题任务目标是什么、做到第几个了、每个单元的结果落在哪。{ task_id: contract_extract_20260115, goal: 抽取 200 份合同的甲乙方、金额、签署日期写入 contracts 表, total_units: 200, last_completed_index: 136, completed_units: [0, 1, 2, ...], failed_units: [], workspace: { output_dir: ./output/contracts, db_table: contracts, last_written_row: 136 }, updated_at: 2026-01-15T23:41:0708:00 }关键字段说明last_completed_index是续跑的起点依据重启后从last_completed_index 1开始。completed_units用来做幂等校验防止重复写入。workspace记录中间产物的位置续跑前可以先检查这些产物是否真实存在。注意last_completed_index的写入时机必须在一份文档抽取成功、且写库成功之后才更新。顺序是「抽取 → 校验 → 写库 → 更新检查点」任何一步失败都不更新。3.2 auth.json 改造统一到 TaoToken如果你用的是支持 auth.json 的客户端比如某些 CLI 工具或 Codex 类配置把认证信息改成下面这样。核心就是三件套对齐{ base_url: https://taotoken.net/api, api_key: sk-你的TaoToken密钥, model: 你的模型ID, timeout: 120, max_retries: 3 }如果你用的是 Claude Code配置方式略有不同但同样是填 Base URL、Key、Model ID 这三样。具体路径和字段名以接入文档为准文档地址在上一节给过了。这里要提醒一句不要把 key 硬编码在任务脚本里统一放配置文件重启的时候只读这一份避免出现「脚本里是旧 key、环境变量里是新 key」这种混乱。3.3 任务脚本里的续跑逻辑下面是一段 Python 伪代码展示续跑的核心逻辑。重点看load_checkpoint和save_checkpoint的调用位置。import json import os from openai import OpenAI CHECKPOINT_PATH ./checkpoint.json def load_checkpoint(): if os.path.exists(CHECKPOINT_PATH): with open(CHECKPOINT_PATH, r, encodingutf-8) as f: return json.load(f) return { task_id: contract_extract_20260115, goal: 抽取合同字段并写库, total_units: 200, last_completed_index: -1, completed_units: [], failed_units: [], workspace: {output_dir: ./output/contracts, db_table: contracts} } def save_checkpoint(ckpt): tmp CHECKPOINT_PATH .tmp with open(tmp, w, encodingutf-8) as f: json.dump(ckpt, f, ensure_asciiFalse, indent2) os.replace(tmp, CHECKPOINT_PATH) # 原子替换防止写一半崩了 def run_task(): ckpt load_checkpoint() start ckpt[last_completed_index] 1 print(f从第 {start} 份开始共 {ckpt[total_units]} 份) client OpenAI( base_urlhttps://taotoken.net/api, api_keyos.environ[TAOTOKEN_API_KEY] ) for i in range(start, ckpt[total_units]): doc read_doc(i) result extract_with_model(client, doc) # 调模型抽取 validate(result) # 校验 write_to_db(result) # 写库 ckpt[last_completed_index] i # 成功后才更新 ckpt[completed_units].append(i) save_checkpoint(ckpt) # 落盘 print(f第 {i} 份完成) if __name__ __main__: run_task()这段代码里有两个细节值得说。第一save_checkpoint用了「写临时文件 原子替换」的方式避免在写检查点的瞬间崩溃导致文件损坏。第二last_completed_index的更新严格放在写库成功之后保证检查点反映的是真实完成状态。4. 验证请求模拟一次中断并确认只补未完成部分配置写好了怎么验证它真的能续跑最直接的办法是人为制造一次中断然后看重启后是不是从正确的位置开始。4.1 制造中断在任务跑到第 10 份左右的时候直接 CtrlC 杀掉进程或者用kill -9模拟硬崩溃。这时候检查 checkpoint.jsonlast_completed_index应该是 9假设从 0 开始计数而不是 10。如果它是 10说明检查点写早了这是个 bug。# 查看当前检查点 cat checkpoint.json | python -m json.tool预期看到last_completed_index等于最后一份成功写库的编号。4.2 重启并观察起点重新运行任务脚本export TAOTOKEN_API_KEYsk-你的密钥 python run_task.py预期输出第一行是「从第 10 份开始共 200 份」。如果它输出「从第 0 份开始」说明load_checkpoint没读到文件或者路径不对。如果它输出「从第 11 份开始」说明检查点写早了跳过了第 10 份这是更危险的情况。4.3 验证模型调用通道正常续跑能不能成功还取决于 TaoToken 通道是否正常。可以单独发一个最小请求验证curl https://taotoken.net/api/v1/chat/completions \ -H Authorization: Bearer sk-你的密钥 \ -H Content-Type: application/json \ -d { model: 你的模型ID, messages: [{role: user, content: 回复 OK}] }如果返回里有正常的choices字段说明 Base URL、Key、Model ID 三件套都对。如果报 401是 key 问题如果报 model not found是 Model ID 写错了如果连接超时检查网络和 base_url 是否写成了https://taotoken.net/api。4.4 确认只补未完成部分最关键的验证让任务继续跑完剩下的部分然后检查completed_units里有没有重复。正常情况下第 0 到 9 份只出现一次第 10 份之后依次追加。如果出现重复说明幂等校验没做好写库的时候要用INSERT ... ON CONFLICT DO NOTHING或者先查后写。我实测下来这套流程跑通之后200 份文档的任务在第 137 份挂掉重启后确实只补了剩下的 63 份前面 136 份的产物一个没动。省下的时间和 token 是实打实的。5. 本篇常见报错排查401、local proxy failed、reading choices、OAuth这一节把实际会撞到的报错列出来对照着查。401 Unauthorized。最常见的原因是 key 没传对。检查三处环境变量TAOTOKEN_API_KEY是否 export 成功、auth.json 里的api_key是否和 TaoToken 控制台里的一致、请求头是不是Authorization: Bearer sk-xxx。还有一种情况是 key 被删了或者额度用尽去控制台确认一下 key 状态。local proxy failed。这个报错通常出现在客户端配置了本地代理端口但代理进程没起来。检查你的客户端配置里有没有指向127.0.0.1:某端口的 proxy 设置如果有要么把代理进程启动要么把 proxy 配置去掉让请求直连https://taotoken.net/api。断点续跑场景下我建议直接去掉本地代理层少一个故障点。reading choices 或 Cannot read properties of undefined (reading choices)。这个报错说明返回体里没有choices字段通常是请求根本没成功但代码直接去读response.choices[0]了。根因可能是base_url 写错导致返回了 HTML 错误页、model ID 不存在、或者请求体格式不对。排查方法是在代码里先打印完整 response看看到底返回了什么。正确的返回应该长这样{ choices: [ {message: {role: assistant, content: ...}} ] }OAuth 相关报错。如果你用的是 Claude Code 这类带 OAuth 登录的客户端报 OAuth 错误通常是因为登录态过期或者配置里同时存在 OAuth 和 API Key 两套认证互相冲突。解决办法是明确只用一套要么走 API Key填 TaoToken 的 key要么走 OAuth。断点续跑的长任务建议用 API Key因为 OAuth token 可能会在任务中途过期导致续跑失败。检查点相关的问题。如果重启后起点不对按这个顺序查checkpoint.json 是否存在且可读、last_completed_index的值是否符合预期、save_checkpoint是否真的被调用到加日志确认、写检查点的时机是否在写库成功之后。还有一个隐蔽的坑如果任务用了多进程或多线程并发处理检查点的更新要做加锁否则会出现「两个单元同时更新后写的覆盖先写的」。6. 把断点续跑变成默认习惯从 TaoToken 统一入口开始回到最开始那个问题Agent 跑到一半挂了怎么办答案不是「重跑」而是「留一条能接上的路」。这条路由三部分组成一份记录进度快照的检查点、一套稳定的认证通道、一个从正确位置续跑的逻辑。TaoToken 在这里的价值是让「认证通道」这一环变得简单。Base URL 固定为https://taotoken.net/apiKey 在控制台创建一次Model ID 选定后写进配置三件套对齐之后重启任务不需要重新折腾环境。对于动辄跑几小时的批处理任务来说这种稳定性比什么都重要。如果你还在用「挂了就从头跑」的方式建议从下一个任务开始先加一个最简单的 checkpoint.json只记录last_completed_index跑通之后再逐步加上completed_units和workspace状态。检查点不用一步到位但一定要有。想先把模型调用通道跑通的可以去模型对话页面直接试一次请求确认 Base URL 和 Key 没问题https://taotoken.net/chat?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content。需要创建和管理 Key 的在 API Keys 页面操作https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content。配置细节以接入文档为准https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content。如果你的场景是长期跑编码类 Agent 任务可以考虑 Coding Plan把通道和额度一次性配好https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content。最后留一个实用技巧在任务脚本启动时先打印一行「本次从第 N 份开始预计还需处理 M 份」然后把这行写进日志。这样每次重启你一眼就能看出续跑逻辑对不对。模型可能会忘事终端可能会关掉但检查点文件里的那个数字不会骗你。