IDE Extension 深度指南：编辑器内的 AI 搭档

Codex IDE Extension 让你无需离开编辑器就能使用 Codex 的全部能力——从快速问答到自主编码，从代码审查到云端委派。它与 VS Code、Cursor、Windsurf 等编辑器深度集成，共享 CLI 的配置体系，同时提供编辑器独有的上下文感知能力。

本篇将全面覆盖 IDE Extension 的安装、模式选择、上下文管理、命令体系和设置项，帮助你在最熟悉的开发环境中释放 Codex 的全部潜力。

一、安装与面板配置

1.1 支持的编辑器

编辑器安装方式平台支持
VS CodeVS Code Marketplace 搜索 "Codex" 或官网下载macOS / Linux
Cursor官网下载 .vsix 安装macOS / Linux
Windsurf官网下载 .vsix 安装macOS / Linux
VS Code Insiders官网下载macOS / Linux
JetBrains IDEsJetBrains 插件市场安装（Rider / IntelliJ / PyCharm / WebStorm）全平台
Windows 用户注意

Windows 支持目前为实验性质。建议在 WSL 工作区中使用 Codex 以获得最佳体验。可在设置中启用 chatgpt.runCodexInWindowsSubsystemForLinux。

1.2 安装后首次配置

  1. 安装扩展 → 在左侧活动栏中找到 Codex 图标（VS Code 可能需要重启）
  2. 登录 → 使用 ChatGPT 账号或 API Key 登录（ChatGPT Plus/Pro/Business/Edu/Enterprise 计划已包含使用额度）
  3. 移动面板位置（推荐）→ 将 Codex 拖到右侧边栏，与文件浏览器分开，编码时更方便

1.3 在 Cursor 中移动面板

Cursor 默认使用水平活动栏，可能隐藏 Codex 图标。解决方法：

  1. 打开编辑器设置 → 搜索 activity bar
  2. 将方向改为 vertical
  3. 重启编辑器
  4. 将 Codex 图标拖到右侧边栏
  5. 恢复活动栏方向为 horizontal

二、审批模式：Chat vs Agent vs Agent (Full Access)

IDE Extension 提供三种审批模式，决定 Codex 拥有多大的自主权：

模式能力范围适用场景自主程度
Chat仅对话和问答，不读取文件、不编辑代码、不执行命令代码解释、方案讨论、学习提问⭐
Agent可读取文件、编辑代码、在工作目录内执行命令；工作目录外和网络访问需审批日常编码、重构、测试（推荐默认）⭐⭐⭐
Agent (Full Access)读取、编辑、执行命令 + 网络访问，无需审批需要安装依赖、调用 API 等网络操作的任务⭐⭐⭐⭐⭐

模式切换

在聊天输入框下方的切换器中选择模式。

推荐策略

日常使用 Agent 模式作为默认。需要纯讨论时切到 Chat，需要网络访问时临时切到 Full Access。

与 CLI/App 审批模式的对应关系

IDE 模式CLI/App 等价
Chat仅问答，无 agent 行为
Agentsuggest 模式（工作区内自动，外部需审批）
Agent (Full Access)auto-edit / full-auto（自动执行，含网络）

三、IDE 特有功能：上下文就是超能力

IDE Extension 最大的优势在于自动感知编辑器上下文——打开的文件、选中的代码、终端输出，这些都成为 Codex 的即时参考。

3.1 代码选区引用

选中代码后，使用命令 chatgpt.addToThread 将选区添加为当前线程的上下文。Codex 可以直接基于选中的代码进行解释、重构或修复。

典型用法：

  1. 选中一段有 bug 的函数
  2. 在 Codex 聊天中输入 "Fix the bug in this function"
  3. Codex 直接基于选区上下文给出修复

3.2 文件上下文

两种方式引用文件：

  • @ 标记引用：在 Prompt 中用 @filename 引用任意文件
  • 整文件添加：使用命令 chatgpt.addFileToThread 将整个文件加入上下文
Text
Use @example.tsx as a reference to add a new page named
"Resources" to the app that contains a list of resources
defined in @resources.ts
上下文越精准，Prompt 越短

当 Codex 已经能看到你打开的文件和选中的代码时，你不需要在 Prompt 中重复描述上下文。

3.3 终端上下文

Codex 可以读取编辑器内置终端的输出。当你遇到构建错误或测试失败时：

  1. 终端中运行命令并看到错误
  2. 在 Codex 中直接说 "Fix this error" 或 "Why is this test failing?"
  3. Codex 结合终端输出和代码自动定位并修复问题

3.4 图片拖入

将图片拖入 Prompt Composer 作为上下文（VS Code 中需要按住 Shift 拖入）。适用于前端开发时参考设计稿或截图反馈。

3.5 TODO 评论 CodeLens

启用 chatgpt.commentCodeLensEnabled 后，代码中的 TODO 注释上方会显示 CodeLens 按钮，点击即可让 Codex 自动完成该 TODO。也可以选中 TODO 后使用 chatgpt.implementTodo 命令。

四、模型选择与推理力度

4.1 切换模型

在聊天输入框下方的模型切换器中选择不同的模型。每个模型有不同的优势：

  • 默认模型适合大多数日常任务
  • 可根据任务复杂度切换到更强的模型

4.2 调节推理力度（Reasoning Effort）

在同一个切换器中选择 low、medium 或 high：

力度特点适用场景
Low快速响应，token 消耗少简单问答、格式修改、小重构
Medium平衡速度与深度（推荐默认）日常编码、bug 修复、功能实现
High深度思考，耗时较长，token 消耗多复杂架构设计、多文件重构、疑难 bug
Warning

高推理力度 + 强模型（如 GPT-5-Codex）会快速消耗速率限制。建议从 medium 开始，只在确实需要更深入分析时切换到 high。

五、云端委派（Cloud Delegation）

IDE Extension 支持将较大的任务委派到云端执行，你无需离开编辑器即可跟踪进度和审查结果。

5.1 基本流程

  1. 配置云端环境 → 确保已设置 Codex Cloud 环境
  2. 选择环境 → 在 Codex 面板中选择目标云端环境
  3. 选择起点 → 从 main 分支（新想法）或本地变更（继续任务）开始
  4. Run in the cloud → Codex 在云端执行任务

5.2 跟进云端工作

  • 预览变更 → 在 IDE 中直接查看云端 diff
  • 追加要求 → 可以继续在云端运行后续任务
  • 应用到本地 → 将云端变更 apply 到本地进行测试和最终确认
  • 保持上下文 → 从本地对话启动的云端任务会保留对话上下文，切回本地继续时也保留

六、Slash Commands

在聊天输入框中输入 / 调出命令列表，快速控制 Codex 的行为。

命令功能
/auto-context开关 Auto Context——自动包含最近的文件和 IDE 上下文
/cloud切换到云端模式，将任务远程运行
/cloud-environment选择云端环境（仅云端模式下可用）
/local切换到本地模式，在工作区内运行任务
/review启动代码审查，审查未提交变更或对比 base branch
/status显示线程 ID、上下文使用量和速率限制
/feedback打开反馈对话框，可附带日志提交
快速切换本地/云端

使用 /local 和 /cloud 可以在同一线程中灵活切换执行环境，无需新建线程。

七、IDE Extension Commands

除了 Slash Commands（在聊天中使用），IDE Extension 还提供了一组编辑器命令，可通过命令面板（Cmd+Shift+P）调用或绑定为键盘快捷键。

7.1 可用命令

命令 ID默认快捷键功能
chatgpt.newChatCmd+N / Ctrl+N创建新线程
chatgpt.addToThread（未绑定）将选中的代码区域添加为当前线程的上下文
chatgpt.addFileToThread（未绑定）将整个文件添加为当前线程的上下文
chatgpt.implementTodo（未绑定）让 Codex 完成选中的 TODO 注释
chatgpt.newCodexPanel（未绑定）创建新的 Codex 面板
chatgpt.openSidebar（未绑定）打开 Codex 侧边栏面板

7.2 设置键盘快捷键

  1. 打开命令面板（Cmd+Shift+P）
  2. 运行 Preferences: Open Keyboard Shortcuts
  3. 搜索 Codex 或具体的命令 ID
  4. 点击铅笔图标，输入你想要的快捷键
推荐绑定

为 chatgpt.addToThread 绑定一个顺手的快捷键（如 Cmd+Shift+L），这样选中代码后一键就能发给 Codex。

八、与 Codex App 的自动同步（Auto Context）

IDE Extension 和 Codex App 之间有一套自动同步机制，当两者打开同一个项目时自动激活。

8.1 同步能力

功能说明
自动连接App 和 IDE Extension 在同一项目时自动建立连接
Auto ContextApp 自动追踪你在 IDE 中正在查看的文件，可以用模糊引用（如 "What's this file about?"）
线程互通App 中的线程在 IDE 可见，IDE 中的线程在 App 可见
IDE Context 选项同步时 App Composer 中出现 "IDE context" 选项

8.2 Auto Context 开关

  • 在 IDE 中使用 /auto-context 命令切换开关
  • 在 App 中可以在 Composer 的上下文选项中切换
  • 如果不确定 App 是否包含了 IDE 上下文，可以关闭 Auto Context 后重新提问对比结果

8.3 最佳使用场景

Mermaid
正在渲染 Mermaid 图表…

典型工作流：在 IDE 中阅读和编辑代码，同时在 App 中启动 Worktree 线程让 Codex 后台工作。App 通过 Auto Context 自动了解你在 IDE 中正在关注什么，无需手动复制文件路径。

九、设置项详解

IDE Extension 的设置分为两层：编辑器设置（VS Code settings）和共享配置（config.toml）。

9.1 编辑器设置（VS Code Settings）

在编辑器设置中搜索 Codex 或 chatgpt：

设置项说明
chatgpt.commentCodeLensEnabled在 TODO 注释上方显示 CodeLens 按钮，一键让 Codex 完成 TODO
chatgpt.localeOverride界面语言覆盖，留空则自动检测
chatgpt.openOnStartup扩展启动时自动聚焦 Codex 侧边栏
chatgpt.runCodexInWindowsSubsystemForLinux（仅 Windows）在 WSL 中运行 Codex，推荐启用以获得更好的沙箱和性能
chatgpt.cliExecutable（开发者专用）自定义 CLI 可执行文件路径，一般无需设置

9.2 共享配置（config.toml）

以下配置通过 ~/.codex/config.toml 管理，App、CLI、IDE Extension 三端共享：

  • 默认模型 → 所有客户端统一使用
  • 审批策略 → approval_policy 设置
  • 沙箱模式 → sandbox 设置
  • MCP 服务器 → 在任一端配置后全部生效
  • Web 搜索 → 启用/禁用或切换缓存/实时模式
  • Feature Flags → 通过 [flags] 节管理
一处配置，三端生效

在 App 中修改了模型或 MCP 设置后，IDE Extension 和 CLI 会自动使用新配置，无需重复设置。详见系列文章第 09 篇《config.toml 完全指南》。

十、Web 搜索

Codex 内置了 Web 搜索工具，在 IDE Extension 中的行为取决于沙箱模式：

沙箱模式Web 搜索行为说明
默认（Agent）搜索缓存使用 OpenAI 维护的 Web 索引，减少 Prompt 注入风险
Full Access实时搜索获取最新数据，但需注意不可信来源

搜索触发时，你会在 transcript 中看到 web_search 条目。可在 config.toml 中禁用或切换模式。

十一、与 GitHub Copilot 的定位区分

这是一个常见问题：Codex IDE Extension 和 GitHub Copilot 有什么不同？

维度Codex IDE Extension
核心定位编码智能体 — 自主完成多步骤任务
工作方式对话式：描述任务 → Codex 读取/编辑/执行
能力范围读文件、改文件、跑命令、Web 搜索、跨文件重构
执行能力✅ 可执行 shell 命令、运行测试、安装依赖
多步骤任务✅ 自动分解复杂任务，逐步执行
云端委派✅ 可将任务交给 Codex Cloud 执行
与 App 联动✅ Auto Context 同步、线程互通
共存关系可以共存：Copilot 负责行级补全，Codex 负责复杂任务。两者互补而非替代。
简单记忆

Copilot 是「打字时的自动补全」，Codex 是「描述任务后的自主执行」。两者可以同时安装，各司其职。

十二、实战工作流：IDE 中的高效编码循环

场景：在 VS Code 中修复一个跨文件的复杂 Bug

Step 1 — 收集上下文

  1. 打开相关源文件 auth.ts 和 session.ts
  2. 选中错误代码区域 → 使用 chatgpt.addToThread 发送给 Codex
  3. 终端中运行测试 → 测试失败的输出自动可见

Step 2 — 描述问题

在 Codex 聊天中输入：

Text
The session timeout test in @auth.test.ts is failing.
The issue seems to be in the selected code in @session.ts.
Fix the timeout logic and make sure all auth tests pass.

Step 3 — Codex 自主工作

Codex 在 Agent 模式下：

  1. 读取引用的文件和选区
  2. 分析问题根因
  3. 修改 session.ts 中的超时逻辑
  4. 运行 npm test -- auth 验证修复
  5. 如有测试仍失败，继续调整直到通过

Step 4 — 审查与确认

  1. 使用 /review 查看 Codex 的变更
  2. 如需微调，直接在聊天中补充要求
  3. 满意后在终端中运行完整测试套件确认

Step 5 — 需要更多工作时

如果后续还需要重构相关模块，可以使用 /cloud 将较大的重构任务委派到云端，自己继续在 IDE 中处理其他工作。

十三、IDE Extension 速查

IDE Extension 核心能力速查
  • 支持编辑器 → VS Code / Cursor / Windsurf / VS Code Insiders / JetBrains - 三种模式 → Chat（纯对话）/ Agent（默认推荐）/ Agent Full Access（含网络） - 上下文感知 → 代码选区 + @file 引用 + 终端输出 + 图片拖入 - 模型与推理 → 模型切换器 + Low/Medium/High 推理力度 - 云端委派 → /cloud 将任务送入云端 + 本地预览 diff + apply 到本地 - Slash Commands → /auto-context / /cloud / /local / /review / /status / /feedback - 编辑器命令 → addToThread / addFileToThread / implementTodo / newChat - App 同步 → Auto Context + 线程互通 + IDE context 选项 - 设置分层 → 编辑器设置（5 项）+ 共享 config.toml（模型/审批/沙箱/MCP） - Web 搜索 → 默认缓存模式（Agent）/ 实时模式（Full Access）
  • 与 Copilot 共存 → Copilot 补全 + Codex 执行，互补不冲突
下一篇 →