OpenCode 连接到 API 中转站

想使用开源AI编码助手OpenCode，却发现官方API价格过高或连接不稳定？API代理是您的最佳选择。本文将通过三个简单的步骤，指导您如何将OpenCode连接到APIYI或OpenRouter等代理。您将能够以更低的成本访问超过75种主流大型语言模型，包括Claude、GPT-4和Gemini。

核心价值：在本指南结束时，您将知道如何配置 OpenCode 以与任何 OpenAI 兼容的 API 配合使用，从而让您可以自由切换模型并优化成本。

什么是 OpenCode？为什么要使用 API 代理？

OpenCode 是一款开源终端 AI 编码助手，通常被称为 Claude Code 的开源替代品。它使用 Go 语言编写，具有简洁的终端用户界面 (TUI)、多会话管理、LSP 集成和其他专业级工具。

OpenCode 主要特性概览

特征

描述

价值

支持 75+ 款机型

可与 OpenAI、Claude、Gemini、Bedrock 等配合使用。

无供应商锁定

终端原生

用珍珠奶茶打造的美丽TUI

对开发者友好的体验

开源且免费

完全开源，无订阅费用

按 API 调用付费；成本可预测。

LSP集成

自动检测语言服务器

智能代码补全和诊断

多会话管理

并行运行多个代理

分解并协作完成复杂任务

Vim 模式

内置 Vim 风格编辑器

对终端电源用户来说很无缝

为什么要使用 API 代理？

直接使用官方 API 有时会带来一些麻烦，原因有以下几点：

问题

API代理解决方案

高昂的成本

代理服务器价格更优惠，因此非常适合个人开发者。

网络不稳定

代理服务器优化连接路径，从而实现更好的全球访问。

复杂计费

统一的计费界面让您可以在一个地方管理所有型号。

速率限制

代理通常可以提供更灵活的配额。

注册障碍

无需外国电话号码或专用信用卡。

快速入门：我们推荐使用APIYI (apiyi.com)作为代理。它提供开箱即用的 OpenAI 兼容接口，注册即可获得免费测试额度。您可以在 5 分钟内完成 OpenCode 的配置。

将 OpenCode 连接到 API 中继站的核心要点

在开始配置之前，让我们先了解一下 OpenCode 的 API 集成是如何工作的：

配置架构概述

OpenCode 使用统一的配置管理系统，支持多层覆盖：

配置级别

文件位置

优先事项

用例

远程配置

.well-known/opencode

最低

团队统一配置

全局配置

~/.config/opencode/opencode.json

中等的

个人默认设置

环境变量

文件指向OPENCODE_CONFIG

中高

临时覆盖

项目配置

项目根目录opencode.json

高的

项目特定设置

内联配置

OPENCODE_CONFIG_CONTENT

最高

CI/CD 场景

API Relay 集成的工作原理

OpenCode 通过适配器支持任何 OpenAI 兼容的 API @ai-sdk/openai-compatible。关键配置项包括：

baseURL：您的 API 中继站的接口地址。
apiKey：中继站提供的 API 密钥。
型号：可用型号列表。

这意味着只要中继站提供标准/v1/chat/completions端点，就可以将其直接插入 OpenCode。

OpenCode 快速入门指南

步骤 1：安装 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

步骤 2：配置您的 API 中继密钥

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

步骤 3：创建 opencode.json 配置文件

这是最关键的一步——创建配置文件来指定您的 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 兼容，可直接使用。

查看完整配置示例（包括多个提供商）

{

"$schema": "https://opencode.ai/config.json",

"provider": {

"apiyi": {

"npm": "@ai-sdk/openai-compatible",

"name": "APIYI (推荐)",

"options": {

"baseURL": "https://api.apiyi.com/v1",

"apiKey": "{env:APIYI_API_KEY}"

},

"models": {

"claude-sonnet-4-20250514": {

"name": "Claude Sonnet 4",

"limit": {

"context": 200000,

"output": 65536

}

},

"claude-opus-4-20250514": {

"name": "Claude Opus 4",

"limit": {

"context": 200000,

"output": 32000

}

},

"gpt-4o": {

"name": "GPT-4o",

"limit": {

"context": 128000,

"output": 16384

}

},

"gpt-4o-mini": {

"name": "GPT-4o Mini",

"limit": {

"context": 128000,

"output": 16384

}

},

"gemini-2.5-pro": {

"name": "Gemini 2.5 Pro",

"limit": {

"context": 1000000,

"output": 65536

}

},

"deepseek-chat": {

"name": "DeepSeek V3",

"limit": {

"context": 64000,

"output": 8192

}

},

"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-site.com",

"X-Title": "OpenCode Client"

}

},

"models": {

"anthropic/claude-sonnet-4": {

"name": "Claude Sonnet 4 (OpenRouter)"

},

"openai/gpt-4o": {

"name": "GPT-4o (OpenRouter)"

}

},

"model": "apiyi/claude-sonnet-4-20250514",

"small_model": "apiyi/gpt-4o-mini",

"agent": {

"coder": {

"model": "apiyi/claude-sonnet-4-20250514",

"maxTokens": 8000

},

"planner": {

"model": "apiyi/gpt-4o",

"maxTokens": 4000

}

},

"tools": {

"write": true,

"bash": true,

"glob": true,

"grep": true

}

OpenCode支持的API中继比较

主流 API 中继的配置参数

中继

基本URL

特征

推荐方案

艾比

https://api.apiyi.com/v1

中文客服支持出色，价格实惠，响应迅速

中国开发者的首选

OpenRouter

https://openrouter.ai/api/v1

最全面，超过 400 种型号

对于经常更换机型的用户来说

人工智能携手共进

https://api.together.xyz/v1

丰富的开源模型选择

非常适合 Llama 和 Mistral 用户

格罗克

https://api.groq.com/openai/v1

速度极快，提供免费套餐

对延迟敏感的场景

APIYI 配置详情

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 配置详情

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 高级配置技巧

代理模型分配策略

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

}

OpenCode故障排除

以下是一些配置过程中可能遇到的常见问题以及解决方法：

问题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 与 Claude Code：API 访问方式对比

比较维度

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.ai/docs

完整配置参考

OpenCode GitHub 代码库

github.com/opencode-ai/opencode

源代码和问题

OpenCode 提供程序配置

opencode.ai/docs/providers

详细的供应商说明

OpenRouter 文档

openrouter.ai/docs

OpenRouter 集成指南

概括

按照这三步配置指南操作后，您现在已经掌握了如何：

安装 OpenCode：使用一键脚本或包管理器快速安装。
配置 API 密钥/connect：通过环境变量设置身份验证。
创建配置文件：编写配置文件opencode.json以指定 API 网关和模型。

作为一款开源终端 AI 编码助手，使用 OpenCode 和 API 网关可以获得与 Claude Code 相媲美的体验，同时还能控制成本并保持模型的灵活性。

我们推荐使用 APIYI (apiyi.com) 快速获取 API 密钥并开始测试。该平台提供免费额度，并支持 Claude、GPT 和 Gemini 等主流大型语言模型。其统一的界面格式使配置变得轻而易举。