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 提供商及其模型列表，只覆盖其请求发送地址。

{
  "$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"
}

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

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

{
  "$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 模型时应采用的方式。

模型与上下文限制

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 时最常见的错误，以及各自的修复方法。

对于来自模型端而非客户端的错误，请参阅 Claude API 错误指南.

常见问题

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