LowHow 文档

中文

English

中文

English

深色模式

在 VS Code 中集成 OpenCode 的完整教程 | IDE 与 AI 编程助手 ​

📚 分类: AI 编程工具配置 ⏱️ 预计耗时: 10 分钟 🎯 难度: 入门 🔧 环境要求: macOS / Windows / Linux，已安装 VS Code

你将学到什么 ​

完成本教程后，你将能够：

  • [ ] 理解 IDE 集成与 OpenCode TUI 的关系
  • [ ] 在 VS Code 的集成终端中启动 OpenCode
  • [ ] 将当前选中的代码或文件作为上下文传递给 OpenCode
  • [ ] 验证集成是否成功，并解决常见的安装问题

最终效果 ​

你将能够在 VS Code 中，选中一段代码，然后通过快捷键或命令，在底部的集成终端中自动启动 OpenCode TUI，并将选中的代码作为上下文传递给它，从而让 AI 助手能更准确地理解你想要修改或分析的部分。

前置准备 ​

在开始前，请确认你的环境满足以下条件：

检查项要求验证命令
Node.js≥ 18.0node -v
OpenCode已安装opencode --version
VS Code code 命令可用code --version

1. 安装 OpenCode ​

如果你还没有安装 OpenCode，请先在全局终端（非 VS Code 内部）中安装：

bash
$ npm install -g @opencode/cli    // 全局安装 OpenCode CLI
$ opencode --version               // 验证安装是否成功

✅ 验证：如果看到类似 1.2.3 的版本号，说明安装成功。

2. 确保 VS Code 的 code 命令可用 ​

这是让 VS Code 能够通过命令行控制自身的关键。在全局终端中执行：

bash
$ code --version
  • ✅ 如果看到版本号：说明 code 命令已配置好，可以跳过此步骤。
  • ⚠️ 如果报错 command not found: code：请按以下步骤操作：
    1. 在 VS Code 中，按下 Cmd+Shift+P (Mac) 或 Ctrl+Shift+P (Windows/Linux) 打开命令面板。
    2. 输入并选择 Shell Command: Install 'code' command in PATH。
    3. 重启你的终端，再次运行 code --version 验证。

第 1 步：理解核心关系 ​

🎯 目标：明确 IDE（VS Code）和 OpenCode TUI 各自扮演的角色，避免概念混淆。

📝 操作：阅读以下核心概念，这是正确使用的基础。

你可能会以为 IDE 集成是 OpenCode 的另一种“模式”，但更准确的理解是：

  • IDE (VS Code)：是你的 上下文提供者。你在这里打开文件、阅读代码、选中片段。它的任务是准备好“你要处理什么”。
  • OpenCode TUI：是你的 执行引擎。它接收 IDE 传来的上下文，理解你的指令，然后操作文件、运行 Git 命令、执行测试等。

🤔 为什么要这样分工？ 这种设计让 OpenCode 保持安全可控。你可以在 IDE 中精确地指定“只改这个函数”，而 OpenCode 在执行时，会在 TUI 中展示它的修改计划（diff），让你 review 后再执行。这比让 AI 直接在你的编辑器里“乱改”要安全得多。

✅ 验证：你能用自己的话说出 IDE 和 OpenCode TUI 分别负责什么。

第 2 步：在 VS Code 集成终端中启动 OpenCode ​

🎯 目标：在 VS Code 内部启动 OpenCode TUI，这是所有后续操作的基础。

📝 操作：

  1. 打开 VS Code，并打开一个你打算使用 OpenCode 的项目文件夹。

  2. 按下 Ctrl+`（反引号，通常在 ESC 键下方）打开 集成终端。

  3. 在集成终端中，输入以下命令并回车：

    bash
    $ opencode

✅ 验证： 你会看到终端界面切换为 OpenCode 的 TUI 界面，通常是一个带有输入框和状态栏的全屏字符界面。这意味着 OpenCode 已经成功启动并等待你的指令。

💡 提示：如果 VS Code 自动提示安装 OpenCode 扩展，请选择“安装”。但这并非强制步骤，因为核心功能仍然通过终端 TUI 完成。

第 3 步：传递上下文到 OpenCode ​

🎯 目标：学会将你在 VS Code 编辑器中选中的代码或文件，作为“上下文”传递给已经启动的 OpenCode TUI。

📝 操作：

  1. 在 VS Code 编辑器中，打开一个代码文件（例如 index.js）。
  2. 用鼠标选中其中几行代码。
  3. 按下 Cmd+Shift+P (Mac) 或 Ctrl+Shift+P (Windows/Linux) 打开命令面板。
  4. 输入并选择 OpenCode: Send Selection to TUI 命令。

💡 提示：你也可以使用默认快捷键 Cmd+L (Mac) 或 Ctrl+L (Windows/Linux) 来快速发送当前选中的内容。

✅ 验证： 切换到 OpenCode TUI 界面，你会发现在输入框上方出现了一条新的“上下文”消息，内容就是你刚才选中的代码。这表示上下文已经成功传递。

🤔 为什么要这样做？ OpenCode TUI 本身并不知道你正在看哪个文件。通过这种方式，你可以精确地告诉 AI：“我只关心这段代码，请基于它来工作。” 这能极大地提高 AI 回答的准确性和相关性。

第 4 步：验证集成是否正常工作 ​

🎯 目标：通过一个简单的测试，确认整个集成链路（VS Code -> 集成终端 -> OpenCode TUI）是畅通的。

📝 操作：

  1. 确认 OpenCode TUI 正在运行（看到它的界面）。

  2. 在编辑器里选中任意一行代码，并使用 Cmd+L 发送上下文。

  3. 在 OpenCode TUI 中输入一个简单的只读指令，例如：

    /ask 解释这段代码的功能

  4. 按回车发送指令。

✅ 验证： OpenCode 应该会开始“思考”，并最终返回一段对这段代码的解释。这证明：

  • 上下文已成功传递。
  • OpenCode 能够与你的 AI 模型（如 GPT-4）正常通信。
  • 整个集成流程是有效的。

⚠️ 常见错误：

  • 问题：执行 /ask 后，OpenCode 没有反应或报错。
  • 排查：
    1. 检查模型配置：确保 OpenCode 已经配置了可用的 API Key 和模型。在全局终端运行 opencode config 检查。
    2. 检查网络：确认你的网络可以访问 AI 模型的 API 服务。
    3. 检查终端：确保你是在 VS Code 的 集成终端 中启动的 opencode，而不是系统的独立终端。

进阶技巧（可选） ​

掌握基础后，你可以尝试：

  1. 发送整个文件：在命令面板中选择 OpenCode: Send File to TUI，可以将当前打开的整个文件作为上下文发送。
  2. 自定义快捷键：如果你觉得 Cmd+L 与其他快捷键冲突，可以在 VS Code 的键盘快捷键设置中搜索 OpenCode 并修改为你喜欢的组合键。

常见问题 (FAQ) ​

Q1: 我在 VS Code 的集成终端里启动 OpenCode，但它没有自动安装扩展，怎么办？A: 这是正常的。自动安装扩展是“最佳情况”，但并非总能成功。你可以：

  1. 在 VS Code 扩展商店搜索“OpenCode”，手动安装官方扩展。
  2. 或者，忽略扩展，直接在集成终端中使用 opencode 命令，核心功能不受影响。

Q2: 我在系统终端里启动了 OpenCode，然后打开 VS Code，为什么不能传递上下文？A: 这是最常见的误解。必须在 VS Code 的集成终端中启动 OpenCode，才能实现上下文传递。系统终端和 VS Code 是两个独立的程序，无法直接通信。请确保你是在 VS Code 内部按下 Ctrl+` 打开的终端里运行的 opencode。

Q3: 发送上下文后，OpenCode TUI 没有反应？A: 请检查 OpenCode TUI 是否处于“等待输入”状态。有时你可能不小心按了 Ctrl+C 或其他键退出了对话。如果界面看起来卡住了，尝试按 Esc 键或重新启动 OpenCode。

总结 ​

恭喜你完成了本教程！🎉

回顾一下我们今天学到的核心内容：

  1. 核心概念：IDE 负责提供“上下文”，OpenCode TUI 负责“执行”，两者分工明确。
  2. 关键操作：必须在 VS Code 的 集成终端 中启动 OpenCode。
  3. 工作流程：在编辑器中选中代码 -> 使用 Cmd+L 发送上下文 -> 在 OpenCode TUI 中下达指令。
  4. 排查思路：遇到问题，优先检查“是否在集成终端”、“模型配置是否正确”、“API 网络是否通畅”。

© 2026 LowHow