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 主要特性概览

为什么要使用 API 代理？

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

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

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

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

配置架构概述

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

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 中继的配置参数

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故障排除

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

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

"baseURL": "https://api.apiyi.com/v1/chat/completions"

{
  "provider": {
    "apiyi": {
      "models": {
        "claude-sonnet-4-20250514": { "name": "Claude Sonnet 4" }
      }
    }
  },
  "model": "apiyi/claude-sonnet-4-20250514"
}

# 查看已配置的认证信息
opencode auth list

# 查看可用模型
opencode
/models

# 测试简单对话
opencode -p "Hello, 请用中文回复"

opencode
/models
# 选择不同 Provider 下的模型即可切换

{
  "model": "apiyi/claude-sonnet-4-20250514"
}

OpenCode 与 Claude Code：API 访问方式对比

 技术提示：OpenCode最大的优势在于其模型灵活性。通过与APIYI（apiyi.com）网关配合使用，您可以使用相同的配置在Claude、GPT-4、Gemini以及其他各种大型语言模型之间切换，从而找到最具成本效益的解决方案。

参考

以下是一些您在配置 OpenCode 时可能会用到的资源：

概括

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

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

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

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