OpenCode 配置教程

获取 API Key 后，按照你的操作系统选择对应步骤完成配置。

OpenCode 是开源的 AI 编程代理（AI coding agent），支持连接多种 AI 模型，包括 Claude、GPT、Gemini 系列。

步骤 1：验证是否安装 Node.js

OpenCode 基于 Node.js 运行，请先确认已安装 Node.js（建议 v18+ LTS 版本）。

打开终端（Windows 用户按 Win+R 输入 cmd 回车）：

如果没有显示版本号，请参考「Node.js 安装教程」进行安装。

步骤 2：安装 OpenCode

方案一：一键脚本安装（macOS / Linux / WSL2）

方案二：npm 全局安装（跨平台）

如果使用 nvm 管理 Node.js，可以不加 sudo。

方案三：使用包管理器

Homebrew (macOS / Linux)：

Chocolatey (Windows)：

choco install opencode

Scoop (Windows)：

scoop bucket add extras
scoop install extras/opencode

验证安装

步骤 3：配置环境变量

如果使用 CC Switch，可以跳转「CC Switch 配置教程」，通过图形界面完成配置。

将下方变量中的占位符替换为你的实际信息：

YOUR_API_KEY → 你在平台创建的令牌

Windows（PowerShell）

临时生效（仅当前终端会话有效）：

$env:ANTHROPIC_BASE_URL = "https://jiniu.ai"
$env:ANTHROPIC_API_KEY  = "YOUR_API_KEY"

永久生效（推荐）：

[System.Environment]::SetEnvironmentVariable("ANTHROPIC_BASE_URL", "https://jiniu.ai", "User")
[System.Environment]::SetEnvironmentVariable("ANTHROPIC_API_KEY",  "YOUR_API_KEY",            "User")

设置后需重新打开终端窗口。

macOS / Linux / WSL2

将以下内容追加到 ~/.bashrc 或 ~/.zshrc：

然后使配置立即生效：

步骤 4：验证环境变量

Windows

echo $env:ANTHROPIC_BASE_URL
echo $env:ANTHROPIC_API_KEY

macOS / Linux / WSL2

步骤 5：开始使用

进入项目目录，运行：

基础命令

命令	说明
`/help`	显示帮助信息
`/models`	切换 AI 模型
`/init`	初始化项目，生成 `AGENTS.md` 文件
`/undo`	撤销上一次修改
`/connect`	重新配置模型连接
`/exit`	退出 OpenCode

两种工作模式

Plan 模式（规划）：只分析不修改，适合代码审查和性能分析

Build 模式（构建）：实际修改代码，适合重构和添加功能

在交互界面中按 Tab 键可在两种模式间切换。

步骤 6：确认配置已生效

进入 OpenCode 交互界面后，输入：

/status

期望值示例：

Provider: Anthropic
Model: claude-sonnet-4-5
Base URL: https://jiniu.ai

如果显示的是官方地址或默认模型，说明环境变量未生效，请重新检查步骤 3。

可选：全局配置文件

系统	路径
Windows	`C:\Users\你的用户名\.config\opencode\opencode.json`
macOS / Linux	`~/.config/opencode/opencode.json`

示例 opencode.json：

{
  "$schema": "https://opencode.ai/config.json",
  "model": "anthropic/claude-sonnet-4-5",
  "providers": {
    "anthropic": {
      "apiKey": "YOUR_API_KEY",
      "options": {
        "baseURL": "https://jiniu.ai"
      }
    }
  }
}

💡 可以在项目根目录下创建 .opencode.json 用于项目级别的特定配置。

常见问题

Q：环境变量设置后不生效？
A：重新打开一个终端窗口，或执行 source ~/.bashrc。

Q：Windows 安装时提示权限错误？
A：以管理员身份运行 PowerShell 后重试。

Q：macOS / Linux 安装时提示权限错误？
A：命令前加 sudo，或使用 nvm 安装 Node.js（nvm 安装的 npm 无需 sudo）。

Q：OpenCode 启动后无法连接提供商？
A：1. 检查 API 密钥是否正确；2. 运行 /connect 重新配置；3. 检查网络是否能访问 API 地址。

Q：OpenCode 启动后界面空白或卡住？
A：按 Ctrl+L 强制刷新屏幕。推荐使用 WezTerm、Alacritty、Windows Terminal 等现代终端。

OpenCode 配置教程

步骤 1：验证是否安装 Node.js#

步骤 2：安装 OpenCode#

方案一：一键脚本安装（macOS / Linux / WSL2）#

方案二：npm 全局安装（跨平台）#

方案三：使用包管理器#

验证安装#

步骤 3：配置环境变量#

Windows（PowerShell）#

macOS / Linux / WSL2#

步骤 4：验证环境变量#

Windows#

macOS / Linux / WSL2#

步骤 5：开始使用#

基础命令#

两种工作模式#

步骤 6：确认配置已生效#

可选：全局配置文件#

常见问题#

步骤 1：验证是否安装 Node.js

步骤 2：安装 OpenCode

方案一：一键脚本安装（macOS / Linux / WSL2）

方案二：npm 全局安装（跨平台）

方案三：使用包管理器

验证安装

步骤 3：配置环境变量

Windows（PowerShell）

macOS / Linux / WSL2

步骤 4：验证环境变量

Windows

macOS / Linux / WSL2

步骤 5：开始使用

基础命令

两种工作模式

步骤 6：确认配置已生效

可选：全局配置文件

常见问题