𝐗𝐀𝐈 𝐂𝐨𝐧𝐭𝐫𝐨𝐥

Windows 上在 VS Code 安装配置 Codex 插件（含 XAI Router 配置）

Posted March 3, 2026 by XAI 技术团队 ‐ 6 min read

很多人已经在终端里使用 Codex，但更高频的工作流其实是在 IDE 内完成：边看代码、边对话、边执行修改。 本文提供一份可以直接落地的 Windows + VS Code 指南，覆盖安装、配置、验证和常见问题。

提示：截至 2026-03-04 的官方说明，Windows 原生支持仍偏实验性质； 在 Windows 上使用 Codex 的最佳实践是：VS Code + WSL2。

你将获得什么

完成本文后，你会得到：

  1. VS Code 内可用的 Codex 插件（openai.chatgpt）。
  2. 稳定的 WSL 运行环境（推荐）。
  3. 一份可直接使用的 ~/.codex/config.toml（XAI Router 方案）。
  4. 常见错误的快速排查路径。

一、先决条件

请先确认以下条件：

  1. Windows 11（或支持 WSL2 的 Windows 10）。
  2. 已安装 VS Code。
  3. 可用的 Node.js 环境（用于安装 Codex CLI）。
  4. 你的 XAI API Key（例如通过 XAI Router / XAI Control 获取）。

二、安装 VS Code 插件

Codex 在 VS Code 中由官方扩展承载：

安装完成后，在 VS Code 左侧活动栏可以看到对应入口。 如果没有出现，重启一次 VS Code。

三、在 Windows 上推荐启用 WSL2

1）安装 WSL

以管理员身份打开 PowerShell：

wsl --install

安装完成后重启系统，首次进入 WSL 完成 Linux 用户初始化（Ubuntu 是常见选择）。

2）安装 VS Code 的 WSL 扩展

安装微软官方扩展：

3）从 WSL 终端打开项目

在 WSL 终端中进入你的项目目录后执行：

code .

请尽量把仓库放在 WSL 的 Linux 文件系统里（如 ~/code/...）， 避免放在 /mnt/c/...，否则 I/O 性能和权限行为会更差。

四、安装 Codex CLI（在 WSL 内执行）

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

如果 which codex 没有输出，通常是 Node 全局 bin 目录没进 PATH， 优先修复 PATH 后再继续。

五、配置 ~/.codex/config.toml（XAI Router 版本）

在 WSL 中创建并编辑：

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

写入以下配置：

model_provider = "xai"
model = "gpt-5.3-codex"
model_reasoning_effort = "xhigh"
plan_mode_reasoning_effort = "xhigh"
model_reasoning_summary = "detailed"
model_verbosity = "high"
approval_policy = "never"
sandbox_mode = "danger-full-access"
suppress_unstable_features_warning = true

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

[features]
responses_websockets_v2 = true
multi_agent = true

关于安全策略的建议

上面配置中的这两项权限较高：

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

如果你希望更安全，建议改成：

approval_policy = "on-request"
sandbox_mode = "workspace-write"

六、设置 API Key 环境变量（WSL 内）

你的 provider 使用了 env_key = "XAI_API_KEY"，因此需要在 WSL 环境里注入密钥：

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

可用下面命令确认变量已生效：

echo $XAI_API_KEY | sed 's/./*/g'

七、VS Code 里打开 WSL 模式开关

打开 VS Code settings.json，加入：

{
  "chatgpt.runCodexInWindowsSubsystemForLinux": true
}

说明：

  1. 该开关用于让插件优先在 WSL 中运行 Codex。
  2. 不建议设置 chatgpt.cliExecutable，这个选项主要用于 Codex CLI 开发调试。

八、首次启动与使用

完成上面步骤后，执行一次完整重启：

  1. 关闭所有 VS Code 窗口。
  2. 重新从 WSL 目录执行 code . 打开项目。
  3. 在 Codex 面板中发起第一次对话。

你可以用这些任务测试环境是否正常：

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

九、常见问题

1）插件装好了但没有反应

优先检查：

  1. 当前窗口是否是 WSL Remote（状态栏应显示 WSL: <发行版>）。
  2. WSL 内 codex --version 是否正常。
  3. 重启 VS Code 后是否恢复。

在极少数情况下，Windows 侧可能缺失构建依赖，可考虑安装 VS Build Tools 后重启编辑器。

2）VS Code in WSL 找不到 codex

在 WSL 终端检查：

which codex
codex --version

如果找不到，通常是 npm 全局安装路径未加入 PATH。

3）为什么我在 Windows 写了 C:\Users\...\.codex\config.toml 但不生效？

因为当你启用了 WSL 模式，Codex 读取的是 WSL 内部 的 ~/.codex/config.toml， 不是 Windows 用户目录下的 .codex。

十、补充：如果你坚持原生 Windows 运行

可以，但需要知道：

  1. 官方将 Windows 原生路径定义为可用但更偏实验性。
  2. 更推荐 WSL 模式，尤其是 agent 工作流。
  3. 若你使用原生 Windows，配置目录通常在 %USERPROFILE%\\.codex，并需要在 Windows 环境里设置 XAI_API_KEY。

结语

如果你主要在 Windows 上开发，最省心的组合是：

  • VS Code 插件：openai.chatgpt
  • 运行环境：WSL2
  • 配置文件：WSL ~/.codex/config.toml
  • 鉴权方式：XAI_API_KEY 环境变量

这样既能获得插件内工作流，也能复用 Codex CLI 的全部能力，并保持和团队配置一致。