Codex 配置故障排查与修复报告

2026-10-13

概述

Codex 在创建任务时因配置文件损坏和端口冲突导致无法启动服务。涉及两个独立问题：

  1. TOML 配置解析失败 — 项目路径中文编码损坏导致 unclosed table 语法错误
  2. 端口 18090 被 Windows 系统保留 — Hyper-V/NAT 驱动预留端口范围，应用程序无法绑定

问题一：TOML 配置解析失败

错误现象

failed to load configuration: C:\Users\用户名\.codex\config.toml:70:50: unclosed table, expected `]`

根因分析

config.toml 第 70 行附近的项目路径中文字符因编码错乱变成了乱码：

位置 原始正确路径 损坏后的乱码
[projects.'c:\users\用户名\desktop\...']（第 70 行） 第十届御网杯 缁楊剙宕勭仦濠傚敖缂冩垶婢?
[projects.'d:\claudecode\work\doc-process\...']（第 106 行） 实训报告 瀹炶鎶ュ憡
[projects.'d:\claudecode\work\...']（第 109 行） 商道系统 鍟嗛亾绯荤粺

损坏原因推测：文件在保存时使用的编码与 TOML 解析器期望的编码不一致（如以 GBK/GB2312 编码写入，但以 UTF-8 解析），导致多字节中文字符被错误解码。

解决方法

将乱码路径还原为原始中文路径。修复后配置格式正确，TOML 解析通过。

涉及文件

  • C:\Users\用户名\.codex\config.toml — 主配置文件（已修复）

问题二：端口 18090 被占用

错误现象

监听内置后端 127.0.0.1:18090 失败: listen tcp 127.0.0.1:18090: bind: An attempt was made to access a socket in a way forbidden by its access permissions.

根因分析

Windows 系统的 NAT 驱动（winnat） 自动将 18089-18188 这段端口声明为系统保留范围（Excluded Port Range），导致任何用户态程序都无法绑定端口 18090。

保留范围快照（修复前已备份）：

开始端口    结束端口
----------    --------
18089       18188      ← 包含 18090

该保留范围由 Windows NAT（winnat）驱动在启动时动态生成，通常由 Hyper-V、Docker Desktop、WSL2 等虚拟化组件触发创建。即使这些组件已停止，保留范围仍然生效。

解决方法

重启 winnat 服务以清除动态保留端口范围。重启后 winnat 会重新加载，不再保留 18089-18188 范围（除非有激活的 Hyper-V/WSL2 虚拟机正在使用它们）。

执行命令（需要 管理员权限）：

net stop winnat
netsh int ipv4 delete excludedportrange protocol=tcp startport=18089 numberofports=100
net start winnat

验证方法

重启服务后查询保留端口范围，确认 18089-18188 不再出现：

netsh int ipv4 show excludedportrange protocol=tcp

标准化操作步骤

  1. 修复 TOML 配置
  2. 打开 C:\Users\用户名\.codex\config.toml
  3. 检查 [projects.'...'] 段中的路径是否存在乱码

  4. 将乱码还原为实际存在的路径（或删除不存在的项目条目）

  5. 释放端口 18090（以管理员身份运行） cmd net stop winnat net start winnat

    如果 net stop winnat 失败，尝试先停止 Hyper-V 服务或 Docker Desktop。

  6. 重启 Codex 并验证

注意事项

winnat 服务重启的影响

  • Docker Desktop：如果 Docker 正在运行，重启 winnat 会中断容器网络连接。此时 Docker 会自行恢复，容器可能需要重启。
  • WSL2：如果 WSL2 正在运行且使用了 NAT 网络，连接会短暂中断。建议先通过 wsl --shutdown 停止 WSL2。
  • Hyper-V 虚拟机：运行中的 Hyper-V 虚拟机网络会受影响。建议先关闭相关虚拟机。
  • Windows 防火墙：不受影响。
  • 本环境 Docker Desktop 和 WSL2 均为 Stopped 状态，重启 winnat 安全。

备份恢复方法

备份文件 用途
config.toml.bak-localhost-3688-20260602-204646 初始配置备份
config.toml.bak-portfix-20260611-181536 portfix 修改前的配置
config.toml.bak-portfix2-20260611-181746 portfix2 修改前的配置
excluded-port-range-backup-before-winnat-restart.txt 端口保留范围快照

如需恢复端口保留范围：

netsh int ipv4 add excludedportrange protocol=tcp startport=18089 numberofports=100

预防建议

  1. 配置文件的编辑建议使用 UTF-8 编码（带 BOM），避免编码转换导致中文字符损坏
  2. 避免使用 18090 等可能落在系统保留动态范围内的端口。范围通常为 1024-13911 中的两段，建议选择 14000 之后的端口以减少冲突概率
  3. 修改配置文件前先备份

参考

  • C:\Users\用户名\.codex\config.toml — Codex 主配置文件
  • Windows winnat 驱动文档：Windows NAT Driver (WinNAT)
  • TOML 规范 v1.0.0：表（Table）的键名必须正确编码

← 返回文章列表