使用 OpenCode 和 CometAPI

使用本指南运行 OpenCode 并搭配 CometAPI 使用。该配置通过独立的自定义提供商提供四种 API 格式。此配置已通过 OpenCode 1.18.16 测试。官方参考：

将每个 your-model-id 值替换为来自以下页面的模型 ID： CometAPI 模型页面。请选择接受周围提供商条目所用 API 格式的模型。

前提条件

Node.js 和 npm，或 OpenCode 指南中的其他安装方法
拥有来自以下位置的有效 API 密钥的 CometAPI 账户：控制台
来自以下页面的一个或多个模型 ID： CometAPI 模型页面

了解 API 格式

每个提供商 ID 都选择一个 SDK 适配器和一种 API 格式。

提供商 ID	OpenCode 适配器	基础 URL	API 格式
`cometapi-chat`	`@ai-sdk/openai-compatible`	`https://api.cometapi.com/v1`	聊天补全
`cometapi-responses`	`@ai-sdk/openai`	`https://api.cometapi.com/v1`	响应
`cometapi-messages`	`@ai-sdk/anthropic`	`https://api.cometapi.com/v1`	Anthropic 消息
`cometapi-gemini`	`@ai-sdk/google`	`https://api.cometapi.com/v1beta`	Gemini generateContent

本指南验证正常 OpenCode 代理轮次中使用的 Gemini 流式操作。Google 适配器会将 :streamGenerateContent?alt=sse 追加到模型路径。请勿添加 /chat/completions、/responses、/messages 或 Gemini 模型路径到 baseURL。每个适配器都会追加其所需的操作路径。

了解运行时权限

OpenCode 使用启动它的进程所具有的权限运行。请在目标项目目录中启动 OpenCode，并保留 git 等回滚途径。在需要更严格的文件系统、进程、网络或 API 密钥边界时，请使用容器或沙箱。

配置 OpenCode

安装 OpenCode

使用官方 npm 包安装 OpenCode：

npm install -g opencode-ai

确认 CLI 可用：

opencode --version

请参阅 OpenCode 安装指南，了解 Homebrew、Windows、Docker 及其他安装方法。

设置 CometAPI API 密钥

将 CometAPI API 密钥存储在 COMETAPI_KEY 环境变量中。

macOS / Linux / WSL
Windows PowerShell

读取 API 密钥而不在终端中显示：

read -rsp "CometAPI API key: " COMETAPI_KEY
printf '\n'
export COMETAPI_KEY

将 API 密钥读取到当前 PowerShell 会话中：

$secureKey = Read-Host "CometAPI API key" -AsSecureString
$env:COMETAPI_KEY = [System.Net.NetworkCredential]::new(
  "",
  $secureKey
).Password

在每个启动 OpenCode 的 shell 会话中设置该变量。请勿将 API 密钥提交到版本控制系统。

选择配置位置

使用以下任一受支持的位置：

全局配置：~/.config/opencode/opencode.json
项目配置：项目根目录中的 opencode.json

OpenCode 会合并配置文件。项目配置会覆盖全局配置中冲突的值。如果希望在每个项目中使用这些提供商，请使用全局文件。如果某个仓库需要自己的模型条目，请使用项目文件。

添加 CometAPI 提供商

创建选定的配置文件。如果该文件已包含一个 provider 对象，请将以下四个条目合并到该对象中：

{
  "$schema": "https://opencode.ai/config.json",
  "provider": {
    "cometapi-chat": {
      "npm": "@ai-sdk/openai-compatible",
      "name": "CometAPI Chat Completions",
      "options": {
        "baseURL": "https://api.cometapi.com/v1",
        "apiKey": "{env:COMETAPI_KEY}"
      },
      "models": {
        "your-model-id": {
          "name": "CometAPI Chat model"
        }
      }
    },
    "cometapi-responses": {
      "npm": "@ai-sdk/openai",
      "name": "CometAPI Responses",
      "options": {
        "baseURL": "https://api.cometapi.com/v1",
        "apiKey": "{env:COMETAPI_KEY}"
      },
      "models": {
        "your-model-id": {
          "name": "CometAPI Responses model"
        }
      }
    },
    "cometapi-messages": {
      "npm": "@ai-sdk/anthropic",
      "name": "CometAPI Anthropic Messages",
      "options": {
        "baseURL": "https://api.cometapi.com/v1",
        "apiKey": "{env:COMETAPI_KEY}"
      },
      "models": {
        "your-model-id": {
          "name": "CometAPI Messages model"
        }
      }
    },
    "cometapi-gemini": {
      "npm": "@ai-sdk/google",
      "name": "CometAPI Gemini",
      "options": {
        "baseURL": "https://api.cometapi.com/v1beta",
        "apiKey": "{env:COMETAPI_KEY}"
      },
      "models": {
        "your-model-id": {
          "name": "CometAPI Gemini model"
        }
      }
    }
  }
}

分别替换每个 your-model-id 键。四个条目可以使用不同的模型 ID。该配置未设置顶层 model。这样您便可通过 /models 选择所需的 API 格式和模型。

请勿在此配置中使用 /connect。apiKey 字段会读取 COMETAPI_KEY 环境变量。未设置的变量会解析为空值，而非已存储的 /connect API 密钥。

选择并验证各个提供商

在您希望 OpenCode 访问的项目中启动它：

opencode

运行 /models，然后选择一个 provider/model 条目。在本指南的四次验证运行中，每个模型轮次都使用了所选条目对应的 API 格式；未观察到跨格式请求扇出或自动协商 API 格式。要从命令行验证聊天补全，请运行：

opencode run \
  --model cometapi-chat/your-model-id \
  "Reply exactly with: COMETAPI_CHAT_OK"

要从命令行验证响应，请运行：

opencode run \
  --model cometapi-responses/your-model-id \
  "Reply exactly with: COMETAPI_RESPONSES_OK"

要从命令行验证 Anthropic 消息，请运行：

opencode run \
  --model cometapi-messages/your-model-id \
  "Reply exactly with: COMETAPI_MESSAGES_OK"

要从命令行验证 Gemini generateContent，请运行：

opencode run \
  --model cometapi-gemini/your-model-id \
  "Reply exactly with: COMETAPI_GEMINI_OK"

故障排除

OpenCode 未显示 CometAPI 模型

确认配置为有效的 JSON。每个自定义条目必须位于顶层 provider 对象内，且每个模型 ID 必须位于对应的 models 对象内。重启 OpenCode，然后再次打开 /models。

OpenCode 报告 API 密钥或身份验证错误

确认在启动 OpenCode 的 shell 中已设置 COMETAPI_KEY。未设置的 {env:COMETAPI_KEY} 引用会变为空值。更改 shell 配置文件后，请打开新的 shell。

模型 ID 不可用

查看 CometAPI 模型页面，然后替换所选提供商条目中的模型 ID。确认该模型接受该提供商的 API 格式。

请求使用了错误的路径

对于聊天补全、响应和消息，请将 baseURL 保持为 /v1。对于 Gemini，请使用 /v1beta 。请勿在 baseURL 中包含操作路径。

一个提供商可用，但另一个提供商失败

请使用接受所选提供商 API 格式的模型 ID。不要假设同一个模型 ID 接受全部四种格式。

项目配置更改了全局提供商

OpenCode 会合并全局配置和项目配置。当希望全局提供商条目保持不变时，请重命名项目提供商 ID 或移除其冲突的值。

OpenCode 的访问权限超出预期

OpenCode 使用启动它的进程所具有的权限。在需要更严格访问边界时，请在容器或沙箱中运行 OpenCode。

概览

AI 编码智能体

AI 智能体

AI 聊天客户端

翻译与语言

自动化平台

可观测性与评估

AI 框架

前提条件

了解 API 格式

了解运行时权限

配置 OpenCode

故障排除

相关资源

​前提条件

​了解 API 格式

​了解运行时权限

​配置 OpenCode

​故障排除

​相关资源

前提条件

了解 API 格式

了解运行时权限

配置 OpenCode

故障排除

相关资源