OpenCode 配置

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

步骤 1: 验证是否安装 Node.jsCopy Anchor Link

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

打开终端
windows用户（win+R）输入 cmd 回车

分别执行
node -v
npm -v
查看是否有版本号，如果没有显示版本号的可以参考 node 安装教程 进行安装

步骤 2：安装 OpenCodeCopy Anchor Link

OpenCode 提供了多种安装方式，你可以根据操作系统和偏好选择。

方案一：一键脚本安装 (macOS / Linux / WSL2)Copy Anchor Link

# 这个命令会自动检测系统架构并安装最新版本。
curl -fsSL https://opencode.ai/install | bash

方案二：npm 全局安装 (跨平台)Copy Anchor Link

npm install -g opencode-ai@latest

方案三：使用包管理器Copy Anchor Link

Homebrew (macOS / Linux)

# 推荐：使用官方维护的 tap，总能获取到最新版本
brew install sst/tap/opencode

Chocolatey (Windows)

# 推荐：使用官方维护的 tap，总能获取到最新版本
choco install opencode

Scoop (Windows)

scoop bucket add extras
scoop install extras/opencode

更多安装选项可参考官方文档。

验证安装Copy Anchor Link

安装完成后，运行以下命令验证。若有版本号输出，则表示安装成功。

opencode --version

若安装失败，请检查 Node.js 版本是否为 18 及以上。

步骤 3：配置环境变量Copy Anchor Link

如果使用CC Switch的可以跳转 CC Switch 配置

OpenCode 支持通过环境变量或配置文件两种方式配置 API 密钥。环境变量适合快速设置，配置文件则适合项目级或持久化配置。

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

• YOUR_API_KEY → 你的 API Key

Windows（PowerShell）Copy Anchor Link

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

$env:ANTHROPIC_BASE_URL = "https://token.firstpy.com"
$env:ANTHROPIC_API_KEY = "YOUR_API_KEY"

永久生效（推荐）：

[System.Environment]::SetEnvironmentVariable("ANTHROPIC_BASE_URL", "https://token.firstpy.com", "User")
[System.Environment]::SetEnvironmentVariable("ANTHROPIC_API_KEY", "YOUR_API_KEY", "User")

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

macOS / Linux / WSL2Copy Anchor Link

将以下内容追加到 ~/.bashrc 或 ~/.zshrc（zsh 用户）：

export ANTHROPIC_BASE_URL="https://token.firstpy.com"
export ANTHROPIC_API_KEY="YOUR_API_KEY"

然后使配置立即生效：

source ~/.bashrc   # 或 source ~/.zshrc

步骤 4：验证环境变量Copy Anchor Link

WindowsCopy Anchor Link

echo $env:ANTHROPIC_BASE_URL
echo $env:ANTHROPIC_API_KEY

macOS / Linux / WSL2Copy Anchor Link

echo $ANTHROPIC_BASE_URL
echo $ANTHROPIC_API_KEY

步骤 5：开始使用Copy Anchor Link

启动 OpenCodeCopy Anchor Link

进入你的项目目录，运行以下命令启动 OpenCode：

cd your-project   # 进入项目目录
opencode

OpenCode 会以当前目录作为项目上下文，请确保在正确的项目目录中启动。

基础命令Copy Anchor Link

两种工作模式Copy Anchor Link

• Plan 模式（规划）：只分析不修改，适合代码审查和性能分析。
• Build 模式（构建）：实际修改代码，适合重构和添加功能。

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

步骤 6：确认配置已生效Copy Anchor Link

进入 OpenCode 交互界面后，输入以下命令查看当前配置状态：

/status

执行后会显示当前使用的模型、提供商等信息。你也可以通过快捷键 Ctrl+P 进入命令面板，选择 switch model 来查看和切换当前使用的模型。

期望值示例（正常）：

Provider: Anthropic
Model: claude-sonnet-4-5
Base URL: https://token.firstpy.com

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

可选：全局配置文件Copy Anchor Link

OpenCode 支持通过 JSON 配置文件进行高级设置，配置文件的加载优先级为：命令行参数 > 环境变量 > 项目级 JSON > 用户级 JSON > 默认配置。

示例 opencode.json 配置：

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

配置文件中可以设置默认模型、提供商 API 密钥、界面主题等。

常见问题Copy Anchor Link

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

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

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

Q：OpenCode 启动后无法连接提供商？

1. 检查 API 密钥是否正确。
2. 运行 /connect 重新配置连接。
3. 检查网络连接，确认是否能访问提供商的 API 地址。

Q：如何指定要使用的模型？
在交互界面中输入 /models，从列表中选择要使用的模型。你也可以在配置文件中设置 model 字段来指定默认模型，格式为 provider_id/model_id（例如 anthropic/claude-sonnet-4-5）。

Q：OpenCode 启动后界面空白或卡住？
按 Ctrl+L 强制刷新屏幕，或检查终端兼容性。官方推荐使用 WezTerm、Alacritty、Windows Terminal 等现代终端模拟器。

Q：如何更新 OpenCode？

npm install -g opencode-ai@latest

Q：Windows 上使用有问题怎么办？
Windows 用户建议使用 WSL 以获得最佳体验。如果使用原生 Windows，确保使用 Windows Terminal 而不是 Command Prompt。

如需更多帮助，可以访问 OpenCode 官方文档 或加入 Discord 社区。