---
title: "调整 IDE 扩展设置"
description: "Codex IDE extension settings 用来调整 IDE 里的 Codex 使用体验。"
verifiedAt: "2026-05-07"
---

> [!NOTE]
> **这一篇用 8 分钟换什么**：把 Codex 的设置面分清楚——哪些归 IDE extension 管（字号、侧边栏、WSL 开关），哪些归 `~/.codex/config.toml` 管（模型、approval、sandbox、网络）。读完之后你不会再把 UI 偏好误当成安全策略。

Codex IDE extension settings 是编辑器里的 Codex 体验层：字体、侧边栏启动、语言偏好、待办 CodeLens、Windows WSL 运行方式。它不是 Codex 的全部配置中心。

真正影响 agent 执行边界的默认模型、approval policy、sandbox mode、network access 等，仍然属于共享的 `~/.codex/config.toml`。**IDE settings 负责编辑器体验，`config.toml` 负责 Codex CLI 和 IDE extension 共用的执行策略。**

```mermaid
flowchart TB
    User["👤 想调整 Codex 行为"]
    Q{"调整什么？"}
    A["📺 UI / 字号 / 启动行为<br/>语言 / WSL 开关"]
    B["🔐 模型 / approval<br/>sandbox / 网络访问"]
    C["⚡ 临时切模式<br/>临时聚焦本任务"]
    IDE["IDE extension settings<br/>VS Code / Cursor / Windsurf"]
    TOML["~/.codex/config.toml<br/>CLI 与 IDE 共享"]
    Session["Codex 面板 / slash<br/>启动参数"]

    User --> Q
    Q -->|UI 体验| A --> IDE
    Q -->|执行边界| B --> TOML
    Q -->|本次会话| C --> Session
```

## Change a setting

修改设置按下面步骤：

1. 打开 editor settings（编辑器设置）。
2. 搜索 `Codex` 或具体 setting name（设置名）。
3. 更新 value（值）。

Codex IDE extension 底层使用 Codex CLI。有些行为不在 editor settings 里配置，而是在共享的 `~/.codex/config.toml` 文件中配置，例如：

- default model（默认模型）
- approval policy（审批策略）
- sandbox settings（沙箱设置）
- network access（网络访问）

配置基础见：

[https://developers.openai.com/codex/config-basic](https://developers.openai.com/codex/config-basic)

Extension 也会遵循 VS Code 内置 chat font settings（聊天字体设置），用于 Codex conversation surfaces（对话界面）。

## 设置分层

实际配置时先分清三层：

| 层级 | 放在哪里 | 适合配置什么 | 不适合配置什么 |
| --- | --- | --- | --- |
| Editor settings | VS Code / Cursor / Windsurf 的 settings | UI 字号、语言、启动行为、WSL 开关、待办 CodeLens | sandbox、approval、默认模型策略 |
| Codex config | `~/.codex/config.toml` | 模型、approval、sandbox、可写目录、网络策略 | 编辑器 UI 偏好 |
| 单次会话 | Codex 面板、slash command、启动参数 | 临时切换模式、临时调整权限、临时聚焦当前任务 | 团队长期默认值 |

这种分层的好处是：团队可以把安全和执行边界写进 `config.toml` 或 managed config，本地用户仍然可以微调 IDE 使用体验，不会把 UI 习惯误当成安全策略。

## Settings reference

| Setting | Description |
| --- | --- |
| `chat.fontSize` | 控制 Codex sidebar 中 chat text（聊天文本）的字号，包括 conversation content（对话内容）和 composer（输入区）。 |
| `chat.editor.fontSize` | 控制 Codex conversations 中 code-rendered content（代码渲染内容）的字号，包括 code snippets（代码片段）和 diffs（差异）。 |
| `chatgpt.cliExecutable` | 仅 development（开发）使用：Codex CLI executable（可执行文件）的路径。除非你正在主动开发 Codex CLI，否则不需要设置。手动设置后，extension 的部分能力可能无法按预期工作。 |
| `chatgpt.commentCodeLensEnabled` | 在 to-do comments 上方显示 CodeLens，让你可以用 Codex 完成这些待办。 |
| `chatgpt.localeOverride` | Codex UI 的 preferred language（首选语言）。留空则自动检测。 |
| `chatgpt.openOnStartup` | Extension 启动完成后，自动 focus（聚焦）Codex sidebar。 |
| `chatgpt.runCodexInWindowsSubsystemForLinux` | 仅 Windows：当 Windows Subsystem for Linux（WSL）可用时，在 WSL 中运行 Codex。当 repositories 和 tooling 位于 WSL2，或你需要 Linux-native tooling 时使用。否则，Codex 可以配合 Windows sandbox 在 Windows 上原生运行。修改这个设置会 reload VS Code，使变更生效。 |

## 关键设置怎么选

### 聊天和代码字号

如果你觉得 Codex 面板里的正文太小，先改 `chat.fontSize`。如果只是代码块、diff、inline code 的字号不合适，改 `chat.editor.fontSize`。

这两个设置来自 VS Code 内置 chat font settings，Codex extension 会遵循它们。它们只影响阅读体验，不影响模型输出、不影响上下文大小，也不改变 diff 的实际内容。

### CLI executable

`chatgpt.cliExecutable` 是 development-only 设置。普通用户不要配置它。

只有在你正在开发 Codex CLI 本身，或者需要让 extension 指向本地构建的 CLI binary 时，才需要设置这个路径。手动指向错误的 executable，可能导致 IDE extension 的部分能力表现异常，例如版本不匹配、命令不可用、面板状态不同步。

### 待办 CodeLens

`chatgpt.commentCodeLensEnabled` 会在待办注释上方显示入口，让你可以直接让 Codex 处理选中的待办项。

适合打开的场景：

- 团队习惯把小修复写成待办注释。
- 你希望从代码附近直接发起任务，不想先复制上下文到 chat。
- 你在整理技术债，希望逐条把待办变成可执行任务。

不适合打开的场景：

- 仓库里历史待办注释很多，编辑器界面已经很拥挤。
- 团队把待办注释当作长期注释，而不是行动项。
- 你正在录屏或演示，不希望页面出现额外 CodeLens。

### Language override

`chatgpt.localeOverride` 控制 Codex UI 的首选语言。留空时自动检测。

教程站、双语团队或中文开发者常见做法是：UI 可以保持中文，但 prompt、命令、文件路径、错误文本保留英文原文。这样既方便阅读，也不丢失技术细节。

### Open on startup

`chatgpt.openOnStartup` 会在 extension 启动完成后聚焦 Codex sidebar。

如果你的 IDE 主要用来和 Codex 协同开发，可以打开；如果你经常只想快速看代码，建议关闭，避免每次启动都打断当前文件视图。

### Windows WSL 模式

`chatgpt.runCodexInWindowsSubsystemForLinux` 是 Windows-only 设置。开启后，只要 WSL 可用，Codex 就在 WSL 中运行。

适合开启：

- 仓库实际位于 WSL2 文件系统。
- 构建、测试、包管理都依赖 Linux 工具链。
- 你希望 IDE extension 的命令、审批、文件访问语义和 Linux sandbox 更一致。

适合保持关闭：

- 仓库和工具链都在 Windows 原生环境。
- 你正在使用 Windows sandbox。
- 团队成员不统一使用 WSL2，配置后反而增加环境差异。

修改这个设置会 reload VS Code 才生效。

## 推荐配置流程

1. 先安装 Codex IDE extension，并确认能登录。
2. 打开一个真实项目，用默认设置完成一次小任务，例如解释项目结构。
3. 只调整 UI 类设置：字号、语言、是否启动自动打开。
4. 如果是在 Windows 上，再决定是否强制 WSL2。
5. 把模型、sandbox、approval、network access 放回 `~/.codex/config.toml` 管理。
6. 调整后重开 IDE，跑一次只读任务和一次小 diff 任务确认行为符合预期。

## 常见误区

| 误区 | 正确理解 |
| --- | --- |
| 在 IDE settings 里能配置所有 Codex 行为 | IDE settings 只覆盖 extension 体验层，执行策略主要在 `config.toml` |
| 改字体会影响模型输出 | 字号只影响显示，不影响上下文和生成结果 |
| 普通用户需要设置 `chatgpt.cliExecutable` | 这是开发 Codex CLI 时才需要的设置 |
| Windows 用户一定要开 WSL | 只有仓库或工具链在 WSL2 时才优先考虑 |
| 打开 `openOnStartup` 会让 Codex 自动工作 | 它只聚焦侧边栏，不会自动执行任务 |

## 自检清单

- 你是否知道哪些设置属于 IDE，哪些属于 `~/.codex/config.toml`？
- Windows 用户是否确认仓库位置和工具链是在 Windows 还是 WSL2？
- 是否避免给 `chatgpt.cliExecutable` 配一个不确定的路径？
- 调整后是否至少跑过一次只读任务和一次小修改任务？
- 团队共享配置是否没有被个人 UI 偏好污染？

## 官方资料

- [Codex IDE extension](https://developers.openai.com/codex/ide)
- [Codex IDE extension settings](https://developers.openai.com/codex/ide/settings)
- [Config basics](https://developers.openai.com/codex/config-basic)

## 接下来去哪

<Cards>
  <Card title="安装 IDE 扩展" href="/docs/codex/official/01-products/20-ide-install" description="先把 extension 装上再来调设置" />
  <Card title="IDE 功能总览" href="/docs/codex/official/01-products/21-ide-features" description="知道 extension 能干什么再决定怎么调" />
  <Card title="IDE 命令" href="/docs/codex/official/01-products/23-ide-commands" description="设置之外的另一类入口：可调用命令" />
  <Card title="config.toml 基础" href="/docs/codex/official/02-config-security/06-basic-config" description="模型 / approval / sandbox 真正的家" />
  <Card title="安全模型" href="/docs/codex/official/02-config-security/72-security-model" description="UI 不是安全边界，安全边界在这里" />
  <Card title="安全运行时" href="/docs/codex/official/02-config-security/73-secure-runtime" description="把 sandbox 和网络策略一并装好" />
</Cards>
