> ## Documentation Index
> Fetch the complete documentation index at: https://api.xcompute.us/llms.txt
> Use this file to discover all available pages before exploring further.

# OpenCode 安装与配置教程

> 在 Windows、macOS、Linux 上安装 Node.js 和 OpenCode，并配置 Xcompute 模型。

这篇教程使用同一套流程完成 OpenCode 安装和 Xcompute 配置：

1. 安装 Node.js 24。
2. 使用 npm 安装 OpenCode CLI。
3. 修改 `.config/opencode/opencode.json`。
4. 启动 OpenCode 并切换模型。

<Info>
  如果你不熟悉下载安装包、PowerShell、终端、命令或配置文件，请先阅读 [电脑基础使用扫盲](/computer-basics)，再回来继续操作。
</Info>

<Note>
  教程中的命令都需要粘贴到“命令行窗口”中，再按 Enter 执行。Windows 使用 PowerShell，macOS 使用“终端”，Linux 使用 Terminal。下面每一步都会告诉你如何打开。
</Note>

<Tip>
  **推荐方案：Node.js 24 安装包 + npm**

  Windows 直接安装 MSI，macOS 直接安装 PKG，操作比先安装 NVM 更简单。Node.js 环境准备好以后，Windows、macOS 和 Linux 都使用同一条 npm 命令安装 OpenCode。
</Tip>

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

本文提供 Node.js 24.18.0 安装包直链，无需进入带广告的下载页面。Windows 和 macOS 用户直接下载安装包即可。

<Tabs>
  <Tab title="Windows">
    1. 点击 [下载 Node.js 24 Windows 64 位安装包](https://npmmirror.com/mirrors/node/v24.18.0/node-v24.18.0-x64.msi)。
    2. 等待浏览器下载 `node-v24.18.0-x64.msi`。
    3. 双击 MSI 文件，按照默认选项完成安装。
    4. 点击 Windows 左下角的 **开始菜单**，输入 `PowerShell`。
    5. 点击搜索结果中的 **Windows PowerShell**。如果后续提示权限不足，请右键选择 **以管理员身份运行**，再点击 **是**。

    在打开的蓝色或黑色窗口中依次输入下面两条命令，每输入一条都按一次 Enter：

    ```powershell theme={null}
    node -v
    npm -v
    ```

    绝大多数 Windows 电脑都应选择 64 位安装包。只有明确知道自己的系统是 32 位时，才使用下方的 32 位安装包。
  </Tab>

  <Tab title="macOS">
    1. 点击 [下载 Node.js 24 macOS 安装包](https://npmmirror.com/mirrors/node/v24.18.0/node-v24.18.0.pkg)。
    2. 等待浏览器下载 `node-v24.18.0.pkg`。
    3. 双击 PKG 文件，按照提示完成安装。
    4. 按 `Command + 空格键` 打开聚焦搜索，输入“终端”或 `Terminal`，再按 Enter 打开。

    在终端窗口中依次输入下面两条命令，每输入一条都按一次 Enter：

    ```bash theme={null}
    node -v
    npm -v
    ```

    该 PKG 安装包支持 64 位 Intel 和 Apple Silicon Mac。
  </Tab>

  <Tab title="Linux">
    按 `Ctrl + Alt + T` 打开终端。部分桌面系统也可以在应用列表中搜索 `Terminal` 或“终端”。

    Debian 和 Ubuntu 在终端中依次执行：

    ```bash theme={null}
    curl -fsSL https://deb.nodesource.com/setup_24.x | sudo -E bash -
    sudo apt install -y nodejs
    ```

    Fedora、RHEL 及其衍生发行版在终端中依次执行：

    ```bash theme={null}
    curl -fsSL https://rpm.nodesource.com/setup_24.x | sudo bash -
    sudo dnf install -y nodejs
    ```

    然后验证安装：

    ```bash theme={null}
    node -v
    npm -v
    ```
  </Tab>
</Tabs>

<Info>
  安装完成后，`node -v` 应显示 `v24.x.x`。OpenCode 也兼容 Node.js 22 或更高版本。
</Info>

<Accordion title="其他架构和压缩包下载">
  新手优先使用上面的 64 位 MSI 或 PKG。只有系统架构不同时，才选择以下文件：

  | 系统                 | 安装包                                                                                 |
  | ------------------ | ----------------------------------------------------------------------------------- |
  | Windows 32 位 MSI   | [下载](https://npmmirror.com/mirrors/node/v24.18.0/node-v24.18.0-x86.msi)             |
  | Windows 32 位 ZIP   | [下载](https://npmmirror.com/mirrors/node/v24.18.0/node-v24.18.0-win-x86.zip)         |
  | Windows 64 位 ZIP   | [下载](https://npmmirror.com/mirrors/node/v24.18.0/node-v24.18.0-win-x64.zip)         |
  | macOS Intel TAR.GZ | [下载](https://npmmirror.com/mirrors/node/v24.18.0/node-v24.18.0-darwin-x64.tar.gz)   |
  | macOS ARM64 TAR.GZ | [下载](https://npmmirror.com/mirrors/node/v24.18.0/node-v24.18.0-darwin-arm64.tar.gz) |
  | Linux x64 TAR.XZ   | [下载](https://npmmirror.com/mirrors/node/v24.18.0/node-v24.18.0-linux-x64.tar.xz)    |
  | Linux ARMv7 TAR.XZ | [下载](https://npmmirror.com/mirrors/node/v24.18.0/node-v24.18.0-linux-armv7l.tar.xz) |
  | Linux ARM64 TAR.XZ | [下载](https://npmmirror.com/mirrors/node/v24.18.0/node-v24.18.0-linux-arm64.tar.xz)  |

  [查看 Node.js 24.18.0 全部安装包](https://npmmirror.com/mirrors/node/v24.18.0/)
</Accordion>

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

需要同时管理多个 Node.js 版本，或者官网安装包无法正常使用时，再选择 NVM。完整步骤请查看 [NVM、Node.js 22 和 npm 环境准备](/node-setup)。

<Tabs>
  <Tab title="Windows">
    点击 **开始菜单**，输入 `PowerShell`，右键点击 **Windows PowerShell**，选择 **以管理员身份运行**，再点击 **是**。然后执行：

    ```powershell theme={null}
    winget install CoreyButler.NVMforWindows
    ```

    关闭并重新打开管理员 PowerShell，然后执行：

    ```powershell theme={null}
    nvm install 24
    nvm use 24
    ```
  </Tab>

  <Tab title="macOS / Linux">
    ```bash theme={null}
    curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.3/install.sh | bash
    ```

    重新打开终端，然后执行：

    ```bash theme={null}
    nvm install 24
    nvm use 24
    nvm alias default 24
    ```
  </Tab>
</Tabs>

## 第二步：统一安装 OpenCode CLI

完成 Node.js 安装后，在刚才打开的 PowerShell 或终端中依次执行下面的命令。可以整段复制粘贴，也可以一行一行执行：

```bash theme={null}
node -v
npm -v
npm install -g opencode-ai
opencode --version
```

你应该看到：

* `node -v` 输出 `v24.x.x`。
* `npm -v` 输出 npm 版本号。
* `opencode --version` 输出 OpenCode 版本号。

<Info>
  Windows PowerShell 通常可以直接按 `Ctrl+V` 粘贴，macOS 终端使用 `Command+V`，Linux 终端通常使用 `Ctrl+Shift+V`。粘贴后按 Enter 开始执行。
</Info>

### 可选：使用官方 curl 脚本

macOS、Linux 和 WSL 也可以跳过 Node.js 环境，直接执行：

```bash theme={null}
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` |

<Tabs>
  <Tab title="macOS / Linux">
    打开终端，复制下面两行并按 Enter。第一行创建配置目录，第二行用 nano 编辑器打开配置文件：

    ```bash theme={null}
    mkdir -p ~/.config/opencode
    nano ~/.config/opencode/opencode.json
    ```

    使用 nano 时，按 `Ctrl+O` 保存，按 Enter 确认，再按 `Ctrl+X` 退出。
  </Tab>

  <Tab title="Windows">
    点击 **开始菜单**，输入 `PowerShell` 并打开 **Windows PowerShell**。复制下面两行并按 Enter，系统会自动创建目录并用记事本打开配置文件：

    ```powershell theme={null}
    New-Item -ItemType Directory -Force "$HOME\.config\opencode"
    notepad "$HOME\.config\opencode\opencode.json"
    ```

    记事本询问是否创建文件时选择 **是**。粘贴配置后按 `Ctrl+S` 保存。如果出现“另存为”窗口，将 **保存类型** 改为 **所有文件**，并确保文件名是 `opencode.json`，而不是 `opencode.json.txt`。
  </Tab>
</Tabs>

## 第四步：写入 Xcompute 配置

将下面的完整内容粘贴到 `opencode.json`，再把 `在这里填写你的APIKey` 替换为你在 [Xcompute 控制台](https://xcompute.us/keys) 创建的 API Key。

```json theme={null}
{
  "$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"
}
```

<Info>
  默认推荐使用 `https://intl.dualseason.com/v1`。如果你具备稳定的科学上网能力，也可以将 `baseURL` 改为 `https://xcompute.us/v1`。两个地址都必须保留末尾的 `/v1`。
</Info>

<Warning>
  配置文件包含 API Key，请勿上传到 GitHub、发送给他人或放入项目目录。全局配置文件只应保存在你自己的电脑中。
</Warning>

### 配置项说明

| 配置项                 | 作用                                                                          |
| ------------------- | --------------------------------------------------------------------------- |
| `provider.xcompute` | 创建名为 Xcompute 的模型提供商                                                        |
| `npm`               | 使用 OpenAI 兼容协议适配器                                                           |
| `baseURL`           | 默认使用 `https://intl.dualseason.com/v1`；具备科学上网能力时可使用 `https://xcompute.us/v1` |
| `apiKey`            | 你的 Xcompute API Key                                                         |
| `models`            | 在 OpenCode 中可选择的模型列表                                                        |
| `model`             | OpenCode 启动时默认使用的模型                                                         |

模型 ID 必须与 Xcompute 支持的模型名称完全一致。需要添加其他模型时，在 `models` 中按照相同格式增加条目，并前往 [模型定价](https://xcompute.us/pricing) 查看当前可用的模型 ID。

例如，新增一个模型：

```json theme={null}
"模型ID": {
  "name": "显示名称"
}
```

添加多个模型时，注意使用英文逗号分隔。JSON 最后一项后面不能保留逗号。

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

如果不希望把 API Key 直接写入配置文件，可以把 `apiKey` 改为：

```json theme={null}
"apiKey": "{env:XCOMPUTE_API_KEY}"
```

然后设置环境变量：

<Tabs>
  <Tab title="macOS / Linux">
    ```bash theme={null}
    echo 'export XCOMPUTE_API_KEY="你的APIKey"' >> ~/.bashrc
    source ~/.bashrc
    ```

    macOS 默认使用 zsh 时，请将文件名改为 `~/.zshrc`。
  </Tab>

  <Tab title="Windows">
    ```powershell theme={null}
    setx XCOMPUTE_API_KEY "你的APIKey"
    ```

    设置后需要关闭并重新打开 OpenCode 和终端。
  </Tab>
</Tabs>

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

进入你的项目目录并启动 OpenCode：

```bash theme={null}
cd /path/to/your-project
opencode
```

进入 OpenCode 后：

1. 输入 `/models`，确认能看到 Xcompute 下配置的模型。
2. 选择需要使用的模型。
3. 输入 `/init`，让 OpenCode 分析项目并生成 `AGENTS.md`。
4. 输入一个简单任务，例如“读取项目结构并告诉我如何启动”。

<Tip>
  修改 `opencode.json` 后，请退出并重新打开 CLI 或桌面端，使新配置生效。
</Tip>

## 桌面端安装

桌面端是可选项。它与 CLI 共用刚才创建的 `opencode.json`，无需重复配置模型。

建议通过 [OpenCode 官方下载页面](https://opencode.ai/download) 获取最新版本。

| 系统                   | 最新安装包                                                            |
| -------------------- | ---------------------------------------------------------------- |
| macOS（Apple Silicon） | [下载 DMG](https://opencode.ai/download/stable/darwin-aarch64-dmg) |
| macOS（Intel）         | [下载 DMG](https://opencode.ai/download/stable/darwin-x64-dmg)     |
| Windows（x64）         | [下载安装程序](https://opencode.ai/download/stable/windows-x64-nsis)   |
| Debian / Ubuntu（x64） | [下载 DEB](https://opencode.ai/download/stable/linux-x64-deb)      |
| Fedora / RHEL（x64）   | [下载 RPM](https://opencode.ai/download/stable/linux-x64-rpm)      |

* macOS：打开 DMG，将 OpenCode 拖入 **Applications** 文件夹。
* Windows：双击安装程序，并按照界面提示完成安装。
* Linux：双击 DEB 或 RPM 安装包，使用系统软件中心安装。

安装后启动桌面端并打开项目。如果模型列表没有立即更新，请完全退出桌面端后重新打开。

## 更新 OpenCode

三个平台都使用同一条 npm 命令更新 CLI：

```bash theme={null}
npm update -g opencode-ai
opencode --version
```

桌面端请访问 [官方下载页面](https://opencode.ai/download) 获取最新安装包。

## 常见问题

### `opencode` 命令不存在

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

```bash theme={null}
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 密钥页面](https://xcompute.us/keys) 确认 Key 可用，并检查复制时是否带入了空格。不要在 API Key 前后添加额外引号或中文符号。

## 官方资源

* [OpenCode 官网](https://opencode.ai)
* [OpenCode 官方文档](https://opencode.ai/docs/)
* [OpenCode 下载页面](https://opencode.ai/download)
* [Xcompute OpenCode 完整接入教程](/opencode)