OpenCode 怎么配置 API？终端 AI 编程工具接入自定义模型完整教程（2026）

摘要

OpenCode 是一款开源的终端 AI 编码工具，类似 Claude Code 的开源替代品。通过 ClaudeYY 接入，可以使用任意模型。本文讲解三种配置方式（OpenAI 环境变量、Anthropic 环境变量、config.toml 配置文件），并给出模型推荐和问题排查方案。

什么是 OpenCode

OpenCode 是一个在终端中运行的 AI 编程助手——能阅读项目代码、编辑文件、执行 shell 命令、理解上下文并给出建议。

和 Claude Code 的核心区别：OpenCode 完全开源，不绑定任何特定 AI 服务商。你可以通过配置 API 端点，接入 Claude、GPT、Gemini、Kimi 等任意大模型。

安装 OpenCode

两种安装方式：

一键安装脚本（推荐）

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

Go 安装

go install github.com/opencode-ai/opencode@latest

安装完成后运行 opencode --version 确认安装成功。

配置方式一：OpenAI 兼容环境变量

最简单直接的方式，适用于大多数场景。编辑 shell 配置文件：

# ~/.zshrc 或 ~/.bashrc
export OPENAI_API_KEY=<你的 CLAUDEYY_API_KEY>
export OPENAI_BASE_URL=https://claude.claudeyy.com/v1

保存后执行 source ~/.zshrc。

通过 OpenAI 兼容协议接入，支持平台上所有模型——不仅是 GPT 系列，Claude、Gemini、Kimi 都通过同一个端点访问。

配置方式二：Anthropic 环境变量

如果主要使用 Claude 系列模型，可以用 Anthropic 原生协议接入：

# ~/.zshrc 或 ~/.bashrc
export ANTHROPIC_API_KEY=<你的 CLAUDEYY_API_KEY>
export ANTHROPIC_BASE_URL=https://claude.claudeyy.com/anthropic

同样保存后 source ~/.zshrc。

注意 Base URL 的区别：OpenAI 兼容协议用 /v1，Anthropic 原生协议用 /anthropic。两者不能混用。

配置方式三：config.toml 配置文件

对于需要精细控制的场景——比如指定默认模型、配置多个 provider——使用配置文件更好。

创建或编辑 ~/.config/opencode/config.toml：

[providers.claudeyy]
api_key = "<你的 CLAUDEYY_API_KEY>"
base_url = "https://claude.claudeyy.com/v1"

[models.default]
provider = "claudeyy"
model = "anthropic/claude-sonnet-4.6"

配置文件可以明确指定默认模型，不需要每次运行时手动选择。provider 字段指向你定义的 provider 名称，model 字段填写模型 ID。

验证配置

opencode "Hello, 你好吗？"

如果配置正确，OpenCode 会调用你配置的模型返回回复。

推荐模型选择

日常开发以 Claude Sonnet 4.6 为主力，遇到复杂架构设计切换到 Opus 4.6，简单查询用 Kimi K2.5 节省成本。

常见问题排查

环境变量不生效

设置后必须重新加载 shell 配置：

source ~/.zshrc

或直接开新终端。用 echo $OPENAI_API_KEY 确认变量已正确加载。

连接超时

检查网络是否能访问端点：

curl -I https://claude.claudeyy.com/v1/models

返回 200 说明网络没问题，检查 API Key。连接超时则检查网络和代理设置。

config.toml 不被识别

确认路径是 ~/.config/opencode/config.toml，目录名是 opencode。如果同时设置了环境变量和配置文件，环境变量通常优先级更高。

模型 ID 写错

模型 ID 必须完整填写，包含 provider 前缀。anthropic/claude-sonnet-4.6 而不是 claude-sonnet-4.6。

注意事项

OpenCode 是活跃开发中的开源项目，配置方式可能随版本更新变化。如果遇到与本文描述不一致的行为，参考 OpenCode 官方文档 获取最新信息。

总结

OpenCode 是终端 AI 编程工具中少见的开源选择，三种配置方式各有适用场景：环境变量适合快速上手，config.toml 适合精细管理。选好模型、配好 API，你就有了一个不受服务商限制的终端 AI 编程搭档。

详细集成文档参考 ClaudeYY OpenCode 集成指南。