使用 Claude API 无限运行 OpenCode

OpenCode 是一个运行在终端里的 AI coding assistant，通过 provider 插件系统获得很高的灵活性。它支持通过 npm packages 接入自定义 providers，可以启动并行 subagents 做代码探索和实现验证，也会维护持续的 terminal sessions，让上下文随着开发过程不断累积。正因为 OpenCode 的架构天然依赖多个 agent 并行、持续工作，它会消耗大量 API 调用和 tokens；使用 AI Prime Tech Unlimited 这样的 Claude API gateway，可以用固定费率获得更接近 claude无限使用、claude无限额度的体验，尤其适合长时间编码、调试和自动化开发流程。

OpenCode 的并行 Agent 架构

OpenCode 的工作方式不是简单地把你的 prompt 发给一个模型然后等待回复。它通常会运行一个 primary agent，也就是 Build 或 Plan，同时还能按任务需要启动 subagents，例如 explore、scout，去并行处理相关的调查工作。Build agent 负责直接改代码、读写文件、执行命令和验证结果；Plan agent 则更偏向先推理方案、拆分步骤，再把实现任务交给后续流程。subagents 会拥有各自独立的 conversation context：它们可能在主 agent 写代码的同时阅读代码库、查找文档、验证假设、比较实现路径，最后把结论反馈给主流程。对于复杂项目来说，这种架构非常实用，因为一个 agent 不必把所有事情串行完成，整体效率和问题覆盖面都会提升。

这种并行能力的代价是 API 消耗会明显增加。多个 Claude conversations 会同时使用同一个 claude api密钥 发起请求。一个看似普通的复杂任务，可能会让 Build agent 修改文件，同时 explore subagent 阅读相关模块，scout subagent 检查外部文档或框架用法。每个 agent 都会积累自己的上下文，十轮对话并不是十次简单请求：如果三个 agents 各跑十轮，就是三十次 API calls，而且每次请求都可能携带越来越长的 conversation history。使用按 token 计费的官方或普通中转服务时，开发者往往会下意识限制 subagents 的数量，避免成本失控；但在固定费率的 claude api中转 场景下，你可以更放心地让 OpenCode 根据任务复杂度启动足够多的并行工作单元。

OpenCode 还允许你为项目定义 custom agents，用于特定工作流。例如，你可以定义一个专门做安全审查的 agent，一个专门做数据库迁移分析的 agent，一个专门检查文档一致性的 agent。每增加一个 custom agent，本质上就是增加一个并行的 API token 消费者。按量计费时，你会频繁权衡 claude api价格 和开发效率，甚至把本该自动化的检查改回手动执行。使用 AI Prime Tech Unlimited 这类面向开发场景的无限网关后，思路可以反过来：根据质量和覆盖率来设计 agent，而不是根据每次调用的费用来收缩工作流。对于需要长时间重构、持续测试、反复探索大型代码库的团队来说，这正是 claude无限额度 的价值所在。

在 opencode.json 中配置 Custom Providers

OpenCode 的 provider system 使用 npm packages 来处理 API 通信。通过 AI Prime Tech Unlimited 接入 Claude 时，通常有两条路径：一种是使用 @ai-sdk/anthropic，走更接近 Anthropic native API 的方式；另一种是使用 @ai-sdk/openai-compatible，走 OpenAI-compatible API 的方式。两种方式都可以把 OpenCode 连接到 https://claudeapikey.dev 这个 Claude API gateway。配置入口是 opencode.json，它可以放在项目根目录，也可以放在 ~/.config/opencode/ 作为用户级配置。对中国开发者来说，这类配置通常会被搜索为 OpenCode Claude API 配置、opencode json Claude 设置、claude api中转 配置等关键词。

如果你选择 OpenAI-compatible path，需要在 providers 中增加一个 provider entry，package 设置为 @ai-sdk/openai-compatible，baseURL 设置为 https://claudeapikey.dev/v1，注意这里必须带 /v1，然后配置你的 API key。之后在 models 中引用这个 provider，并指定实际模型 ID。这个方式和很多 OpenAI SDK、OpenAI-compatible tools 的接入习惯一致，因此在 OpenCode 配置里也比较常见。如果你选择 native Anthropic path，则使用 @ai-sdk/anthropic，baseURL 设置为 https://claudeapikey.dev，也就是 root host，不要加 /v1。两者最容易出错的地方就是 baseURL 后缀，错了之后常见表现不是直观的 404，而是模型不可用、provider 加载失败或请求格式不匹配。

opencode.json 的结构把 providers 和 models 分开：providers 描述“怎么连接”，models 描述“用什么模型”。这是一种很干净的设计。你只需要定义一次 unlimited provider，然后创建多个 model entries，例如 sonnet、opus、haiku，分别指向 claude-sonnet-4-5、claude-opus-4-6、claude-haiku-4-5。这样当你想切换模型时，只需要调整 model mapping 或 agent assignment，不必反复改 provider 的 baseURL、apiKey 等连接设置。对于团队项目，建议把 provider 命名得清楚，比如 unlimited、aiprimetech 或 claude_gateway，同时把 claude api密钥 放在安全位置，避免直接提交到 Git。购买claude api 服务后，优先确认网关支持的模型 ID、鉴权格式和是否兼容 OpenAI path，这样能减少大量排查时间。

为 Agents 和 Subagents 配置模型

OpenCode 允许你给不同角色分配不同模型。primary model 负责主要交互，包括理解任务、改代码、调用工具、组织最终结果。small_model 负责较轻的任务，例如生成摘要、格式化输出、快速查找或处理不需要深度推理的步骤。subagents 可以继承 primary model，也可以在 custom agent 定义中使用自己的模型配置。所有这些映射都可以放在 opencode.json 的 models 和 agent 配置里。这样的模型分层对于 OpenCode 很重要，因为它既需要强推理能力处理复杂代码问题，也需要低延迟模型完成大量琐碎辅助工作。

在无限额度场景下，primary model 可以优先选择 claude-sonnet-4-5，获得较好的速度、代码能力和推理质量平衡；如果任务非常复杂，例如大型架构迁移、跨模块重构、深度 bug 分析，可以选择 claude-opus-4-6 作为主模型，以获得更强的推理质量。small_model 建议设置为 claude-haiku-4-5，用于快速、轻量的操作。它适合生成文件摘要、整理 terminal output、做简单格式化、快速提取信息等场景。这样既能让主要任务保持高质量，也能让频繁的小操作保持响应速度。

custom agents 也可以分别指定自己的模型。例如 research agent 可以使用 Opus 做深度分析，implementation agent 使用 Sonnet 快速生成和修改代码，documentation agent 使用 Sonnet 或 Haiku 处理文档草稿，review agent 则根据严格程度选择 Opus 或 Sonnet。按量计费时，开发者常常会因为 claude api价格 而把所有角色都压到便宜模型上，结果复杂任务质量下降，反复修改反而消耗更多。使用 AI Prime Tech Unlimited 之后，模型选择可以回归工程目标：哪个角色需要最强能力，就给它最适合的模型。对于想购买claude api 并长期用于 coding agent 的用户来说，这种固定费率的思路比单次调用价格更贴近真实开发成本。

MCP 集成与工具扩展

OpenCode 支持 MCP，也就是 Model Context Protocol。通过 MCP servers，你可以把自定义工具接入 agents，例如数据库查询、文档检索、部署脚本、监控系统、issue tracker、内部知识库等。配置方式是在 opencode.json 的 mcp section 中指定 server command、arguments 和 environment。MCP server 暴露出来的 tools 会对 agents 可用，让 OpenCode 在不修改核心代码的情况下扩展能力。对于现代开发流程来说，MCP 的意义很大：agent 不再只是读写本地文件，而是可以连接更多真实系统，完成更接近端到端的工程任务。

不过，MCP 工具集也会显著增加 token 消耗。每个 MCP tool 都有 schema，这些 schema 通常会被加入 system prompt 或工具说明中，并随请求发送给模型。即使 agent 没有实际调用某个工具，工具定义本身也会增加 baseline token consumption。当 agent 调用 MCP tool 时，tool call、arguments、tool result 又会继续加入 conversation context。如果你连接多个 MCP servers，每个 server 提供十几个甚至几十个工具，那么每次请求在正式开始处理代码之前，就可能已经有 5,000 到 10,000 tokens 的工具定义开销。按量计费时，这会让开发者非常谨慎，甚至不得不删减工具集。

在 claude无限使用 的模式下，你可以更自然地接入真正有用的 MCP servers，而不是为了省 token 人为限制工具能力。数据库 client、文档 server、部署工具、日志和监控接口、feature flag 平台、CI/CD 工具，都可以根据实际项目需要接入。固定费率覆盖了丰富工具集带来的 token overhead，让 OpenCode 更像一个完整的 development environment，而不是只能在本地文件夹里工作的聊天机器人。当然，无限并不代表无脑堆工具：工具太多也会增加模型选择成本和 prompt 噪音。最佳实践是保留对项目有明确价值的工具，并用清晰命名和描述帮助 Claude 正确选择。

持续 Terminal Sessions 与上下文增长

OpenCode 会维护持久化的 terminal sessions，让 agents 执行命令并观察输出。它不是那种发出命令后就忘记结果的工具；OpenCode 的 agents 可以观察 long-running processes，读取 streaming output，并根据实时变化做出反应。比如，它可以看着测试套件运行，等待 dev server 输出编译结果，跟踪日志中出现的错误，或者在构建失败后直接读取错误栈并修改代码。每一次 terminal interaction 都会加入 conversation context：command output、error messages、log lines、test failures、compiler diagnostics，都会成为不断增长的历史记录。

一个典型开发 session 往往包含多轮 build-test-fix 循环。每一轮都会产生新的上下文：编译器错误、单元测试结果、应用日志、lint 输出、运行时异常、dependency warning。活跃开发一个小时后，仅 terminal output 就可能增长到数万 tokens。再加上读取过的文件内容、用户需求、agent 的推理过程和工具调用记录，整个 session 很容易逼近模型 context limits。对于普通按量 API 来说，这种持续上下文会让成本快速上升，也会让开发者频繁中断 session、清理上下文或减少自动验证步骤。

使用 AI Prime Tech Unlimited 的固定费率后，这种持续工作流会顺畅很多。你可以让 OpenCode 观察测试套件完整运行，读取 build output，监控 server logs，跟踪失败重试，而不用每次都担心 token 账单。每一次 observation 都会让 agent 更了解系统状态，从而减少误判和盲改。对于长时间维护大型项目的开发者来说，这比所谓 免费claude api 的短期限额体验更实用：免费额度通常只能做少量测试，而真正的编码代理需要连续上下文、反复工具调用和多轮验证。claude无限额度 的意义不只是“多聊几句”，而是让 AI coding workflow 变得稳定、连续、可依赖。

Build Agent 与 Plan Agent 的工作流差异

Build agent 直接执行修改。它会读取文件、写代码、运行命令、检查结果并继续迭代。适合使用 Build 的场景通常是需求明确、路径清楚的任务，例如修复一个具体 bug、添加一个有明确输入输出的函数、重命名变量、调整格式、把一个已知模式重构到另一个已知模式。Build 的优势是行动快、API 调用相对少、流程短，非常适合机械性或范围较小的工作。对于这类任务，额外规划反而可能变成无必要的开销。

Plan agent 则会在行动前先思考方案。它会分析需求、识别约束、比较不同实现路径、拆分步骤，并在必要时把实现交给后续 agent 或 subagents。适合使用 Plan 的场景包括需求不清晰的功能、架构设计、跨模块改造、性能优化、安全修复、复杂 bug 追踪，以及任何“怎么做才是正确方案”并不明显的任务。Plan 通常能产出更稳健的结果，因为它在动手前会先建立问题模型；但它也会使用更多 API calls，因为规划、推理、探索和验证都需要额外轮次。

在无限 API 模式下，一个实用策略是：只要任务不够简单，就默认使用 Plan agent。规划和推理多出来的 API calls 不再带来额外费用，却能显著降低走错方向、反复返工和引入回归的概率。Build agent 则保留给简单、机械、确定性强的修改，例如格式修复、简单 rename、明显 bug fix、单文件小改动。换句话说，claude api价格 不再是决定你是否规划的主要因素，任务复杂度和质量要求才是。对于购买claude api 用来跑 OpenCode 的团队，这一点会直接影响交付稳定性：复杂任务愿意先 Plan，通常比直接让 agent 盲改更省时间。

排查 OpenCode Provider 配置问题

如果 OpenCode 无法加载你的 provider，首先检查对应的 npm package 是否已经安装。OpenAI-compatible path 需要在项目目录运行 npm install @ai-sdk/openai-compatible；native Anthropic path 需要运行 npm install @ai-sdk/anthropic。OpenCode 会从项目的 node_modules 中解析 provider packages，如果 package 没有安装，provider 配置可能会被忽略，表现为模型找不到、provider 不生效或 fallback 到其他配置。很多人以为是 claude api密钥 错了，实际上只是依赖没有安装。

如果遇到 connection errors，要重点核对 baseURL 是否和 provider package 匹配。@ai-sdk/openai-compatible 需要 https://claudeapikey.dev/v1，也就是带 /v1 后缀；@ai-sdk/anthropic 需要 https://claudeapikey.dev，也就是 root host，不带 /v1。把这两种格式混用，会导致 404、模型不可用、请求路径错误或含糊的 model not available 消息。排查时建议先用最小配置，只保留一个 provider 和一个 model，确认能正常调用后再加入 subagents、MCP servers 和多模型映射。

如果 primary agent 能工作，但 subagents 失败，通常要检查 model configuration 是否完整。subagents 可能使用不同的 model assignment；如果某个 subagent 配置的模型 ID 在 gateway 上不存在，或者 models section 中没有正确引用 provider，它可能会静默失败或返回不直观的错误。确保 opencode.json 中所有 model entries 都指向 AI Prime Tech Unlimited 支持的有效 model IDs，并且 agent、custom agents、small_model 的引用名称完全一致。对于想从 免费claude api 测试迁移到长期无限方案的用户，建议先验证基础请求、再验证多模型、最后验证并行 subagents 和 MCP，这样排查链路最清晰。

// opencode.json - OpenAI-compatible 路径
{
  "providers": {
    "unlimited": {
      "package": "@ai-sdk/openai-compatible",
      "options": {
        "baseURL": "https://claudeapikey.dev/v1",
        "apiKey": "<your AI Prime Tech Unlimited key>"
      }
    }
  },
  "models": {
    "sonnet": { "provider": "unlimited", "model": "claude-sonnet-4-5" },
    "opus":   { "provider": "unlimited", "model": "claude-opus-4-6" },
    "haiku":  { "provider": "unlimited", "model": "claude-haiku-4-5" }
  },
  "agent": { "model": "sonnet", "small_model": "haiku" }
}

FAQ

OpenCode 里接入 Claude 应该用哪个 npm package？
可以使用 @ai-sdk/openai-compatible，并把 baseURL 设置为 https://claudeapikey.dev/v1；也可以使用 @ai-sdk/anthropic，并把 baseURL 设置为 https://claudeapikey.dev，注意不要带 /v1。两种方式都可用，但在 OpenCode 配置中，OpenAI-compatible path 更常见，也更符合很多开发者使用 claude api中转 的习惯。

OpenCode 的 subagents 会怎样影响 API 用量？
每个 subagent，例如 explore、scout 或 custom agent，都会运行自己独立的 conversation，并且上下文会持续增长。三个并行 subagents 各运行十轮，就意味着三十次独立 API calls，而且每次都可能携带更长历史。在 AI Prime Tech Unlimited 的固定费率方案下，这种并行能力由套餐覆盖，更适合 claude无限使用 的开发工作流。

small_model 是什么，什么时候会用到？
small_model 用来处理轻量任务，例如生成摘要、格式化输出、快速查找信息等，这些任务更看重速度而不是深度推理。建议设置为 claude-haiku-4-5，以便在轻量操作中获得更快响应，同时把 Sonnet 或 Opus 留给主要编码和复杂推理任务。

我可以在 OpenCode 中定义 custom agents 吗？
可以。你可以在 opencode.json 中添加 agent definitions，为不同 agent 设置 custom system prompts、tool access 和 model assignments。使用无限额度时，可以根据工作流创建 research、implementation、review、documentation 等多个专用 agents，而不用为每个 agent 的额外调用单独担心成本。

为什么 OpenCode 的 terminal sessions 会让上下文变得很大？
OpenCode 会维护持久 terminal sessions，所有 command output，包括 build logs、test results、error messages 和 server logs，都会累积到 conversation context 里。一个小时的活跃开发仅 terminal output 就可能增加数万 tokens。使用 claude无限额度 后，这种上下文增长不会产生额外按量费用，agent 也能更完整地理解系统状态。