想使用开源AI编码助手OpenCode,却发现官方API价格过高或连接不稳定?API代理是您的最佳选择。本文将通过三个简单的步骤,指导您如何将OpenCode连接到APIYI或OpenRouter等代理。您将能够以更低的成本访问超过75种主流大型语言模型,包括Claude、GPT-4和Gemini。
核心价值:在本指南结束时,您将知道如何配置 OpenCode 以与任何 OpenAI 兼容的 API 配合使用,从而让您可以自由切换模型并优化成本。
OpenCode 是一款开源终端 AI 编码助手,通常被称为 Claude Code 的开源替代品。它使用 Go 语言编写,具有简洁的终端用户界面 (TUI)、多会话管理、LSP 集成和其他专业级工具。
特征
描述
价值
支持 75+ 款机型
直接使用官方 API 有时会带来一些麻烦,原因有以下几点:
问题
API代理解决方案
高昂的成本
代理服务器价格更优惠,因此非常适合个人开发者。
网络不稳定
代理服务器优化连接路径,从而实现更好的全球访问。
复杂计费
统一的计费界面让您可以在一个地方管理所有型号。
速率限制
代理通常可以提供更灵活的配额。
注册障碍
无需外国电话号码或专用信用卡。
快速入门:我们推荐使用APIYI (apiyi.com)作为代理。它提供开箱即用的 OpenAI 兼容接口,注册即可获得免费测试额度。您可以在 5 分钟内完成 OpenCode 的配置。
在开始配置之前,让我们先了解一下 OpenCode 的 API 集成是如何工作的:
OpenCode 使用统一的配置管理系统,支持多层覆盖:
配置级别
文件位置
优先事项
用例
远程配置
OpenCode 通过适配器支持任何 OpenAI 兼容的 API @ai-sdk/openai-compatible。关键配置项包括:
baseURL:您的 API 中继站的接口地址。
apiKey:中继站提供的 API 密钥。
型号:可用型号列表。
这意味着只要中继站提供标准/v1/chat/completions端点,就可以将其直接插入 OpenCode。
OpenCode 提供了多种安装方法;请选择最适合您的一种:
一键安装脚本(推荐):
curl -fsSL https://opencode.ai/install | bash
Homebrew 安装(macOS/Linux):
brew install opencode-ai/tap/opencode
npm 安装:
npm i -g opencode-ai@latest
Go 安装:
go install github.com/opencode-ai/opencode@latest
验证安装情况:
opencode --version
OpenCode 支持两种身份验证方法:
选项 1:使用/connect命令(推荐)
启动 OpenCode 后,输入以下/connect命令:
opencode
# Enter in the TUI interface
/connect
选择Other添加自定义提供商并输入您的 API 密钥。密钥将安全地存储在~/.local/share/opencode/auth.json.
选项 2:环境变量配置
将以下内容添加到您的~/.zshrc或~/.bashrc:
# APIYI Relay Configuration
export OPENAI_API_KEY="sk-your-apiyi-key"
export OPENAI_BASE_URL="https://api.apiyi.com/v1"
应用更改:
source ~/.zshrc
这是最关键的一步——创建配置文件来指定您的 API 中继站:
全局配置(适用于所有项目):
mkdir -p ~/.config/opencode
touch ~/.config/opencode/opencode.json
项目配置(仅适用于当前项目):
touch opencode.json # In the project root
{
"$schema": "https://opencode.ai/config.json",
"provider": {
"apiyi": {
"npm": "@ai-sdk/openai-compatible",
"name": "APIYI",
"options": {
"baseURL": "https://api.apiyi.com/v1",
"apiKey": "{env:OPENAI_API_KEY}"
},
"models": {
"claude-sonnet-4-20250514": {
"name": "Claude Sonnet 4"
},
"gpt-4o": {
"name": "GPT-4o"
}
}
}
},
"model": "apiyi/claude-sonnet-4-20250514"
}
配置说明:该{env:OPENAI_API_KEY}语法会自动读取环境变量,因此您无需在配置文件中硬编码密钥。从 APIYI (apiyi.com) 获取的 API 密钥与 OpenAI 兼容,可直接使用。
查看完整配置示例(包括多个提供商)
中继
基本URL
特征
推荐方案
艾比
APIYI 是一个专为中国开发者优化的 AI API 中继平台,它提供:
统一的 OpenAI 兼容接口
支持主流大型语言模型,例如 Claude、GPT、Gemini 和 DeepSeek。
按需付费,无月租费
免费试用积分
中文客服支持
{
"provider": {
"apiyi": {
"npm": "@ai-sdk/openai-compatible",
"name": "APIYI",
"options": {
"baseURL": "https://api.apiyi.com/v1"
},
"models": {
"claude-sonnet-4-20250514": { "name": "Claude Sonnet 4" },
"claude-opus-4-20250514": { "name": "Claude Opus 4" },
"gpt-4o": { "name": "GPT-4o" },
"gpt-4o-mini": { "name": "GPT-4o Mini" },
"gemini-2.5-pro": { "name": "Gemini 2.5 Pro" },
"deepseek-chat": { "name": "DeepSeek V3" }
}
}
}
}
OpenRouter 聚合了 400 多个 AI 模型,非常适合需要频繁切换模型的场景:
{
"provider": {
"openrouter": {
"npm": "@ai-sdk/openai-compatible",
"name": "OpenRouter",
"options": {
"baseURL": "https://openrouter.ai/api/v1",
"apiKey": "{env:OPENROUTER_API_KEY}",
"headers": {
"HTTP-Referer": "https://your-app.com",
"X-Title": "My OpenCode App"
}
},
"models": {
"anthropic/claude-sonnet-4": {
"name": "Claude Sonnet 4"
},
"google/gemini-2.5-pro": {
"name": "Gemini 2.5 Pro"
},
"meta-llama/llama-3.1-405b": {
"name": "Llama 3.1 405B"
}
}
}
}
}
选择建议:如果您主要使用 Claude 和 GPT 系列路由器,强烈推荐 APIYI (apiyi.com),因为它价格更优惠,响应速度更快。如果您需要尝试开源或小众型号的路由器,OpenRouter 则提供了更全面的覆盖范围。
OpenCode 内置了两个代理:编码员和规划员。您可以为它们分别分配不同的模型:
{
"agent": {
"coder": {
"model": "apiyi/claude-sonnet-4-20250514",
"maxTokens": 8000,
"description": "主要编码任务,使用强模型"
},
"planner": {
"model": "apiyi/gpt-4o-mini",
"maxTokens": 4000,
"description": "规划分析,使用轻量模型节省成本"
}
}
}
配置好多个提供程序后,您可以随时在 OpenCode 中使用以下/models命令在它们之间切换:
# 启动 OpenCode
opencode
# 在 TUI 中切换模型
/models
# 选择 apiyi/claude-sonnet-4-20250514 或其他模型
我们建议您将 API 密钥管理在.env文件中:
# .env 文件
APIYI_API_KEY=sk-your-apiyi-key
OPENROUTER_API_KEY=sk-or-your-openrouter-key
然后,在你的文章中引用它们opencode.json:
{
"provider": {
"apiyi": {
"options": {
"apiKey": "{env:APIYI_API_KEY}"
}
}
}
}
为模型指定上下文和输出限制,以避免出现“超出限制”错误:
{
"models": {
"claude-sonnet-4-20250514": {
"name": "Claude Sonnet 4",
"limit": {
"context": 200000,
"output": 65536
}
}
}
}
以下是一些配置过程中可能遇到的常见问题以及解决方法:
问题1:配置后出现“找不到路由/api/messages”错误?
这通常是由baseURL配置错误引起的。请检查以下几点:
确保baseURL以逗号结尾/v1,而不是以句点结尾/v1/chat/completions。
确认代理/网关支持标准的 OpenAI API 格式。
请验证您的API密钥是否有效。
正确格式:
"baseURL": "https://api.apiyi.com/v1"
格式错误:
"baseURL": "https://api.apiyi.com/v1/chat/completions"
通过 APIYI (apiyi.com) 获取的 API 地址已验证,可以直接使用。
Q2:出现“ProviderModelNotFoundError”错误,提示找不到模型?
当配置的模型 ID 与提供程序中定义的 ID 不匹配时,就会发生这种情况。解决方法如下:
检查model字段格式:provider-id/model-id。
确保模型已在models对象中定义。
例子:
{
"provider": {
"apiyi": {
"models": {
"claude-sonnet-4-20250514": { "name": "Claude Sonnet 4" }
}
}
},
"model": "apiyi/claude-sonnet-4-20250514"
}
Q3:如何验证配置是否成功?
使用以下命令进行检查:
# 查看已配置的认证信息
opencode auth list
# 查看可用模型
opencode
/models
# 测试简单对话
opencode -p "Hello, 请用中文回复"
如果收到正常响应,那就没问题了!您还可以在 APIYI (apiyi.com) 控制台中查看 API 调用日志,以帮助进行故障排除。
Q4:配置文件应该放在哪里最好?
根据您的使用场景选择:
设想
推荐地点
描述
个人全局默认设置
~/.config/opencode/opencode.json
所有项目共享
项目特定配置
项目根目录opencode.json
可以提交到 Git(密钥除外)
CI/CD 环境
环境变量OPENCODE_CONFIG_CONTENT
动态注入配置
Q5:如何在 OpenCode 中切换不同的 API 代理?
配置多个提供商后,使用以下/models命令进行切换:
opencode
/models
# 选择不同 Provider 下的模型即可切换
您也可以在配置中设置默认模型:
{
"model": "apiyi/claude-sonnet-4-20250514"
}
比较维度
OpenCode
克劳德·科德
模型支持
75+ 款型号,可自由配置
克劳德系列
API代理
支持任何 OpenAI 兼容接口
不支持自定义接口
定价
免费软件 + 按需付费 API
每月订阅费 17-100 美元 + API
配置
JSON 配置文件 + 环境变量
内置配置,不可修改
开源状态
完全开源
闭源
表现
取决于所选型号
Claude原生优化,SWE-bench 80.9%
技术提示:OpenCode最大的优势在于其模型灵活性。通过与APIYI(apiyi.com)网关配合使用,您可以使用相同的配置在Claude、GPT-4、Gemini以及其他各种大型语言模型之间切换,从而找到最具成本效益的解决方案。
以下是一些您在配置 OpenCode 时可能会用到的资源:
资源
关联
描述
OpenCode 官方文档
按照这三步配置指南操作后,您现在已经掌握了如何:
安装 OpenCode:使用一键脚本或包管理器快速安装。
配置 API 密钥/connect:通过环境变量设置身份验证。
创建配置文件:编写配置文件opencode.json以指定 API 网关和模型。
作为一款开源终端 AI 编码助手,使用 OpenCode 和 API 网关可以获得与 Claude Code 相媲美的体验,同时还能控制成本并保持模型的灵活性。
我们推荐使用 APIYI (apiyi.com) 快速获取 API 密钥并开始测试。该平台提供免费额度,并支持 Claude、GPT 和 Gemini 等主流大型语言模型。其统一的界面格式使配置变得轻而易举。