1. OpenCode task 工具提示词到底在管什么为什么要把 settings 改到 TaoTokenOpenCode 里的 task 工具提示词本质上是主 Agent 的“派活说明书”。它规定了主 Agent 在什么情况下应该自己动手什么情况下应该启动一个子 Agent 去独立处理复杂任务。这个提示词文件通常放在opencode/packages/opencode/src/tool/task.txt内容不短核心就三件事什么时候用 task、必须指定哪个 subagent_type、以及哪些简单操作不要用 task。我一开始只把它当成一个普通的工具描述文件后来发现它其实决定了整个 Agent 的任务分流效率。比如你输入/check-file path/to/file.py主 Agent 不会自己去逐行读文件而是通过 task 工具把整条 slash command 下发给一个专门处理文件检查的子 Agent。子 Agent 有独立的会话环境可以自己规划步骤、调用其他工具最后把结果返回给主 Agent。这个过程听起来很顺但前提是模型接入通道得稳定否则子 Agent 刚启动就因为请求超时挂掉整个任务链就断了。这就是为什么我要把 settings 里的模型接入地址改到 TaoToken。OpenCode 默认可能走的是官方或其他第三方通道但在实际使用中子 Agent 的冷启动会频繁发起模型请求如果通道不稳定或者 Key 管理混乱task 工具的成功率会明显下降。TaoToken 提供统一的 Key 和 API 通道把 Base URL 指向https://taotoken.net/api之后主 Agent 和子 Agent 共用同一套接入配置省去了每个子 Agent 单独配 Key 的麻烦。适合谁看这篇如果你已经在用 OpenCode 的 Agent 功能尤其是经常触发 task 工具做多步骤任务或者你正在调试子 Agent 的提示词效果那这篇的配置链路和验证方法可以直接拿去用。如果你还没接触过 OpenCode但想了解 Agent 工具提示词怎么和模型接入层配合也可以顺着看下去配置部分都是可复制的。我试过在同一个项目里混用两套接入配置结果子 Agent 启动时偶尔会走到旧的 Base URL导致 401 报错。后来统一改到 TaoToken 之后这个问题就没再出现过。下面从 settings 文件的位置开始一步步把配置改到位。2. TaoToken 前置准备Key、Base URL 和 OpenCode settings 文件定位在改 settings 之前先把 TaoToken 这边的三件套准备好API Key、Base URL、以及你要用的 Model ID。这三样东西在 OpenCode 的配置里会反复出现尤其是 task 工具启动子 Agent 时子 Agent 会继承主 Agent 的模型配置所以 Base URL 和 Key 必须写对。先拿 Key。打开 TaoToken 的 API Keys 页面路径是https://taotoken.net/api-keys登录后创建一个新的 Key。建议给这个 Key 起个能识别的名字比如opencode-agent方便后面在 settings 里对照。创建完复制出来后面配置里用得到。注意 Key 只显示一次复制后先存到安全的地方。Base URL 用https://taotoken.net/api这个地址不加任何 UTM 参数直接写进配置就行。Model ID 根据你实际要用的模型来填比如claude-sonnet-4-20250514或者gpt-4o这类具体以 TaoToken 模型对话页面里列出的为准。你可以先在模型对话里发一条测试消息确认这个 Model ID 能正常返回再去改 OpenCode 的 settings。接下来定位 OpenCode 的 settings 文件。OpenCode 的配置通常放在用户目录下的.opencode文件夹里具体路径取决于你的操作系统。macOS 和 Linux 一般在~/.opencode/settings.jsonWindows 在%USERPROFILE%\.opencode\settings.json。如果你用的是项目级配置也可能在项目根目录的.opencode文件夹里。先确认你当前生效的是哪一个避免改了全局配置但项目里覆盖了。打开 settings.json 之后你会看到类似provider或model的字段。OpenCode 的配置结构里模型接入通常包含baseURL、apiKey、model这几个关键项。不同版本的 OpenCode 字段名可能略有差异但核心逻辑是一样的把 baseURL 指向 TaoToken 的 API 地址apiKey 填刚才创建的 Keymodel 填你要用的 Model ID。这里有个容易踩的坑OpenCode 的 settings 里可能同时存在多个 provider 配置比如anthropic、openai各有一套。如果你只改了其中一个task 工具启动子 Agent 时可能走到另一个没改的 provider结果还是报 401。所以改的时候要把所有可能被 Agent 用到的 provider 都统一指向 TaoToken或者至少确认主 Agent 和子 Agent 用的是同一个 provider。另外task 工具提示词里提到的 subagent_type在 OpenCode 客户端里对应的是预置的子 Agent 类型。这些子 Agent 在启动时会读取 settings 里的模型配置所以你的 TaoToken 配置必须对它们可见。如果你用的是项目级 settings确认子 Agent 启动时的工作目录能读到这个文件。准备好这三样之后就可以进入实际的配置修改了。下一节给出可复制的 settings 片段以及 task 工具提示词的模板你可以直接对照着改。3. 可复制配置settings.json 片段与 task 工具提示词模板这一节直接给可复制的内容。先看 settings.json 的配置片段路径以~/.opencode/settings.json为例如果你用的是项目级配置把同样的内容放到项目根目录的.opencode/settings.json里。{ provider: { taotoken: { baseURL: https://taotoken.net/api, apiKey: sk-你的TaoTokenKey, model: claude-sonnet-4-20250514 } }, agent: { defaultProvider: taotoken, task: { enabled: true, subagentProvider: taotoken } } }这段配置里provider.taotoken定义了 TaoToken 的接入信息baseURL固定为https://taotoken.net/apiapiKey换成你刚才创建的那个 Keymodel换成你要用的 Model ID。agent.defaultProvider和agent.task.subagentProvider都指向taotoken确保主 Agent 和 task 工具启动的子 Agent 走同一个通道。如果你原来的 settings 里已经有其他 provider不要直接删掉而是把defaultProvider和subagentProvider改成taotoken。这样即使其他 provider 还在Agent 也不会走到它们。改完之后保存文件OpenCode 下次启动时会读取新的配置。接下来是 task 工具提示词的模板。这个模板对应opencode/packages/opencode/src/tool/task.txt的内容你可以根据自己项目的情况调整。核心是让主 Agent 清楚什么时候该派活、派给谁、以及哪些简单操作不要用 task。Task 工具用于启动一个新的子 Agent 来独立处理复杂的多步骤任务。 使用条件 - 任务需要跨多个文件、多种操作且步骤无法在一次响应内完成 - 需要执行预定义的 slash command例如 /check-file path/to/file.py - 任务需要独立的会话环境避免污染主 Agent 的上下文 必须指定 subagent_type根据任务性质选择 - code-review代码审查类任务 - refactor大规模重构任务 - slash-command执行自定义斜杠命令 不要使用 Task 工具的场景 - 查找特定文件路径例如搜索 *.js直接用 Glob 工具 - 查找特定类定义例如 class Foo直接用 Glob 工具 - 在 2 到 3 个指定文件里搜索代码直接用 Read 工具 启动子 Agent 有冷启动成本包括加载上下文和初始化环境。简单操作直接用主 Agent 现有工具完成不要为了省事而派发。这个模板可以直接覆盖到 task.txt 里也可以作为你自定义提示词的起点。注意subagent_type的取值要和 OpenCode 客户端里实际预置的类型对上不同版本的 OpenCode 可能名称略有差异改之前先确认一下。配置改完之后还需要确认 OpenCode 能正确加载。有些版本会在启动时缓存 settings改完文件后最好重启一次 OpenCode或者执行一次重新加载配置的命令。如果你用的是 VS Code 插件形态的 OpenCode重启窗口通常就够了。这里再强调一下三件套的对应关系Base URL 是https://taotoken.net/apiKey 是你创建的sk-开头的字符串Model ID 是你在 TaoToken 模型对话里验证过的那个。这三样在 settings 里必须一致否则 task 工具启动子 Agent 时会因为配置不匹配而失败。配置写完之后下一节用一个实际的任务调用来验证提示词和通道是否都生效。4. 验证请求一次 task 工具调用确认提示词与通道均生效配置改完不能只看文件得实际跑一次 task 工具调用确认子 Agent 能正常启动、提示词按预期分流、并且模型请求走的是 TaoToken 通道。下面用一个具体的 slash command 场景来验证。假设你的项目里有一个自定义命令/check-file它对应的子 Agent 类型是slash-command。在 OpenCode 的对话窗口里输入/check-file src/utils/parser.js主 Agent 收到这条命令后会根据 task 工具提示词的规则判断这是一个预定义的 slash command需要启动子 Agent 来执行。于是它会调用 task 工具指定subagent_type为slash-command把整条命令下发给子 Agent。子 Agent 启动后会读取 settings 里的模型配置向https://taotoken.net/api发起请求。如果配置正确你会看到子 Agent 开始输出文件检查的结果比如解析parser.js的结构、列出潜在问题、给出修改建议。整个过程主 Agent 不会自己去读文件而是等子 Agent 返回结果后再汇总。验证成功的标志有三个。第一子 Agent 正常启动没有出现local proxy failed或401之类的报错。第二子 Agent 的输出内容符合/check-file命令的预期说明提示词里的分流逻辑生效了。第三在 TaoToken 的 console 里能看到这次请求的记录路径是https://taotoken.net/console确认请求确实走了 TaoToken 通道。如果你在 console 里看不到请求记录或者子 Agent 返回的是其他 provider 的模型特征那说明 settings 里的 provider 没有完全切换过来。这时候回去检查defaultProvider和subagentProvider是否都指向了taotoken以及是否有其他配置文件覆盖了当前设置。再验证一个简单场景确认 task 工具提示词里的“不要使用 Task 工具”规则也生效。在对话窗口输入帮我找一下项目里所有的 *.test.js 文件按照提示词主 Agent 应该直接用 Glob 工具搜索而不是启动子 Agent。如果你看到主 Agent 直接返回了文件列表没有触发 task 工具说明提示词里的排除规则起作用了。反过来如果它启动了一个子 Agent 去干这件事那提示词可能没加载对或者被其他配置覆盖了。这两个场景跑通之后基本可以确认 settings 配置和 task 工具提示词都生效了。接下来把常见的报错和排查方法整理一下方便你遇到问题时对照。5. 本篇常见错排查401、local proxy failed、reading choices、OAuth配置过程中最容易遇到的就是接入层的报错。下面按真实报错信息来对照排查每条都给出可能的原因和解决方向。401 Unauthorized这是最常见的报错通常出现在子 Agent 启动时。原因一般是 apiKey 没填对或者 Key 已经失效。先检查 settings 里的apiKey是不是完整的sk-开头字符串有没有多余空格。然后去 TaoToken 的 API Keys 页面确认这个 Key 还在有效期内。如果 Key 没问题再检查baseURL是不是写成了https://taotoken.net/api少写/api或者多写斜杠都可能导致鉴权失败。还有一种情况是 settings 里存在多个 provider子 Agent 走到了旧的 provider 配置。这时候把defaultProvider和subagentProvider都显式指向taotoken并且确认没有其他配置文件覆盖。local proxy failed这个报错说明 OpenCode 在尝试连接本地代理但代理没有启动或者端口不对。如果你之前配置过本地代理检查代理进程是否还在运行。如果不需要代理把 settings 里相关的 proxy 配置删掉让请求直接走https://taotoken.net/api。注意不要在任何配置里写涉及网络代理工具的地址保持接入层干净。reading choices 相关报错这类报错通常出现在模型返回格式不符合预期时。比如子 Agent 期望的是标准的 chat completion 响应但实际返回的结构不对。先确认 Model ID 是否在 TaoToken 模型对话里验证过有些模型 ID 写错了会返回错误格式。另外检查 settings 里的 model 字段有没有拼写错误大小写要一致。OAuth 相关报错如果你之前用 OAuth 方式登录过其他 providersettings 里可能残留了 OAuth 的 token 配置。这些配置和 TaoToken 的 apiKey 方式冲突时会报 OAuth 相关的错误。解决办法是把 OAuth 相关的字段从 settings 里移除只保留 TaoToken 的 apiKey 配置。如果你用的是 Codex 的 auth.json确认里面的 Base URL 和 Key 也统一指向 TaoToken避免两套配置打架。子 Agent 启动后没有输出如果子 Agent 启动了但一直没返回结果先看 TaoToken console 里有没有请求记录。有记录但没返回可能是 Model ID 对应的模型响应慢换个模型试试。没有记录说明请求根本没发出去回去检查 baseURL 和网络连通性。task 工具没有触发输入 slash command 后主 Agent 自己干了没有启动子 Agent。这说明 task 工具提示词没生效或者提示词里的使用条件没被满足。检查 task.txt 是否被正确加载以及subagent_type的取值是否和 OpenCode 客户端预置的类型匹配。如果提示词里写的类型客户端里不存在主 Agent 可能就放弃派发了。排查的时候建议按顺序来先确认 Key 和 Base URL再确认 provider 指向最后看提示词加载。大部分问题都出在前两步。6. 把配置沉淀下来长期编码与 Agent 任务的接入建议配置改完、验证跑通之后建议把 settings 和 task 提示词一起纳入版本管理。尤其是团队协作场景每个人的 OpenCode 配置可能不一样统一到 TaoToken 通道之后Key 的管理和轮换会简单很多。你可以把 settings.json 里的敏感字段抽成环境变量比如TAOTOKEN_API_KEY然后在配置里引用这样提交到仓库时不会泄露 Key。对于长期跑 Agent 任务的场景比如每天都要触发多次 task 工具做代码审查或重构建议关注一下 Coding Plan 的额度情况。路径是https://taotoken.net/coding-plan里面有适合持续编码任务的方案。如果你只是偶尔用 task 工具按量走 API 通道就够了。另外task 工具提示词不是一成不变的。随着你项目里子 Agent 类型的变化提示词里的subagent_type列表也需要同步更新。建议每次新增或修改子 Agent 类型后回来检查一下 task.txt 里的对应关系避免主 Agent 派发到不存在的类型。如果你在配置过程中遇到本篇没覆盖的报错可以去接入文档里对照排查路径是https://taotoken.net/doc。文档里有完整的 Base URL、Key 创建流程和常见错误码说明。需要快速验证模型连通性的时候直接用模型对话页面发一条消息比在 OpenCode 里反复试要快得多。最后提醒一点settings 改完之后如果 OpenCode 有多个工作区或项目确认每个项目用的都是同一份配置或者项目级配置里也同步了 TaoToken 的接入信息。否则你在 A 项目里跑通了 task 工具切到 B 项目又报 401来回排查很浪费时间。把配置统一之后task 工具提示词的分流逻辑才能真正稳定跑起来。