1. 先说清楚这套方案到底解决什么问题如果你最近在折腾 Codex CLI多半会遇到这么几个痛点默认模型不支持、API 地址连不上、配置完提示400或者model not supported。我刚在 Rocky Linux 上把 Codex 接上 DeepSeek-V4-Pro 的时候也差点被劝退网上零散教程不少但要么是 Ubuntu 的路径要么直接用 Docker 绕开宿主机配置很少有把命令行模式完整走通的。这篇东西适合谁看在 Rocky Linux8.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 而不是直接装 CodexCodex 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 gitgit 是必须的后面配置完 Codex 大多要关联代码仓库而且npm install -g某些包的时候也会用到 git。python3的版本不用太纠结Rocky Linux 8.x 自带 3.69.x 自带 3.9Codex 官方要求是 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 Keychmod 600 ~/.codex/auth.json3.3 config.toml 的完整字段表config.toml是 Codex 配置文件的核心采用 TOML 格式。下表的字段是我在 Rocky Linux 上实测可用的完整版字段说明我的配置值model请求的模型名称deepseek-v4-promodel_provider模型提供方名称deepseekmodel_providers.deepseek.name提供方名称deepseekmodel_providers.deepseek.base_urlAPI 地址https://api.deepseek.com/v1model_providers.deepseek.env_key环境变量名OPENAI_API_KEYmodel_providers.deepseek.wire_api调用协议格式responsesdisable_model_catalog是否禁用内置模型目录truemodel_context_window上下文窗口大小131072model_max_output_tokens最大输出 token 数8192对应的~/.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 versions model catalog。设成true之后Codex 不再做本地校验直接把模型名透传给 API 端点。wire_api responsesCodex 和模型通信有两种协议格式一种是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 LinuxCodex 会在当前目录生成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] DescriptionCodex CLI Service Afternetwork.target [Service] Typesimple Userroot WorkingDirectory/root/codex-workspace EnvironmentDEEPSEEK_API_KEY你的DeepSeek_API_Key ExecStart/root/.npm-global/bin/codex --config /root/.codex/config.toml Restarton-failure RestartSec5 [Install] WantedBymulti-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 在返回错误告诉你模型列表里没有你要的那个名字。我当时的排查过程是这样的先用 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 的配置。检查模型名称是否完全匹配。注意报错里列出的可用模型是deepseek-v4-pro和deepseek-v4-flash中间有连字符。我之前一度填成deepseek-v4pro少了连字符结果报错一直消不掉。确认 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 versions 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指向了不存在的代理端口。我的排查步骤检查config.toml里的base_url确认协议头是https不是httpv1后缀不能丢。查看系统代理变量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 205.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 官方文档的模型列表页比到处搜教程靠谱得多。