---
title: "连接 IDE"
description: "在 VS Code、Cursor、Windsurf、VSCodium 等 IDE 中使用 OpenCode。"
verifiedAt: "2026-05-09"
---

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

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

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

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

```mermaid
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`。

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

## 使用边界

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

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

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

## 安装方式

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

```bash
opencode
```

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

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

```bash
export EDITOR="code --wait"
```

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

## 手动安装

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

## 验收步骤

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

```text
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，也就不能完成同样的自动安装路径。

## 接下来去哪

<Cards>
  <Card title="TUI 工作流" description="IDE 只是承载终端，核心操作仍然是 `@`、`!`、`/` 和 diff 检查。" href="/docs/opencode/official/00-getting-started/tui" />
  <Card title="快捷键" description="如果 IDE、终端和 OpenCode 快捷键冲突，从 keybinds 页开始调整。" href="/docs/opencode/official/01-customization/keybinds" />
  <Card title="入门" description="回到第一天安全闭环，确认安装、provider、只读和单文件写入都跑通。" href="/docs/opencode/official/00-getting-started" />
  <Card title="分享会话" description="从 IDE 里分享上下文前，先理解公开链接和数据边界。" href="/docs/opencode/official/00-getting-started/share" />
</Cards>

## 官方资料

- OpenCode IDE：[https://opencode.ai/docs/ide](https://opencode.ai/docs/ide)
- OpenCode TUI：[https://opencode.ai/docs/tui](https://opencode.ai/docs/tui)
