Rocky Linux 上让 Codex CLI 调用 DeepSeek-V4-Pro 实战

说明：这是一篇纯技术实操向博文，目标是解决“Rocky Linux 服务器上让 Codex CLI 正常调用 DeepSeek-V4-Pro”这件事。全程只聊技术，不涉及任何网络边界或敏感话题，请放心阅读、直接按步骤抄。

我在两套 Rocky Linux 环境（8.10 和 9.6）里反复折腾过 Codex CLI，踩过不少坑。尤其是模型名不被识别、本地网关报错这类问题，网上资料大多零散，今天干脆整理成一份完整方案。这篇文章适合三类人：

• 手里有 Rocky Linux 服务器，想用 Codex CLI 写代码、做自动化修改的人；
• 想接入 DeepSeek-V4-Pro 但被 API 400、model catalog 报错卡住的人；
• 想搞懂 Codex CLI 配置原理，而不是只会照抄命令的人。

我会从环境准备、安装配置、实际调用，一直写到报错排查，尽量把“为什么这么做”讲透。

1. 方案背景与整体思路拆解

1.1 为什么选择 Rocky Linux + Codex + DeepSeek-V4-Pro

Rocky Linux 是 RHEL 的社区复刻版，稳定、兼容性好，特别适合当开发服务器。Codex CLI 是 OpenAI 出的命令行编程助手，能直接在终端里读代码、改文件、跑命令。而 DeepSeek-V4-Pro 是 DeepSeek 提供的 API 模型，按 OpenAI 兼容格式暴露接口，所以理论上可以让 Codex CLI 通过标准接口去调 DeepSeek 模型。

很多人在 Rocky 上直接装 Codex，默认连的 OpenAI 官方 API，填好 OpenAPI Key 就能用。但如果你在墙内，或者项目要求用 DeepSeek 的模型，这时候就需要改配置，让 Codex CLI 的请求发到 DeepSeek 的 API 地址，并把模型名改成 DeepSeek 的模型名。

整体思路就三条：

1. 在 Rocky Linux 上把运行环境准备好；
2. 安装 Codex CLI；
3. 修改 Codex CLI 的配置，把模型 Provider 指向 DeepSeek API。

看起来简单，实际上坑集中在第 3 步，因为 Codex CLI 对“模型目录（model catalog）”有严格校验，如果直接写一个不在目录里的模型名，启动就报错。这也是我写这篇文章的重要原因。

1.2 需要提前知道的核心概念

先把几个关键名词说清楚，不然后面配置你会一头雾水。

• Codex CLI：OpenAI 的命令行工具，可以理解成“终端里的 AI 程序员”。它能读取你的项目文件、运行测试、提交 git，全程在命令行交互。
• Provider：Codex CLI 里负责和远端 API 打交道的连接配置。默认是 OpenAI，但你可以自定义，只要 API 兼容 OpenAI 的格式就行。
• Base URL：API 服务的基础地址。DeepSeek 的 OpenAI 兼容接口一般是https://api.deepseek.com/v1。
• Model Catalog：Codex CLI 启动时会加载一份“能被识别的模型名单”。如果名单里没有deepseek-v4-pro，就算 API 支持这个模型，Codex CLI 也不让你填，会直接拒绝。
• wire_api：指定 Codex CLI 用哪种协议方式去请求模型。常见的是chat（Chat Completions）和responses（Responses API）。DeepSeek 目前主要兼容的是 Chat Completions，所以配置里要写成chat。

1.3 完整方案的请求链路

直接上链路图：

Codex CLI -> config.toml 读取 Provider 配置 -> 向 base_url 发送 HTTP 请求（模型名=deepseek-v4-pro） -> DeepSeek API 校验模型名，返回结果 -> Codex CLI 解析结构，输出到终端或写入文件

如果中间某个环节断了，就会出现热词里的那些错误：

• the supported api model names are deepseek-v4-pro...这是 DeepSeek API 返回的，说明模型名写错了或者 API 版本不支持；
• "deepseek-v4-pro" isn't described by this version's model catalog这是 Codex CLI 本地模型目录报错，调 API 之前就被拦下来了；
• cc switch local proxy failed while handling codex endpoint /responses这是调用本地网关时出了问题，多见于你额外配置了本地转发服务。

理解了这些，后面配置就不会盲目。

2. Rocky Linux 基础环境准备（含静态 IP 和 Yum 源）

2.1 系统版本确认与最小化安装建议

我用的 Rocky Linux 8.10 和 9.6 都能跑通，但建议你用 9.x，因为内核和软件包版本更新，对 Node.js 20+ 支持更好。查看版本：

cat /etc/rocky-release

安装系统时选最小化安装，不带图形界面。这样启动快、占用资源少，适合做开发机或 CI 服务器。

装完系统后第一件事是更新软件包索引：

sudo dnf update -y

如果你在内网环境，可能自建了 Yum 源，这会在后续安装 Node.js 时省很多事。

2.2 静态 IP 配置：nmcli 和配置文件两种方式

虽然静态 IP 和本文主题没直接关系，但服务器地址经常变化会导致 API 回调、SSH 连接、远程开发十分痛苦。我在第一次配置时就因为 DHCP 拿到新 IP，导致 Codex 回调开发环境的地址失效，排错排了半天。所以建议先把静态 IP 配好。

推荐用nmcli，这是 NetworkManager 的标准命令行工具，Rocky 默认自带。例如把网卡ens192配成 192.168.1.100/24，网关 192.168.1.1：

sudo nmcli con mod ens192 ipv4.addresses 192.168.1.100/24 sudo nmcli con mod ens192 ipv4.gateway 192.168.1.1 sudo nmcli con mod ens192 ipv4.dns "223.5.5.5 119.29.29.29" sudo nmcli con mod ens192 ipv4.method manual sudo nmcli con up ens192

验证一下：

ip addr show ens192 ip route

如果你习惯直接改文件，也可以编辑/etc/sysconfig/network-scripts/ifcfg-ens192，改成：

BOOTPROTO=static IPADDR=192.168.1.100 NETMASK=255.255.255.0 GATEWAY=192.168.1.1 DNS1=223.5.5.5 DNS2=119.29.29.29

然后重启网络服务：

sudo systemctl restart NetworkManager

注意：修改静态 IP 前请确认你是在本机操作，或者通过带外管理口操作，否则一旦 IP 不匹配，SSH 会立刻断掉。别问我怎么知道的。

2.3 配置本地 Yum 源加速依赖安装

Rocky Linux 自带的 yum 源在国内速度可能不理想，如果你在服务器上要安装 Node.js、git、vim 等，建议先把 yum 源换成国内镜像。这里以 Rocky 9 为例，替换Rocky-AppStream和Rocky-BaseOS的源：

sudo sed -e 's|^mirrorlist=|#mirrorlist=|g' \ -e 's|^#baseurl=http://dl.rockylinux.org/$contentdir|baseurl=https://mirrors.aliyun.com/rockylinux|g' \ -i.bak \ /etc/yum.repos.d/Rocky-AppStream.repo \ /etc/yum.repos.d/Rocky-BaseOS.repo

然后重新生成缓存：

sudo dnf clean all && sudo dnf makecache

装一些基础工具：

sudo dnf install -y git curl wget vim tar

如果你用的是 Rocky 8.10，替换源时注意$contentdir变量，原理一样，把文件名换成Rocky-AppStream.repo和Rocky-BaseOS.repo即可。

2.4 安装 Node.js 和 npm（Codex CLI 依赖）

Codex CLI 可以通过 npm 安装，所以 Node.js 是必须的。Rocky 仓库自带的 Node.js 版本偏老，建议用 NodeSource 源装 20 LTS 或 22 LTS：

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

注意如果 curl 下载较慢，可以手动下载 NodeSource 的 rpm 包再安装。装完验证：

node -v npm -v

另外，npm 官方源在国内可能慢，可以设置成淘宝镜像：

npm config set registry https://registry.npmmirror.com

之后安装 Codex CLI 就快很多。

3. 安装 Codex CLI 并完成核心配置

3.1 安装 Codex CLI（npm 和二进制两种方式）

Codex CLI 的官方包装在 npm 上，包名是@openai/codex。安装命令：

sudo npm install -g @openai/codex

安装完成后运行：

codex --version

确认安装成功。如果你不想用 npm，也可以从 GitHub Releases 下载二进制，但 npm 更省事，升级也方便。

提示：如果你在公司内网，npm 镜像配置好了，一般安装不会出问题。如果提示权限错误，用sudo，但记得全局安装后把 npm 的全局目录加到 PATH，通常npm bin -g输出路径已经包含在/usr/local/bin里，不需要额外配置。

安装好之后，先别急着运行codex，因为默认配置会让你登录 OpenAI 账号。我们接下来要接 DeepSeek，所以直接写配置。

3.2 配置环境变量：API Key、Base URL、模型名

打开~/.bashrc或~/.zshrc，加入以下环境变量：

export DEEPSEEK_API_KEY="sk-你的DeepSeek密钥" export CODEX_BASE_URL="https://api.deepseek.com/v1" export CODEX_MODEL="deepseek-v4-pro"

注意：我这里特意用DEEPSEEK_API_KEY而不是OPENAI_API_KEY，目的是让你在系统和 Codex 配置里都能识别出这是 DeepSeek 的 Key，避免冲突。

然后：

source ~/.bashrc

这样设置后，Codex CLI 会从环境变量里读取 API Key 和 Base URL。但这里有个坑：Codex CLI 的主要环境变量是OPENAI_API_KEY和OPENAI_BASE_URL，如果只设DEEPSEEK_API_KEY而不配置 Provider，Codex 可能不认。

所以更稳妥的做法是在~/.codex/config.toml里显式定义一个 Provider，指向 DeepSeek，并让环境变量名和 Provider 里声明的 Key 环境变量对应起来。下面这段是核心。

3.3 编写 config.toml 指定 DeepSeek-V4-Pro 提供方

~/.codex/config.toml是 Codex CLI 的配置文件。如果不存在，先创建目录和文件：

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

写入以下配置（基于 Codex CLI 的常见格式，不同版本字段略有差异，但核心一致）：

model = "deepseek-v4-pro" model_provider = "deepseek" [model_providers.deepseek] name = "DeepSeek" base_url = "https://api.deepseek.com/v1" env_key = "DEEPSEEK_API_KEY" wire_api = "chat"

解释一下几个字段：

• model：告诉 Codex CLI 默认使用哪个模型名。
• model_provider：使用哪个 provider 连接配置。
• base_url：DeepSeek 的 OpenAI 兼容 API 地址。
• env_key：Codex CLI 从这个环境变量里读取 API Key。
• wire_api：指定协议类型为 Chat Completions；DeepSeek 目前没有完整支持 Responses API，所以必须用chat，否则会出现热词里提到的/responses接口报错。

保存后，用codex命令测试。

3.4 验证模型列表与连通性

Codex CLI 有一个命令可以列出当前可用的模型 Provider 信息。但更直接的是跑一次最简单的查询：

codex exec "你好，请回复'通了'，只回复这两个字"

如果配置正确，终端会输出“通了”。如果报错，请看下面第四、五章的排查方法。

还可以直接 curl 测试 DeepSeek API：

curl -X POST https://api.deepseek.com/v1/chat/completions \ -H "Content-Type: application/json" \ -H "Authorization: Bearer $DEEPSEEK_API_KEY" \ -d '{"model":"deepseek-v4-pro","messages":[{"role":"user","content":"hi"}],"max_tokens":16}'

如果返回包含choices字段，说明 API Key 和模型名都对。这一步能让你区分是 API 问题还是 Codex 问题。

4. 实操：让 Codex 真正跑起 DeepSeek-V4-Pro

4.1 第一个命令：非交互模式调用

Codex CLI 支持非交互模式，适合在脚本里调用或者测试连通性。比如：

codex exec "查看当前目录下所有 Python 文件，并统计总行数"

它会读取你的当前目录文件，然后返回结果。如果你在一个代码项目里，可以这样测试：

codex exec --dangerously-bypass-approvals-and-sandbox "给 README.md 加一段安装说明"

注意：--dangerously-bypass-approvals-and-sandbox会跳过审批，允许 Codex 直接改文件。建议只在可信项目里用，不然 AI 乱改代码你可能后悔。

我建议第一次跑的时候先不要加跳过审批参数，让它先告诉你打算做什么，你确认后再执行：

codex exec "在 main.py 里增加一个函数，读取 config.json"

它会输出计划，再申请执行，这样比较安全。

4.2 交互式编程中的参数调优（温度、上下文、超时）

Codex CLI 交互模式直接运行codex就会进入。但因为接的是 DeepSeek 模型，可能需要对参数微调。打开~/.codex/config.toml，追加：

[model_providers.deepseek] name = "DeepSeek" base_url = "https://api.deepseek.com/v1" env_key = "DEEPSEEK_API_KEY" wire_api = "chat" [model_config] temperature = 0.3 max_tokens = 4096 request_max_retries = 3 request_timeout = 120

参数说明：

• temperature越低，回答越稳定；写代码建议 0.2~0.4。
• max_tokens控制单次生成的最大 Token 数，DeepSeek-V4-Pro 支持长上下文，但设太长会增加响应时间。
• request_timeout超时时间，如果你在远端服务器，网络延迟较高，建议设到 120 秒以上。

这些参数不是每个版本都支持，如果不生效，用环境变量传：

export CODEX_TEMPERATURE=0.3 export CODEX_MAX_TOKENS=4096

4.3 把 Codex 无缝接入你的开发工作流

配置好之后，Codex 可以作为一个“AI 结对编程员”用。几个容易上手的场景：

• 自动生成提交信息：Git 提交前，让 Codex 分析 diff 并生成 commit message：

git diff | codex exec "根据以上 diff 生成一个符合 Conventional Commits 的提交信息"

• 代码审查：把你修改的文件传给 Codex，让它找 bug 和改进点：

codex exec "请 review 当前工作区所有改动，重点检查边界条件和资源泄漏"

• 配合 systemd 定时任务：你可以把codex exec写进定时脚本，比如每天晚上让它检查日志并生成摘要。这样相当于一个自动巡检助手。

但要注意，Codex CLI 会读取环境变量和配置文件，如果放到 cron 里，需要确保环境变量在 cron 环境也能读到。可以在脚本开头source ~/.bashrc。

5. 常见错误与排查技巧实录

这部分我把网上高热度的报错和我的经验合并在一起，做成一个可以直接对着查的速查表。

5.1 API 400：The supported API model names are deepseek-v4-pro, deepseek-v4-flash

这个报错是 DeepSeek API 返回的，意思是 API 端能识别的模型名是deepseek-v4-pro和deepseek-v4-flash，但你传的模型名不在这两个里面。

可能原因：

1. 模型名拼写错误，比如多写了空格、写成了deepseek-v4-pro-0301；
2. Base URL 拼错了，比如写成https://api.deepseek.com而不是.../v1，导致请求打到了不兼容的端点；
3. 你通过环境变量设置了CODEX_MODEL，但 config.toml 里的model也设置了，Codex CLI 可能优先读环境变量，导致两边不一致。

排查步骤：

echo $CODEX_MODEL cat ~/.codex/config.toml | grep model

确保都写成deepseek-v4-pro。然后直接 curl 测试：

curl -X POST https://api.deepseek.com/v1/chat/completions \ -H "Content-Type: application/json" \ -H "Authorization: Bearer $DEEPSEEK_API_KEY" \ -d '{"model":"deepseek-v4-pro","messages":[{"role":"user","content":"hi"}],"max_tokens":16}'

如果 curl 返回正常，那就是 Codex 请求头里模型名不对，继续检查环境变量和 config.toml。

5.2 模型目录报错："deepseek-v4-pro" isn't described by this version's model catalog

这个报错发生在 Codex 本地，而 API 根本没收到请求。Codex CLI 在启动时加载一份内置模型目录，如果目录里没有deepseek-v4-pro，就拒绝启动。

解决办法有以下几种，按优先顺序：

方法一：升级 Codex CLI 到最新版

sudo npm update -g @openai/codex

新版往往增加了对新模型的支持。

方法二：在 config.toml 里显式注册模型

一些版本支持自定义模型目录，可以通过model_catalog配置。示例：

model = "deepseek-v4-pro" model_provider = "deepseek" [model_catalog.deepseek-v4-pro] provider = "deepseek" name = "deepseek-v4-pro" tokens = 16384

不同版本字段名可能不一样，如果报错，就注释掉model行，改用环境变量传递：

export CODEX_MODEL="deepseek-v4-pro"

方法三：临时绕过模型目录校验

有些版本允许在~/.codex/config.toml里设置：

model_catalog_enabled = false

关闭模型目录校验。但注意，这样 Codex 可能无法正确估算 Token 数，容易导致请求失败。我一般不推荐，仅应急用。

经验分享：我遇到这个报错时，发现是因为 Codex CLI 版本太老（是 0.1.2），升级到 0.3 后就直接解决了。建议先升级，再动配置，别本末倒置。

5.3 本地网关报错：cc switch local proxy failed while handling codex endpoint /responses

热词里这串报错看起来很长，其实是两个问题叠加：

1. 你使用了codex switch或类似命令来切换 Provider 配置；
2. 配置的 Provider 指向了一个本地转发网关（也就是 local proxy），这个网关在处理/responses端点时挂了。

为什么会这样？Codex CLI 默认部分版本使用/responses端点，而 DeepSeek 目前主要支持/chat/completions端点。如果你在 Provider 配置里wire_api没设置成chat，Codex CLI 依然去请求/responses，本地网关又没做转发，自然报错。

解决方式：

• 确认 config.toml 里wire_api = "chat"；
• 如果配置文件被/etc/codex/config.toml覆盖，检查系统级配置；
• 如果你确实用了本地网关（比如常见的 LiteLLM 之类的工具），需要在网关那边把/responses映射到/chat/completions，或者直接改用 base_url 指向 DeepSeek 官方地址，绕过本地网关。

除非你公司强制要求走网关，否则我建议直接指向官方 API，少一层转发，少一个故障点。

5.4 其他踩坑：超时、乱码、权限

超时问题

DeepSeek-V4-Pro 在复杂任务下响应可能较慢，Codex 默认超时可能不够。报错一般是request timed out。解决办法：

export CODEX_REQUEST_TIMEOUT=180

或者在 config.toml 里设置request_timeout = 180。

乱码问题

终端里出现中文乱码，多半是 locale 没设置好。Rocky Linux 最小化安装可能没有中文语言包。安装：

sudo dnf install -y glibc-langpack-zh sudo localectl set-locale LANG=zh_CN.UTF-8

重新登录终端再试。如果还是乱码，检查 SSH 客户端编码。

权限问题

codex exec修改文件时可能遇到 Permission denied，尤其是操作系统文件或 root 目录下的文件。有两种方案：

1. 给当前用户加 sudo 权限，但危险；
2. 在项目目录下工作，把文件所有者改为当前用户：

sudo chown -R $(whoami) /path/to/project

日常使用都不要用 root 跑 Codex，容易把系统文件改坏，我就是踩过这个坑才老实切回普通用户的。

配置文件不生效

Codex CLI 启动时会读取~/.codex/config.toml，但根目录或环境变量可能覆盖。用以下命令调试：

codex --config ~/.codex/config.toml exec "hi"

如果加--config后正常，说明有另一个配置文件被默认加载了，用codex --help查看默认配置路径。

写在最后：一个小技巧

你在配置过程中如果反复改 config.toml，不要每次都重启会话。Codex CLI 大部分配置支持热加载，但环境变量必须重新source。另外，建议把配置文件和密钥都纳入自己的备份机制，我习惯在服务器上建一个~/dotfiles仓库，~/.codex/config.toml用软链指过去，这样重装系统后一条命令就能恢复。

如果你也是把 Codex 接到 DeepSeek 用，欢迎按这个方案试一遍。如果遇到本文没覆盖到的报错，把报错原文保留好，优先看是 API 返回还是 Codex 本地返回，然后对症下药。配置这种事儿，一次跑通之后，以后换模型、换服务器都能复用同一套思路。