跳转到主要内容
只需一个 Capriole AI API Key,就能在 OpenCode 中使用 GPT-6.2 Astra、Claude Fable 5.1、Opus 5.5 和 Gemini 4 Carbon,价格比官方 API 最多低 92%。

OpenCode 是什么

OpenCode 是开源 AI 编程智能体,提供终端界面、桌面应用和 IDE 扩展。这套配置把 Capriole AI 添加为一个自定义提供商,其中每个模型都使用 Capriole AI 为该模型系列提供的 API 协议。

前置条件

开始前请确保你已经拥有以下内容。
  • Capriole AI 账户,可在此处注册
  • Premium 方案(每月 USD 9,还包含无限网页聊天)或 Team 方案,获取 API Key 需要其中之一,可在此处订阅
  • Capriole AI API Key,可在此处获取

安装

OpenCode 2 和 OpenCode 1 都使用 opencode 命令,因此同一时间只能安装其中一个。使用官方安装脚本安装 OpenCode 2。
也可以使用 npm 安装。
如需从 OpenCode 1 升级,请运行 opencode upgrade --major。https://opencode.ai/install 脚本和 opencode-ai npm 包仍然安装 OpenCode 1。 验证安装。

配置

模型验证

使用 OpenCode 2 配置,OpenCode 2.2.5 经 Capriole AI 调用“支持的模型”一节中的每个模型,都通过了文件读取和最终答案检查。使用 OpenCode 1 配置,OpenCode 1.19.3 通过了文件读取、文件写入和最终答案检查。

OpenCode 2

创建或更新 ~/.config/opencode/opencode.json。
各项设置的作用如下。
  • package: "@opencode/ai/providers/openai-compatible" 是该提供商的默认包,因此 Gemini、Grok、GLM 和 Kimi 使用 Chat Completions。
  • 每个 GPT 模型都用 @opencode/ai/providers/openai-compatible/responses 覆盖 package,从而使用 Responses API。每个 Claude 模型都用 @opencode/ai/providers/anthropic-compatible 覆盖它,从而使用 Anthropic Messages。
  • env 指定存放 API Key 的环境变量。Authorization 请求头让每个包都以 Bearer Token 形式发送 Key。
  • reasoningEffort 为每个 GPT 模型设定默认推理强度。没有它时,GPT 模型回答时不进行推理。
  • 每个包的 baseURL 都包含 /v1。limit 告诉 OpenCode 每个模型的上下文窗口和输出上限。
  • agents.title 设置 OpenCode 生成会话标题时使用的模型。

OpenCode 1

OpenCode 1 不读取 OpenCode 2 的写法,但 OpenCode 2 能读取下面的写法,因此升级后原有的 OpenCode 1 配置仍可使用。创建或更新 ~/.config/opencode/opencode.json。
各项设置的作用如下。
  • npm: "@ai-sdk/openai-compatible" 是该提供商的默认包,因此 Gemini、Grok、GLM 和 Kimi 使用 Chat Completions。
  • 每个 GPT 模型都用 @ai-sdk/openai 覆盖 provider.npm,从而使用 Responses API。每个 Claude 模型都用 @ai-sdk/anthropic 覆盖它,从而使用 Anthropic Messages。
  • 每个包的 baseURL 都包含 /v1。
  • {env:CAPRIOLE_AI_API_KEY} 从环境变量读取你的 API Key。Authorization 请求头让每个包都以 Bearer Token 形式发送 Key。
  • limit 告诉 OpenCode 每个模型的上下文窗口和输出上限,让它能跟踪上下文并及时压缩会话。
  • small_model 是 OpenCode 处理会话标题等轻量任务时使用的模型。

运行 OpenCode

设置 API Key,然后在项目目录中启动 OpenCode。
OpenCode 2 通过后台服务发送模型请求,该服务在启动时读取 API Key,因此 opencode service restart 会让它读到你刚设置的 Key。使用 OpenCode 1 时跳过这一步。 使用 /models 切换模型。如需非交互式运行,请使用 opencode run。

支持的模型

模型引用格式为 capriole-ai/<model-id>。 openai-latest、claude-latest 和 google-latest 始终指向各自系列中我们最新的旗舰模型,目前分别是 GPT-6.2 Astra、Claude Fable 5.1 和 Gemini 4 Carbon。

故障排除

为什么 OpenCode 返回身份验证错误

启动 OpenCode 前,确认已在同一个 Shell 中导出 CAPRIOLE_AI_API_KEY,并确认 headers(OpenCode 2)或 options.headers(OpenCode 1)下有 Authorization 请求头。如果 OpenCode 2 报 Missing Bearer token,说明它的后台服务启动时没有拿到 Key,请在该 Shell 中运行 opencode service restart。

为什么 Claude 请求因 Unsupported Claude Messages model 失败

使用 Anthropic 包的 Claude 模型需要不带前缀的 Claude ID,例如 claude-opus-5-5。带 anthropic/ 前缀的 ID 用于 Chat Completions。

为什么 GPT 请求失败

确认每个 GPT 模型都有 "package": "@opencode/ai/providers/openai-compatible/responses"(OpenCode 2)或 "provider": { "npm": "@ai-sdk/openai" }(OpenCode 1),让它的请求使用 Responses API。

为什么 Capriole AI 模型没有出现

确认模型引用使用 capriole-ai/<model-id> 格式,例如 capriole-ai/moonshot/kimi-k3,并确认 disabled_providers 没有屏蔽 capriole-ai。OpenCode 1 会忽略 OpenCode 2 的 providers 写法。

为什么配置修改没有生效

检查是否存在项目级 opencode.json 或 OPENCODE_CONFIG 覆盖,然后重新启动 OpenCode。

为什么出现提供商包错误

清除 ~/.cache/opencode 并重新启动 OpenCode,让它重新安装提供商包。

说明

最后修改于 2026年11月18日