OpenCode

OpenCode 是一款面向终端的开源 AI 编程工具。Bita API 提供 OpenAI 兼容的 Chat Completions 和 Responses 接口，可以在 OpenCode 中配置为自定义服务商。

准备工作

开始前，请准备：

已安装的 OpenCode。
一个处于启用状态、仍有可用额度的 Bita API 密钥。
密钥所属分组可以使用的模型 ID。
已确认该模型支持 Chat Completions 还是 Responses 接口。

如果尚未创建密钥或选择模型，请阅读创建 API 密钥和选择模型。

安装 OpenCode

macOS、Linux 或 WSL

使用官方安装脚本：

curl -fsSL https://opencode.ai/install | bash

也可以通过 npm 安装：

npm install -g opencode-ai

macOS 和 Linux 还可以使用 OpenCode 官方 Homebrew Tap：

brew install anomalyco/tap/opencode

Windows

OpenCode 官方推荐 Windows 用户通过 WSL 使用。也可以直接在 PowerShell 中通过 npm、Chocolatey 或 Scoop 安装：

npm install -g opencode-ai

安装方式可能随 OpenCode 版本更新，其他安装选项参见 OpenCode 官方安装说明。

选择接口格式

OpenCode 使用的 provider 包决定最终请求哪种 OpenAI 兼容接口：

Bita API 接口	OpenCode provider 包	适用模型
Chat Completions	`@ai-sdk/openai-compatible`	模型广场中支持 `Chat` 端点的模型
Responses	`@ai-sdk/openai`	模型广场中支持 `Response` 端点的模型

第一次配置时，建议先选择一种接口。不要只根据模型名称判断协议，应以模型广场显示的端点类型为准。

保存 API 密钥

推荐让 OpenCode 单独保存 API 密钥，不要把密钥直接写入项目配置。

进入准备使用 OpenCode 的项目目录并启动：
```
cd /path/to/project
opencode
```
在 OpenCode 中输入：
```
/connect
```
在服务商列表底部选择 Other。
Provider ID 输入 bita-api。
粘贴完整的 Bita API 密钥。

Provider ID 必须与后面 opencode.json 中 provider 下的键完全一致，否则 OpenCode 无法把凭据与服务商配置关联。

可以在终端中检查 OpenCode 已保存的凭据：

opencode auth list

配置 Chat Completions 模型

如果模型支持 Chat 端点，创建或编辑 OpenCode 配置文件：

配置范围	文件位置
当前用户的所有项目	`~/.config/opencode/opencode.json`
仅当前项目	项目根目录下的 `opencode.json`

用户级配置适合复用同一套 Bita API 模型；项目级配置优先级更高，适合为单个项目指定模型。把下面配置中的 YOUR_MODEL_ID 替换为模型广场中的完整模型 ID：

opencode.json
{
  "$schema": "https://opencode.ai/config.json",
  "model": "bita-api/YOUR_MODEL_ID",
  "provider": {
    "bita-api": {
      "npm": "@ai-sdk/openai-compatible",
      "name": "Bita API",
      "options": {
        "baseURL": "https://www.bita-api.com/v1"
      },
      "models": {
        "YOUR_MODEL_ID": {
          "name": "YOUR_MODEL_ID"
        }
      }
    }
  }
}

这里各字段的作用如下：

字段	说明
`provider.bita-api`	自定义服务商 ID，必须与 `/connect` 时填写的 ID 一致
`npm`	使用 OpenAI-compatible provider，请求 Chat Completions 接口
`options.baseURL`	Bita API OpenAI 兼容地址，需要包含 `/v1`
`models`	OpenCode 中可选择的模型，键必须是真实模型 ID
`model`	默认模型，格式为 `provider_id/model_id`

需要添加多个模型时，继续在 models 中增加条目：

"models": {
  "YOUR_FIRST_MODEL_ID": {
    "name": "YOUR_FIRST_MODEL_ID"
  },
  "YOUR_SECOND_MODEL_ID": {
    "name": "YOUR_SECOND_MODEL_ID"
  }
}

配置 Responses 模型

如果目标模型只支持或更适合 Response 端点，把 provider 包改为 @ai-sdk/openai：

opencode.json
{
  "$schema": "https://opencode.ai/config.json",
  "model": "bita-api/YOUR_RESPONSES_MODEL_ID",
  "provider": {
    "bita-api": {
      "npm": "@ai-sdk/openai",
      "name": "Bita API",
      "options": {
        "baseURL": "https://www.bita-api.com/v1"
      },
      "models": {
        "YOUR_RESPONSES_MODEL_ID": {
          "name": "YOUR_RESPONSES_MODEL_ID"
        }
      }
    }
  }
}

接口格式必须与模型匹配

@ai-sdk/openai-compatible 用于 /v1/chat/completions，@ai-sdk/openai 用于 /v1/responses。如果 provider 包与模型支持的端点不匹配，可能出现 404、请求格式错误或工具调用异常。

使用环境变量提供密钥

如果不使用 /connect，也可以通过环境变量向配置文件传递密钥。先在启动 OpenCode 的终端中设置：

export BITA_API_KEY="YOUR_BITA_API_KEY"

PowerShell 使用：

$env:BITA_API_KEY="YOUR_BITA_API_KEY"

然后在对应 provider 的 options 中增加 apiKey：

"options": {
  "baseURL": "https://www.bita-api.com/v1",
  "apiKey": "{env:BITA_API_KEY}"
}

不要提交 API 密钥

项目根目录中的 opencode.json 可能会被提交到 Git。不要在其中填写真实密钥；应使用 /connect 或 {env:BITA_API_KEY}。

启动并验证

保存配置后，在项目目录启动 OpenCode：

opencode

进入交互界面后：

输入 /models。
找到 Bita API，选择刚配置的模型。
发送一条简单消息，确认模型能够回复。
再让模型读取一个文件或执行安全的只读命令，检查工具调用是否正常。

首次在项目中使用时，还可以运行：

/init

OpenCode 会分析项目并创建 AGENTS.md，用于记录项目结构和开发约定。生成后应先检查内容，再决定是否提交到版本库。

切换默认模型

在交互界面中使用 /models 可以临时选择其他模型。需要修改默认模型时，更新配置文件顶层的 model：

"model": "bita-api/YOUR_MODEL_ID"

完整模型标识由服务商 ID 和模型 ID 组成。如果配置了多个 Bita API 服务商，例如 bita-chat 和 bita-responses，还需要分别通过 /connect 保存凭据，或者为它们配置同一个 BITA_API_KEY 环境变量。

常见问题

现象	建议检查
`/models` 中没有 Bita API	`provider` 配置是否位于正确文件；JSON 是否有效；是否已经在 `models` 中显式添加模型
显示 Bita API 但调用时提示缺少密钥	`/connect` 时的 Provider ID 是否与配置中的 `bita-api` 完全一致；运行 `opencode auth list` 检查凭据
返回 `401`	是否使用完整 Bita API 密钥；环境变量是否在启动 OpenCode 的同一个终端中生效
返回 `403`	密钥是否启用、过期或超额；密钥分组是否支持当前模型
返回 `404`	Base URL 是否为 `https://www.bita-api.com/v1`；provider 包是否与模型端点类型匹配
返回模型不存在	模型 ID 是否与模型广场完全一致，密钥分组是否包含该模型
对话正常但工具调用失败	换用明确支持工具调用的模型，并确认使用了正确的 Chat Completions 或 Responses provider 包
修改配置后仍使用旧模型	退出并重新启动 OpenCode，再通过 `/models` 重新选择
配置正确但调用失败	查看 Bita API 使用日志中的请求接口、模型和错误信息

OpenCode 的配置结构和安装方式会持续更新，具体以 OpenCode 配置文档、自定义服务商文档和模型文档为准。

如果希望通过图形界面管理多个服务商，也可以使用 CC Switch。

下一步：Hermes。

准备工作​

安装 OpenCode​

macOS、Linux 或 WSL​

Windows​

选择接口格式​

保存 API 密钥​

配置 Chat Completions 模型​

配置 Responses 模型​

使用环境变量提供密钥​

启动并验证​

切换默认模型​

常见问题​