1. OpenCode Agent 里 todowrite 工具提示词到底解决什么问题如果你最近在折腾 OpenCode 这类终端 Agent大概率会遇到一个很具体的困惑明明模型能力不差但一让它做多步任务它就开始东一榔头西一棒子改完 A 文件忘了 B 文件重构到一半突然跑去写测试最后你只能自己拿小本本记它到底改到哪了。todowrite 这个工具提示词本质上就是给 Agent 装一个「任务看板」让它把脑子里那团乱麻先拆成一条条能打勾的清单再按顺序执行。我在实际项目里试过让 Agent 做一次跨 8 个文件的重命名没有 todowrite 的时候它改到第 5 个文件就「失忆」了前面改过的引用关系全乱套加上 todowrite 提示词之后它会先搜索、再列清单、逐项执行、逐项回传结果整个过程你能在终端里看到它一步步推进。这就是 todowrite 的核心价值把「多步、复杂、高风险」的任务从模型脑内推理变成外部可见的结构化状态。它适合谁三类人最该关注。第一类是正在用 OpenCode 做日常编码的开发者尤其是需要 Agent 帮忙做重构、批量修改、新功能拆解的场景第二类是在调 Agent 工具链的人想搞清楚工具提示词怎么写才能让模型稳定触发 todowrite第三类是准备把模型请求统一走一个 API 通道的团队因为 todowrite 这类工具调用对请求稳定性、模型 ID 一致性要求比较高通道换来换去很容易出现工具调用格式对不上的问题。这篇要做的三件事很明确把 OpenCode 的 settings 配置改到 TaoToken 统一通道给出可复制的 todowrite 工具提示词模板然后跑一次完整的 Agent 任务验证工具调用和结果回传是否正常。全程都是可跟做的步骤配置片段直接抄就行。2. 把 OpenCode settings 接到 TaoToken 的前置准备在动 settings 之前先把几个概念对齐不然后面配置报错你会不知道错在哪。OpenCode 的模型请求最终是发到一个兼容 OpenAI 协议风格的 Base URL 上工具调用tool call依赖模型返回结构化的 function call 字段。todowrite 作为一个工具它的提示词会作为 system 或工具描述注入到请求里模型根据提示词决定什么时候调用、传什么参数。所以整条链路是OpenCode 读 settings → 拼请求含工具提示词→ 发到 Base URL → 模型返回 tool call → OpenCode 执行并回传结果。TaoToken 在这里扮演的角色就是那个统一的 Base URL 和 Key 通道。你不需要在 OpenCode 里为每个模型单独配一套地址只要把 Base URL 指向https://taotoken.net/apiKey 用你在控制台生成的Model ID 填你实际要用的模型标识工具调用链路就能跑通。这样做的好处是todowrite 提示词里如果写死了模型行为假设换模型时不用改提示词只改 Model ID 就行。前置准备清单如下。先去控制台生成一个 API Key地址是https://taotoken.net/console生成后复制保存后面 settings 里要用。然后确认你要用的 Model ID这个在模型列表或文档里能查到地址https://taotoken.net/doc。如果你还没决定用哪个模型可以先在模型对话页面试一下工具调用是否正常地址https://taotoken.net/models输入一段需要多步拆解的任务看它会不会主动列清单。这里有个容易踩的坑很多人以为 Base URL 填官网首页就行结果请求 404。记住 API 地址是https://taotoken.net/api不带任何多余路径OpenCode 会自己在后面拼/v1/chat/completions这类端点。另外 Key 不要带空格复制的时候容易多一个换行导致 401。还有一点关于 todowrite 提示词的准备。你要在 OpenCode 的工具配置里定义 todowrite 这个工具的 schema包括它接受哪些参数通常是任务列表数组每项含 id、content、status以及工具描述文本。这个描述文本就是「工具提示词」它决定了模型什么时候触发 todowrite。描述里要写清楚触发条件比如「当任务涉及 3 个以上步骤、或涉及多个文件修改、或属于高风险重构时必须先调用 todowrite 建立清单」。这段文本后面我会给模板。3. 可复制的 settings 配置与 todowrite 提示词模板这一节是核心直接给可复制的片段。OpenCode 的 settings 文件通常是 JSON 或 TOML 格式路径一般在项目根目录的.opencode/settings.json或用户目录下的配置里。下面给一份 JSON 版本字段名按 OpenCode 常见约定来你对照自己的版本微调。{ provider: { taotoken: { type: openai-compatible, baseURL: https://taotoken.net/api, apiKey: sk-你的TaoTokenKey, models: { default: { id: 你的ModelID, name: taotoken-default } } } }, agent: { tools: { todowrite: { enabled: true, description: 当任务涉及3个以上步骤、多个文件修改、或高风险重构时必须先调用本工具建立任务清单。清单每项包含 id、content、statusstatus 取值 pending/in_progress/completed。执行过程中每完成一项必须更新状态。, parameters: { type: object, properties: { todos: { type: array, items: { type: object, properties: { id: { type: string }, content: { type: string }, status: { type: string, enum: [pending, in_progress, completed] } }, required: [id, content, status] } } }, required: [todos] } } } } }如果你用的是 TOML 版本等价写法如下注意[provider.taotoken]这种表头结构。[provider.taotoken] type openai-compatible baseURL https://taotoken.net/api apiKey sk-你的TaoTokenKey [provider.taotoken.models.default] id 你的ModelID name taotoken-default [agent.tools.todowrite] enabled true description 当任务涉及3个以上步骤、多个文件修改、或高风险重构时必须先调用本工具建立任务清单。清单每项包含 id、content、statusstatus 取值 pending/in_progress/completed。执行过程中每完成一项必须更新状态。三件套对照一下Base URL 是https://taotoken.net/apiKey 是控制台生成的sk-开头字符串Model ID 是你选的模型标识。这三个必须同时正确缺一个都会在验证阶段报错。关于 todowrite 提示词模板我建议在 description 里再补一段「反例约束」防止模型滥用。比如加上「如果任务只是单文件单步骤修改不要调用本工具直接执行」。这样能避免模型为了「显得严谨」而给一个改错别字的任务也列五步清单。实测下来加了反例约束后简单任务的响应速度明显变快工具调用次数也降下来了。另外如果你的 OpenCode 版本支持在工具描述里引用变量可以把当前工作目录、项目类型这些上下文注入进去让模型判断复杂度时更准。比如描述里写「当前项目为 {projectType}涉及 {fileCount} 个文件」模型看到文件数多就会更倾向触发 todowrite。这个不是必须的但能提升触发准确率。配置改完之后别急着跑复杂任务先做一次最小验证让 Agent 做一个明确需要三步以上的任务看它是否先返回 todowrite 的 tool call参数里 todos 数组是否结构正确。如果它直接开始改文件而不列清单说明 description 的触发条件写得不够强回去把「必须先调用」改成「必须首先调用否则视为违规」。4. 验证请求与成功结果跑一次完整 Agent 任务配置就位后来跑一次真实任务。我选一个典型场景把项目里一个函数名oldHandler全局重命名为newHandler涉及多个文件。这个任务复杂度够能触发 todowrite也能验证工具调用链。启动 OpenCode输入任务描述「把项目中所有 oldHandler 重命名为 newHandler注意不要改到注释和字符串里的同名内容改完跑一次构建确认没有引用错误。」预期行为分四步。第一步Agent 先调用搜索工具摸清 oldHandler 出现在哪些文件、哪些位置。第二步它调用 todowrite返回一个 tool call参数类似下面这样。{ todos: [ { id: 1, content: 搜索 oldHandler 所有引用位置, status: completed }, { id: 2, content: 修改 src/handler.js 中的函数定义, status: in_progress }, { id: 3, content: 修改 src/router.js 中的调用点, status: pending }, { id: 4, content: 修改 src/middleware.js 中的引用, status: pending }, { id: 5, content: 运行构建并处理报错, status: pending } ] }第三步OpenCode 执行这个 tool call把清单渲染到终端然后逐项推进每完成一项就发一次 todowrite 更新状态。第四步全部完成后Agent 返回最终结果包含修改的文件列表和构建输出。成功结果的判断标准有三个。一是 todowrite 的 tool call 在请求日志里能看到说明工具提示词生效了二是清单状态从 pending 逐步变成 completed说明结果回传正常三是最终构建通过说明任务真的执行到位了。如果构建报错Agent 应该把报错信息作为新任务追加到清单里而不是直接结束。这里贴一段验证时终端输出的简化示意帮你对照。[tool call] todowrite todos: 5 items [execute] 搜索完成找到 8 个文件 15 处引用 [tool call] todowrite todos: item2 - in_progress [execute] src/handler.js 修改完成 ... [result] 构建通过0 errors如果你在模型对话页面单独测工具调用地址用https://taotoken.net/models输入同样的任务看模型是否返回结构化的 function call。这一步能帮你排除是 OpenCode 配置问题还是模型本身不支持工具调用。验证通过后建议把这次成功的 settings 和提示词存一份到项目里团队其他人直接复用。因为 todowrite 的触发效果和模型强相关换模型时最好重新跑一次这个验证任务确认新模型的 tool call 格式没变。5. 本篇常见错误排查401、local proxy failed 与 choices 解析失败配置和验证过程中报错基本集中在几个地方。下面按真实报错对照排查。401 Unauthorized。这个最常见原因就三个Key 错了、Key 过期了、Key 带了多余字符。先检查 settings 里的 apiKey 字段确认是sk-开头且没有换行和空格。然后去控制台https://taotoken.net/api-keys确认这个 Key 还在有效期内。如果都没问题用 curl 直接测一下排除是 OpenCode 的问题。curl https://taotoken.net/api/v1/chat/completions \ -H Authorization: Bearer sk-你的Key \ -H Content-Type: application/json \ -d {model:你的ModelID,messages:[{role:user,content:hi}]}如果 curl 返回 200说明 Key 和 Base URL 没问题问题在 OpenCode 配置读取上检查 settings 文件路径是否被正确加载。local proxy failed。这个报错通常出现在你本地有代理设置或者 OpenCode 尝试走本地代理端口但没起来。先检查环境变量里有没有HTTP_PROXY、HTTPS_PROXY这类设置有的话临时清掉再试。另外确认 Base URL 没有写成localhost或127.0.0.1开头的地址必须是https://taotoken.net/api。如果报错信息里提到端口检查那个端口是不是被别的进程占了。reading choices 解析失败。这个报错说明请求发出去了模型也返回了但返回结构里没有choices字段或者choices是空的。原因可能是 Model ID 填错了请求被路由到了一个不返回标准结构的端点。去https://taotoken.net/doc核对 Model ID 拼写注意大小写。还有一种可能是请求体里stream参数和 OpenCode 的解析逻辑不匹配试试在 settings 里显式关掉流式。OAuth 相关报错。如果你在配置里看到了 OAuth 字样说明 OpenCode 尝试走 OAuth 认证而不是 API Key。检查 settings 里 provider 的 type 是不是openai-compatible如果是oauth或类似值改成兼容模式。OAuth 那套是给特定平台用的走 TaoToken 统一通道不需要。工具调用不触发。这个不算报错但很常见。表现是 Agent 直接开始改文件不调 todowrite。排查顺序先看 description 里触发条件是否够强把「当任务涉及」改成「必须首先调用」再看模型是否支持 function call有些轻量模型不支持工具调用换一个支持 tool use 的 Model ID最后看 OpenCode 版本老版本可能工具注册方式不同升级到最新版。排查时有个通用技巧把 OpenCode 的日志级别调到 debug看完整请求和响应。请求里能看到工具提示词有没有被注入响应里能看到模型返回的原始结构。对照这两端问题基本能定位。6. 把 todowrite 用顺之后的下一步todowrite 跑通之后你会发现 Agent 做多步任务的可控性上了一个台阶。但工具提示词不是一劳永逸的不同模型对同一段 description 的响应差异挺大。我的做法是维护一个提示词版本表每换一次 Model ID 就跑一次第 4 节那个重命名验证任务记录触发率和清单质量选触发稳定、清单粒度合理的那个组合。如果你打算长期用 Agent 做编码建议把 todowrite 和 Coding Plan 配合起来地址https://taotoken.net/coding-plan这样工具调用链路的请求量有保障不会因为额度问题中断任务。接入文档在https://taotoken.net/doc里面有各语言的调用示例对照着调 settings 更快。最后留一个实用技巧todowrite 的清单项 content 写得越具体Agent 执行时越不容易跑偏。比如「修改 src/router.js 第 42 行的调用点」就比「修改路由文件」好得多。你可以在工具提示词里加一句「每项 content 必须包含具体文件路径和修改位置」模型列清单时就会自动细化。这个改动很小但实测对执行准确率提升明显。