OpenCode
OpenCode 是一款开源 AI 编码 Agent，支持终端界面、桌面应用和 IDE 扩展等形态。它可以阅读项目上下文、解释代码、修改文件、执行命令并协助完成开发任务。本页主要说明如何在 OpenCode 中接入彼源 AI，将模型调用统一切换到彼源 AI API。
适用场景
- 希望在终端中使用 AI 编码 Agent 处理本地项目。
- 希望通过彼源 AI 令牌接入 OpenAI 兼容模型。
- 希望在彼源 AI 控制台统一查看 OpenCode 的使用日志、额度消耗，并统一管理令牌权限。
- 希望为 OpenCode 单独创建令牌，避免与生产服务或其他客户端共用同一密钥。
前置条件
开始前，请先准备以下信息：
| 项目 | 说明 |
|---|---|
| OpenCode | 已安装并可运行 opencode 命令 |
| API endpoint | https://api.biyuan.ai/v1 |
| 彼源 AI 令牌 | 在控制台令牌管理中创建的 sk- 开头令牌 |
| 模型名称 | 从模型广场复制；令牌设置了模型限制时，以 GET /v1/models 返回为准 |
OpenCode 的 OpenAI-compatible provider 需要填写包含
/v1的 API endpoint。接入彼源 AI 时请使用https://api.biyuan.ai/v1。
安装 OpenCode
如本机尚未安装 OpenCode，可使用官方安装脚本：
curl -fsSL https://opencode.ai/install | bash
也可以使用 npm 或 Homebrew 安装：
npm install -g opencode-ai
brew install anomalyco/tap/opencode
安装完成后执行：
opencode --version
如果能够输出版本号，说明 OpenCode 已可在当前终端中使用。
接入流程
创建 OpenCode 专用令牌
-> 在 OpenCode 中添加自定义 provider 凭证
-> 写入 opencode.json
-> 选择彼源 AI 模型
-> 发送测试请求
-> 在彼源 AI 控制台「使用日志」确认请求
如何接入
1. 创建 OpenCode 专用令牌
进入彼源 AI 控制台：
令牌管理 -> 添加令牌
建议命名为 opencode-mac、opencode-work、opencode-project 等便于识别的名称。后续查看消耗、停用令牌或排查请求时，可以直接定位到对应客户端。
2. 添加自定义 provider 凭证
进入项目目录并启动 OpenCode：
cd /path/to/your/project
opencode
在 OpenCode 界面中执行：
/connect
选择 Other，并按提示填写：
| 项目 | 建议填写 |
|---|---|
| Provider ID | biyuan |
| API Key | 彼源 AI 控制台生成的 sk- 开头令牌 |
Provider ID 会在后续 opencode.json 中使用。建议保持为 biyuan，避免凭证和配置文件中的 provider 名称不一致。
3. 配置 opencode.json
在项目根目录创建或更新 opencode.json：
{
"$schema": "https://opencode.ai/config.json",
"provider": {
"biyuan": {
"npm": "@ai-sdk/openai-compatible",
"name": "Biyuan",
"options": {
"baseURL": "https://api.biyuan.ai/v1"
},
"models": {
"gpt-5.4": {
"name": "gpt-5.4"
}
}
}
},
"model": "biyuan/gpt-5.4"
}
字段说明：
| 字段 | 说明 |
|---|---|
provider.biyuan | 自定义 provider，名称需要与 /connect 中填写的 Provider ID 一致 |
npm | OpenAI 兼容接口使用 @ai-sdk/openai-compatible |
options.baseURL | 彼源 AI API endpoint，需要包含 /v1 |
models | 在 OpenCode 中展示的模型列表 |
model | OpenCode 默认使用的模型，格式为 provider/model |
请将示例中的 gpt-5.4 替换为真实模型 ID。模型 ID 从模型广场复制；想确认当前令牌实际可用的模型，调用 GET /v1/models（令牌设置了模型限制时，以这个返回为准）。首次接入建议只配置一个模型完成验证，确认链路正常后再增加其他模型。
4. 选择模型
回到 OpenCode，执行：
/models
在模型列表中选择 Biyuan 下的目标模型。如果列表中没有看到目标模型，请检查 opencode.json 中的 models 配置和 provider 名称是否一致。
5. 发送测试请求
在 OpenCode 中发送一条简单请求：
请用三句话总结这个项目的目录结构。
OpenCode 正常返回后，回到彼源 AI 控制台，打开「使用日志」，能看到刚才这条请求（模型、时间、消耗），说明接入成功。
使用环境变量保存令牌
如果不希望通过 /connect 保存凭证，也可以使用环境变量方式。先在终端中设置：
export BIYUAN_API_KEY="<你的彼源 AI 令牌>"
然后在 opencode.json 中加入 apiKey：
{
"$schema": "https://opencode.ai/config.json",
"provider": {
"biyuan": {
"npm": "@ai-sdk/openai-compatible",
"name": "Biyuan",
"options": {
"baseURL": "https://api.biyuan.ai/v1",
"apiKey": "{env:BIYUAN_API_KEY}"
},
"models": {
"gpt-5.4": {
"name": "gpt-5.4"
}
}
}
},
"model": "biyuan/gpt-5.4"
}
请勿把真实令牌写入公开文档、截图、代码仓库或聊天记录中。如果 opencode.json 会提交到 Git，建议使用环境变量或 /connect 保存凭证，不要在配置文件中明文写入令牌。
全局配置方式
如果希望所有项目都默认使用彼源 AI，可以把配置放到全局配置文件：
~/.config/opencode/opencode.json
如果只希望某个项目使用彼源 AI，建议把 opencode.json 放在该项目根目录。项目级配置优先级更高，适合按项目选择不同模型或权限边界。
验证方法
推荐按以下顺序验证：
- 执行
opencode --version，确认 OpenCode 已安装。 - 执行
opencode auth list，确认biyuan凭证已存在。 - 检查
opencode.json中是否存在provider.biyuan。 - 确认
options.baseURL为https://api.biyuan.ai/v1。 - 执行
/models，选择Biyuan下的目标模型。 - 发送一条测试请求。
- 回到彼源 AI 控制台，打开「使用日志」，确认能看到刚才这条请求（模型、时间、消耗）。
注意事项
baseURL需要填写https://api.biyuan.ai/v1，不要省略/v1。provider名称需要与/connect中填写的 Provider ID 保持一致。- 模型 ID 从模型广场复制；令牌设置了模型限制时，以
GET /v1/models返回为准。 - 不建议多个客户端共用同一枚高权限令牌。
- 不建议把真实令牌提交到项目仓库。
- 如果某个模型依赖 Responses 风格接口，先到模型广场查看该模型卡片的接口标注；想确认当前令牌实际可用的模型，调用
GET /v1/models（令牌设置了模型限制时，以这个返回为准）。
常见问题
Base URL 应该填写什么
填写：
https://api.biyuan.ai/v1
OpenCode 的 OpenAI-compatible provider 会基于该地址请求 OpenAI 兼容接口，因此这里需要包含 /v1。
执行 /models 看不到 Biyuan
请检查：
opencode.json是否位于当前项目根目录，或是否已放入全局配置目录。provider中是否存在biyuan。/connect中填写的 Provider ID 是否也是biyuan。- JSON 格式是否正确，例如引号、逗号和括号是否完整。
提示 401 或 403
常见原因包括：
- 令牌填写错误或已经失效。
- 当前令牌没有目标模型权限。
- 令牌额度不足或被停用。
Provider ID与opencode.json中的 provider 名称不一致。
建议先在彼源 AI 控制台确认令牌状态和可用模型，再重新启动 OpenCode 验证。
模型名称应该怎么写
模型 ID 从模型广场复制；想确认当前令牌实际可用的模型，调用 GET /v1/models（令牌设置了模型限制时，以这个返回为准）。models 中的 key 是实际请求使用的模型名称，name 是在 OpenCode 中展示的名称。通常保持两者一致即可。
示例：
"models": {
"gpt-5.4": {
"name": "gpt-5.4"
}
}
默认模型需要写成：
"model": "biyuan/gpt-5.4"
如何确认请求是否经过彼源 AI
最直接的方式：回到彼源 AI 控制台，打开「使用日志」，能看到刚才这条请求（模型、时间、消耗），说明请求确实经过了彼源 AI。如果 OpenCode 返回成功，但「使用日志」里没有这条请求，通常说明当前配置仍在使用其他 provider，或当前项目没有加载包含 biyuan 的 opencode.json。