AI 编程教程中文版
官方教程中文版入门

连接 IDE

在 VS Code、Cursor、Windsurf、VSCodium 等 IDE 中使用 OpenCode。

OpenCode 可以与 VS Code、Cursor 或任何支持终端的 IDE 配合使用。它的核心仍然是终端里的 opencode，IDE 扩展主要负责打开、聚焦和传递上下文。

这一篇用 5 分钟换什么：你会知道 IDE 集成解决什么问题、常用快捷键是什么、怎么自动安装扩展，以及扩展没有安装时先排查哪里。

先给结论：IDE 负责上下文，TUI 负责执行

IDE 集成不要理解成另一套 OpenCode。更准确的关系是：

flowchart LR
  IDE["VS Code / Cursor / Windsurf"] --> Context["当前文件 / 选中内容 / 文件引用"]
  Context --> Terminal["集成终端"]
  Terminal --> TUI["OpenCode TUI"]
  TUI --> Project["项目文件 / Git / 测试命令"]

  style IDE fill:#dbeafe,stroke:#3b82f6
  style TUI fill:#dcfce7,stroke:#22c55e,stroke-width:2px
  style Project fill:#fef3c7,stroke:#f59e0b

你仍然应该按 TUI 的安全方式工作：先只读、限定文件、看工具详情、检查 diff。

官方 IDE 页给出的定位很短：OpenCode integrates with VS Code, Cursor, or any IDE that supports a terminal。关键不是扩展本身，而是“在 IDE 终端里启动 OpenCode，并把当前选择、标签页、文件引用交给终端会话”。因此新手要把 IDE 集成当成上下文入口，不要把它当成权限边界。

IDE 集成解决什么

场景IDE 帮你做什么仍然要由 OpenCode TUI 做什么
读当前文件自动共享 selection 或 tab判断上下文是否足够、是否需要更多文件
引用文件行插入 @File#L37-42基于引用生成修改计划或解释
快速开会话在分屏终端打开或聚焦 OpenCode执行工具、显示 diff、请求确认
多次切任务新建新的 terminal session保持会话边界，不把不相关上下文混在一起
编辑器回写/editor 或 /export 调用外部编辑器等编辑器关闭后继续处理消息

这也是为什么官方安装方式是“打开 IDE 集成终端，运行 opencode”，而不是让你单独配置一个复杂的 IDE 后台服务。

常用操作

  • 快速启动：Cmd+Esc（Mac）或 Ctrl+Esc（Windows/Linux）在分屏终端视图中打开 OpenCode；如果已有终端会话，会自动聚焦。
  • 新建会话：Cmd+Shift+Esc（Mac）或 Ctrl+Shift+Esc（Windows/Linux）启动新的 OpenCode 终端会话。
  • 上下文感知：自动将当前选中内容或标签页共享给 OpenCode。
  • 文件引用：Cmd+Option+K（Mac）或 Alt+Ctrl+K（Linux/Windows）插入文件引用，例如 @File#L37-42。

自动共享上下文很方便，但不要把包含密钥、客户数据、内部日志或未公开策略的文件选中后直接发给模型。

使用边界

IDE 能让上下文输入更快，也更容易误发内容。建议默认遵守这几条：

  1. 选中内容只包含当前任务需要的片段，不把整份 .env、日志、客户数据、私有策略放进 selection。
  2. 文件引用优先引用小范围行号，例如 @File#L37-42，不要把大目录当作第一轮输入。
  3. 开新功能、修 bug、做 review 分别用不同 session，避免历史上下文串线。
  4. 修改前要求 OpenCode 说明将读取和修改哪些文件。
  5. 修改后回到 IDE Source Control 或 Git diff 做人工复查。

如果你已经在终端里熟悉 OpenCode，IDE 集成只是减少复制粘贴，不改变验收标准。

安装方式

在 VS Code 及其常见分支上，最简单的方式是在集成终端里运行：

opencode

扩展会自动安装。支持的 IDE 包括 VS Code、Cursor、Windsurf、VSCodium 等。

如果你希望在 TUI 中执行 /editor 或 /export 时使用自己的 IDE，需要设置 EDITOR：

export EDITOR="code --wait"

GUI 编辑器通常需要 --wait，否则编辑器一打开，OpenCode 可能就认为消息已经结束。

手动安装

如果自动安装失败，可以在扩展商店中搜索 OpenCode，然后点击 Install。

验收步骤

安装完成后，用一个安全的小任务验收，不要直接让它改生产代码：

1. 在 IDE 集成终端运行 opencode
2. 用快捷键打开或聚焦 OpenCode 分屏
3. 选中当前文件中一小段无敏感内容
4. 用文件引用快捷键插入 @File#Lx-y
5. 让 OpenCode 只解释这段代码，不编辑
6. 再让它生成修改计划，不执行
7. 最后关闭会话，确认没有误改文件

这轮通过后，再尝试单文件文案、小范围重命名或只读 review。

故障排除

如果扩展未能自动安装，先检查：

  • 是否是在 IDE 的集成终端中运行 opencode。
  • IDE 对应的 CLI 命令是否已安装。
  • VS Code：code。
  • Cursor：cursor。
  • Windsurf：windsurf。
  • VSCodium：codium。
  • IDE 是否有权限安装扩展。

如果 CLI 命令缺失，按 Cmd+Shift+P（Mac）或 Ctrl+Shift+P（Windows/Linux），搜索 Shell Command: Install 'code' command in PATH，或安装对应 IDE 的 shell command。

还有一个常见误判：你在系统终端运行了 opencode，但期待 IDE 自动安装扩展。官方写的是在 IDE integrated terminal 中运行。普通终端不会知道当前 IDE 的 extension host，也就不能完成同样的自动安装路径。

接下来去哪

TUI 工作流

IDE 只是承载终端，核心操作仍然是 `@`、`!`、`/` 和 diff 检查。

快捷键

如果 IDE、终端和 OpenCode 快捷键冲突，从 keybinds 页开始调整。

入门

回到第一天安全闭环，确认安装、provider、只读和单文件写入都跑通。

分享会话

从 IDE 里分享上下文前，先理解公开链接和数据边界。

官方资料

使用 TUI

说明 OpenCode 终端界面的基本操作、常见状态和新手第一次使用的检查点。

分享会话

说明 OpenCode 会话分享的用途、公开边界、撤销方式和团队默认策略。

本页目录

先给结论：IDE 负责上下文，TUI 负责执行IDE 集成解决什么常用操作使用边界安装方式手动安装验收步骤故障排除接下来去哪官方资料