企业官网建设流程全解析

1. 先说清楚这套方案到底解决什么问题

如果你最近在折腾 Codex CLI，多半会遇到这么几个痛点：默认模型不支持、API 地址连不上、配置完提示400或者model not supported。我刚在 Rocky Linux 上把 Codex 接上 DeepSeek-V4-Pro 的时候也差点被劝退，网上零散教程不少，但要么是 Ubuntu 的路径，要么直接用 Docker 绕开宿主机配置，很少有把命令行模式完整走通的。

这篇东西适合谁看：在 Rocky Linux（8.x/9.x 都行）上跑服务器开发环境的人，想用 Codex CLI 干活但不想付费订阅官方模型，或者想把手头的 DeepSeek API Key 利用起来的人。我也会把过程中踩过的报错、查看日志的方法、配置文件的坑一并写清楚。

先说结论：Codex CLI 本身是一个开源命令行工具，核心能力是接入各类模型。DeepSeek-V4-Pro 是当前 DeepSeek 比较新的模型标识，API 兼容 OpenAI 格式，理论上只要 Codex 能配置自定义模型提供方，就能接。但实际操作中 Rocky Linux 的依赖环境、Node.js 版本、配置文件字段写法，一个不对就起不来。

2. Rocky Linux 上的基础环境准备：比 Ubuntu 多的那几步

2.1 为什么先折腾 Node.js 而不是直接装 Codex

Codex CLI 是 Node.js 写的，官方推荐用 npm 全局安装。Rocky Linux 默认带的 Node.js 版本通常比较老（8.x 自带的是 10.x 左右，9.x 自带 16.x），而 Codex 对 Node.js 版本有要求。实测下来 Node.js 18 以上比较稳，20 LTS 最省心。版本太低会直接报glibc相关错误，或者安装过程中 npm 就挂了。

在 Rocky Linux 上装 Node.js，我推荐用 NodeSource 的源，而不是直接dnf install nodejs——官方源的版本太旧，装完还要再折腾 nvm，多一步没必要。NodeSource 的安装命令如下：

curl -fsSL https://rpm.nodesource.com/setup_20.x | bash - dnf install -y nodejs

装完验证一下：

node -v npm -v

这里有个小坑：如果服务器在隔离网络环境，curl那一步可能超时。我当时的做法是提前把 NodeSource 的 RPM 包下载好传到服务器上，然后dnf install本地文件。不过一般能通外网的机器直接跑上面两条命令就够了。

2.2 依赖库检查：别等报错再回头装

Codex 在 Linux 上运行还依赖python3、make、gcc这些基础工具链。虽然 Codex 本身是 Node.js 程序，但它在执行代码解释、跑沙箱的时候会调用系统的 Python 解释器。Rocky Linux 最小化安装通常不带make和gcc，提前装齐能省不少事：

dnf install -y python3 python3-pip make gcc git

git 是必须的，后面配置完 Codex 大多要关联代码仓库，而且npm install -g某些包的时候也会用到 git。python3的版本不用太纠结，Rocky Linux 8.x 自带 3.6，9.x 自带 3.9，Codex 官方要求是 Python 3.8 以上，所以 9.x 没问题，8.x 可能要手动升一下。

2.3 网络访问限制：很多人忽略的根源

Rocky Linux 常用于服务器，服务器环境经常有防火墙、代理限制。Codex 安装时需要访问 npm 仓库，运行时需要访问 DeepSeek 的 API 地址。如果你在的公司网络有 egress 限制，需要提前确认两个域名能通：

• registry.npmjs.org（安装 Codex 用）
• api.deepseek.com（调用模型用）

排查命令：

curl -I https://registry.npmjs.org curl -I https://api.deepseek.com

如果返回的不是200或者403，就要先找网络管理员开放权限，或者配置 npm 代理。npm 配置代理的方式：

npm config set proxy http://你的代理地址:端口 npm config set https-proxy http://你的代理地址:端口

这个步骤我当初没注意，结果npm install -g @openai/codex的时候卡在sill idealTree buildDeps大半天，最后才发现是网络问题。顺序不对，后面所有操作都白搭。

3. Codex 配置文件的底层逻辑：auth.json 和 config.toml 职责解耦

3.1 全局配置目录和文件路径

Codex CLI 的配置目录是~/.codex/，里面有auth.json和config.toml两个核心文件。很多人搞混了这两个文件的职责，导致配了config.toml但不起作用，或者反过来。

• auth.json：存 API Key、认证信息。Codex 启动的时候会先读这里，拿到 Key 之后再去请求模型接口。
• config.toml：存模型名称、API 地址、模型参数（temperature、max_tokens 等）。

简单理解：auth.json是“证明你是谁”，config.toml是“告诉 Codex 去找谁干活”。两边缺一个都跑不起来。

3.2 手写 auth.json：两个关键字段实测

用codex login会弹出浏览器授权页面，但服务器上根本没浏览器，所以手动创建auth.json是最靠谱的方式。直接编辑：

mkdir -p ~/.codex cat > ~/.codex/auth.json << 'EOF' { "OPENAI_API_KEY": "你的DeepSeek_API_Key", "tokens": { "OPENAI_API_KEY": { "type": "Bearer", "secret": "你的DeepSeek_API_Key" } } } EOF

这里有个细节：Codex 读取OPENAI_API_KEY这个字段时，不只是读字符串值，还会看tokens里的 Bearer Token 类型。我第一次配置的时候只写了OPENAI_API_KEY这一个字段，结果 Codex 一直报认证失败。后来翻源码才发现，CLI 优先从tokens里读。

提示：auth.json的权限建议设置为600，防止其他用户读到 API Key：chmod 600 ~/.codex/auth.json

3.3 config.toml 的完整字段表

config.toml是 Codex 配置文件的核心，采用 TOML 格式。下表的字段是我在 Rocky Linux 上实测可用的完整版：

对应的~/.codex/config.toml写法：

model = "deepseek-v4-pro" model_provider = "deepseek" disable_model_catalog = true model_context_window = 131072 model_max_output_tokens = 8192 [model_providers.deepseek] name = "deepseek" base_url = "https://api.deepseek.com/v1" env_key = "OPENAI_API_KEY" wire_api = "responses"

重点解释两个字段：

• disable_model_catalog = true：这个非常关键。Codex 默认有一个内置的模型目录（catalog），里面只包含 OpenAI 官方模型。不关掉的话，Codex 会拿deepseek-v4-pro去和目录里的模型比对，发现目录里没有，直接拒绝请求，报错类似is not described by this version's model catalog。设成true之后，Codex 不再做本地校验，直接把模型名透传给 API 端点。

• wire_api = "responses"：Codex 和模型通信有两种协议格式，一种是responses，一种是chat。DeepSeek 的 API 目前兼容 OpenAI 的/responses端点，所以这里要填responses。如果你的 API 提供商只支持/chat/completions，就改成chat，否则请求会 404。

3.4 环境变量方案：另一种更灵活的配置方式

如果你不想写auth.json，也可以用环境变量。Codex 支持通过env_key引用的环境变量名来动态读取 API Key。比如在config.toml里写上：

[model_providers.deepseek] env_key = "DEEPSEEK_API_KEY"

然后在~/.bashrc或~/.zshrc里追加：

export DEEPSEEK_API_KEY="你的DeepSeek_API_Key"

之后source ~/.bashrc让它生效。这种方式适合多环境复用同一份config.toml，但注意环境变量生效范围是当前 Shell，用 systemd 服务跑 Codex 的话要单独配环境变量。

4. 深度拆解：从安装 Command Line 到跑通第一个请求

4.1 npm 全局安装与版本验证

配置写完之后，就可以安装 Codex 本体了：

npm install -g @openai/codex

安装过程可能出现以下几种错误，我分别给解决方案：

• 权限不足：npm 全局安装目录通常是/usr/lib/node_modules，普通用户没写权限。解决方案是给 npm 配置一个用户级目录：

npm config set prefix ~/.npm-global echo 'export PATH=$PATH:~/.npm-global/bin' >> ~/.bashrc source ~/.bashrc

• 编译错误：有些 npm 包需要从源码编译，如果报gyp ERR!之类，说明python3和make没装好。回看 2.2 节，把依赖补上再删掉node_modules重装。

• 卡在下载：大概率是网络问题，按 2.3 节设置代理。

安装完成后验证版本：

codex --version

如果显示类似codex 0.5.x的版本号，说明安装成功。

4.2 交互模式测试：先让 Codex 能开口说话

很多教程一上来就让你codex exec "写一个俄罗斯方块"，但如果配置有问题，exec 模式只会返回一堆让人摸不着头脑的报错。我的建议是先跑交互模式：

codex

正常情况下会进入一个类似>>>的交互提示符。这时候输入一个简单的指令，比如：

你好，请用一句话自我介绍

如果配置正确，Codex 会调用 DeepSeek-V4-Pro 模型返回内容。如果这里报错，后面的 exec 模式、文件操作模式全都跑不通，所以第一步先把交互模式调通。

4.3 exec 模式与文件操作：实际干活的方式

交互模式确认没问题之后，就可以用exec模式干活了。如果要在当前目录下新建文件：

codex exec "在当前目录创建一个 hello.py，内容为打印 Hello, Rocky Linux"

Codex 会在当前目录生成hello.py，然后你运行python3 hello.py验证。

如果想要让 Codex 能读写文件、执行 shell 命令，需要保证 Codex 的沙箱权限。Codex 默认开启沙箱，只允许在--sandbox指定的目录下操作，如果没有指定，只读当前目录。允许 Codex 完整操作当前目录的方式：

codex exec --sandbox workspace "写一个 Python 脚本读取 data.json 并输出所有 key"

--sandbox workspace表示允许 Codex 访问名为workspace的目录。这里我踩过一个坑：如果不加--sandbox参数，Codex 默认沙箱是只读的，你让它“修改文件”它会拒绝，并给出 Permission denied 之类的提示，一度让我以为 API 配置又出问题了。

4.4 systemd 服务方式：让 Codex 常驻后台

服务器上跑 Codex，一般希望它一直挂着，随时可以调。写个 systemd 服务比较干净：

[Unit] Description=Codex CLI Service After=network.target [Service] Type=simple User=root WorkingDirectory=/root/codex-workspace Environment="DEEPSEEK_API_KEY=你的DeepSeek_API_Key" ExecStart=/root/.npm-global/bin/codex --config /root/.codex/config.toml Restart=on-failure RestartSec=5 [Install] WantedBy=multi-user.target

把这个文件放到/etc/systemd/system/codex.service，然后：

systemctl daemon-reload systemctl enable --now codex

注意Environment那行，如果你用的是auth.json而不是环境变量方式，这里就不需要写了。个人建议服务方式用环境变量，方便排查问题，改 Key 不用动 systemd 文件。

5. 典型报错排查：我从 400 到跑通的完整折腾记录

配 Codex + DeepSeek 期间，我至少碰到了五六种报错，每种的根源都不一样。这里挑最有代表性的三个，完整还原排查链路。

5.1400 the supported api model names are deepseek-v4-pro, deepseek-v4-flash

这个报错是很多人拿到 Codex 之后第一次遇到的。表面上是“模型名不存在”，但实际问题是 DeepSeek 的 API 在返回错误，告诉你模型列表里没有你要的那个名字。

我当时的排查过程是这样的：

1. 先用 curl 直接测试 API 能不能通：

curl -X POST https://api.deepseek.com/v1/responses \ -H "Content-Type: application/json" \ -H "Authorization: Bearer 你的DeepSeek_API_Key" \ -d '{"model": "deepseek-v4-pro", "input": "hello"}'

如果 curl 也返回同样的400，说明问题出在模型名或 API 地址上，而不是 Codex 的配置。

2. 检查模型名称是否完全匹配。注意报错里列出的可用模型是deepseek-v4-pro和deepseek-v4-flash，中间有连字符。我之前一度填成deepseek-v4pro（少了连字符），结果报错一直消不掉。

3. 确认 base_url。DeepSeek 的 API 分两个版本：旧的v0端点和新的v1端点。如果是新 Key，要填https://api.deepseek.com/v1。填成v0也会导致模型名对不上。

注意：这个报错不代表 Codex 配置有问题，反而说明 Codex 已经成功把请求发出去了，问题出在 API 端点侧的参数校验。排查顺序应该是：先 curl 验证 API，再回看 Codex 配置。

5.2is not described by this version's model catalog

这个报错就是前面说的disable_model_catalog没设。Codex 自己维护了一份模型目录，里面有gpt-4o、gpt-5等名字，你告诉它要用deepseek-v4-pro，它翻了半天目录找不到，就直接拒绝了。

解决方案就是在config.toml里加一行：

disable_model_catalog = true

加完之后重启 Codex，问题解决。这个字段是 Codex 针对自定义模型提供方预留的开关，不写的话永远只能用内置模型。

5.3cc switch local proxy failed while handling codex endpoint /responses

报错里带cc前缀的，一般是 Codex 内部走本地代理失败。这个问题的根源多半是配置文件里写了一个不可用的base_url，或者环境变量HTTP_PROXY指向了不存在的代理端口。

我的排查步骤：

1. 检查config.toml里的base_url，确认协议头是https不是http，v1后缀不能丢。
2. 查看系统代理变量：

env | grep -i proxy

如果有HTTP_PROXY或HTTPS_PROXY，并且值是一个已经挂掉的代理端口，Codex 会尝试走这个代理转发请求，结果代理不通，就报local proxy failed。临时清掉这些变量再试：

unset HTTP_PROXY HTTPS_PROXY ALL_PROXY codex

如果干净环境下能跑，再去改.bashrc里写死的代理变量。

5.4 Codex 打不开或者直接闪退

这种情况大概率是 Node.js 版本太高或太低。Codex 官方支持 Node.js 18 和 20，如果你用的是 Node 22，某些依赖包可能还没跟上，启动直接崩。用 nvm 切换版本是最快的：

nvm install 20 nvm use 20

5.5 排查工具：一份快速定位脚本

把下面这段放到diagnose.sh里，一键检查常见配置问题：

#!/bin/bash echo "=== 1. Node.js 版本 ===" node -v echo "=== 2. Codex 版本 ===" codex --version echo "=== 3. auth.json 是否存在 ===" ls -la ~/.codex/auth.json echo "=== 4. config.toml 是否存在 ===" ls -la ~/.codex/config.toml echo "=== 5. 关键配置字段 ===" grep -E "model_provider|base_url|env_key" ~/.codex/config.toml echo "=== 6. 代理变量 ===" env | grep -i proxy || echo "无代理变量" echo "=== 7. API 连通性 ===" curl -s -o /dev/null -w "%{http_code}\n" https://api.deepseek.com/v1

跑一遍基本能定位 80% 的问题。

6. 进阶玩法：Docker 封装、非交互模式和团队共享配置

6.1 为什么要考虑 Docker 封装

虽然宿主机直接装 Codex 已经能跑，但服务器环境通常还有别的业务，Node.js 版本、全局包、环境变量这些容易互相干扰。Docker 封装是把 Codex 隔离到独立容器里，宿主机只暴露一个codex命令入口，干净利落。

我的 Dockerfile 思路是：

FROM node:20-slim RUN apt-get update && apt-get install -y python3 make gcc git curl RUN npm install -g @openai/codex RUN mkdir -p /root/.codex WORKDIR /workspace CMD ["codex"]

构建并运行：

docker build -t codex-deepseek . docker run -it --rm \ -v ~/.codex:/root/.codex \ -v $(pwd):/workspace \ codex-deepseek codex

这样宿主机不需要装 Node.js，~/.codex目录通过 volume 挂载进去，宿主机改配置，容器内立即生效。

6.2 系统级非交互模式：脚本化调用 Codex

如果是要在 CI/CD 或者定时任务里调用 Codex，就不能用交互模式。Codex 提供了非交互模式，输出 JSON 结构化结果：

codex exec --json "检查当前目录所有 Python 文件并修复语法错误"

输出会包含每个操作的 status、file 路径、message 等字段，方便后续脚本解析。实测在 Rocky Linux 上的输出格式稳定，可以直接jq处理。

给个场景：我写过一个脚本，每天凌晨用 Codex 扫描代码库里的 TODO 注释，自动生成待办清单。命令大致是：

codex exec --json "读取项目中的 *.py 文件，找出所有 TODO 注释，输出为 markdown 待办列表" > /tmp/todos.json

--json模式的好处是即使 Codex 执行过程中有沙箱警告，也不会混杂在正常输出里，脚本处理起来方便。

6.3 团队共享配置：把 config.toml 纳入版本管理

如果你和小伙伴一起用这套方案，建议把config.toml提交到 git 仓库，auth.json绝对不要提交。用config.toml里引用环境变量的方式，每个团队成员只需要在自己的~/.bashrc里配置DEEPSEEK_API_KEY，然后克隆仓库把config.toml软链接到~/.codex/下：

ln -s $(pwd)/config.toml ~/.codex/config.toml

这样配置统一由仓库维护，Key 各管各的，安全性和可维护性都兼顾了。

7. 写在最后的几个实操建议

配置这套环境的过程中，我最大的感受是：Codex 这个工具对配置文件的要求非常严格，一个字段名写错、一个斜杠漏掉，都会导致完全不同的报错，但报错信息又不会明确告诉你“是配置文件哪里写错了”，所以排查的时候一定要从底往上验证：先确认 API 本身通不通，再看 Codex 的配置，不要一上来就怀疑工具坏了。

还有一点，codex命令在 Rocky Linux 上的使用体验和其他发行版基本一致，但 Rocky Linux 作为服务器系统，默认的 SELinux 是开启的，如果遇到奇怪的权限问题，可以临时setenforce 0测试一下是不是 SELinux 拦截了 Codex 访问~/.codex配置文件的路径。我当时遇到过 Codex 能启动但读不到auth.json的情况，关掉 SELinux 就好了，后来给~/.codex目录加了正确的restorecon -R标签解决。

最后提一下，DeepSeek 的模型列表是动态更新的，deepseek-v4-pro这个名称如果之后不能用了，大概率是模型更新换代或者你的 API Key 权限级别不支持。到时候只需要改config.toml里的model = "新模型名"就行，其余配置不用动。多关注 DeepSeek 官方文档的模型列表页，比到处搜教程靠谱得多。