从零开始：WSL + Codex + 自定义网关完全配置与卸载指南

SHUIPING_YANG

433人浏览 · 2026-06-13 07:36:18

SHUIPING_YANG · 2026-06-13 07:36:18 发布

从零开始：WSL + Codex + 自定义网关完全配置与卸载指南

本文将带你一步步完成从安装 WSL 到配置 Codex 并连接自定义 API 网关的全过程，同时包含完整的卸载与清理步骤，适合初学者和遇到配置问题的开发者。

1. 环境准备

Windows 10/11（建议 22H2 及以上）
稳定的网络连接（可能需要代理）
一个可用的自定义 API 网关地址（如 https://ss.sdf.ai/v1）和 API Key

2. 安装 WSL 和 Ubuntu

2.1 启用 WSL 功能

以管理员身份打开 PowerShell，执行：

dism.exe /online /enable-feature /featurename:Microsoft-Windows-Subsystem-Linux /all /norestart
dism.exe /online /enable-feature /featurename:VirtualMachinePlatform /all /norestart

重启电脑。

2.2 设置 WSL 2 为默认版本

wsl --set-default-version 2

2.3 安装 Ubuntu 发行版

wsl --install -d Ubuntu

安装完成后，系统会提示你设置用户名和密码。请记住它们。

2.4 启动 Ubuntu

在 PowerShell 中输入 wsl 或者从开始菜单打开 Ubuntu 图标。

进入 Ubuntu 后，先更新软件源：

sudo apt update && sudo apt upgrade -y

可选：若遇到 0x8007273d 网络错误，请在 Windows 中以管理员身份运行 netsh winsock reset 并重启。

3. 安装 Codex CLI

3.1 安装 Node.js（推荐使用 nvm）

# 安装 nvm
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash
# 重启终端或执行 source ~/.bashrc
source ~/.bashrc
# 安装 Node.js 20 LTS
nvm install 20
nvm use 20

3.2 全局安装 Codex

npm install -g @openai/codex

验证安装：

codex --version

3.3 安装沙箱依赖（可选但推荐）

sudo apt install -y bubblewrap

此步骤可消除启动时的警告。

4. 配置 Codex 使用自定义网关

4.1 创建配置文件

Codex 的用户级配置文件位于 ~/.codex/config.toml。执行：

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

4.2 写入完整配置

将以下内容粘贴进去，务必替换 base_url 和 api_key：

# ===== 全局设置 =====
model = "gpt-5.5"                     # 模型名称（根据你的网关支持）
model_provider = "custom"             # 启用自定义提供商
model_reasoning_effort = "high"
preferred_auth_method = "apikey"      # 跳过 ChatGPT 登录，强制使用 API Key
disable_response_storage = true

# ===== 自定义网关配置 =====
[model_providers.custom]
name = "custom"
base_url = "https://your-gateway.com/v1"   # 替换为实际网关地址
wire_api = "responses"                     # Codex 基于 Responses API
api_key = "sk-your-real-api-key"           # 替换为真实 API Key

# 或者使用环境变量（更安全，二选一即可）
# env_key = "CUSTOM_API_KEY"

# ===== 项目信任设置（示例）=====
[projects."/mnt/d/WWW/ProjectsPython"]
trust_level = "trusted"

# ===== TUI 提示计数（保留）=====
[tui.model_availability_nux]
"gpt-5.5" = 4

保存：Ctrl+O，回车；退出：Ctrl+X。

4.3 可选：使用环境变量存储 Key

若不想明文写 Key，修改配置中 api_key 行为：

[model_providers.custom]
# 删除 api_key 行，改为：
env_key = "CUSTOM_API_KEY"

然后在 ~/.bashrc 末尾添加：

export CUSTOM_API_KEY="sk-your-real-api-key"

执行 source ~/.bashrc。

4.4 启动 Codex

在终端输入 codex，应该直接进入对话界面，不再出现登录提示。

5. 验证与调试

5.1 检查运行时配置

在 Codex 对话界面中输入：

/debug-config

查看输出中 model_provider 是否为 custom，base_url 是否为你的网关地址。

5.2 发送测试消息

随便问一个问题，观察响应是否来自你的自定义网关。你也可以检查网关的日志。

5.3 常用调试命令

命令	作用
`codex --version`	查看版本
`cat ~/.codex/config.toml`	查看配置文件
`codex config show`	显示合并后的配置（部分版本支持）
`env \| grep -i key`	查看环境变量中的 Key

6. 常见错误及解决

错误现象	可能原因	解决方案
启动后出现 ChatGPT 登录界面	未设置 `preferred_auth_method = "apikey"` 或未配置 `api_key`	在配置文件中添加该行并填写正确 Key
请求仍然发往 `api.openai.com`	未设置 `model_provider = "custom"` 或配置未生效	检查配置文件位置和语法，重启 Codex
`401 Incorrect API key provided`	网关的 Key 无效或配置中的 `api_key` 错误	确认 Key 正确，或者网关是否需要不同的鉴权方式
`could not find bubblewrap`	未安装沙箱依赖	`sudo apt install bubblewrap`
WSL 网络错误 `0x8007273d`	代理软件冲突	管理员 PowerShell 执行 `netsh winsock reset` 后重启
连接 `localhost` 失败	WSL 中 localhost 指向容器内部	使用 `ip route show default` 获取宿主机 IP，替换配置中的 `base_url`

7. 完全卸载与清理

如果需要彻底移除 WSL 和 Codex，请按顺序执行。

7.1 卸载 Codex

npm uninstall -g @openai/codex

删除配置文件：

rm -rf ~/.codex
rm -rf ~/.npm

7.2 卸载 Node.js 和 nvm

rm -rf ~/.nvm
# 删除 ~/.bashrc 中与 nvm 相关的行

7.3 卸载 WSL 发行版

在 PowerShell（管理员）中：

# 查看已安装的发行版
wsl --list --verbose

# 注销 Ubuntu（会删除所有数据）
wsl --unregister Ubuntu

# 如果有 docker-desktop 等，也一并注销
wsl --unregister docker-desktop
wsl --unregister docker-desktop-data

7.4 禁用或卸载 WSL 功能

在 PowerShell（管理员）中：

# 禁用 WSL 功能（可选）
dism.exe /online /disable-feature /featurename:Microsoft-Windows-Subsystem-Linux /norestart
dism.exe /online /disable-feature /featurename:VirtualMachinePlatform /norestart