OpenCode VSCode 使用教程：7 个安装、上下文与排错检查

VS Code 扩展并不替代 OpenCode CLI，它只是为 CLI 增加编辑器上下文、快捷键和稳定的分屏终端入口。先在 VS Code 集成终端执行 opencode --version；如果这里提示找不到命令，扩展无法替你补齐 PATH。应先修复终端配置，再检查编辑器功能。

请打开真实仓库目录，而不是空白窗口。OpenCode 需要明确的项目边界、Git 状态、配置文件与当前选区。首次使用前检查忽略规则，避免密钥、生产配置或大体积无关文件进入上下文。同时在普通终端验证 Provider 和模型可用，把认证、网络、模型限流与扩展故障分开判断。

第一步打开仓库；第二步选择“终端 > 新建终端”；第三步运行 opencode。根据 2026 年 7 月 29 日核验的官方 IDE 文档，OpenCode 会识别 VS Code 并自动安装扩展。第四步确认 CLI 能读取当前项目；第五步使用 Ctrl+Esc 或 Cmd+Esc，验证扩展能打开或聚焦分屏会话。

如需手动安装，可在 VS Code 扩展市场搜索 OpenCode 并点击安装。但“已安装”徽标只说明扩展文件存在，不能证明 opencode 命令、模型 Provider 或工作区权限正确。另开会话使用 Ctrl+Shift+Esc 或 Cmd+Shift+Esc；多个会话应分配不同任务和文件边界，避免同时修改同一文件。

扩展最有价值的能力是上下文感知。提问前只选中能够解释问题的最小代码块，例如一个函数、异常分支或配置对象。整份大文件虽然信息更多，却会稀释目标并增加审查成本。活动标签页也能提供上下文，但显式选区更容易确认到底发送了什么。

需要稳定引用时，Windows/Linux 使用 Alt+Ctrl+K，macOS 使用 Cmd+Option+K，插入类似 @File#L37-42 的文件与行号。行号适合代码审查、窄范围重构与错误定位；完成较大编辑后要重新确认范围，因为新增或删除行可能让旧引用指向另一段代码。选区只是上下文，不会覆盖 OpenCode 的文件和命令权限。

每个任务先检查 Git 状态，说明预期结果，并指出禁止修改的文件。再选择相关代码或插入文件引用，让 OpenCode 先定位问题。跨模块改动可以先要简短计划，窄范围修复则直接要求修改与验证。判断质量的依据是干净、可解释的 diff，而不是对话长度。

让集成终端保持可见，随时确认工作目录、准备执行的命令和实际输出。修改后先看 Source Control 差异，再运行最小相关测试或格式化，风险较高时再扩大验证。会话积累了无关指令就新建会话并重述边界；多人或多会话协作时，同一变化文件应只有一个明确所有者。

VS Code 可能连接 PowerShell、WSL、SSH、Dev Containers 或远程目录。同一个命令在本地克隆中无害，在远程生产环境却可能产生真实影响。批准命令前检查终端配置、提示符路径与环境名称，尤其谨慎对待部署、数据库、支付和认证相关操作。

不要因为选区方便就发送私钥、客户数据、生产配置或无关大文件。除非已经验证为全本地模型链路，相关上下文通常会发送到配置的模型 Provider。使用环境变量或密钥管理器，保持敏感文件被忽略，并在错误示例中脱敏。权限规则应由仓库风险决定，扩展只负责缩短编辑器与终端之间的操作路径。

自动安装失败时，先证明 opencode 能在 VS Code 集成终端运行。外部 PowerShell 能执行，不代表编辑器内部 PATH 已刷新；安装 CLI 或修改 PATH 后应完全关闭并重开 VS Code。随后比较两个终端中的可执行文件位置，并确认集成终端使用了预期的 Shell 配置。

再检查 VS Code 的 code 命令。官方排错页列出 VS Code 使用 code、Cursor 使用 cursor、Windsurf 使用 windsurf、VSCodium 使用 codium。macOS 可在命令面板执行“Shell Command: Install 'code' command in PATH”；Windows/Linux 应在同一集成终端运行 code --version。扩展存在但快捷键无反应时检查键位冲突；会话启动但模型失败时转查 Provider、代理、模型可用性与限流。

只有当 CLI 在集成终端正常、code 命令存在、Provider 请求成功，而编辑器命令仍缺失或损坏时，重装才有意义。卸载 OpenCode 扩展，关闭全部 VS Code 窗口，重开仓库，再在新集成终端运行 opencode 触发自动安装。先测试默认快速启动键，再恢复自定义键位。

没有扩展支持的编辑器只要能打开终端，仍可运行 OpenCode，只是缺少自动选区和快捷键。若要让 TUI 的 /editor 或 /export 调用 VS Code，可按官方建议设置 EDITOR="code --wait"。最终验收应包含：CLI 从项目目录启动、扩展能聚焦会话、选区传递准确、小改动形成可审查 diff、相关测试通过。