OpenCode 安装基础教程

OpenCode 是一款终端优先、开源免费、多模型兼容的 AI 编程助手（目前GitHub 143K+ star），支持终端 TUI、桌面 App、VS Code 插件三端协同，可一键切换 Claude/GPT/Gemini/ 本地模型，主打隐私安全、零代码上传、轻量高效，能大幅提升编程、调试、项目规划效率，适合所有阶段的开发者使用。

优先查看：官方文档

一、前置准备（必看）

Node.js 环境：仅 npm 安装方式需要，推荐 v20+。
API 密钥（可选）：使用第三方模型需要，新手可先用免费模型。
网络环境：使用海外模型需配置代理，国产免费模型可直连。
mise 环境（可选）：多项目、多 Node 版本管理必备。

二、Windows 安装方式

（一）桌面端安装（推荐新手）

打开官网：https://opencode.ai/zh/download
点击顶部 Download，下载 Windows 版 .exe 安装包。
双击运行安装包，一路默认 Next 即可。
安装完成后勾选 Launch OpenCode 启动软件。
验证：正常打开界面即安装成功。

（二）终端安装

方式 1：npm 全局安装

安装 Node.js 后，打开终端执行：
```
npm install -g opencode-ai@latest
```
验证：
```
opencode -v
```

注意：如果你用 mise 切换 Node 版本，这种安装方式会失效，建议使用下面的 mise 安装方式。

方式 2：Scoop 安装（Windows 包管理器）

scoop install opencode

方式 3：Chocolatey 安装

choco install opencode

🔥 方式 4：mise 全局安装（多 Node 版本必选）

如果你用 mise 管理多个 Node 版本，进入不同项目会自动切换 Node，必须用此方式安装，否则全局 npm 安装的 OpenCode 会无法启动。并且也要使用mise进行版本更新。mise教程

确保已安装 mise。

终端执行：

# 安装
mise use -g github:anomalyco/opencode
# 更新
mise upgrade -g github:anomalyco/opencode
# 从 mise 中卸载 opencode
mise uninstall -g opencode

重启终端或执行：
```
exec $SHELL
```
验证：
```
opencode -v
```

✅ 优点：

切换任何 Node 版本都不影响 opencode 使用
无需为每个项目重复安装
无依赖冲突、稳定不报错

三、首次配置

（一）使用免费模型（无需 API 密钥）

opencode默认有一些免费的模型可以使用。如图：

终端进入项目目录：
```
cd 你的项目路径
```
启动 OpenCode：
```
opencode
```
连接免费模型：
```
/connect zen
```

即可直接使用。

（二）第三方模型配置（可选）

/connect 可以连接一些常用的三方模型，配置对应的key即可。如图：

如果使用第三方模型供应商或者自定义的，则可以用如下方式添加供应商和模型。推荐使用 cc-switch 进行管理。

配置文件路径：

# 例如我的：C:\Users\hz\.config\opencode\opencode.json
 ~/.config/opencode/opencode.json

填入 API 信息后重载配置：

// 复制使用时需要删掉注释
{
  "$schema": "https://opencode.ai/config.json",
  // 添加多个供应商
  "provider": {
    // 第一个供应商
    "LXQ": { // 供应商唯一标识，自定义命名（需唯一）
      "npm": "@ai-sdk/openai-compatible", // 核心依赖包，兼容OpenAI协议接口
      "name": "LXQ", // 供应商显示名称，可自定义
      "options": {
        "baseURL": "http://192.168.18.157:20128/v1" // 供应商API接口地址
      },
      "models": { // 该供应商下可用的模型列表
        "alicode/qwen3.5-plus": {
          "name": "alicode/qwen3.5-plus"  // 模型显示名称，建议与模型ID一致
        },
        "alicode/kimi-k2.5": {
          "name": "alicode/kimi-k2.5"
        },
        "alicode/glm-5": {
          "name": "alicode/glm-5"
        },
        "alicode/MiniMax-M2.5": {
          "name": "alicode/MiniMax-M2.5"
        }
      }
    },
    // 添加的第二个供应商
    "claudeio-codex": {
      "npm": "@ai-sdk/openai-compatible",
      "name": "group-codex",
      "options": {
          # 使用 newapi 第三方中转的api
          "baseURL": "https://authentic.xxx.top/v1",
          "apiKey": "sk-3OBWy2J2cDeZsn2xxxxxOxxxxlSN70alpwAxlDjKKEQ",
          "headers": { // 可选：自定义请求头，部分供应商需额外配置
            "User-Agent": "Mozilla/5.0",
            "X-Client": "chat"
          }
        },
      "models": { // 该供应商下可用的模型列表
        "gpt-5.3-codex": {
          "name": "gpt-5.3-codex"
        },
        "gpt-5.4": {
          "name": "gpt-5.4"
        }
      }
    }
  }
}

四、基础使用

进入项目目录：cd 项目路径
启动：opencode
输入需求，AI 自动生成 / 修改代码

五、Windows 常见问题

1. 提示 `command not found`

重启终端
检查环境变量是否包含 npm 全局路径
改用 mise 安装方式

2. mise 切换 Node 后 opencode 不能用

卸载旧版：npm uninstall -g opencode-ai
重新用 mise 安装：
```
mise use -g github:anomalyco/opencode
```

3. 启动报错、依赖缺失

清除缓存：
```
%USERPROFILE%\.cache\opencode
```
删除整个文件夹后重启 opencode

4. 网络超时 / 模型连不上

检查代理配置
改用 /connect zen 免费国产模型