1. 多步任务跑偏的根源为什么 ClaudeCode 需要 TodoWrite用 ClaudeCode 做重构、批量改文件、写完整模块这类多步任务时你可能遇到过这种情况前两步做得挺好第三步开始它突然重复改同一个文件或者干脆跳过某个环节直接给你一段总结说已完成。对话越长这种跑偏越明显。根因不在模型笨而在计划没有落地。早期 Agent 的规划都藏在思维链里思维链一旦滚出上下文窗口计划就永久丢失了。工具返回的结果不断填满上下文系统提示的约束力被稀释一个十步任务做到第三步就开始即兴发挥——因为第四到第十步早被挤出注意力窗口了。TodoWrite 解决的就是这个问题它强制模型把计划写进一个独立于 LLM 上下文的外部状态里每一项都有 pending、in_progress、completed 三种状态。计划可见、可追踪、可引用即使早期上下文滚出窗口任务清单还在。这篇聚焦 ClaudeCode 中 TodoWrite 工具调用在 Agent 多步规划里的协调作用同时把 settings 改到 TaoToken 统一 Key 和 API 通道让多步任务不再跑偏。适合正在用 ClaudeCode 做工程级 Agent 开发、被长任务跑偏折磨过的同学。下面给出可复制的 settings 配置片段、TodoWrite 任务清单示例以及三步验证动作。2. TaoToken 前置准备统一 Key 与 API 通道在动 TodoWrite 之前先把通道理顺。ClaudeCode 默认走 Anthropic 官方端点但很多同学在本地调试时希望统一管理 Key、方便切换模型、集中看调用日志。TaoToken 提供的就是这样一个统一入口官网在 https://taotoken.net/?utm_sourcetaotoken_aicg_blog_end API 端点是 https://taotoken.net/api 。你需要准备三样东西我把它叫做三件套第一是 Base URL也就是 API 端点地址填https://taotoken.net/api。第二是 API Key在控制台的 API Keys 页面生成形如sk-开头的一串字符。第三是 Model ID也就是你要调用的模型标识比如claude-sonnet-4-5这类具体型号具体以控制台模型列表为准。这三件套在 ClaudeCode 里通过 settings 文件配置。ClaudeCode 读取的 settings 路径通常是用户目录下的.claude/settings.json项目级则是项目根目录的.claude/settings.json。我建议先用用户级配置做全局统一项目特殊需求再在项目级覆盖。为什么强调统一通道因为 TodoWrite 这类多步任务会频繁发起工具调用一次任务可能触发十几次甚至几十次请求。如果 Key 分散在多个地方、端点不统一排查某一步为什么没走通会非常痛苦。统一到 TaoToken 后所有调用都从同一个入口出去日志集中定位问题快很多。这里有个容易踩的坑环境变量和 settings 文件可能同时存在导致优先级混乱。ClaudeCode 的读取顺序一般是环境变量优先于 settings 文件。如果你在 shell 里 export 过ANTHROPIC_BASE_URL或ANTHROPIC_AUTH_TOKEN它会覆盖 settings 里的配置。所以配置前先检查一下当前 shell 有没有残留的环境变量有的话先清掉避免我明明改了 settings 怎么没生效。另外API Key 不要硬编码进会提交到 git 的文件里。settings.json 如果进了版本库Key 就泄露了。建议把 Key 放在环境变量或本地不提交的配置文件里settings 里引用变量。下面第三节给出两种写法。3. 可复制配置settings.json 与 TodoWrite 清单先给 settings 配置。ClaudeCode 的 settings.json 结构大致如下把三件套填进去{ env: { ANTHROPIC_BASE_URL: https://taotoken.net/api, ANTHROPIC_AUTH_TOKEN: sk-你的Key填这里, ANTHROPIC_MODEL: claude-sonnet-4-5 }, permissions: { allow: [ Read, Write, Edit, Bash(git status), Bash(git diff:*) ] } }如果你不想把 Key 写死在文件里可以改成引用环境变量在 shell 里 export 后再启动 ClaudeCodeexport ANTHROPIC_BASE_URLhttps://taotoken.net/api export ANTHROPIC_AUTH_TOKENsk-你的Key export ANTHROPIC_MODELclaude-sonnet-4-5注意如果你同时用了环境变量和 settings环境变量会赢。所以要么全放环境变量要么全放 settings别混着来。我试过混用结果改了 settings 半天不生效最后发现是 shell 里的旧变量在作祟。配置好通道后TodoWrite 本身不需要额外配置它是 ClaudeCode 内置的工具。你要做的是在提示里引导模型使用它。一个有效的系统提示片段长这样You are a coding agent. Use the todo tool to plan multi-step tasks. Mark in_progress before starting, completed when done. Prefer tools over prose. Keep at most one task in_progress.TodoWrite 的任务清单结构是数组每项包含 id、text、status 三个字段。status 只能是 pending、in_progress、completed 三者之一。一个典型的多步任务清单示例{ items: [ { id: 1, text: 读取现有配置文件, status: in_progress }, { id: 2, text: 解析并校验字段, status: pending }, { id: 3, text: 生成新的配置结构, status: pending }, { id: 4, text: 写回文件并备份原文件, status: pending }, { id: 5, text: 运行校验脚本确认, status: pending } ] }这里有三条硬约束必须记住最多 20 条任务同一时间只能有一个 in_progress状态值只能是那三个。违反任何一条TodoManager 会直接抛错。这三条不是限制是护栏。20 条上限防止模型把任务拆成 50 个微不足道的步骤单 in_progress 防止模型交替处理多个任务导致状态混乱固定状态值让渲染和判断逻辑简单可靠。如果你用的是 Codex 或 Cline 这类工具配置思路类似但文件位置不同。Codex 的 auth.json 里放凭据Cline 的 MCP 配置里放端点。核心还是三件套Base URL 填https://taotoken.net/apiKey 填你的Model ID 填具体型号。CC Switch 这类切换工具也是同样的三件套逻辑只是帮你把多套配置管理起来。4. 三步验证发起任务、观察流转、核对日志配置完别急着上大任务先用三步验证通道和 TodoWrite 是否都走通了。第一步发起一个明确的多步任务。在 ClaudeCode 里输入类似这样的指令帮我完成三件事1) 在当前目录创建 hello.py打印 Hello TaoToken 2) 运行它确认输出3) 把运行结果写进 result.txt。 请先用 todo 工具列出计划再执行。关键在最后一句请先用 todo 工具列出计划再执行。没有这句模型可能直接开干你就看不到计划外化的效果。加上这句后正常情况下模型第一轮就会调用 todo 工具返回一个渲染后的清单形如[] #1: 创建 hello.py [ ] #2: 运行 hello.py 确认输出 [ ] #3: 将结果写入 result.txt (0/3 completed)第二步观察 todo 状态流转。任务执行过程中每次模型调用 todo 工具清单都会更新。你会看到[]从第一项移到第二项[x]逐渐增多。如果模型连续三轮没调用 todo系统会自动注入reminderUpdate your todos./reminder提醒它。这个 nag 机制是问责压力实测下来对保持进度很有用。第三步核对调用日志是否走通。这一步验证的是通道不是 TodoWrite。去 TaoToken 控制台的调用日志页面看刚才那几次请求有没有记录。如果日志里有对应的请求说明 Base URL 和 Key 都对了。如果日志是空的说明请求根本没到 TaoToken大概率是环境变量覆盖了 settings或者 Base URL 写错了。三步都通过说明通道和 TodoWrite 都正常。这时候再上真实的多步重构任务跑偏概率会明显下降。5. 常见报错排查401、local proxy failed、reading choices配置和验证过程中几个报错特别常见逐个说。401 Unauthorized。这个最直接Key 不对或没带上。检查三处settings 里的ANTHROPIC_AUTH_TOKEN是不是完整、有没有多余空格环境变量里有没有另一个旧 Key 在覆盖Key 是不是在控制台被禁用或删除了。还有一种隐蔽情况Key 对了但 Base URL 写成了官网首页而不是 API 端点。记住 API 端点是https://taotoken.net/api不是首页。local proxy failed。这个报错通常出现在你本地配了代理类工具但代理没起来或端口不对。ClaudeCode 本身不需要额外代理如果你之前为了别的目的配过先检查代理进程是否在跑、端口是否被占用。最省事的做法是先把代理相关配置清掉直接用 TaoToken 端点排除干扰。reading choices 相关报错。这类报错一般出现在响应解析阶段提示读取 choices 字段失败。常见原因是端点返回的不是预期的 JSON 结构或者 Model ID 填错了导致服务端返回了错误格式。检查ANTHROPIC_MODEL是不是控制台模型列表里的有效型号别自己拼一个不存在的名字。OAuth 相关报错。如果你之前用 OAuth 方式登录过 ClaudeCode本地可能残留了 OAuth 凭据和 API Key 方式冲突。表现是明明配了 Key请求还是走旧的 OAuth 通道然后失败。解决办法是清掉本地 OAuth 缓存强制走 API Key。具体位置在用户目录的.claude下找到凭据相关文件移除或重命名。TodoWrite 报错 Only one task can be in_progress。这不是通道问题是任务清单本身违反了单 in_progress 约束。检查你或模型生成的清单是不是有两项同时标了 in_progress。改成一个另一个退回 pending。TodoWrite 报错 Max 20 todos allowed。任务拆得太细了。把粒度调粗合并那些打开文件读取第一行之类的微步骤。经验上 5 到 15 个有意义的步骤足够表达绝大多数编码任务。排查顺序建议先确认通道看日志有没有请求再确认配置三件套对不对最后确认任务清单有没有违反约束。通道问题占大多数别一上来就怀疑 TodoWrite。6. 把通道和规划都固定下来TodoWrite 的价值不在它多复杂而在它把计划从易失的思维链里拽出来变成外部可见、可追踪、可引用的状态。配合单 in_progress 和 20 条上限两条硬约束多步任务的完成率会有肉眼可见的提升。通道这边把 settings 统一到 TaoToken 之后所有调用从一个入口出去日志集中排查快。三件套记牢Base URL 是https://taotoken.net/apiKey 在控制台生成Model ID 填有效型号。配置时注意环境变量和 settings 的优先级别让旧变量偷偷覆盖。如果你还在选模型或验证通道可以先用模型对话页面发一条简单请求确认连通如果准备长期跑编码和 Agent 任务Coding Plan 更适合高频调用场景接入细节和参数说明在接入文档里都有。把通道固定下来把规划交给 TodoWrite剩下的就是让模型专注干活。