Source: https://aiprimetech.io/zh/learn/use-claude-api-with-opencode/

[首页](/zh/) / [学习](/zh/learn/) / 面向 Claude 的 OpenCode 配置：opencode.json 设置、模型与常见错误 

# OpenCode 的 Claude 配置：opencode.json 设置、模型与常见错误 

OpenCode 从以下文件读取设置： opencode.json。要通过此网关让 OpenCode 使用 Claude，只需修改一个值，即 Anthropic 提供商的 baseURL，并为其提供密钥。下文给出了两个可用配置、重要的模型与上下文设置，以及 OpenCode 用户在此网关上遇到的错误的修复方法；这些问题来自我们自己的请求日志。 

## opencode.json 的存放位置 

OpenCode 会合并全局配置与项目配置： ~/.config/opencode/opencode.json 用于设置你希望在所有位置生效的选项，而 opencode.json 放在项目根目录中，用于该仓库。添加 $schema 这一行后，大多数编辑器都能提供自动补全和校验。 

不要将密钥写入文件。将它放在环境变量中，并使用以下方式引用： {env:AIPRIME_API_KEY}。通过 /connect 在 OpenCode 内添加的密钥会存储在 ~/.local/share/opencode/auth.json; opencode auth list 可显示其中存储的内容。 

终端复制

```
export AIPRIME_API_KEY=your_gateway_key   # add to ~/.bashrc or ~/.zshrc
opencode auth list                         # credentials OpenCode already knows about
```

## 方案 1：将内置 Anthropic 提供商指向网关 

改动最少的方式：保留 OpenCode 自带的 Anthropic 提供商及其模型列表，只覆盖其请求发送地址。 

opencode.json复制

```
{
  "$schema": "https://opencode.ai/config.json",
  "provider": {
    "anthropic": {
      "options": {
        "baseURL": "https://aiprimetech.io/v1",
        "apiKey": "{env:AIPRIME_API_KEY}"
      }
    }
  },
  "model": "anthropic/claude-sonnet-5",
  "small_model": "anthropic/claude-haiku-4-5"
}
```

该 baseURL 必须以 /v1。OpenCode 的 Anthropic 提供商使用 AI SDK 的 @ai-sdk/anthropic，其默认值为 https://api.anthropic.com/v1；它会追加 /messages 附加到你提供的任何内容后面。如果没有 /v1 请求就会落到网站上并返回 HTML，OpenCode 会将其报告为解析错误。 

## 方案 2：使用自定义提供商并配置自己的模型列表 

单独添加一个提供商条目，可以将网关与任何 Anthropic 登录分开，让你在模型选择器中只列出所需模型，并为每个模型设置上下文限制。 

opencode.json复制

```
{
  "$schema": "https://opencode.ai/config.json",
  "provider": {
    "aiprime": {
      "npm": "@ai-sdk/anthropic",
      "name": "AI Prime Tech",
      "options": {
        "baseURL": "https://aiprimetech.io/v1",
        "apiKey": "{env:AIPRIME_API_KEY}"
      },
      "models": {
        "claude-sonnet-5":  { "name": "Claude Sonnet 5",  "limit": { "context": 200000, "output": 64000 } },
        "claude-opus-5-5":  { "name": "Claude Opus 5.5",  "limit": { "context": 200000, "output": 64000 } },
        "claude-haiku-4-5": { "name": "Claude Haiku 4.5", "limit": { "context": 200000, "output": 32000 } }
      }
    }
  },
  "model": "aiprime/claude-sonnet-5",
  "small_model": "aiprime/claude-haiku-4-5"
}
```

优先选择 @ai-sdk/anthropic 用于 Claude：它使用原生 Messages API，因此提示缓存和思考功能都能按 Anthropic 的设计运行。网关也支持 OpenAI 格式，因此 @ai-sdk/openai-compatible 使用相同的 https://aiprimetech.io/v1 基础 URL 也能正常工作，这也是使用同一密钥调用 GPT 模型时应采用的方式。 

## 模型与上下文限制 

  | 模型 ID  | 适用场景  

 | claude-sonnet-5 | 编程和智能体任务的默认选择：速度快、能力强、价格适中。 

 | claude-opus-5-5 | 更复杂的推理、大规模重构、长时间运行的智能体任务。 

 | claude-fable-5-1 | 能力最强，价格也最高；留给最困难的任务使用。 

 | claude-haiku-4-5 | 价格低、速度快：标题、摘要、分类和小步骤。  

model 是主智能体使用的模型； small_model 负责生成会话标题等低成本辅助任务。 limit.context 数值告诉 OpenCode 何时压缩会话。如果较长的会话出现以下错误 prompt is too long，请降低该值（200000 是一个安全值），让 OpenCode 更早进行摘要，而不是发送超出端点可接受范围的内容。 

模型 ID 必须是完全匹配的字符串。较旧的名称，例如 claude-3-5-sonnet-20241022 或带日期的快照版本均不受支持；请使用上面列出的 ID，或控制台列表中的 ID。 

## 启动 OpenCode 前检查密钥和 URL 

从终端发送一次请求，就能独立于 OpenCode 配置验证密钥和 URL 是否正确： 

终端复制

```
curl -s https://aiprimetech.io/v1/messages \
  -H "x-api-key: $AIPRIME_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "content-type: application/json" \
  -d '{"model":"claude-haiku-4-5","max_tokens":20,"messages":[{"role":"user","content":"ping"}]}'
```

如果收到 JSON 响应，其中包含一个 content 数组，就说明网关端正常，剩余问题出在 opencode.json. Invalid API key 表示该变量为空或包含错误的密钥。 

## 故障排查：OpenCode 用户常见错误 

以下是在此网关上使用 OpenCode 时最常见的错误，以及各自的修复方法。 

  | 你会看到什么  | 原因  | 解决方法  

 | JSON 解析错误，响应以 < | baseURL 不带 /v1：请求到达了网站，而不是 API | 结尾 baseURL 替换为 /v1 

 | 404 page not found | /v1 重复了两次，因此路径变成了 /v1/v1/messages | 请严格使用 https://aiprimetech.io/v1 

 | Invalid API key | 该变量未在启动 OpenCode 的 shell 中导出，或正在使用其他密钥 | echo $AIPRIME_API_KEY, opencode auth list，重启 OpenCode 

 | 模型不受支持 / 找不到模型 | 端点不提供该 ID 对应的模型，通常是带日期的旧名称 | 使用上表中的 ID 

 | prompt is too long: N tokens > N tokens | 会话超出了模型可接受的范围 | /compact，并降低 limit.context 

 | Concurrency limit exceeded for user | 并行子智能体数量超出了密钥的并发限制 | 减少同时运行的子智能体数量，或联系支持团队申请更高的并发额度 

 | Insufficient account balance | 余额已用尽 | [充值](/zh/topup/) 并重试 

 | No available accounts 或 This request could not be completed | 上游暂时出现容量问题 | 重新发送消息；如果问题持续存在，请切换模型  

对于来自模型端而非客户端的错误，请参阅 [Claude API 错误指南](/zh/learn/claude-api-errors-troubleshooting/). 

## 常见问题 

 OpenCode 配置文件在哪里？

全局配置文件位于 ~/.config/opencode/opencode.json，项目配置文件则是仓库根目录中的 opencode.json。OpenCode 会合并这两份配置。 如何通过 API 密钥在 OpenCode 中使用 Claude？

将 provider.anthropic.options.baseURL 设置为以 /v1 结尾的网关 URL，并将 apiKey 设置为 {env:YOUR_VAR}；或者添加一个使用 npm @ai-sdk/anthropic 的自定义提供商，然后通过 model: provider/model-id 选择模型。 为什么 OpenCode 会出现解析错误，或收到以 '<' 开头的响应？

baseURL 缺少 /v1，导致请求到达网站而不是 API。@ai-sdk/anthropic 需要完整的前缀，例如 https://aiprimetech.io/v1. OpenCode 能否使用 Claude Pro 或 Max 登录？

OpenCode 文档指出，Anthropic 禁止第三方 Pro/Max 插件，OpenCode 已于 1.3.0 停止捆绑这些插件。受支持的接入方式是使用 API 密钥。  

几分钟内开始使用 Claude

获取 API 密钥，无需 Anthropic 账户，也无需加入候补名单。[获取你的 API 密钥](/register) 

AI Prime Tech 是独立的 API 网关，与 Anthropic 无关联，未获得其背书，也不是其经销商。Claude 及相关模型名称是其各自所有者的商标。    

## 更多 Claude API 指南

[如何获取 Claude API 密钥](/zh/learn/how-to-get-a-claude-api-key/)[Claude API 定价详解](/zh/learn/claude-api-pricing-explained/)[使用 Claude API 最便宜的方式](/zh/learn/cheapest-way-to-use-claude-api/)[通过 Claude API 不限量使用 Cursor](/learn/use-claude-api-with-cursor/)[不限量访问 Claude Code](/zh/learn/use-claude-api-with-claude-code/)[Claude API 网关与 Anthropic 直连对比](/zh/learn/claude-api-vs-anthropic-direct/)[通过兼容 OpenAI 的 API 使用 Claude](/zh/learn/openai-compatible-claude-api/)[Claude 模型详解：Claude Opus、Sonnet、Haiku 与 Fable 的模型对比——全部 Claude API 模型、Anthropic 模型名称与价格（2026）](/zh/learn/claude-api-models-compared/)[使用加密货币支付 Claude API 费用](/zh/learn/claude-api-with-crypto-payment/)[无需候补名单即可访问 Claude API](/zh/learn/claude-api-without-waitlist/)[如何减少 Claude 词元用量](/zh/learn/how-to-reduce-claude-token-usage/)[通过 Claude API 不限量使用 Cline](/zh/learn/use-claude-api-with-cline/)[通过 Claude API 不限量使用 Roo Code](/zh/learn/use-claude-api-with-roo-code/)[在 JetBrains IDE 中不限量使用 Claude](/zh/learn/use-claude-api-with-jetbrains/)[通过 Claude API 无限制使用 Aider](/zh/learn/use-claude-api-with-aider/)[在 VS Code 中不限量使用 Claude](/zh/learn/use-claude-api-with-vscode/)[在 Claude 上运行不受限制的 Hermes 智能体](/zh/learn/run-hermes-agent-with-claude-api/)[使用 Claude 不限量运行 OpenClaw](/zh/learn/run-openclaw-with-claude-api/)[兼容 Anthropic 的 API 意味着什么](/zh/learn/anthropic-compatible-api/)[Claude Code API 密钥 — ANTHROPIC_API_KEY：如何获取、配置，以及何时应改用 claude setup-token](/zh/learn/claude-code-api-key-setup/)[Claude Code API 成本 — 定价与降低成本的方法](/zh/learn/claude-code-api-costs/)[Claude API 错误详解：服务器错误 500、过载 529、速率限制 429、错误请求 400 — 以及各自的修复方法](/zh/learn/claude-api-errors-troubleshooting/)[如何购买 Claude API 额度，以及为什么购买 Claude 额度比任何“购买 Claude 账户”的方案都更好](/zh/learn/buy-claude-api-credits/)[Claude 免费 API：有免费的 Claude API 密钥吗？2026 年究竟有哪些内容免费？](/zh/learn/claude-api-free-trial/)[Claude API 与 Claude Pro/Max 订阅——如何选择](/zh/learn/claude-api-vs-subscription/)[使用 Claude 运行 Codex CLI](/zh/learn/use-claude-api-with-codex/)[将 Claude 连接到 n8n](/zh/learn/use-claude-api-with-n8n/)[通过 LiteLLM 路由到 Claude](/zh/learn/use-claude-api-with-litellm/)[在 Kilo Code 中使用 Claude](/zh/learn/use-claude-api-with-kilo-code/)[将 Claude 接入 GitHub Copilot](/zh/learn/use-claude-api-with-github-copilot/)[通过网关将 Zed 连接到 Claude](/zh/learn/use-claude-api-with-zed/)[将 Cherry Studio 连接到 Claude](/zh/learn/use-claude-api-with-cherry-studio/)[LangChain 中的 ChatAnthropic：导入、base_url、流式传输、工具和错误](/zh/learn/use-claude-api-with-langchain/)[Anthropic Python SDK：安装、设置 base_url、流式传输和错误处理](/zh/learn/anthropic-python-sdk/)[通过 Vercel AI SDK 使用 Claude：createAnthropic baseURL、流式传输和问题修复](/zh/learn/use-claude-api-with-vercel-ai-sdk/)[使用 Claude 运行 Factory Droid](/zh/learn/use-claude-api-with-factory-droid/)[Claude Code API 详解](/zh/learn/claude-code-api/)[将 Claude API 集成到您的应用中](/zh/learn/claude-api-integration/)[如何不受限制地使用 Claude，以及为什么不存在“Claude Code 破解版本”](/zh/learn/get-unlimited-claude-usage/)