Windows OpenCode CLI 安装教程与常用命令速查清单

一、安装前准备

1. 系统要求：Windows 10/11（64位操作系统）

2. 权限准备：全程建议使用管理员身份打开终端（Win+X→终端(管理员)），避免因权限不足导致安装失败

3. 网络要求：确保网络通畅，建议切换至稳定网络或使用国内镜像源提升安装速度

二、三种安装方式（按需选择）

方式1：npm全局安装（推荐，适配已有Node.js环境）

1. 安装Node.js 18+（OpenCode CLI依赖Node.js运行）

   • 官网下载：访问Node.js官网，选择“Windows 64位安装包（.msi）”

   • 安装步骤：双击安装包，必须勾选“Add to PATH”（默认已勾选，切勿取消），后续按提示点击“Next”完成安装

   • 验证安装：关闭所有终端后重新打开，执行以下命令，能正常输出版本号即成功
     node -v # 验证Node.js版本 npm -v # 验证npm版本

2. 切换国内镜像源（避免安装超时）
   npm config set registry https://registry.npm.taobao.org

3. 安装OpenCode CLI
   npm install -g opencode-ai

4. 验证安装：执行以下命令，输出版本号即安装成功
   opencode --version

方式2：Chocolatey/Scoop包管理器安装（适合习惯包管理的用户）

2.1 Chocolatey安装

1. 先安装Chocolatey（管理员PowerShell中执行）
   Set-ExecutionPolicy Bypass -Scope Process -Force; [System.Net.ServicePointManager]::SecurityProtocol = [System.Net.ServicePointManager]::SecurityProtocol -bor 3072; iex ((New-Object System.Net.WebClient).DownloadString('https://community.chocolatey.org/install.ps1'))

2. 安装OpenCode CLI
   choco install opencode

2.2 Scoop安装

1. 先安装Scoop（PowerShell中执行）Set-ExecutionPolicy RemoteSigned -Scope CurrentUser; irm get.scoop.sh | iex

2. 添加存储桶并安装OpenCode CLI
   scoop bucket add extras scoop install extras/opencode

方式3：二进制文件安装（无需Node.js，适合纯净环境）

1. 下载二进制包：访问OpenCode GitHub Releases，下载对应Windows版本的二进制包（通常命名为opencode-windows-amd64.exe）

2. 重命名与放置：将下载的文件重命名为opencode.exe，放入系统PATH目录（如C:\Windows\System32，放入前建议确认该目录已在系统PATH中）

3. 验证安装：打开终端执行以下命令，输出版本号即成功
   opencode --version

三、关键配置（连接AI模型，必做步骤）

1. 初始化配置：终端执行以下命令，启动配置向导
   opencode init

2. 模型选择（按需选择，推荐免费方案）

   • 免费优先：选择“智谱GLM-4”或“MiniMax”，按提示前往对应官网注册账号，获取API密钥

   • 本地隐私优先：选择“Ollama”，需先安装Ollama（官网：https://ollama.com/），并拉取对应模型（如ollama run llama3）

3. 配置API密钥：将获取的API密钥粘贴到终端提示位置，完成初始化

4. 指定端口启动服务（解决端口需求，示例端口60953）
   opencode --port 60953

四、VS Code 1.108.0集成配置

1. 安装插件：打开VS Code，在扩展商店搜索“OpenCode”，点击“安装”，安装完成后重启VS Code

2. 配置插件：打开VS Code设置文件（快捷键Ctrl+, → 右上角点击“打开设置(JSON)”图标），添加以下配置（与启动端口、选择的模型匹配）
   { // 与初始化时选择的模型一致 "opencode.model": "glm-4", // 与启动OpenCode CLI时指定的端口一致 "opencode.server.port": 60953, // 保留之前的字体配置（可选，按个人需求调整） "editor.fontSize": 20, "workbench.tree.fontSize": 20 }

3. 启动插件：打开VS Code命令面板（快捷键Ctrl+Shift+P），输入“OpenCode: Start”，按回车启动插件

五、常见问题解决

常见问题	解决方法
终端提示“无法将‘opencode’项识别为 cmdlet、函数、脚本文件或可运行程序的名称”	1. 检查安装是否成功：执行npm list -g opencode-ai；2. 配置PATH环境变量：执行npm config get prefix获取npm全局安装路径，将该路径添加到系统用户变量的Path中；3. 关闭所有终端后重新打开
安装过程中出现超时错误	1. 切换国内镜像源（npm方式参考步骤二方式1的第2点）；2. 检查网络连接，切换至更稳定的网络；3. 用管理员权限重新执行安装命令
模型连接失败/无法正常调用AI	1. 检查API密钥是否正确，若密钥过期需重新获取；2. 切换网络环境，避免网络限制；3. 若使用本地Ollama模型，检查Ollama是否正常运行、模型是否拉取成功
指定端口启动时提示“端口被占用”	1. 更换未被占用的端口，如opencode --port 60954；2. 同步更新VS Code中OpenCode插件的端口配置（对应步骤四第2点的opencode.server.port字段）
npm安装时出现“权限拒绝”错误	1. 确保使用管理员身份打开终端；2. 若仍报错，可修复npm权限：执行npm install -g npm更新npm，再重新安装OpenCode CLI

六、OpenCode CLI常用命令速查清单

1. 基础配置与启动命令

命令	功能说明	示例
opencode --version	查看OpenCode CLI版本号	opencode --version（输出类似：opencode/1.xx.x win32-x64 node-v20.xx.x）
opencode init	初始化OpenCode配置，用于连接AI模型、设置API密钥等	opencode init（按向导提示完成模型选择和密钥配置）
opencode --port <端口号>	指定端口启动OpenCode服务，用于与VS Code插件等集成	opencode --port 60953（指定60953端口启动服务）
opencode --help	查看所有命令的帮助信息，了解命令参数用法	opencode --help（输出所有命令列表及功能说明）

2. 代码生成与编辑命令

命令	功能说明	示例（游戏开发场景）
opencode <需求描述>	根据需求描述生成代码，支持直接生成文件	opencode "写一个Unity 2D角色跳跃脚本，支持双击连跳，保存为PlayerJump.cs"（生成脚本文件并保存）
opencode fix <文件路径>	修复指定代码文件中的语法错误、逻辑错误	opencode fix ./Assets/PlayerMovement.cs（修复PlayerMovement.cs文件中的错误）
opencode refactor <文件路径> -d <重构需求>	重构指定代码文件，优化代码结构、提升性能等	opencode refactor ./Assets/GameLoop.cs -d "优化游戏循环逻辑，提升帧率稳定性"（重构游戏循环代码）
opencode explain <文件路径>	解释指定代码文件的功能、逻辑流程，生成注释	opencode explain ./Assets/EnemyAI.cs（解释敌人AI脚本的逻辑并添加注释）

3. 模型相关命令

命令	功能说明	示例
opencode model list	查看当前支持的所有AI模型列表	opencode model list（输出支持的模型名称、类型等信息）
opencode model switch <模型名称>	切换当前使用的AI模型	opencode model switch glm-4（切换模型为智谱GLM-4）
opencode model test <模型名称>	测试指定AI模型的连接状态和响应速度	opencode model test llama3（测试本地Ollama的llama3模型）

4. 交互与其他命令

命令	功能说明	示例
opencode	进入OpenCode交互模式，可直接输入问题与AI对话	opencode（进入后输入：“Unity中如何实现角色受击击退效果？”获取回复）
opencode doc <技术主题>	生成指定技术主题的文档、教程	opencode doc "Unity 2D碰撞检测机制详解"（生成碰撞检测机制的详细文档）
opencode update	检查并更新OpenCode CLI到最新版本	opencode update（自动检测更新并完成安装）

七、游戏开发场景专用命令示例

# 1. 生成Unity 2D角色移动脚本（支持键盘+摇杆控制）
opencode "写一个Unity 2D角色移动脚本，支持WASD键盘控制和虚拟摇杆控制，包含移动速度参数调节，保存为PlayerMovement.cs"

# 2. 生成Godot 3D敌人巡逻AI脚本
opencode "写一个Godot 3D敌人巡逻脚本，实现指定路径点之间的往返巡逻，检测到玩家后自动追击，保存为EnemyPatrol.gd"

# 3. 修复Unity游戏存档脚本错误
opencode fix ./Assets/SaveSystem.cs

# 4. 重构Unity战斗系统代码，提升性能
opencode refactor ./Assets/CombatSystem.cs -d "优化战斗伤害计算逻辑，减少GC开销，提升大数量敌人同时战斗时的帧率"

# 5. 生成游戏性能优化建议文档
opencode doc "Unity 2D游戏性能优化关键要点，包含Draw Call优化、内存管理、代码优化"

# 6. 交互查询：解决角色跳跃后落地卡顿问题
opencode
# 进入交互模式后输入："Unity中角色跳跃后落地出现卡顿，可能的原因有哪些？如何解决？"

（注：文档部分内容可能由 AI 生成）