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。如果后续提示权限不足，请右键选择 以管理员身份运行，再点击 是。
Windows 开始菜单中打开 Windows PowerShell
在打开的蓝色或黑色窗口中依次输入下面两条命令，每输入一条都按一次 Enter：
绝大多数 Windows 电脑都应选择 64 位安装包。只有明确知道自己的系统是 32 位时，才使用下方的 32 位安装包。
安装完成后，node -v 应显示 v24.x.x。OpenCode 也兼容 Node.js 22 或更高版本。
新手优先使用上面的 64 位 MSI 或 PKG。只有系统架构不同时，才选择以下文件：查看 Node.js 24.18.0 全部安装包

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

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

​
第二步：统一安装 OpenCode CLI

完成 Node.js 安装后，在刚才打开的 PowerShell 或终端中依次执行下面的命令。可以整段复制粘贴，也可以一行一行执行：
PowerShell 中安装 OpenCode 并显示版本号
你应该看到：
  • 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 环境，直接执行：
原生 Windows 无法直接使用这条 Bash 命令，所以需要三平台统一操作时，仍然推荐 npm 方案。

​
第三步：创建配置文件

CLI 和桌面端共用同一个全局配置文件。配置一次后，两边都可以使用 Xcompute 模型。
点击 开始菜单，输入 PowerShell 并打开 Windows PowerShell。复制下面两行并按 Enter，系统会自动创建目录并用记事本打开配置文件：
记事本询问是否创建文件时选择 是。粘贴配置后按 Ctrl+S 保存。如果出现“另存为”窗口，将 保存类型 改为 所有文件，并确保文件名是 opencode.json，而不是 opencode.json.txt。

​
第四步：写入 Xcompute 配置

打开 Xcompute API Key 页面，创建 API Key 后点击 使用令牌。
Xcompute API Key 页面中的使用令牌按钮
选择 OpenCode 客户端并复制配置。请仍以本页的完整 JSON 为准，避免漏掉必要字段。
Xcompute 使用令牌窗口中的 OpenCode 配置
把 在这里填写你的APIKey 替换为你的 Xcompute API Key，然后将下面内容完整粘贴到 opencode.json：
默认推荐使用 https://intl.dualseason.com/v1。如果你具备稳定的科学上网能力，也可以将 baseURL 改为 https://xcompute.us/v1。两个地址都必须保留末尾的 /v1。
配置文件包含 API Key，请勿上传到 GitHub、发送给他人或放入项目目录。全局配置文件只应保存在你自己的电脑中。

​
配置项说明

模型 ID 必须与 Xcompute 支持的模型名称完全一致。需要添加其他模型时，在 models 中按照相同格式增加条目，并前往 模型定价 查看当前可用的模型 ID。 例如，新增一个模型：
添加多个模型时，注意使用英文逗号分隔。JSON 最后一项后面不能保留逗号。

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

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

​
桌面端安装

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

​
可选：在桌面端手动添加提供商

如果你不想编辑 JSON，也可以在桌面端的提供商设置中选择 Custom Provider。
OpenCode 桌面端的自定义提供商表单
按下表填写。Base URL 必须保留末尾的 /v1。 添加后，在提供商设置中确认 API Key 和模型，然后选择需要使用的模型。
OpenCode 桌面端的提供商 API Key 和模型设置

​
更新 OpenCode

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

​
常见问题

​
opencode 命令不存在

关闭并重新打开终端，然后依次执行：

​
看不到 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 前后添加额外引号或中文符号。

​
官方资源