第 1 步：装 Node.js

OpenCode 是 Node.js 应用，需要 Node 18 或以上。团队提供的是免安装的 zip 包 node-v24.15.0-win-x64.zip——解压 + 配 PATH 就能用，不需要管理员权限。

2.1 下载并解压

下载安装包：node-v24.15.0-win-x64.zip（约 35 MB）。

下载完右键 → 解压。把解压出来的整个 node-v24.15.0-win-x64 文件夹移动到一个固定位置，推荐：

C:\nodejs\

移动后这个目录里应该能看到 node.exe、npm.cmd、npx.cmd 等文件——这就是装好了。

2.2 把 Node 加进 PATH

这一步告诉 Windows 在哪能找到 node 和 npm 命令。

1. 按 Win → 搜"环境变量" → 点"编辑账户的环境变量"（不需要管理员权限）
2. 在上面的"用户变量"里找到 Path，双击
3. 点"新建"，输入 C:\nodejs（注意：是文件夹路径，不是 node.exe 的路径）
4. 一路"确定"关闭所有窗口

或者用 PowerShell 一行命令搞定（更快）：

[Environment]::SetEnvironmentVariable(
  "Path",
  [Environment]::GetEnvironmentVariable("Path", "User") + ";C:\nodejs",
  "User"
)

2.3 验证版本

关掉所有 PowerShell 窗口（PATH 改了之后必须重开新窗口才生效），重新打开一个，运行：

node --version
npm --version

能看到 v24.15.0 和对应的 npm 版本号就 OK 了。

如果命令找不到：

• 确认 PowerShell 是改完 PATH 之后才开的——旧窗口不会刷新
• 运行 $env:Path -split ';' 看输出列表里有没有 C:\nodejs
• 确认 C:\nodejs\node.exe 文件确实存在——可能解压时多套了一层目录，导致实际路径是 C:\nodejs\node-v24.15.0-win-x64\node.exe，把里层文件夹的内容上移一层即可

第 2 步：装 OpenCode

3.1 全局安装

PowerShell 里运行：

npm install -g opencode-ai

等它跑完，最后一行没报红色 ERR 就成。

3.2 验证

opencode --version

能输出版本号说明装好了。如果提示 opencode 不是内部或外部命令：

• 新开一个 PowerShell（旧窗口的 PATH 没刷新）
• 检查 npm config get prefix 输出的目录是否在 PATH 里（一般是 %APPDATA%\npm）

3.3 升级与卸载

# 升级
npm update -g opencode-ai

# 卸载
npm uninstall -g opencode-ai

3.4 可选路径：桌面版（Beta）

适合谁

• 非工程师同事——产品 / 设计 / 运营想试试 OpenCode，对终端不熟、不想装 Node.js
• 快速体验——只是想看看长什么样，不打算深度配置 skill 体系

需要走完整工程流程（skill、AGENTS.md、自动化）的话，仍然走前面的 npm 路径——本文档其余章节也都按 CLI 版来写。

怎么装

1. 下载安装包：OpenCode Desktop Installer.exe（约 113 MB）
2. 双击 .exe 文件，跟着向导一路 Next 装完——首次运行 Windows SmartScreen 可能拦截，点"更多信息"→"仍要运行"
3. 在开始菜单 / 桌面找到 OpenCode 图标，双击启动——出来的是 GUI 窗口而不是 TUI 终端

装完之后

桌面版的配置文件路径跟 CLI 版一致（%USERPROFILE%\.config\opencode\opencode.json），所以第 4 章的 sub2api provider 配置直接复用。验证步骤参考第 5 章——只是界面变成了 GUI，/model、/init 这些命令通过菜单或输入框触发。

第 3 步：配置内网 Provider

公司要求所有模型调用必须走内网代理服务，不能直接连 Anthropic / OpenAI 公网 API。这一步配置完，OpenCode 就会把所有请求转到内网网关。

4.1 创建配置文件

OpenCode 在 Windows 上读取的全局配置路径是：

%USERPROFILE%\.config\opencode\opencode.json

等价于：C:\Users\<你的用户名>\.config\opencode\opencode.json。

用 PowerShell 一键创建目录并打开：

New-Item -ItemType Directory -Force "$env:USERPROFILE\.config\opencode" | Out-Null
notepad "$env:USERPROFILE\.config\opencode\opencode.json"

Notepad 提示文件不存在时点"是"创建。

4.2 粘贴配置内容

把下面的 JSON 完整粘贴进去，把 apiKey 替换成你自己在 sub2api 控制台创建的真实 key：

{
  "$schema": "https://opencode.ai/config.json",
  "provider": {
    "sub2api": {
      "npm": "@ai-sdk/anthropic",
      "options": {
        "baseURL": "http://172.168.128.172:8080/v1",
        "apiKey": "sk-XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"
      },
      "models": {
        "kimi-for-coding": {
          "name": "K2.6"
        }
      }
    }
  }
}

保存关闭。

4.3 配置项逐字段说明

4.4 项目级覆盖（可选）

如果某个项目要用不同的模型 / 配置，在项目根目录放一份 opencode.json，OpenCode 会优先读项目级、再 fallback 到全局级。常见场景：

• 沙箱项目开 YOLO 模式，主仓保留确认模式
• 临时项目用更便宜的模型
• 客户演示项目用单独的 key 计费

项目级配置示例（只覆盖需要的字段）：

{
  "$schema": "https://opencode.ai/config.json",
  "permission": "allow"
}

第 4 步：启动并验证

5.1 启动

找个空目录（避免在重要项目上做第一次测试），打开 PowerShell：

mkdir hello-opencode
cd hello-opencode
opencode

第一次启动会进入 TUI 主界面。

5.2 确认模型已加载

进入 OpenCode 后输入：

/model

能在列表里看到 K2.6（你在 opencode.json 里给它起的友好名）就说明 provider 配置生效了。选中它。

如果看不到 K2.6 / 报错"无可用模型"——参考第 6 章的排查清单。

5.3 跑一个 hello world 任务

在输入框敲：

创建一个 README.md，写一段简短的项目介绍，主题随便编。

预期看到：

1. 它先输出一段 plan / 复述需求
2. 调用 write 工具写文件——会停下来让你确认
3. 确认后写入 README.md
4. 报告完成

看到这一连串就说明从安装到模型到工具调用整条链路都通了。退出：/exit。

常见问题排查

6.1 opencode 命令找不到

• 装完后没重开终端——关掉 PowerShell 重新打开
• npm config get prefix 输出的目录不在 PATH 里——把它加进系统环境变量 PATH
• npm 全局安装失败——回看 3.1 的输出，是否有红色 ERR

6.2 /model 看不到 K2.6

• 配置文件路径错了：必须是 %USERPROFILE%\.config\opencode\opencode.json，不是 %APPDATA%\opencode\ 也不是 %USERPROFILE%\.opencode\
• JSON 格式错了：粘贴时多了/少了逗号、引号不配对。把内容贴到 jsonlint.com 验一下
• Notepad 把文件存成了 .json.txt：打开"显示文件扩展名"检查，文件名必须是 opencode.json
• 权限问题：用 type "$env:USERPROFILE\.config\opencode\opencode.json" 看 PowerShell 能不能读到

6.3 网络报错 / 连接超时

• 不在公司网络：内网地址 172.168.128.172 必须在公司内网或 VPN 下才能访问。先 ping 172.168.128.172 看通不通
• VPN 没连上：连上 VPN 再启动 OpenCode
• 代理服务挂了：找 IT 确认 http://172.168.128.172:8080 服务状态

6.4 401 / 403 鉴权失败

• API Key 错了：复制时漏了字符，或者引号粘到了 key 里。回 sub2api 控制台重新复制
• Key 已过期 / 被撤销：回 sub2api 控制台重新创建一个
• Key 用错了环境：sub2api 控制台如果区分了 dev / prod，确认你创建的是当前要连的那套环境

6.5 终端字符乱码 / 渲染错位

原生 cmd / 老 PowerShell 控制台对 TUI 支持不全。换成 Windows Terminal（Microsoft Store 免费）：

winget install Microsoft.WindowsTerminal

6.6 /bin/sh.exe 找不到

npm 在 Windows 上的已知问题。解法：装 Git for Windows（git-scm.com），它自带 sh.exe 并能被 OpenCode 找到。

6.7 还卡住？

找团队 OpenCode 群求助时，附上：

• opencode --version 输出
• node --version 输出
• 报错截图（含完整错误信息）
• 你的 opencode.json去掉 apiKey 后的内容

这 4 项齐全的话定位会很快。

命令速查

安装相关

# 装 Node.js
# → 解压团队提供的 node-v24.15.0-win-x64.zip 到 C:\nodejs\
# → 把 C:\nodejs 加进用户 PATH，重开 PowerShell

# 装 OpenCode
npm install -g opencode-ai

# 升级 OpenCode
npm update -g opencode-ai

# 卸载 OpenCode
npm uninstall -g opencode-ai

# 验证
node --version
opencode --version

关键路径

OpenCode 内置命令

最小可用配置（脱敏版）

{
  "$schema": "https://opencode.ai/config.json",
  "provider": {
    "sub2api": {
      "npm": "@ai-sdk/anthropic",
      "options": {
        "baseURL": "http://172.168.128.172:8080/v1",
        "apiKey": "sk-XXXX...XXXX"
      },
      "models": {
        "kimi-for-coding": {
          "name": "K2.6"
        }
      }
    }
  }
}

※ apiKey 字段在本指南中已脱敏处理，使用时请去 sub2api 控制台自助创建真实 key 并替换。