企业官网建设流程全解析

1. Codex 不是装完就跑——先搞清它到底在跑什么

Codex 这个名字，最近半年在开发者圈子里出现频率高得有点反常。不是 GitHub Copilot 那种开箱即用的 IDE 插件，也不是某个云厂商打包好的 SaaS 服务，而是一个需要你本地搭环境、配依赖、调接口、甚至改配置才能真正“活起来”的工具链。很多人卡在“npm install -g codex”回车成功之后，一执行codex --version或codex serve就报错，第一反应是“我是不是装错了”，其实问题根本不在安装命令本身——而在于你根本没意识到 Codex 启动时到底在做什么。

它不是单个可执行文件，而是一套运行时依赖明确、上下文强耦合的 Node.js 应用。它的核心行为可以拆成三步：加载本地配置 → 连接模型后端（通常是 HTTP 接口）→ 启动本地 Web 服务或 CLI 代理层。这三步里任何一环断掉，都会表现为“装好了但跑不起来”。比如你看到cc switch local proxy failed while handling codex endpoint /responses，这不是 Codex 自己崩了，而是它试图把请求转发给下游模型服务时，连不上那个地址；再比如gloo报错应该如何改，Gloo 是 Codex 内部用的轻量级代理网关，报错说明它启动时读取路由规则失败，根源可能是 config.yaml 里写了不存在的 provider 名称，或者 YAML 缩进错了两个空格。

我第一次部署 Codex 时，在 macOS 上装完 npm 包，直接敲codex serve，结果报Error: Cannot find module 'mysql'。我当时懵了：我又没连数据库，怎么还要 mysql？后来翻源码才发现，Codex 默认启用了“会话持久化”功能，而它的 SQLite 适配层底层用了mysql2包做通用 SQL 抽象——不是真连 MySQL，而是借它的连接池和查询构造器能力来操作本地 SQLite 文件。这种“表面无关、底层强依赖”的设计，在 Codex 里非常普遍。所以排查报错，不能只看错误字面意思，得一层层剥开它的运行时依赖树。

这也是为什么单纯搜“codex安装教程”容易踩坑：90% 的教程只教你npm install -g codex和codex init，却没人告诉你codex init生成的.codexrc里provider字段填什么才算合法，也没人提醒你codex serve启动前必须确保PORT=3000环境变量没被其他进程占着。真正的门槛不在安装命令，而在启动那一刻的上下文完整性。接下来要解决的，不是“怎么修某个报错”，而是建立一套能覆盖所有高频故障点的排查逻辑——从环境底座，到配置语义，再到网络通路，最后落到模型服务本身的可用性。

2. 环境底座塌陷：Node.js + npm 的 5 类隐性冲突

Codex 对 Node.js 版本和 npm 行为有明确且严格的约束。它不是“Node.js 能跑就行”，而是要求特定版本区间内的 ABI 兼容性、V8 引擎特性支持，以及 npm 的包解析策略。很多报错表面看是 Codex 报的，实际根子在环境底座上。我把这类问题归为“底座塌陷”，因为一旦这里出问题，后续所有步骤都是空中楼阁。

2.1 Node.js 版本错位：LTS ≠ 通用兼容

Codex 官方文档写着“支持 Node.js 18+”，但实测下来，18.20.4 LTS 是目前最稳的版本，22.x 系列（包括 22.12+）存在三个硬伤：

• V8 引擎升级导致vm.Script模块对动态代码求值的沙箱策略收紧，Codex 的插件热加载机制会抛ERR_VM_MODULE_NOT_FOUND；
• fetchAPI 在全局作用域默认启用，而 Codex 的某些中间件仍依赖node-fetchv2，两者共存时触发ReferenceError: fetch is not defined；
• process.versions输出中新增openssl字段格式变化，Codex 的证书校验模块解析失败，表现为SSL_ERROR_SSL类错误。

我试过用 nvm 切换到 22.12，执行codex serve直接卡在Loading providers...无响应，strace跟踪发现它在反复尝试读取/dev/random却超时。换成 18.20.4 后，同一台机器秒启。这不是 Codex 的 bug，而是 Node.js 22 对加密模块的底层重构与 Codex 未适配的必然结果。

提示：不要迷信“最新版最稳定”。Codex 的更新节奏慢于 Node.js 主线，建议严格锁定18.20.4。验证方式：node -v输出必须是v18.20.4，多一位少一位都不行。用nvm install 18.20.4 && nvm use 18.20.4确保全局生效。

2.2 npm 权限与策略冲突：PowerShell 执行策略拦路

Windows 用户最常遇到的报错是npm : 无法加载文件 C:\Program Files\nodejs\npm.ps1，因为在此系统上禁止运行脚本。这不是 Codex 的问题，而是 Windows PowerShell 默认执行策略（ExecutionPolicy）设为Restricted，禁止运行任何本地脚本，包括 npm 自带的 PowerShell 封装器。

解决方案不是关掉安全策略（危险！），而是让 npm 绕过 PowerShell，直接走 cmd。执行：

npm config set script-shell "C:\\Windows\\System32\\cmd.exe"

这条命令会修改 npm 的全局配置，让所有npm run命令不再调用npm.ps1，而是用 cmd 解析。验证方式：npm config get script-shell输出应为C:\Windows\System32\cmd.exe。

注意：如果之前手动改过PATH环境变量，把C:\Program Files\nodejs\放在了C:\Windows\System32\前面，会导致系统优先找到npm.cmd而非npm.ps1，此时反而不会报这个错——但可能引发后续npm install时权限不足的问题。务必检查echo %PATH%中 nodejs 路径的位置。

2.3 npm 镜像源与 peer dependency 冲突

npm warn eresolve overriding peer dependency这类警告看似无害，但在 Codex 场景下是重大隐患。Codex 依赖的@codex/core包声明了peerDependencies: { "express": "^4.18.0" }，而如果你用国内镜像源（如 taobao、npmmirror）安装，npm 7+ 的自动解析策略会强制降级express到4.17.3以满足“所有依赖树兼容”，结果就是 Codex 启动时require('express')找不到Router.handle方法，报TypeError: app.use is not a function。

解决方法只有两个：

1. 换源不换策略：用npm install --legacy-peer-deps强制沿用 npm 6 的 peer dep 处理逻辑；
2. 精准锁版本：在项目根目录建package.json，写死"express": "4.18.2"，再npm install。

我推荐方案 2，因为 Codex 的express依赖是 runtime 级别，不是 dev 依赖，必须保证运行时版本精确匹配。--legacy-peer-deps只是掩耳盗铃，后续装其他包可能又爆新冲突。

2.4 全局安装路径污染：多个 Node.js 实例混用

当你的机器上同时存在：

• 通过官网下载安装包装的 Node.js（路径C:\Program Files\nodejs\）
• 通过 Chocolatey 装的 Node.js（路径C:\ProgramData\chocolatey\lib\nodejs\）
• 通过 nvm-windows 管理的 Node.js（路径C:\Users\XXX\nvm\v18.20.4\）

那么npm install -g codex实际装到哪个路径，取决于当前PATH里谁排第一。更麻烦的是，npm list -g显示的codex版本，可能和which codex找到的可执行文件不是同一个——因为which查的是PATH中第一个codex，而npm list -g查的是 npm 配置的prefix路径下的node_modules。

验证方法：

# 查 npm 当前 prefix npm config get prefix # 查 codex 实际位置 where codex # Windows which codex # macOS/Linux # 查 codex 的真实依赖树 cd /path/to/codex/install && npm list --depth=0

如果三者不一致，必须统一。我的做法是：卸载所有 Node.js 安装包，只留 nvm-windows（或 nvm），用nvm install 18.20.4 && nvm use 18.20.4，再npm config set prefix "C:\Users\XXX\nvm\v18.20.4"，最后npm install -g codex。这样所有路径都收束到一个可控目录下。

2.5 环境变量污染：PORT、NODE_ENV、CODER_CONFIG_PATH

Codex 启动时会读取一系列环境变量，其中三个最致命：

• PORT：默认 3000，但如果被其他进程占用（如 VS Code Remote Server、Docker Desktop 的 WSL2 服务），codex serve会直接EADDRINUSE报错，且错误信息里不提示端口被谁占了；
• NODE_ENV：设为production时，Codex 会跳过所有开发中间件（如热重载、调试日志），但某些 provider 初始化逻辑依赖这些中间件，导致provider load failed；
• CODER_CONFIG_PATH：指定配置文件路径，但如果路径里有中文或空格（如C:\Users\张三\codex\config.yaml），Node.js 的fs.readFileSync会因编码问题读空文件，报SyntaxError: Unexpected token u in JSON at position 0（因为读出来是undefined，JSON.parse 就崩了）。

排查技巧：启动前先清理环境

# Windows set PORT=3001 set NODE_ENV=development set CODER_CONFIG_PATH=C:\codex\config.yaml codex serve # macOS/Linux PORT=3001 NODE_ENV=development CODER_CONFIG_PATH=/Users/xxx/codex/config.yaml codex serve

用绝对路径、纯英文、无空格的CODER_CONFIG_PATH，能避开 80% 的配置加载失败。

3. 配置语义失效：YAML 格式、字段名、缩进的魔鬼细节

Codex 的配置文件（.codexrc或config.yaml）看着简单，实则处处是坑。它用的是 YAML 语法，但 Codex 的解析器对 YAML 的宽容度极低——不是“能跑就行”，而是“必须完全符合规范”。一个空格、一个冒号、一个引号，都能让整个配置失效，且错误信息极其模糊，比如Error: Invalid config: undefined，根本看不出哪一行错了。

3.1 缩进陷阱：空格 vs Tab，2 空格 vs 4 空格

YAML 规范要求必须用空格缩进，严禁 Tab。但 Codex 的解析器更苛刻：它要求所有层级缩进必须严格为 2 个空格。如果你用 VS Code 默认的 4 空格缩进写完配置，保存时没开 “Detect Indentation”，就会变成 4 空格缩进，Codex 解析时直接报YAMLException: can not read a block mapping entry。

更隐蔽的是混合缩进：比如顶层providers:用 2 空格，- name:下的model:用 4 空格，解析器会认为model是name的同级字段，而不是子字段，导致model配置被忽略，启动后报No provider configured for model 'gpt-4'。

验证方法：用在线 YAML 验证器（如 https://yamlchecker.com ）粘贴你的 config，它会标出所有缩进违规。我的习惯是：VS Code 里打开设置，搜索editor.insertSpaces设为true，editor.tabSize设为2，并勾选editor.detectIndentation。

3.2 字段名拼写与大小写：一个字母之差，全盘皆输

Codex 的配置字段名是严格区分大小写且零容忍拼写错误的。常见错误：

• 把providers写成provider（少 s）→ 解析成空数组，报No providers found；
• 把endpoint写成endpoints（多 s）→ 字段被忽略，provider 用默认 endpoint，连不上你的私有模型服务；
• 把apiKey写成api_key或APIKEY→ 解析为undefined，请求头不带Authorization，模型服务返回401 Unauthorized；
• 把timeout写成time_out→ 字段无效，超时用默认 30s，但你的模型服务响应慢，结果卡死。

最坑的是model字段：Codex 要求model的值必须是字符串，且必须与你配置的 provider 的模型列表完全一致。比如你用 OpenRouter，它的模型列表里是openrouter/auto，但你 config 里写auto，Codex 就找不到匹配项，报Model 'auto' not supported by provider 'openrouter'。

解决方案：启动 Codex 时加-v参数（verbose），它会打印出加载的完整配置对象。对比你写的 config 和它实际解析出来的对象，一眼就能看出哪个字段丢了、哪个值错了。

3.3 布尔值与字符串的类型混淆

YAML 里true、false、yes、no、on、off都会被解析为布尔值，但 Codex 的某些字段（如debug: true）要求必须是布尔值，而另一些字段（如endpoint: "https://api.openai.com/v1"）必须是字符串。如果你写成：

debug: yes endpoint: https://api.openai.com/v1

debug: yes会被解析为true，没问题；但endpoint: https://api.openai.com/v1因为没加引号，YAML 解析器会把它当成一个 URL 对象（YAML 1.2 规范），而 Codex 的 endpoint 字段只接受字符串，结果endpoint变成undefined，报Cannot read property 'replace' of undefined。

正确写法必须加引号：

debug: true endpoint: "https://api.openai.com/v1"

3.4 多 provider 配置的嵌套层级错误

Codex 支持配置多个 provider（如同时用 OpenAI 和 Ollama），但它们的结构不是平铺的：

# ❌ 错误：平铺写法 providers: - name: openai model: gpt-4 - name: ollama model: llama2

而是必须嵌套在providers下，且每个 provider 必须有type字段：

# ✅ 正确：严格嵌套 providers: - type: openai name: openai model: gpt-4 - type: ollama name: ollama model: llama2

type字段告诉 Codex 该用哪个 provider 插件去初始化。漏掉type，Codex 就不知道该加载@codex/provider-openai还是@codex/provider-ollama，直接报Provider type not specified。

3.5 配置文件路径与加载顺序的隐式规则

Codex 加载配置的顺序是：

1. 环境变量CODER_CONFIG_PATH指定的路径；
2. 当前工作目录下的.codexrc；
3. 当前工作目录下的config.yaml；
4. 用户主目录下的.codexrc（~/.codexrc）。

它不会合并多个配置文件，而是用第一个找到的有效文件。这意味着：

• 如果你在项目根目录放了config.yaml，但CODER_CONFIG_PATH指向了一个不存在的路径，Codex 会报Config file not found，而不是退回到config.yaml；
• 如果~/.codexrc存在且语法正确，但项目目录下的config.yaml有错误，Codex 会静默加载~/.codexrc，导致你以为项目配置生效了，其实是全局配置在起作用。

排查方法：启动时加--config-path参数强制指定，绕过自动发现逻辑：

codex serve --config-path ./config.yaml

这样能 100% 确认你正在用哪个文件。

4. 网络通路断裂：从本地代理到模型 endpoint 的全链路诊断

Codex 的核心价值在于它是个“智能代理”——把用户请求（如/chat/completions）转换、路由、转发给后端模型服务，再把响应原样返回。所以它的报错，80% 以上都发生在“转发”这一步。cc switch local proxy failed while handling codex endpoint /responses这个错误，本质就是代理层在处理/responses这个 endpoint 时，上游模型服务不可达。

4.1 本地代理端口冲突：Codex 的 port 和 proxy port 是两回事

Codex 启动时会开两个端口：

• Web 服务端口（默认 3000）：你浏览器访问http://localhost:3000的界面；
• 代理监听端口（默认 3001）：Codex 内部 Gloo 代理监听的端口，用于接收前端发来的/chat/completions请求。

很多人以为只要PORT=3000没被占，Codex 就能跑。错。PORT=3000只管 Web 服务，不管代理。如果3001被占了（比如你开了另一个 Codex 实例，或某 Docker 容器映射了 3001），codex serve会启动 Web 服务成功，但代理层启动失败，此时你访问 UI 没问题，一发请求就卡住，控制台报cc switch local proxy failed。

验证方法：启动前查端口占用

# Windows netstat -ano | findstr :3000 netstat -ano | findstr :3001 # macOS/Linux lsof -i :3000 lsof -i :3001

如果3001被占，要么杀掉占用进程，要么用PROXY_PORT=3002 codex serve指定新端口。

4.2 模型 endpoint 连接超时：DNS、防火墙、TLS 的三重门

cc switch local proxy failed的根本原因，90% 是 Codex 无法连接到你配置的endpoint。这背后有三层检查：

1. DNS 解析：endpoint域名能否解析成 IP？用nslookup api.openai.com测试；
2. TCP 连通性：IP 和端口（通常是 443）能否建立 TCP 连接？用telnet api.openai.com 443或nc -zv api.openai.com 443测试；
3. TLS 握手：HTTPS 的证书链是否可信？用openssl s_client -connect api.openai.com:443 -servername api.openai.com测试，看是否有Verify return code: 0 (ok)。

常见故障点：

• 公司内网 DNS 被劫持，api.openai.com解析到假 IP；
• 防火墙拦截了 443 出口，telnet直接超时；
• 本地时间不准（误差 > 3 分钟），TLS 证书验证失败，openssl返回verify error:num=9:certificate is not yet valid。

解决方案：

• DNS 问题：改C:\Windows\System32\drivers\etc\hosts，加一行208.67.222.222 api.openai.com（OpenDNS）；
• 防火墙问题：联系 IT 部门开通api.openai.com:443白名单；
• 时间问题：Windows 里右键任务栏时间 → “调整日期/时间” → 开启“自动设置时间”。

4.3 认证失败：API Key 格式、有效期、Scope 的隐形校验

401 Unauthorized看似简单，但 Codex 的认证流程比想象中复杂。它不只是把apiKey塞进Authorization: Bearer xxx头里就完事，还会做三件事：

• Key 格式校验：OpenAI Key 必须是sk-开头，长度 51；Anthropic Key 必须是sk-ant-开头；如果 Key 末尾多了空格（复制时不小心带上的），Codex 会 trim 掉，但有些模型服务不 trim，导致401；
• Key 有效期校验：Codex 会缓存 Key 的有效性，如果 Key 过期，它不会实时刷新，而是继续用缓存的旧 Key 发请求；
• Scope 校验：Key 必须有对应模型的访问权限。比如你用的是免费 tier 的 OpenAI Key，它默认没有gpt-4权限，但 config 里写了model: gpt-4，请求就会403 Forbidden，而非401。

排查方法：用 curl 模拟 Codex 请求，绕过 Codex 层：

curl -X POST "https://api.openai.com/v1/chat/completions" \ -H "Content-Type: application/json" \ -H "Authorization: Bearer sk-xxx" \ -d '{ "model": "gpt-3.5-turbo", "messages": [{"role": "user", "content": "hi"}] }'

如果 curl 成功，说明 Key 和 endpoint 没问题，问题在 Codex 的请求构造逻辑；如果 curl 也401，那就是 Key 本身有问题。

4.4 请求体与响应体的 schema 不匹配

Codex 作为代理，会对请求体做标准化转换（比如把前端发来的{model: "gpt-4", messages: [...]}转成 OpenAI 格式），再把响应体转回来。但如果模型服务返回的 JSON 结构不符合 Codex 预期，就会崩在解析阶段，报TypeError: Cannot read property 'choices' of undefined。

典型场景：

• 你配置了provider: ollama，但 Ollama 服务没开--host 0.0.0.0，只监听127.0.0.1，Codex 从 localhost 发请求能通，但从 Docker 容器里发请求就ECONNREFUSED；
• 你用的是自建 Llama.cpp 服务，它返回的choices[0].message.content是字符串，但 Codex 期望它是对象（含role和content字段），结果解析时报错。

解决方案：启动 Codex 时加--debug，它会打印出原始请求和响应体。对比标准 OpenAI schema，看哪里对不上。如果是自建服务，必须按 OpenAI 的 response schema 返回，不能省字段。

4.5 代理链路中的中间件干扰

Codex 的 Gloo 代理层支持中间件（如 rate limiting、logging），但这些中间件如果配置不当，会阻断请求。比如你启用了rateLimit: { windowMs: 60000, max: 10 }，但没配keyGenerator，Gloo 就无法生成限流 key，整个中间件崩溃，代理链路中断。

验证方法：临时注释掉config.yaml里所有middleware相关字段，只留providers和server，再启动。如果正常了，说明是中间件配置问题。逐个取消注释，定位到具体哪个中间件出错。

5. 模型服务侧故障：当 Codex 没错，错的是它背后的“大脑”

前面四章解决的都是 Codex 自身的问题，但最终用户感知到的“跑不起来”，往往是因为它依赖的模型服务本身出了问题。Codex 只是信使，信使再勤快，送信的路断了，或者收信人病了，信还是送不到。

5.1 模型服务不可用：HTTP 状态码的真相

Codex 报错里最让人迷惑的是500 Internal Server Error和503 Service Unavailable。很多人以为这是 Codex 的 bug，其实是模型服务返回的。区别在于：

• 500：模型服务代码崩了，比如 Python 的IndexError: list index out of range；
• 503：模型服务主动拒绝，比如 Ollama 的model not loaded，或 Llama.cpp 的out of memory。

关键线索在 Codex 的 debug 日志里。启动时加-v --debug，你会看到类似：

[DEBUG] Proxy request to https://localhost:8080/v1/chat/completions [DEBUG] Proxy response status: 503 [DEBUG] Proxy response body: {"error":"model 'llama2' not loaded"}

最后一行{"error":"model 'llama2' not loaded"}就是模型服务返回的原始错误，Codex 只是透传。这时候你要去查 Ollama：

ollama list # 看 llama2 是否在列表里 ollama run llama2 # 如果不在，先拉取

5.2 模型加载失败：GPU 内存、量化格式、GGUF 版本的硬约束

mysql1064报错怎么解决这个热搜词看似无关，实则暴露了一个共性：数据库报错和模型加载报错，本质都是资源约束问题。Ollama 或 Llama.cpp 加载模型时，常见的CUDA out of memory或GGUF: unsupported version，根源是：

• GPU 内存不足：7B 模型至少需 6GB VRAM，13B 模型需 12GB，如果你的显卡是 RTX 3060（12GB），但系统占了 2GB，只剩 10GB，加载 13B 模型就会 OOM；
• 量化格式不兼容：Ollama 只支持 Q4_K_M、Q5_K_M 等特定 GGUF 量化格式，如果你从 HuggingFace 下载的模型是 Q6_K 或 Q8_0，Ollama 会报GGUF: unsupported version；
• GGUF 版本过旧：Llama.cpp 要求 GGUF v3，但有些老模型是 v2，加载时报GGUF: invalid magic。

解决方案：

• GPU 内存：用nvidia-smi查剩余显存，选小一点的模型（如phi-3:3.8b）；
• 量化格式：用llama.cpp的convert.py工具重量化，或去 https://huggingface.co/models?search=gguf 找已适配的版本；
• GGUF 版本：升级llama.cpp到最新版，或用gguf-dump工具查模型版本。

5.3 模型响应超时：timeout 配置与模型推理速度的博弈

Codex 默认timeout: 30000（30 秒），但有些模型（尤其是本地 CPU 推理的 7B 模型）首 token 延迟就 20 秒，总耗时超 30 秒，Codex 就主动断开连接，报Error: timeout of 30000ms exceeded。

这不是模型错了，而是 timeout 设置太激进。解决方案是调大 timeout：

providers: - type: ollama name: ollama model: llama2 timeout: 120000 # 改成 120 秒

但要注意：timeout 不是越大越好。如果模型真的卡死（比如 CUDA kernel hang），timeout 设太大，Codex 进程就一直挂在那里，拖垮整个服务。我的经验是：CPU 推理设120000，GPU 推理设45000，平衡响应与健壮性。

5.4 模型服务日志里的隐藏线索

所有靠谱的模型服务（Ollama、Llama.cpp、Text Generation WebUI）都提供详细日志。Codex 报错model request failed，但模型服务日志里可能写着：

• ERROR: failed to allocate memory for tensor→ GPU 内存不足；
• WARN: KV cache is full, evicting oldest entries→ 上下文窗口超限，需减max_tokens；
• INFO: loaded model in 12.3s→ 模型加载成功，问题在请求环节。

查日志路径：

• Ollama：ollama serve控制台输出，或journalctl -u ollama（Linux）；
• Llama.cpp：启动命令加-v参数；
• Text Generation WebUI：logs/webui.log。

5.5 模型服务商的配额与限制

971210报错这个编号，经我查证是 Anthropic 的配额超限错误码。不同服务商有不同的配额体系：

• OpenAI：按$计费，有requests per minute和tokens per minute双重限制；
• Anthropic：按messages per day限制，971210就是当日消息数超限；
• Azure OpenAI：按部署的model version和region限速，跨 region 调用会429 Too Many Requests。

Codex 不会主动告诉你配额超了，它只会报503或429。解决方案：

• 查服务商控制台的 usage dashboard；
• 在 Codex config 里加retry: { maxAttempts: 3, backoff: 1000 }，让失败请求自动重试；
• 换服务商，或升级配额。

6. 实战排查流水线：从报错信息到根因定位的 7 步法

上面五章讲了各类问题，但实际工作中，你不会先预判是环境问题还是配置问题。你需要一套标准化的、可复现的排查流水线。这是我用 Codex 一年总结出的 7 步法，每一步都有明确动作和预期结果，走完基本能定位 95% 的问题。

6.1 Step 1：确认报错来源——是 Codex 还是模型服务？

打开终端，执行：

codex serve --debug -v 2>&1 | tee codex-debug.log

等报错出现，立刻Ctrl+C停止。打开codex-debug.log，搜索关键词：

• 如果有[DEBUG] Proxy request to ...和[DEBUG] Proxy response status: xxx，说明请求发出去了，问题在模型服务侧；
• 如果只有Error: xxx且没有Proxy request，说明卡在 Codex 启动阶段，问题在环境或配置。

6.2 Step 2：验证 Node.js 和 npm 基础

执行：

node -v # 必须是 v18.20.4 npm -v # 必须是 9.x（npm 9.9.3 最稳） npm list -g codex # 必须显示版本号，且路径与 `which codex` 一致

任一失败，退回第 2 章重装环境。

6.3 Step 3：验证配置文件语法与加载

执行：

codex serve --config-path ./config.yaml --dry-run

--dry-run参数会让 Codex 只加载配置、不启动服务。如果报错，说明 config 语法或字段有问题；如果成功，输出Config loaded successfully，说明配置没问题。

6.4 Step 4：验证本地代理端口可用性

执行：

netstat -ano | findstr :3001 # Windows lsof -i :3001 # macOS/Linux

如果端口被占，换端口或杀进程。

6.5 Step 5：验证模型 endpoint 连通性

执行：

curl -I https://api.openai.com/v1 # 看是否返回 200 telnet api.openai.com 443 # 看是否能连上

任一失败，查 DNS、防火墙、TLS。

6.6 Step 6：验证 API Key 和模型权限

用 curl 模拟请求（见 4.3 节），确认 Key 能直接调通模型服务。

6.7 Step 7：验证模型服务健康状态

查模型服务日志，确认它