OpenCode 代码任务安装与配置

OpenCode 用于修改网站、程序和项目文件。写邮件、整理资料等日常工作请使用 WorkBuddy。

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

安装 Node.js 24。
使用 npm 安装 OpenCode CLI。
修改 .config/opencode/opencode.json。
打开项目文件夹并开始代码任务。

如果你不熟悉下载安装包、PowerShell、终端、命令或配置文件，请先阅读电脑基础操作，再回来继续操作。

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

推荐方案：Node.js 24 安装包 + npm

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

第一步：直接安装 Node.js

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

点击下载 Node.js 24 Windows 64 位安装包。
等待浏览器下载 node-v24.18.0-x64.msi。
双击 MSI 文件，按照默认选项完成安装。
点击 Windows 左下角的 开始菜单，输入 PowerShell。
点击搜索结果中的 Windows PowerShell。如果后续提示权限不足，请右键选择 以管理员身份运行，再点击是。

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

12node -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。

点击 开始菜单，输入 PowerShell，右键点击 Windows PowerShell，选择 以管理员身份运行，再点击是。然后执行：

1winget install CoreyButler.NVMforWindows

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

12nvm install 24
nvm use 24

第二步：统一安装 OpenCode CLI

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

1234node -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 环境，直接执行：

1curl -fsSL https://opencode.ai/install | bash

原生 Windows 无法直接使用这条 Bash 命令，所以需要三平台统一操作时，仍然推荐 npm 方案。

第三步：创建配置文件

CLI 和桌面端共用同一个全局配置文件。配置一次后，两边都可以使用 TokenFlash 模型。

点击 开始菜单，输入 PowerShell 并打开 Windows PowerShell。

复制下面两行并按 Enter，系统会自动创建目录并用记事本打开配置文件：

12New-Item -ItemType Directory -Force "$HOME\.config\opencode"
notepad "$HOME\.config\opencode\opencode.json"

记事本询问是否创建文件时选择是。粘贴配置后按 Ctrl+S 保存。

如果出现“另存为”窗口，将 保存类型 改为 所有文件，并确保文件名是 opencode.json，而不是 opencode.json.txt。

第四步：写入 TokenFlash 配置

打开 TokenFlash API Key 页面，创建 API Key 后点击 使用令牌。

选择 OpenCode 客户端并复制配置。请仍以本页的完整 JSON 为准，避免漏掉必要字段。

把 在这里填写你的APIKey 替换为你的 TokenFlash API Key，然后将下面内容完整粘贴到 opencode.json：

12345678910111213141516171819{
  "$schema": "https://opencode.ai/config.json",
  "provider": {
    "tokenflash": {
      "npm": "@ai-sdk/openai-compatible",
      "name": "TokenFlash",
      "options": {
        "baseURL": "https://intl.dualseason.com/v1",
        "apiKey": "在这里填写你的APIKey"
      },
      "models": {
        "gpt-5.6-sol": {
          "name": "GPT-5.6-Sol"
        }
      }
    }
  },
  "model": "tokenflash/gpt-5.6-sol"
}

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

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

配置项说明

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

模型 ID 必须与 TokenFlash 支持的模型名称完全一致。需要更换文本模型时，在 models 中按照相同格式增加条目，并前往模型广场查看当前可用的模型 ID。

例如，新增一个模型：

123"模型ID": {
  "name": "显示名称"
}

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

第五步：启动并切换模型

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

12cd /path/to/your-project
opencode

进入 OpenCode 后：

输入 /models，确认能看到 TokenFlash 下配置的文本模型。
输入 /init，让 OpenCode 分析项目并生成 AGENTS.md。
输入“读取项目结构并告诉我如何启动，不要修改文件”。
确认理解无误后，再让它修改代码。

修改 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 安装包，使用系统软件中心安装。

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

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

如果你不想编辑 JSON，也可以在桌面端的提供商设置中选择 Custom Provider。

按下表填写。Base URL 必须保留末尾的 /v1。

字段	值
Provider ID	`tokenflash`
Display Name	`TokenFlash`
Base URL	`https://intl.dualseason.com/v1`
API Key	你的 TokenFlash API Key
Model ID	`gpt-5.6-sol`

添加后，在提供商设置中确认 API Key 和模型，然后选择需要使用的模型。

更新 OpenCode

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

12npm update -g opencode-ai
opencode --version

桌面端请访问官方下载页面获取最新安装包。

常见问题

`opencode` 命令不存在

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

1234node -v
npm -v
npm install -g opencode-ai
opencode --version

看不到 TokenFlash 模型

依次检查：

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

提示 API Key 无效

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