OpenCode 跑 subagent_depth 边界测试：Key 用 TaoToken

OpenCode v1.18.2 的发布说明里，最值得在本地跑一遍的不是界面修复，而是 subagent 的默认深度边界：默认情况下，subagent 不能再启动下一层 subagent，确有必要时通过 subagent_depth 显式放开。这件事听起来很安全，但我在验证时发现，任务编排测试最怕的不是递归写错，而是模型通道不稳定、Key 到处散落：一会儿是 GPT-5.6 的上下文限制，一会儿是 Luna 的存储行为，分不清递归是被 OpenCode 拦下来的，还是模型请求根本没发出去。所以我先把模型入口统一到 TaoToken 上，注册只需要去 https://taotoken.net/?utm_source=taotoken_aicg_blog_end 拿一把 Key，再把 OpenCode 的 provider Base URL 填成 https://taotoken.net/api，用同一把 Key 把 subagent_depth 的边界完整测了一遍。下面的步骤包含模型通道配置、两种测试状态、报错对照和用量核对，按顺序做大概二十分钟。

1. 先明确 subagent_depth 测的是哪条边界

1.1 默认阻止嵌套的实际表现

在 v1.18.2 之前，OpenCode 的 subagent 可以继续拉起下一层 subagent，递归链条一旦因为工具反复调用而变得不稳定，成本会成倍放大。v1.18.2 把默认行为改成阻止嵌套：主 agent 可以调用 subagent，但 subagent 不再有权限再启动自己的 subagent。这个限制的设计意图是防失控，不是禁用多级协作。需要更多层级时，用 subagent_depth 显式声明。测试时要先理解这一点，否则你会把“被默认阻止”误判成“模型通道出错”。

如果做一个类比：它更像是访客门禁，默认只放行到第一层会客区，subagent 想再往内走，需要额外签批。签批就是 subagent_depth，而没签批时被保安拦下，跟大楼停电是两回事。你在验证时，要能区分“OpenCode 的策略生效”和“模型请求失败”，前者会给你明确的编排反馈，后者往往表现为超时或 401。本地验证时建议直接用 v1.18.3，因为它的 Home 会话搜索和 WSL 启动修复包含更完整的发布链；subagent_depth 的行为从 v1.18.2 起就已经稳定。

1.2 维护者提醒：深度限制不是权限沙箱

原周报里维护者说得非常明确：subagent_depth 控制的是递归深度，不是文件系统、命令执行或网络访问的边界。V2 permission 可能不会完整传播到 active session，external_directory: deny 对 subagent 的实际边界还有开放 issue，Plan mode 也存在被绕过的方式。所以即便你显式放开了一层，默认阻止只说明“递归层级受控”，不说明“subagent 能碰的东西受控”。安全敏感场景仍然需要把容器、系统权限和网络策略放在 OpenCode 之外。这条提醒应该写进你的测试结论里，而不是只在周报里看到。

把这两件事分开，是整篇测试的前提：subagent_depth 解决的是“递归会不会失控”，权限沙箱解决的是“越权行为会不会发生”。前者是 OpenCode 自己的参数，后者需要你在外部环境补齐。

2. 为什么边界测试先换到统一 API 通道

2.1 多 Key 切换会污染编排测试结论

我在验证 subagent 边界时踩过的坑是：模型通道的噪音比编排逻辑的噪音还大。如果同时给 OpenCode 配了官方 Key、测试 Key、Azure Key，某一次请求失败时，你很难判断是 subagent 嵌套被默认阻止，还是那个 provider 的模型元数据不对。原周报里也提到，GPT-5.6、Luna、xAI 这波兼容修复涉及请求路径、上下文限制和 storage 行为，每一个都会造成“看起来像编排坏了”的假象。换用 TaoToken 统一 API 通道后，所有模型走同一个 Base URL 和同一把 Key，出问题时变量就少很多。

TaoToken 在这里只作为模型通道的统一入口，不替 OpenCode 执行任何 subagent 逻辑。换句话说，OpenCode 负责编排和递归限制，TaoToken 负责把模型请求稳定送达。两者职责分离，测试时才能定位得更干净。

2.2 OpenCode provider 里的 Base URL 与官网地址要分开

OpenCode 的 provider 配置支持 OpenAI-compatible 接口。把 provider 的 Base URL 填成 https://taotoken.net/api，注意末尾不要加 /v1。官网落地页 https://taotoken.net/?utm_source=taotoken_aicg_blog_end 只用来注册、创建 Key、看模型广场和用量；填进工具的永远只有 https://taotoken.net/api。不少人喜欢把浏览器地址栏里的链接直接粘进配置，结果请求全部打到了 HTML 页面而不是 API，表现就是一连串 404 或解析错误。

之所以先统一到 TaoToken 再测 subagent_depth，还有一个现实原因：Key 管理。任务编排测试需要反复跑同一场景，每次换 Key 都会让 token 消耗和失败记录对不上账。TaoToken 的模型广场会列出当前可用的模型 ID，你不用在多个控制台之间横跳。

3. 配置 OpenCode 指向 TaoToken：三样东西就够了

3.1 先从 TaoToken 官网拿 Key

打开 TaoToken，完成注册后创建一把 API Key，复制时注意别带空格或换行。本文所有配置里的 Key 一律用 YOUR_API_KEY 占位，你实际填写的是自己在 TaoToken 创建出来的那串。接下来到模型广场确认你要用的模型 ID：原周报里提到的 GPT-5.6、Luna、xAI 等模型，在广场上都有对应的模型 ID，以广场显示的为准。不要凭记忆填网上旧教程里的 ID，模型 ID 对不上会在后续请求阶段直接报错。

这一小步对应原周报里反复出现的“模型元数据正确性”问题——v1.17.19 修的就是 GPT-5.6 的 context limit 和 Luna 的请求路径。你用 TaoToken 之后，这些元数据由模型广场统一维护，配置端只需要复制 ID 而不是手工拼接。

3.2 把 provider 写进 opencode.json

OpenCode 的全局配置一般在 ~/.config/opencode/opencode.json，你也可以在项目根目录建一份项目级配置。下面是一个可用的 provider 片段：

{
  "$schema": "https://opencode.ai/config.json",
  "provider": {
    "taotoken": {
      "npm": "@ai-sdk/openai-compatible",
      "name": "TaoToken Unified API",
      "options": {
        "baseURL": "https://taotoken.net/api",
        "apiKey": "YOUR_API_KEY"
      },
      "models": {
        "your-model-id": {
          "name": "Model from TaoToken Model Hub"
        }
      }
    }
  }
}

把 apiKey 的值换成你在 TaoToken 创建的真实 Key，再把 models 里的 your-model-id 换成模型广场复制的 ID。注意 baseURL 保持 https://taotoken.net/api 原样，不要加 /v1，也不要把 https://taotoken.net/?utm_source=taotoken_aicg_blog_end 填进来。保存后重启 OpenCode，在模型选择器里应该能看到刚刚配置的 provider 和对应模型。

如果你用的是 OpenCode Desktop v2，Settings 里的 provider 分组也能完成同样配置；桌面端和 JSON 配置是同一套字段，选一种即可。配置完成后，先跑一条最简单的对话确认通道通着，再开始 subagent 边界测试。这一步不需要同时配七个 Key，一个 provider、一个模型 ID、一把 Key，把测试变量压到最小。

4. subagent_depth 边界测试的两种状态与预期

4.1 状态一：不设 subagent_depth，确认默认阻止

新建一个空目录，跑一个主任务，让它调用 subagent 去完成一件非常小的子任务，比如“用 subagent 列出当前目录的文件，再让那个 subagent 继续用 subagent 执行 ls”。不需要真的去生产目录，本地临时目录就够了。不设置 subagent_depth 时，预期是第二层 subagent 被默认阻止，OpenCode 的输出会给出明确的编排反馈，而不是模型返回的报错。

提示：测试时把工作目录固定在临时目录，避免 subagent 误触项目真实文件。这个测试只是确认递归策略，不需要任何真实业务数据。

这一步也可以验证你上一步配置的模型通道是否稳定：如果主 agent 和第一层 subagent 都正常完成，只有第二层嵌套被拦下来，说明通道没问题，策略生效了。如果连第一层都频繁超时，说明去查 TaoToken 的 Key 或模型 ID，不要急着改 subagent 配置。

4.2 状态二：显式放开一层，观察递归行为与 token 消耗

确认默认阻止后，在 OpenCode 的 agent 配置或当前会话参数里显式设置 subagent_depth 为 1（具体字段名以你安装版本的 --help 或 release note 为准）。再次运行同样的任务，预期是 subagent 可以再启动一层 subagent，第二层再往下就被拦。放开这一层之后，观察两件事：递归行为是否按预期展开，以及 token 消耗是否明显上升。

token 消耗是这次测试最值得记录的部分。可以用一个表格记录三组数据：

建议先测前两行就够了。放开两层容易让任务在本地空转，消耗不必要的额度。如果你只是验证边界，第一行和第二行的对比已经能说明问题。测试时尽量用短 prompt 和小任务，避免长上下文本身成为干扰变量。TaoToken 的用量记录会在这里派上用场：每跑完一种状态，去控制台看一次消耗，确认递归层级和 token 的对应关系是否合理。

5. 边界测试容易遇到的三个配置错

5.1 401：先检查 Key 是否复制完整

如果你按上面的配置跑，第一层就报 401，优先检查 opencode.json 里的 apiKey 是不是 YOUR_API_KEY 原样留在那里。YOUR_API_KEY 是占位符，不是真实 Key。确认 Key 从 https://taotoken.net/?utm_source=taotoken_aicg_blog_end 创建后完整复制，且没有多余空格。401 在这个场景里跟 subagent_depth 没有关系，不要因为在测嵌套就把锅甩给递归策略。把 Key 修正后重跑 4.1，递归行为没变，但请求会变正常。

5.2 模型 not found 或请求路径错误：检查模型 ID 和 Base URL

如果报错信息里出现 model not found 或请求 404，先回模型广场核对当前使用的模型 ID。原周报里 GPT-5.6 的 model not found issue 就是这类问题的典型：模型元数据变了，旧 ID 跟着失效。另一个容易踩的是 Base URL 多写了 /v1。https://taotoken.net/api 是接口统一入口，填成 https://taotoken.net/api/v1 会让请求路径变形。把配置里这两处修好，再回到第 4 章的状态一重跑一遍。排障要点就这三个：Key、模型 ID、有没有多写 /v1。其他兼容问题等你真的遇到了再看模型广场的公告或日志，不要提前做一堆无关优化。

6. 测完回控制台核对一次用量

6.1 用量的落差对应递归层数的落差

测试跑完后，回到 https://taotoken.net/?utm_source=taotoken_aicg_blog_end 的控制台查看用量记录。你把“默认阻止”和“放开一层”两次调用的记录并排看，应该能发现 token 消耗有明显落差：默认阻止那次只到第一层 subagent，放开一层那次多了第二层请求。这个落差就是你为了“放开嵌套”付出的真实成本，也是决定生产环境要不要打开 subagent_depth 的依据。如果两次用量几乎一样，说明你测试任务根本没触发递归，回去检查 subagent 是否真的被调用。这一步其实就是把周报里提到的 session totals 与用量信息落到自己的账号上看一眼。追踪上下文压缩、会话成本和可用额度，是该喂给模型之前先喂给自己的功课。

6.2 边界测试的结论要分两层写

测试结束后，把结论拆成两层记录：第一层是递归控制——默认阻止生效，放开到 subagent_depth=1 后行为符合预期；第二层是安全边界——subagent_depth 不替代权限沙箱。原周报里维护者的建议是自动化团队可以在受控试点采用，安全敏感团队仍要把容器、系统权限和网络策略放在 OpenCode 之外。我在测完后认同这个判断：递归深度限制解决的是“失控放大”，不解决“越权访问”。如果后续你要在生产任务里放开嵌套，务必让权限隔离先于深度放开，顺序不能反过来。

7. 结论：深度可以放开，权限沙箱不能省

subagent_depth 是 OpenCode v1.18.2 给任务编排上的一道保险：默认保险是合上的，需要时用 subagent_depth 逐层放开。整套测试做完，最有价值的不是“我设置了 1”，而是你同时验证了模型通道稳定、递归行为可预期、token 消耗可追踪。这三件事缺一不可：通道不稳定会让你误判递归策略，递归不可预期会让你不敢放开嵌套，消耗不可追踪会让你无法判断成本上限。

TaoToken 在这里承担的是统一模型入口。把散落的 Key 收成一把，把官方、测试、备用的模型请求都走同一个 Base URL，你才能把注意力留在 OpenCode 的编排逻辑上。还没拿 Key 的话，去 https://taotoken.net/?utm_source=taotoken_aicg_blog_end 注册并创建 API Key，在模型广场复制你打算用的模型 ID，回到 OpenCode 把 provider 配好，先跑一次默认阻止，再放开一层，最后去控制台把两次用量对一眼。这条链路跑通后，subagent_depth 在你项目里就不再是一个需要猜的功能。