VS Code 安装配置 Codex 插件指南（Windows / macOS，含 XAI Router）

本文面向在 VS Code 中使用 Codex 的开发者，分别说明 macOS、Windows + WSL、Windows Native 三种运行方式下的配置方法。

先看结论（30 秒版）

核心原则：

1. 插件设置 决定 Codex 在哪儿运行。
2. config.toml 决定模型、Provider、审批策略、沙箱等核心行为。
3. Windows 一旦切到 WSL，生效的就不再是 Windows 用户目录里的 .codex，而是 WSL 里的 ~/.codex。

一、先搞清楚：哪些配置归 VS Code，哪些配置归 Codex

先把这两层配置分清楚。

1）VS Code 侧的设置，负责“跑在哪”

这类设置写在 VS Code settings.json，主要是运行方式相关：

• 是否在 Windows 上把 Codex 跑进 WSL：chatgpt.runCodexInWindowsSubsystemForLinux
• 是否指定一个自定义 CLI 可执行文件：chatgpt.cliExecutable

第二项通常不需要改。 chatgpt.cliExecutable 更适合 自定义 CLI 路径或调试场景，不是普通开发者日常安装后必须配置的入口。

2）Codex 侧的设置，负责“怎么跑”

这类配置写在 config.toml，包括：

• model_provider
• model
• approval_policy
• sandbox_mode
• model_providers.*
• features.*

也就是说，你在 VS Code 里使用 Codex，本质上仍然是在用同一套 Codex 配置体系。 这也是为什么很多关键能力并不应该去 VS Code 设置里找，而应该去改 config.toml。

二、先装通用部分

1）安装 VS Code 扩展

官方扩展：

• 扩展 ID：openai.chatgpt
• Marketplace：https://marketplace.visualstudio.com/items?itemName=openai.chatgpt
• 官方 IDE 文档：https://developers.openai.com/codex/ide

如果你只想在 VS Code 里使用 Codex，先装扩展即可。

2）如果你还想在终端里直接用 codex

这是可选项，不是这篇插件配置文档的强制前置条件。

• macOS：可用 Homebrew 或 npm 安装
• Windows：官方开源 CLI 文档仍然以 WSL2 作为主推荐路径

常见命令示例：

# macOS
brew install --cask codex

# Linux / WSL
npm install -g @openai/codex

三、先准备一份共用的 config.toml（XAI Router 示例）

如果你用的是 XAI Router，可以先从下面这份开始。

model_provider = "xai"
model = "gpt-5.4"
model_reasoning_effort = "xhigh"
plan_mode_reasoning_effort = "xhigh"
model_reasoning_summary = "detailed"
model_verbosity = "high"
approval_policy = "on-request"
sandbox_mode = "workspace-write"

[model_providers.xai]
name = "xai"
base_url = "https://api.xairouter.com"
wire_api = "responses"
requires_openai_auth = false
env_key = "XAI_API_KEY"

[features]
multi_agent = true

这个示例完成了四件事：

1. 默认 Provider 走 xai
2. 默认模型用 gpt-5.4
3. 认证不走 OpenAI 登录，而是直接读环境变量 XAI_API_KEY
4. 默认用更稳妥的交互式权限组合：on-request + workspace-write

如果你想先跑通最小配置

你可以先把 [features] 整段去掉，再确认主流程是否跑通。

这样会更接近最基础的 Responses 配置。

如果你需要更高权限

有些高级用户会把权限改成：

approval_policy = "never"
sandbox_mode = "danger-full-access"

这会让代理更激进，但风险也更高。 如果是团队电脑、生产仓库或你不想让模型自动执行高权限操作，建议仍然保留 on-request + workspace-write。

四、团队共享配置怎么放

OpenAI 的配置体系并不只支持用户级 ~/.codex/config.toml，也支持项目级 .codex/config.toml。

一个实用的分工方式是：

1. 用户级 config.toml：放个人默认项，例如 Provider、模型、审批偏好
2. 仓库内 .codex/config.toml：放项目特定覆盖，例如某个仓库专用的 MCP、规则或模型偏好

这在 Windows + WSL 下尤其重要：

• 如果仓库是从 WSL 里打开的，就要看 WSL 视角下 的项目路径
• 如果仓库是 Windows Native 打开的，就要看 Windows 视角下 的项目路径

项目级配置也遵循同样规则：Codex 跑在哪个环境里，就读那个环境看到的 .codex/config.toml。

五、macOS 下的 VS Code Codex 插件配置细节

如果你是 macOS 用户，这条路径最简单：直接本机运行。

1）创建并编辑 config.toml

mkdir -p ~/.codex
vi ~/.codex/config.toml

把上一节的 XAI Router 配置写进去即可。

2）设置 XAI_API_KEY

macOS 默认 shell 多数是 zsh，优先写入 ~/.zshrc：

echo 'export XAI_API_KEY="你的真实密钥"' >> ~/.zshrc
source ~/.zshrc

如果你平时用 bash，则改成：

echo 'export XAI_API_KEY="你的真实密钥"' >> ~/.bashrc
source ~/.bashrc

3）VS Code 一般不用额外开关

在 macOS 下，通常不需要额外改 VS Code settings.json。

下面这类设置先不要碰：

• chatgpt.cliExecutable

除非你是在调试自己的 Codex CLI 构建版本，否则常规使用下不建议设置它。

4）如果你还想在终端直接使用 Codex CLI

可以再装一份 CLI：

brew install --cask codex
codex --version
which codex

5）重启 VS Code 并验证

建议完整重启一次 VS Code，然后打开项目测试：

• “解释当前仓库结构”
• “为这个函数补充测试”
• “搜索并修复这个报错”

如果这些请求都能正常工作，macOS 侧基本就已经配置完成。

六、Windows 下的 VS Code Codex 插件配置细节（推荐：WSL）

Windows 这部分最重要的不是“怎么写 config.toml”，而是先决定：你是不是让 Codex 跑在 WSL 里。

对于大多数写代码的人，推荐答案是：是。

1）先装 WSL 和 VS Code 的 WSL 扩展

管理员 PowerShell：

wsl --install

然后安装 VS Code 扩展：

• ms-vscode-remote.remote-wsl
• Marketplace：https://marketplace.visualstudio.com/items?itemName=ms-vscode-remote.remote-wsl

2）从 WSL 里打开项目

在 WSL 终端中进入项目目录：

code .

尽量把项目放在 WSL 自己的 Linux 文件系统里，例如：

~/code/my-project

而不是长期放在：

/mnt/c/Users/...

这样通常会更稳定，I/O 行为也更接近真实 Linux 开发环境。

3）打开 VS Code 的 WSL 运行开关

在 VS Code settings.json 中加入：

{
  "chatgpt.runCodexInWindowsSubsystemForLinux": true
}

这个设置的意义非常直接：

1. 告诉扩展优先在 WSL 中运行 Codex
2. 一旦你启用了它，后面应该去改的就是 WSL 内部 的 ~/.codex/config.toml
3. 此时 Windows 用户目录下的 %USERPROFILE%\.codex\config.toml 不再是主配置入口

4）在 WSL 内创建并编辑 config.toml

mkdir -p ~/.codex
vi ~/.codex/config.toml

把第三节那份配置写到 WSL 内的这个文件里，不要写到 Windows 用户目录。

5）在 WSL 内设置 XAI_API_KEY

如果你的 WSL 默认 shell 是 bash：

echo 'export XAI_API_KEY="你的真实密钥"' >> ~/.bashrc
source ~/.bashrc

如果你装了 zsh，就写到 ~/.zshrc。

6）如果你也要在 WSL 终端里直接跑 codex

这一步同样是可选的；如果你只是用 VS Code 扩展，不一定非要手动装。

npm install -g @openai/codex
codex --version
which codex

7）重启 VS Code 再测试

建议按照下面顺序做一次完整切换：

1. 关闭所有 VS Code 窗口
2. 回到 WSL 目录重新执行 code .
3. 在状态栏确认当前窗口是 WSL: <你的发行版>
4. 再发起第一条 Codex 请求

如果这一步仍然不生效，优先检查的不是模型配置，而是：你现在打开的是不是 WSL Remote 窗口。

七、Windows Native 下的配置细节（只在你明确不用 WSL 时）

如果你就是想让 Codex 跑在 Windows 本机，而不是 WSL，那么配置逻辑也很明确。

1）用户级配置文件位置

这时要改的是：

%USERPROFILE%\.codex\config.toml

例如：

C:\Users\Alice\.codex\config.toml

PowerShell 中创建并打开：

New-Item -ItemType Directory -Force $HOME\.codex
notepad $HOME\.codex\config.toml

2）把 API Key 写进 Windows 环境变量

当前 PowerShell 会话：

$env:XAI_API_KEY = "你的真实密钥"

写入用户环境变量：

setx XAI_API_KEY "你的真实密钥"

设置完后重新打开 PowerShell / VS Code。

3）不要再开 WSL 运行开关

如果你走的是 Windows Native，就不要开启：

{
  "chatgpt.runCodexInWindowsSubsystemForLinux": true
}

否则你会出现“明明改了 %USERPROFILE%\.codex\config.toml，为什么插件不理我”的经典问题。

4）什么时候不建议走 Windows Native

如果你主要依赖这些东西，还是建议回到 WSL：

• bash / zsh 工作流
• GNU 工具链
• Linux Node / Python / Rust 生态
• 与 CI 更一致的 Linux 环境

Windows Native 更适合你本来就主要在 PowerShell / 原生 Windows 工具链里工作。

八、常见误区

1）把配置写进了错误的操作系统环境

这是第一常见错误：

• 你在 WSL 运行 Codex，却去改 %USERPROFILE%\.codex\config.toml
• 你在 Windows Native 运行 Codex，却去改 WSL 里的 ~/.codex/config.toml

2）把 API Key 配到了错误的 shell 启动文件

例如：

• macOS 用的是 zsh，你却只改了 ~/.bashrc
• VS Code 跑在 WSL，结果你只在 Windows 里设置了 XAI_API_KEY

3）把 chatgpt.cliExecutable 当成常规配置入口

如果你不是在调试自己的 Codex CLI，可先把它留空。 这项设置最容易把简单问题复杂化。

4）只改了模型配置，却忘了 Provider 认证方式

如果你走的是 XAI Router，关键不只是模型名，还包括：

requires_openai_auth = false
env_key = "XAI_API_KEY"

少了这两项中的任意一个，插件可能会继续按默认 OpenAI 登录逻辑处理。

5）仓库明明在 Windows 盘，却希望获得完整 Linux 开发体验

不是绝对不行，但通常更容易遇到性能和权限边界问题。 如果你已经决定走 WSL 工作流，尽量把仓库也放在 WSL 文件系统里。

推荐默认方案

对大多数开发者，推荐直接按下面这套来：

• macOS：直接本机运行，改 ~/.codex/config.toml
• Windows：优先走 WSL + VS Code Remote，改 WSL 里的 ~/.codex/config.toml
• chatgpt.cliExecutable：除非你在调试 CLI，否则先不要动
• XAI Router：用 requires_openai_auth = false + env_key = "XAI_API_KEY"

这样配置后，VS Code 插件和 Codex CLI 的行为会更一致，后续再增加项目级 .codex/config.toml、MCP 或多代理能力也更容易维护。