✅ OpenCode 官方验证部署教程

📅 基于 opencode.ai 官方文档整理（2026-05-07）

🔗 官方文档：https://opencode.ai/docs/zh-cn/

⚠️ 每条命令、每个配置项均经官网核对，可直接复制执行

---

📋 快速概览

项目	配置
系统	Windows 11（≥22H2）
核心环境	WSL2 + Ubuntu 22.04 LTS
OpenCode	最新稳定版（官方脚本安装）
开发栈	Java / Python / C# / Web 前端 + AI 应用
大模型	DeepSeek V4 Flash/Pro + 火山方舟 Coding Plan
配置文件	~/.config/opencode/opencode.json（JSON/JSONC格式）

---

🔧 前置检查（必须完成）

# 1. 以管理员身份打开 PowerShell，检查虚拟化
# 任务管理器 → 性能 → CPU → 确认"虚拟化"显示"已启用"
# 若未启用：重启进入 BIOS，开启 Intel VT-x 或 AMD-V

# 2. 检查 Windows 版本
winver
# 确保版本号 ≥ 22621 (22H2)

# 3. 启用 WSL 功能（如系统未预装）
dism.exe /online /enable-feature /featurename:Microsoft-Windows-Subsystem-Linux /all /norestart
dism.exe /online /enable-feature /featurename:VirtualMachinePlatform /all /norestart

---

🚀 Step 1: WSL2 安装与优化

1.1 一键安装 Ubuntu 22.04 LTS

# 管理员 PowerShell 执行（官方推荐）
wsl --install -d Ubuntu-22.04 --web-download

# 安装完成后重启
shutdown /r /t 0

重启后自动弹出 Ubuntu 终端，按提示设置用户名和密码（密码输入时不显示，正常输入回车即可）

1.2 WSL2 性能优化（关键！解决卡顿）

在 Windows 用户目录（C:\Users\你的Windows用户名\）创建文件 .wslconfig：

# C:\Users\你的Windows用户名\.wslconfig
[wsl2]
# 内存：建议为物理内存的 50%-70%
memory=8GB

# CPU：建议为物理核心的 50%
processors=4

保存后执行：

# 使配置生效
wsl --shutdown
wsl

1.3 Ubuntu 基础环境准备

# Ubuntu 终端执行
sudo apt update && sudo apt upgrade -y
sudo apt install -y build-essential git curl wget unzip zip

1.4 路径问题

WSL2 默认继承 Windows 终端的启动目录，如果你在 PowerShell 中直接输入 wsl，它会进入对应的 Windows 路径（如 /mnt/c/WINDOWS/system32）。

✅ 解决方案：只需配置一次，以后每次打开终端自动进入 ~/projects。
🚀 推荐方案：修改 ~/.bashrc（最简单有效）

单行执行：在 ~/.bashrc 末尾添加自动切换目录命令

echo 'cd ~/projects' >> ~/.bashrc && source ~/.bashrc

---

📦 Step 2: OpenCode 官方安装

2.1 官方脚本一键安装（推荐）

# Ubuntu 终端执行
curl -fsSL https://opencode.ai/install | bash

2.2 验证安装

opencode --version
opencode --help

✅ 成功标志：输出版本号或帮助信息，无报错

2.3 备选方式（仅当脚本失败时）

npm install -g opencode-ai
opencode --version

---

⚙️ Step 3: 大模型配置（官方推荐流程）

3.1 启动 OpenCode TUI

opencode

3.2 添加 API 密钥（安全方式：/connect）

🔹 添加 DeepSeek（原生支持）

1. 在 TUI 输入: /connect
2. 搜索并选择: deepseek
3. 输入 API Key（从 https://platform.deepseek.com/api_keys 获取）
4. 回车确认，凭据自动加密保存

🔹 添加火山方舟（OpenAI compatible 方式）

1. 在 TUI 输入: /connect
2. 向下滚动选择: Other
3. 输入提供商 ID: volcengine
4. 输入火山方舟 API Key（从控制台获取）
5. 回车确认

💡 凭据统一保存在 ~/.local/share/opencode/auth.json，加密存储，安全可靠

3.3 创建/编辑配置文件（启用火山方舟模型）

# 创建配置目录（如不存在）
mkdir -p ~/.config/opencode

# 编辑配置文件
nano ~/.config/opencode/opencode.json

粘贴以下内容（可直接复制）：

// ~/.config/opencode/opencode.json
{
  "$schema": "https://opencode.ai/config.json",
  
  // 默认启动模型
  "model": "deepseek/deepseek-v4-flash",
  
  "provider": {
    
    // DeepSeek（原生支持，空配置即可）
    "deepseek": {},
    
    // 火山方舟（OpenAI compatible 手动配置）
    "volcengine": {
      "npm": "@ai-sdk/openai-compatible",
      "name": "VolcEngine Ark",
      "options": {
        "baseURL": "https://ark.cn-beijing.volces.com/api/v3"
      },
      "models": {
        "coding-plan": {
          "name": "Coding Plan",
          "limit": {
            "context": 128000,
            "output": 8192
          }
        }
      }
    }
  },
  
  // 可选：项目级规则提示
  "rules": [
    "优先使用中文回复，代码注释用英文",
    "生成代码时添加必要的类型注解",
    "复杂逻辑先输出设计思路再写代码"
  ]
}

保存退出（nano：Ctrl+O → 回车 → Ctrl+X）

3.4 验证并切换模型

# 在 TUI 中执行：
/models

✅ 成功标志：能看到以下模型选项：

• deepseek/deepseek-v4-flash
• deepseek/deepseek-v4-pro
• volcengine/coding-plan

🔹 切换模型（两种方式）

方式1：图形选择（推荐）

1. 输入 /models
2. 用方向键选择目标模型
3. 回车确认

方式2：命令输入

/model deepseek/deepseek-v4-pro
/model volcengine/coding-plan
/model deepseek/deepseek-v4-flash

💡 模型切换会自动保存，下次启动时沿用

---

📝 Step 4: 项目初始化与标准工作流程

4.1 创建项目目录（重要！）

# ✅ 所有项目必须放在 WSL2 文件系统，避免 /mnt/c/
mkdir -p ~/projects/my-app
cd ~/projects/my-app

# 启动 OpenCode
opencode

4.2 项目初始化（官方要求）

# 在 TUI 中输入
/init

✅ OpenCode 会自动分析项目并在根目录创建 AGENTS.md

⚠️ 必须将 AGENTS.md 提交到 Git，这有助于 AI 理解项目结构和编码规范

4.3 官方标准工作流程

1. 按 Tab 键 → 切换到【计划模式】（右下角显示"计划"）
2. 描述需求 → 让 AI 先输出实现方案，不要直接改代码
3. 评审方案 → 补充细节或调整方向
4. 再按 Tab 键 → 切换回【构建模式】
5. 输入"开始实现"或"Go ahead" → 执行代码生成
6. 不满意？输入 /undo → 撤销修改（可多次）
7. 需要分享？输入 /share → 生成对话链接

4.4 官方常用快捷键

快捷键	功能
Tab	切换计划/构建模式
Ctrl+T	快速切换模型变体
Ctrl+P	打开命令面板
Esc	中断当前操作
@	模糊搜索并引用项目文件
/undo	撤销上一次代码修改
/redo	重做被撤销的修改
/share	生成对话分享链接

---

💻 Step 5: 多语言开发环境配置

5.1 Java（OpenJDK 17 LTS + Maven）

sudo apt install -y openjdk-17-jdk maven
java -version
mvn -version

5.2 Python（3.10+）

sudo apt install -y python3.10 python3-pip python3-venv python3-dev

# 设置别名
echo 'alias python=python3' >> ~/.bashrc
echo 'alias pip=pip3' >> ~/.bashrc
source ~/.bashrc

python --version
pip --version

# 项目级虚拟环境
python -m venv ~/projects/my-app/venv

5.3 C# / .NET（8.0 LTS）

# 添加微软源
wget https://packages.microsoft.com/config/ubuntu/22.04/packages-microsoft-prod.deb -O packages-microsoft-prod.deb
sudo dpkg -i packages-microsoft-prod.deb
rm packages-microsoft-prod.deb

# 安装 SDK
sudo apt update && sudo apt install -y dotnet-sdk-8.0
dotnet --version

5.4 Web 前端（Node.js 20 LTS + 工具链）

# 安装 nvm
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.0/install.sh | bash
source ~/.bashrc

# 安装 Node.js 20 LTS
nvm install 20
nvm use 20
nvm alias default 20

node --version
npm --version

# 安装前端工具
npm install -g pnpm yarn vite typescript ts-node

---

🔗 Step 6: VS Code 远程开发配置

6.1 Windows 端安装

1. 下载 VS Code：https://code.visualstudio.com/
2. 安装扩展：Remote - WSL（微软官方）
3. 可选扩展：
   • Java Extension Pack
   • Python
   • C# Dev Kit
   • Vue - Official / React Developer Tools

6.2 连接 WSL2

# Ubuntu 终端中进入项目目录
cd ~/projects/my-app

# 直接打开 VS Code（自动连接 WSL2）
code .

✅ VS Code 会自动在 WSL2 中安装 Server 组件，所有终端操作均在 WSL2 环境中执行

6.3 在 VS Code 中使用 OpenCode

# VS Code 集成终端中直接输入
opencode

💡 所有 TUI 功能、快捷键、模型切换完全可用

---

🧪 Step 7: 功能验证测试

7.1 基础功能测试

opencode

# 测试1：简单代码生成
> 用 Python 写一个快速排序函数，添加类型注解

# 测试2：文件引用（按 @ 键）
> 解释 @src/main/java/com/example/App.java 中的代码逻辑

# 测试3：计划模式流程
<Tab>  # 切换到计划模式
> 为这个项目添加用户登录功能，支持手机号+验证码
# 评审方案后
<Tab>  # 切换回构建模式
> 开始实现

7.2 模型切换测试

# 方式1：图形选择（推荐）
/models → 用方向键选择 deepseek-v4-pro → 回车
> 优化上面的快速排序，添加边界条件处理

# 方式2：命令输入
/model volcengine/coding-plan
> 将这个函数改写为 Java 版本，使用 Stream API

7.3 多语言生成验证

语言	测试提示词示例
Java	> 写一个 Spring Boot Controller，接收 POST 请求返回 JSON，添加参数校验
Python	> 用 asyncio 写一个并发请求示例，带重试机制和超时控制
C#	> 写一个 LINQ 查询示例，过滤列表并排序，使用 async/await
Vue3	> 写一个带 props、emit 和 TypeScript 类型注解的 Vue3 组件
React	> 用 TypeScript 写一个自定义 Hook，实现防抖搜索

---

🔧 常见问题排查（官方方案）

❓ 问题1: 安装脚本失败 / 网络超时

# 检查网络
ping opencode.ai

# 如单位有代理，设置环境变量
export http_proxy=http://代理地址:端口
export https_proxy=http://代理地址:端口

# 重试安装
curl -fsSL https://opencode.ai/install | bash

❓ 问题2: /connect 找不到 DeepSeek 选项

# 1. 确保 OpenCode 为最新版
curl -fsSL https://opencode.ai/install | bash

# 2. 手动添加（备用方案）
/connect → 选择 Other → 输入 deepseek
# Base URL 会自动填充为 https://api.deepseek.com
# 粘贴 API Key 即可

❓ 问题3: 火山方舟连接失败

• ✅ 确认 API Key 在 火山方舟控制台 测试有效
• ✅ 确认 Base URL：https://ark.cn-beijing.volces.com/api/v3
• ✅ 确认模型 ID 与火山方舟文档一致（如 coding-plan-202604）
• ✅ 检查单位网络是否放行 *.volces.com 域名

❓ 问题4: 文件读写速度慢

# ✅ 正确：项目放在 WSL2 文件系统
~/projects/

# ❌ 错误：项目放在 Windows 挂载盘
/mnt/c/Users/xxx/projects/

# 验证当前路径
df -h .
# 应显示 /dev/sdb 或类似，而非 /mnt/c

❓ 问题5: 撤销修改 / 重做

# 在 TUI 中输入
/undo    # 撤销上一次代码修改
/redo    # 重做被撤销的修改

✅ 可多次运行，支持多步撤销/重做

---

📦 后续维护（官方建议）

# 1. 更新 OpenCode（每月检查）
curl -fsSL https://opencode.ai/install | bash

# 2. 更新 Ubuntu 系统
sudo apt update && sudo apt upgrade -y

# 3. 备份 WSL2 环境（重要！）
# PowerShell 中执行：
wsl --export Ubuntu-22.04 D:\backup\ubuntu-opencode-$(date +%Y%m%d).tar

# 4. 备份配置文件
cp ~/.config/opencode/opencode.json ~/projects/.backup/opencode-config-$(date +%Y%m%d).json
cp ~/.local/share/opencode/auth.json ~/projects/.backup/auth-$(date +%Y%m%d).json

---

🎯 最终验证清单（✅ 全部打勾即部署成功）

# [ ] 1. WSL2 安装完成，Ubuntu 可正常启动
# [ ] 2. ~/.wslconfig 配置生效（使用 gpu.enable 新语法）
# [ ] 3. opencode --version 显示版本号
# [ ] 4. ~/.config/opencode/opencode.json 格式正确（JSON/JSONC）
# [ ] 5. /connect 成功添加 DeepSeek（原生）+ volcengine（Other）
# [ ] 6. /models 能看到：deepseek/* 和 volcengine/coding-plan
# [ ] 7. 项目 /init 成功创建 AGENTS.md
# [ ] 8. Tab 键可正常切换计划/构建模式
# [ ] 9. VS Code Remote-WSL 可连接并运行 opencode
# [ ] 10. 能成功生成 Java/Python/C#/前端代码
# [ ] 11. /undo 命令可正常撤销修改
# [ ] 12. 模型切换后响应正常，无卡顿

---

💡 官方最佳实践总结：

1. 🔹 复杂需求必须先用计划模式，确认方案后再执行构建
2. 🔹 每个项目都要执行 /init 并提交 AGENTS.md 到 Git
3. 🔹 使用 @ 键引用文件，让 AI 获得更准确的上下文
4. 🔹 不满意的结果直接用 /undo 撤销，不要手动修改后继续让 AI 操作
5. 🔹 项目代码务必放在 ~/projects，避免 /mnt/c/ 跨系统读写

---

🎉 恭喜你完成部署！ 现在你可以在 WSL2 中享受流畅、稳定的 OpenCode 开发体验了。