Skip to main content
这篇教程使用同一套流程完成 OpenCode 安装和 Xcompute 配置：
  1. 安装 Node.js 24。
  2. 使用 npm 安装 OpenCode CLI。
  3. 修改 .config/opencode/opencode.json。
  4. 启动 OpenCode 并切换模型。
如果你不熟悉下载安装包、PowerShell、终端、命令或配置文件，请先阅读 电脑基础使用扫盲，再回来继续操作。
教程中的命令都需要粘贴到“命令行窗口”中，再按 Enter 执行。Windows 使用 PowerShell，macOS 使用“终端”，Linux 使用 Terminal。下面每一步都会告诉你如何打开。
推荐方案：Node.js 24 安装包 + npmWindows 直接安装 MSI，macOS 直接安装 PKG，操作比先安装 NVM 更简单。Node.js 环境准备好以后，Windows、macOS 和 Linux 都使用同一条 npm 命令安装 OpenCode。

​
第一步：直接安装 Node.js

本文提供 Node.js 24.18.0 安装包直链，无需进入带广告的下载页面。Windows 和 macOS 用户直接下载安装包即可。
  1. 点击 下载 Node.js 24 Windows 64 位安装包。
  2. 等待浏览器下载 node-v24.18.0-x64.msi。
  3. 双击 MSI 文件，按照默认选项完成安装。
  4. 点击 Windows 左下角的 开始菜单，输入 PowerShell。
  5. 点击搜索结果中的 Windows PowerShell。如果后续提示权限不足，请右键选择 以管理员身份运行，再点击 是。
在打开的蓝色或黑色窗口中依次输入下面两条命令，每输入一条都按一次 Enter：
node -v
npm -v
绝大多数 Windows 电脑都应选择 64 位安装包。只有明确知道自己的系统是 32 位时，才使用下方的 32 位安装包。
安装完成后，node -v 应显示 v24.x.x。OpenCode 也兼容 Node.js 22 或更高版本。
新手优先使用上面的 64 位 MSI 或 PKG。只有系统架构不同时，才选择以下文件：
系统安装包
Windows 32 位 MSI下载
Windows 32 位 ZIP下载
Windows 64 位 ZIP下载
macOS Intel TAR.GZ下载
macOS ARM64 TAR.GZ下载
Linux x64 TAR.XZ下载
Linux ARMv7 TAR.XZ下载
Linux ARM64 TAR.XZ下载
查看 Node.js 24.18.0 全部安装包

​
备用方案：使用 NVM 安装 Node.js 24

需要同时管理多个 Node.js 版本，或者官网安装包无法正常使用时，再选择 NVM。完整步骤请查看 NVM、Node.js 22 和 npm 环境准备。
点击 开始菜单，输入 PowerShell，右键点击 Windows PowerShell，选择 以管理员身份运行，再点击 是。然后执行：
winget install CoreyButler.NVMforWindows
关闭并重新打开管理员 PowerShell，然后执行：
nvm install 24
nvm use 24

​
第二步：统一安装 OpenCode CLI

完成 Node.js 安装后，在刚才打开的 PowerShell 或终端中依次执行下面的命令。可以整段复制粘贴，也可以一行一行执行： 
node -v
npm -v
npm install -g opencode-ai
opencode --version
你应该看到：
  • node -v 输出 v24.x.x。
  • npm -v 输出 npm 版本号。
  • opencode --version 输出 OpenCode 版本号。
Windows PowerShell 通常可以直接按 Ctrl+V 粘贴，macOS 终端使用 Command+V，Linux 终端通常使用 Ctrl+Shift+V。粘贴后按 Enter 开始执行。

​
可选：使用官方 curl 脚本

macOS、Linux 和 WSL 也可以跳过 Node.js 环境，直接执行： 
curl -fsSL https://opencode.ai/install | bash
原生 Windows 无法直接使用这条 Bash 命令，所以需要三平台统一操作时，仍然推荐 npm 方案。

​
第三步：创建配置文件

CLI 和桌面端共用同一个全局配置文件。配置一次后，两边都可以使用 Xcompute 模型。
系统配置文件路径
macOS~/.config/opencode/opencode.json
Linux~/.config/opencode/opencode.json
Windows%USERPROFILE%\.config\opencode\opencode.json
打开终端，复制下面两行并按 Enter。第一行创建配置目录，第二行用 nano 编辑器打开配置文件：
mkdir -p ~/.config/opencode
nano ~/.config/opencode/opencode.json
使用 nano 时，按 Ctrl+O 保存，按 Enter 确认，再按 Ctrl+X 退出。

​
第四步：写入 Xcompute 配置

将下面的完整内容粘贴到 opencode.json，再把 在这里填写你的APIKey 替换为你在 Xcompute 控制台 创建的 API Key。 
{
  "$schema": "https://opencode.ai/config.json",
  "provider": {
    "xcompute": {
      "npm": "@ai-sdk/openai-compatible",
      "name": "Xcompute",
      "options": {
        "baseURL": "https://intl.dualseason.com/v1",
        "apiKey": "在这里填写你的APIKey"
      },
      "models": {
        "gpt-5.6-sol": {
          "name": "GPT 5.6 Sol"
        },
        "claude-sonnet-5": {
          "name": "Claude Sonnet 5"
        },
        "gemini-3.5-flash": {
          "name": "Gemini 3.5 Flash"
        }
      }
    }
  },
  "model": "xcompute/gpt-5.6-sol"
}
默认推荐使用 https://intl.dualseason.com/v1。如果你具备稳定的科学上网能力，也可以将 baseURL 改为 https://xcompute.us/v1。两个地址都必须保留末尾的 /v1。
配置文件包含 API Key，请勿上传到 GitHub、发送给他人或放入项目目录。全局配置文件只应保存在你自己的电脑中。

​
配置项说明

配置项作用
provider.xcompute创建名为 Xcompute 的模型提供商
npm使用 OpenAI 兼容协议适配器
baseURL默认使用 https://intl.dualseason.com/v1；具备科学上网能力时可使用 https://xcompute.us/v1
apiKey你的 Xcompute API Key
models在 OpenCode 中可选择的模型列表
modelOpenCode 启动时默认使用的模型
模型 ID 必须与 Xcompute 支持的模型名称完全一致。需要添加其他模型时，在 models 中按照相同格式增加条目，并前往 模型定价 查看当前可用的模型 ID。 例如，新增一个模型： 
"模型ID": {
  "name": "显示名称"
}
添加多个模型时，注意使用英文逗号分隔。JSON 最后一项后面不能保留逗号。

​
可选：使用环境变量保存 API Key

如果不希望把 API Key 直接写入配置文件，可以把 apiKey 改为： 
"apiKey": "{env:XCOMPUTE_API_KEY}"
然后设置环境变量： 
echo 'export XCOMPUTE_API_KEY="你的APIKey"' >> ~/.bashrc
source ~/.bashrc
macOS 默认使用 zsh 时，请将文件名改为 ~/.zshrc。

​
第五步：启动并切换模型

进入你的项目目录并启动 OpenCode： 
cd /path/to/your-project
opencode
进入 OpenCode 后：
  1. 输入 /models，确认能看到 Xcompute 下配置的模型。
  2. 选择需要使用的模型。
  3. 输入 /init，让 OpenCode 分析项目并生成 AGENTS.md。
  4. 输入一个简单任务，例如“读取项目结构并告诉我如何启动”。
修改 opencode.json 后，请退出并重新打开 CLI 或桌面端，使新配置生效。

​
桌面端安装

桌面端是可选项。它与 CLI 共用刚才创建的 opencode.json，无需重复配置模型。 建议通过 OpenCode 官方下载页面 获取最新版本。
系统最新安装包
macOS（Apple Silicon）下载 DMG
macOS（Intel）下载 DMG
Windows（x64）下载安装程序
Debian / Ubuntu（x64）下载 DEB
Fedora / RHEL（x64）下载 RPM
  • macOS：打开 DMG，将 OpenCode 拖入 Applications 文件夹。
  • Windows：双击安装程序，并按照界面提示完成安装。
  • Linux：双击 DEB 或 RPM 安装包，使用系统软件中心安装。
安装后启动桌面端并打开项目。如果模型列表没有立即更新，请完全退出桌面端后重新打开。

​
更新 OpenCode

三个平台都使用同一条 npm 命令更新 CLI： 
npm update -g opencode-ai
opencode --version
桌面端请访问 官方下载页面 获取最新安装包。

​
常见问题

​
opencode 命令不存在

关闭并重新打开终端，然后依次执行： 
node -v
npm -v
npm install -g opencode-ai
opencode --version

​
看不到 Xcompute 模型

依次检查：
  1. 配置文件路径和文件名是否正确。
  2. Windows 文件名是否被保存成 opencode.json.txt。
  3. JSON 是否使用英文双引号，最后一项后面是否有多余逗号。
  4. baseURL 是否为默认的 https://intl.dualseason.com/v1，或可科学上网时使用的 https://xcompute.us/v1。
  5. 修改后是否完全重启 OpenCode。

​
提示 API Key 无效

前往 API 密钥页面 确认 Key 可用，并检查复制时是否带入了空格。不要在 API Key 前后添加额外引号或中文符号。

​
官方资源