Claude Max额度用不上？OpenCode帮你花掉免费API额度

Claude 的 Max 和 Team 订阅里藏着一笔每月免费 API 额度，但官方客户端 Claude Code 花不掉它。第三方开源客户端 OpenCode 却可以，前提是配一把 Console API key。本文整理一位开发者的实测记录：额度规则、OpenCode 接入步骤，以及把整套 Claude Code 配置迁移到 OpenCode V2 时会踩的坑。

一笔被忽视的额度：Max 每月最高 200 美元

根据 Claude 帮助中心与 Platform 文档，Max 5x、Max 20x 和 Team 订阅每月附带一笔 API 额度，Max 5x 为 100 美元，Max 20x 为 200 美元，Team 按席位汇成一个池子、上限 500 美元。额度按月刷新、不累计，Pro 订阅不在范围内。

关键在于谁能花这笔钱。官方给出的可用范围很窄：直接用 API key 跑的 claude -p 或 Agent SDK 可以，Claude API 和 Console Playground 可以；而交互式 Claude Code（终端、IDE、桌面、网页）明确不可用，Bedrock、Vertex AI、Foundry 也不可用。至于 OpenCode 这类第三方客户端，官方页面只字未提。

这位作者在自己的机器上实测发现，用 OpenCode 发起请求后，Console 里的 Promotional credits 确实在下降。也就是说，第三方客户端大概率也能消耗这笔额度，但没有任何官方背书，随时可能变。

额度不会自动到账，需要在 claude.ai 的 Settings > Billing 里手动关联一个 Console 组织。一个订阅只能关联一个组织，且关联后无法自行更换，得走客服。新订阅要等满 7 天才允许关联。

Console 组织与 API key 的关系：Anthropic 的 Console（console.anthropic.com）是面向开发者的管理后台，独立的组织（Organization）是计费、API key 与用量的最小归属单位。一个组织下可以创建多把 sk-ant- 开头的 API key，也可以有多个 workspace，但同一组织内所有 key 共享同一份余额与用量统计。把订阅额度关联到 Console 组织，本质上是让订阅附带的 Promotional credits 挂在该组织名下，之后任何用该组织 key 发起的请求都会优先消耗这笔额度。反过来，如果 key 属于另一个未关联的组织，请求就只会扣该组织自己购买的额度——这正是“额度没下降”时第一个要排查的地方。

三步接入 OpenCode

接入流程本身不复杂，作者给出的最小路径如下：

# 1. 在 claude.ai 的 Settings > Billing 关联 Console 组织，再到 Console 创建 API key
# 2. 在 OpenCode 中注册 key（交互式终端里粘贴）
opencode auth login anthropic --method key
# 3. 验证
opencode run --model anthropic/claude-haiku-5-5 "Reply with exactly one word: pong"

在 Console 的 Settings → API keys 里点 Create key，命名并设置有效期，Linked account 选自己。key 以 sk-ant- 开头，只在创建时显示一次。同一组织下的 key 共用同一份余额，跨 workspace 也一样。

如果之前已经注册过别的 key，用 opencode auth list 查看，用 opencode auth switch anthropic <label> 切到关联组织那把。每注册一次 key 就多一个账号，最新注册的会变成默认激活的那个，这点容易踩坑。

两个危险操作

作者反复强调两条禁令。

不要用 Pro/Max 订阅登录 OpenCode。 Anthropic 的法律页面明确不允许第三方开发者把用户请求走 Free、Pro、Max 的订阅凭证。OpenCode 自己的 V1 文档也写着"Anthropic explicitly prohibits this"，相关插件早在 1.3.0 就被移除，但旧文档里"选择 Claude Pro/Max"的步骤还挂着，照做是无效的。合法做法只有一条：在你自己的开发环境里使用自建的 Console API key。

不要把 ANTHROPIC_API_KEY 写进 ~/.zshrc。 一旦 Claude Code 从环境变量里发现并批准了这把 key，它就会绕过订阅直接用 key，而交互式模式又不在这笔额度的可用范围内，结果就是 Credit balance is too low。用 claude -p 时环境变量里的 key 更是无审批直接生效。

怎么确认额度真的在用

看 Console 的 Settings > Billing 下的 Promotional credits，以及 Cost 页面，在请求前后各看一次。作者的机器上确实下降了。如果没下降，首先怀疑 key 不是来自已关联的组织。余额用尽后，请求会转而消耗你购买的额度或自动充值，两者都没有时 API 请求直接停止，订阅本身不会被扣费。

把 Claude Code 配置搬到 OpenCode V2

后半部分是重头戏：如何迁移 CLAUDE.md、subagents、skills、MCP、hooks 这一整套配置。作者做了一份可直接粘贴的提示词，并把自己手工迁移时踩过的坑列成清单。

命名和路径全变了

拿 V1 的示例配置照抄，很多名字是错的。V2 里 permission 变成 permissions，bash 变成 shell，task 变成 subagent，MCP 服务器从 mcp.<name> 挪到 mcp.servers.<name>。

更隐蔽的是 CLAUDE.md 直接失效。V2 只读 AGENTS.md，不做向下兼容。作者在一个临时 git 仓库里让 Haiku 5.5 只凭指令文件回答一个暗号：放在 CLAUDE.md 里的词没有出现，贴上 AGENTS.md 后才答对。把 CLAUDE.md 写进 instructions 设置也没用——V2 接受这个条目但不加载它。折中方案是在全局 AGENTS.md 里加一句让模型自己去读仓库里的 CLAUDE.md。

Subagent 的 frontmatter 会静默失效

作者把 coder、reviewer、review-lead、Plan 四个 Claude Code agent 原样拷进 .opencode/agents/，再用 opencode debug agents 检查，结果四个全变成了 primary，model 字段为空，name、model、effort 统统没生效。要命的是标了 disallowedTools 只读的 cc-Plan，编辑权限的 deny 完全丢了，本意是让它可以改文件。

正确写法需要重写：用 mode: subagent 指定类型，model 写成 provider/model#variant 的形式，disallowedTools 翻译成 permissions 里的 deny 规则。主会话的 effort 等级也不能放在根 model 里，#variant 会丢失，得放进 agents.build.model。作者还提醒，把 opencode debug agents 直接管道给 jq 会把 JSON 截断，要先输出到文件再处理。

什么是 frontmatter 与 subagent 的 mode：frontmatter 指 Markdown 文件开头用 --- 包裹的 YAML 元数据块，Claude Code 和 OpenCode 都靠它声明 agent 的名称、模型、工具权限等属性。subagent（子代理）是主会话派生出的、拥有独立上下文和工具集的助手，可被主代理调用去专注完成某类任务，例如写代码或做审查。OpenCode V2 要求显式写 mode: subagent 才会被当作可委派的子代理，否则默认按 primary（可主导会话的顶层代理）处理。这也解释了为什么原样拷贝的 agent 会“降级”：缺了 mode 字段，系统不报错，只是按默认值走，于是权限 deny、model、effort 这些依赖类型的属性全部落空。

Skills、MCP、Hooks、命令的对应关系

~/.claude/skills 会被自动读取，但插件里的 skill 不会，得手动把插件缓存里的 skills 目录写进配置。路径带版本号，插件更新后要跟着改。ID 冲突时后者覆盖前者，所以个人 skill 要排在插件后面。又因为 ~/.claude/skills 在工作目录之外，还需要放开 external_directory 权限，skill 才能读到自己的辅助文件。

MCP 要挪到 mcp.servers 下。远程服务器默认走 OAuth，像 context7 这种免账号的可以设 oauth: false。工具名从 mcp__plugin_context7_context7__… 变成 <server>_<tool>，在默认的 Code Mode 下还要通过 execute 调用。

Hooks 被拆成两半。作者原本有个 PreToolUse hook，专门拦住 subagent 执行 git push 和部署，主会话豁免。V2 里改用 permissions 实现：顶层 deny 对所有 agent 生效，再为 build agent 单独放开。规则从上往下匹配、最后一条命中者胜，而且 subagent 不继承父级权限，只跑自己那套。作者特别说明，pattern 匹配的是整条命令字符串，* 能匹配空格和引号，所以像 git * push* 这种宽泛写法连 git commit -m "fix push bug" 都会误拦，他的规则保持狭窄，只用 git push* 和 git -C * push。而编辑后和停止时触发的 hook 没有对应设置，得改写成插件。

斜杠命令则退化成 skill 的薄包装。作者实测发现 $ARGUMENTS 在 skill 里根本不会展开——传进 skill 工具的只有 {"id": "argtest"}，模型看到的是原样的占位符，靠猜来补参数，所以看起来能用。正确做法是写一个只负责让模型加载 skill 的命令文件，由命令层来展开 $ARGUMENTS。

MCP 与 OAuth：MCP（Model Context Protocol）是一套让模型访问外部工具和数据源的开放协议，客户端把每个 MCP server 暴露的工具注册成可调用函数。远程 MCP server 通常要求身份验证，OAuth 是其中最主流的方式，会在首次调用时弹出浏览器授权、换取 token 并缓存。像 context7 这种公开、无需登录的文档检索服务并不需要 OAuth，若配置仍默认走 OAuth，可能卡在授权流程上，所以显式设 oauth: false 可跳过。工具命名从 mcp__<plugin>_<server>__<tool> 改为 <server>_<tool>，是因为 OpenCode 不再用插件前缀做命名空间隔离，配置时要注意重名冲突。

工具名也没法一一对应

OpenCode 没有 Agent 工具、没有 SendMessage、没有 isolation: worktree。作者在全局 AGENTS.md 里维护了一张翻译表：subagent_type 对 subagent 工具里的 agent 参数，run_in_background 对 background，SendMessage 改成用同一个 sessionID 重调 subagent，worktree 隔离要自己跑 git worktree add 并把路径写进指令。git worktree add 不会带上 .gitignore 的文件，Claude Code 自动做的 .worktreeinclude 拷贝也得自己来。

git worktree 与隔离：git worktree add 允许在同一个仓库上挂出多个独立工作目录，各自检出不同分支，用来并行开发或让自动化任务在互不干扰的副本里跑。它和完整 clone 的区别是共享同一份 .git 对象库，所以创建快、省磁盘。但 worktree 只会检出被 Git 跟踪的文件，像 .env、node_modules、构建产物这类被 .gitignore 排除的内容不会被带过去。Claude Code 的 isolation: worktree 会自动补拷一份 .worktreeinclude 里列出的额外文件，迁移到 OpenCode 时这一步需要手动完成，否则新 worktree 里可能缺依赖或配置而直接报错。

哪些验证过，哪些没验证

作者很坦诚地列出了证据边界。额度消耗确实在 Console 里观察到了下降，但官方页面没写第三方客户端，政策随时可能变。权限匹配规则里 git * push* 会误伤 commit message 这一点，是从文档推导的，没有实际跑。别名 skill 只软链了 SKILL.md，带辅助文件的 skill 相对路径能不能解析没测。$ARGUMENTS 的展开行为是读文档得出的。其他操作系统、桌面应用、Team 订阅都没验证。

一句话结论

这笔每月额度只属于 Max 5x、Max 20x 和 Team，靠关联 Console 组织获取，交互式 Claude Code 花不掉。想在 OpenCode 里用，就注册 Console API key，别用 Pro/Max 登录，别把 ANTHROPIC_API_KEY 放进 shell 配置。迁移配置时记住：原样拷过去的 agent 和 CLAUDE.md 会被静默忽略，hooks 要一拆为二。对卡在 Claude Code 限额上的开发者来说，这是多出来的一条路。