企业官网建设流程全解析

最近我在一台 Rocky Linux 9 服务器上折腾 Codex 接入 DeepSeek-V4-Pro，过程中踩了不少文档里根本不会写的坑。这篇文章就是把完整方案和排查过程记下来——从裸机环境准备、Codex CLI 安装，到自定义模型供应商配置，再到接入 DeepSeek-V4-Pro 之后的常见报错处理，全部按我实际操作过的顺序展开。适合想在自己服务器上跑 AI 编码助手、又不想只依赖官方云端订阅的开发者参考，也适合刚接触 Rocky Linux 的运维朋友照着抄作业。

1. 为什么是这套组合：AI 编码助手在服务器上的正确定位

1.1 三个组件各自解决什么问题

先说清楚这套组合里的每一环是干嘛的，避免一上来就 confusion。

Rocky Linux 是服务器操作系统，我选它的原因很朴素：RHEL 系生态，稳定、生命周期长，跑在服务器上不用担心桌面环境拖后腿。对 AI 编码助手这种需要长时间占用终端、经常连着仓库跑批处理任务的场景来说，服务器环境比本地笔记本靠谱得多。

Codex 是 OpenAI 出的命令行编码代理，能够在终端里理解自然语言指令，操作文件、跑命令、提交代码。它本质上是一个 agentic 的 CLI 工具，不是简简单单的代码补全插件。

DeepSeek-V4-Pro 是 DeepSeek 提供的模型服务，走的是 OpenAI 兼容 API 格式。这意味着它可以用一套标准的 HTTP 接口对接各种工具，Codex 恰好支持自定义 API 端点，两者就能串起来。

1.2 不依赖云端订阅的接入逻辑：OpenAI 兼容 API

Codex 官方默认连接 OpenAI 的服务，要走 ChatGPT 订阅或 OpenAI API Key。但 Codex 从某个版本开始支持配置自定义模型供应商（model provider），只要对方提供 OpenAI 兼容接口，就能把 Codex 的请求转发过去。

DeepSeek-V4-Pro 正好满足这个条件。它的 API 端点和请求格式与 OpenAI 兼容，所以核心思路是：

• 让 Codex 把模型请求发到 DeepSeek 的 base_url
• 让 DeepSeek 识别 Codex 的身份凭据（API Key）
• 让 Codex 使用 DeepSeek 认可的模型名“deepseek-v4-pro”

听着简单，实际配置里有几个隐藏很深的坑，后面章节逐个展开。

1.3 这套方案能跑通的效果长什么样

我在这台 Rocky Linux 上配好之后，可以直接在项目目录里执行类似这样的命令：

codex --profile deepseek "分析一下当前仓库的代码结构，找出潜在的 bug"

Codex 会基于 DeepSeek-V4-Pro 的推理能力，结合本地 git 历史和文件内容给出回答，并且能自动修改文件、运行测试。整个过程全部走命令行，不需要打开浏览器，也不需要离开终端。

这套方案适合谁：手上有 Linux 服务器、想自动化处理代码任务的开发者，或者想在公司内网离线环境里搭一套私有编码助手的团队。如果你只是想在本地点一点补全，那 VSCode 插件可能更合适，但如果你想要一个能真正操作代码仓库的智能体，Codex 这套是更接近生产环境的方案。

2. Rocky Linux 基础环境：从裸机到 Codex 就绪

2.1 静态 IP 与系统初始化

Rocky Linux 安装完成后，我第一时间会配置静态 IP。很多人觉得无所谓，但服务器重启后如果 IP 变了，SSH 连接直接断，尤其你后续还要通过远程终端来跑 Codex，这种事情发生一次就够难受了。

Rocky Linux 9 默认使用 NetworkManager，配置静态 IP 最直接的方式是 nmcli：

nmcli con mod ens160 ipv4.addresses 192.168.1.100/24 nmcli con mod ens160 ipv4.gateway 192.168.1.1 nmcli con mod ens160 ipv4.dns "223.5.5.5 8.8.8.8" nmcli con mod ens160 ipv4.method manual nmcli con up ens160

注意 ens160 是网卡名，你机器上可能是 ens3、eth0 之类，用ip addr先确认。配置完之后用ip a检查 IP 是否生效。

另外建议顺手把 dnf 源切换成国内镜像源，Rocky 默认源在部分地区拉包慢到让人崩溃。以 Rocky 9 为例，替换 BaseOS 和 AppStream 的 baseurl 即可，方法网上已经很多人写过，这里不展开。

系统初始化阶段还应该做的几件事：

• dnf update -y升级系统包
• 安装基础工具dnf install -y git curl wget vim bash-completion
• 配置好 firewalld，放行 SSH 端口
• 创建普通用户，禁止 root 直接 SSH 登录

2.2 安装 Node.js 与 npm 的版本细节

Codex CLI 是 Node.js 写的，所以 Node.js 版本直接决定了能不能装上、跑得稳不稳。我踩过的一个坑是 Rocky Linux 默认的 Node.js 版本太老，装 codex 时报引擎版本不兼容。

Rocky Linux 9 的 AppStream 仓库里默认提供 Node.js 18，但 Codex 对 Node.js 的版本要求通常比较新。建议直接启用 Node.js 20 或者 22 模块流：

dnf module list nodejs dnf module enable nodejs:20 -y dnf install -y nodejs

装完验证一下：

node -v npm -v

如果你需要更新的版本，可以用 NodeSource 的仓库，但在 Rocky 上我建议优先用 dnf module，毕竟是系统原生管理方式，升级和回滚都方便。万一你后面还要在同一台机器上跑其他 Node 项目，nvm 是更好的选择，但那是另一个话题了。

2.3 安装 Codex CLI 并完成身份凭据准备

Codex 官方推荐的安装方式是通过 npm 全局安装：

npm install -g @openai/codex

安装完成后确认版本：

codex --version

如果提示command not found，检查 npm 全局 bin 目录是否在 PATH 里。用npm config get prefix查看路径，然后把这个路径加到 /etc/profile.d/ 下的脚本里。

接下来是凭据准备。Codex 支持两种方式：

• 官方登录：codex login，会打开浏览器完成 OAuth 流程，适合使用 ChatGPT 订阅额度
• API Key 方式：设置环境变量，适合我们这种要接第三方模型供应商的场景

因为我们目标是接入 DeepSeek-V4-Pro，所以不需要 codex login，直接配置 API key 环境变量即可。在后面配置 provider 时，我会用环境变量承载密钥，这样不会把密钥写死在 config.toml 里。

这里有一个重要的注意点：如果你之前执行过codex login，Codex 会优先使用登录态，可能导致自定义 API 端点配置不生效。如果发现请求还是打到官方端点，先清掉登录态：

codex logout

3. Codex 接入 DeepSeek-V4-Pro 的配置链路全拆解

3.1 Codex 的模型发现机制：为什么它不认你写的模型名

很多人第一次配置时直接写这样的环境变量：

export OPENAI_API_KEY="sk-xxx" export OPENAI_BASE_URL="https://api.deepseek.com" export OPENAI_MODEL="deepseek-v4-pro" codex "help me debug this code"

结果 Codex 报错，常见的有：

• the supported api model names are deepseek-v4-pro, deepseek-v4-flash...
• 'deepseek-v4-pro' is not a model this version of codex recognizes
• the 'gpt-5.6-sol' model is not supported when using codex with a...

为什么会这样？因为 Codex 内部维护了一份 model catalog，只有它认识的模型，才允许被使用。你把一个陌生模型名塞给它，它直接拒绝。

有两个层面的校验：

• Codex 本地版本内置模型列表，不认识 deepseek-v4-pro
• DeepSeek 服务端也有自己的模型白名单，你传一个它不支持的模型名，服务端直接返回 400

所以这里不能只是粗暴地设置模型名，而是要通过 Codex 的 model provider 机制，把 DeepSeek 定义成 Codex 认可的外部模型提供商，然后在 provider 内部指定模型名。Codex 对自定义 provider 里的模型名不做本地 catalog 强校验，因为服务端会做最终的校验。

3.2 用 config.toml 定义一个 DeepSeek Provider

Codex 的配置文件默认在~/.codex/config.toml。我第一次配置的时候，这个文件默认不存在，需要手动创建。

先设置环境变量，把 API Key 准备好：

export DEEPSEEK_API_KEY="sk-你的key"

然后编辑 config.toml：

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

逐行解释一下：

• model_provider = "deepseek"：默认使用 deepseek 这个 provider
• [model_providers.deepseek]：定义一个名为 deepseek 的模型供应商
• name只是展示名称
• base_url是 API 端点，这里用 DeepSeek 官方兼容端点
• env_key告诉 Codex 从哪个环境变量读取 API key
• wire_api = "chat"很关键，后面单独讲
• [profiles.deepseek]：定义一个配置模板，方便直接codex --profile deepseek调用，里面指定实际要用的模型名

配置保存后，用这个 profile 跑：

codex --profile deepseek "你好，用一句话介绍你自己"

如果能看到来自 DeepSeek-V4-Pro 的回复，就说明链路通了。

3.3 wire_api 的参数：chat 和 responses 的区别

这是我最想强调的一点，因为很多人卡在配置上就是这里出问题。

Codex 本身就支持两种 API 协议风格：

• OpenAI Responses API，对应端点/responses
• OpenAI Chat Completions API，对应端点/chat/completions

不同版本的 Codex、不同模型供应商支持的方式不一样。我用的 DeepSeek 兼容端点支持的是 Chat Completions 格式，所以我配置了wire_api = "chat"。

如果不配置或者配置错误，会出现一种很迷惑的报错：

cc switch local proxy failed while handling codex endpoint /responses

/responses这个路径就透露了问题：Codex 默认在用 Responses API 协议发请求，但 DeepSeek 端点并不按这个协议工作。设置wire_api = "chat"之后，Codex 会把请求转换成 Chat Completions 协议，问题就消失了。

所以当你遇到任何涉及/responses的报错时，第一反应应该是去看 provider 的 wire_api 设置是否正确，而不是慌着查网络、查防火墙。

另外要说明的是，wire_api的合法值一般是"chat"或"responses"，具体以你 Codex 版本支持的写法为准。如果配置里写错了，Codex 启动时一般会给出 schema 提示，按照提示改即可。

4. 五个高频报错的排查过程记录

4.1 服务端拒绝支持的模型名

有一个报错长这样：

API Error: 400 the supported api model names are deepseek-v4-pro, deepseek-v4-flash, and deepseek-...

这个报错其实非常有信息量，它告诉你三件事：

• 请求已经成功到达 DeepSeek 服务端
• 你的凭据是被接受的
• 你传的模型名不在服务端模型列表里

我遇到的情况是：在配置 profile 时，把模型名写成了deepseek-v4-pro-2025，想着带个版本后缀更精准，结果服务端不认。

排查思路很简单：先确认服务端到底支持哪些模型名，再改配置文件里的model字段。支持列表通常可以直接通过 API 查询：

curl https://api.deepseek.com/v1/models \ -H "Authorization: Bearer $DEEPSEEK_API_KEY"

返回结果里会列出可用的模型名。以返回结果为准，不要在模型名上加额外后缀，不要从别人博客里复制一个过时的模型名就往上填。

另外注意一个细节：DeepSeek 的服务端校验是严格的，连大小写都必须一致。我试过把deepseek-v4-pro写成DeepSeek-V4-Pro，照样被拒。改回全小写就通了。

4.2 local proxy failed 到底败在哪

热搜里有一个很典型的报错：

cc switch local proxy failed while handling codex endpoint /responses. provided...

很多第一次看到local proxy这个词就慌了，以为是自己网络出口的问题。实际上这是两回事。Codex 在本地启动了一个内部 HTTP 服务，用来处理和转发会话请求，这个组件被称为 local proxy。你调 Codex 时，请求先经过这个本地服务，再由它转发给远端 API。

这个报错有哪些常见诱因？我梳理一下我实际遇到的：

• wire_api 配置和 base_url 实际支持的协议不匹配，请求在本地转换阶段就失败
• ~/.codex 目录权限有问题，之前用 root 跑过 codex，之后切普通用户，本地服务没有权限写状态文件
• Codex 进程被异常杀掉，留下一个暂时的锁文件，重启后本地服务起不来

排查路径：

# 1. 看日志 ls ~/.codex/log/ tail -f ~/.codex/log/codex.log # 2. 确认目录权限 ls -la ~/.codex # 3. 如果权限混乱，修复归属 chown -R 你的用户名:你的用户名 ~/.codex # 4. 如果怀疑有锁文件残留，备份后清掉 mv ~/.codex ~/.codex.bak codex --profile deepseek "test"

注意第 4 步会清掉之前的会话记录和登录态，操作前先备份。

4.3 Claude Code 的报错不要混进 Codex 排障

在搜索相关词的时候，我发现很多人其实在问同一个报错：

'deepseek-v4-pro' is not a model this version of claude code recognizes

这个报错里写了 claude code，不是 codex。Claude Code 是 Anthropic 的命令行编码工具，和 Codex 是完全不同的两个程序。虽然两者都可以配置 DeepSeek 这类第三方模型，但配置方式完全不同：

• Codex 使用~/.codex/config.toml，通过model_provider和profiles定义模型
• Claude Code 使用环境变量ANTHROPIC_BASE_URL和ANTHROPIC_MODEL，并且要求把第三方模型映射成它认识的 Anthropic 模型名

如果你在终端里敲codex却看到 claude code 的报错，先检查你到底执行的哪个命令：

which codex which claude

这两者虽然都是 AI 编码助手，但在配置细节上是两套完全独立的体系。不要拿着 Codex 的配置思路去套 Claude Code，反之亦然。本文只讲 Codex 侧的处理方法，Claude Code 的问题对应去查 Anthropic 模型的兼容配置。

4.4 网络和防火墙导致的超时排查

有一种情况是 Codex 配置看起来全部正确，但请求就是卡住，最后超时。这个时候要分层次排查网络。

先确认服务器能不能访问 DeepSeek 的 API 端点：

curl -sS -m 10 https://api.deepseek.com/v1/models \ -H "Authorization: Bearer $DEEPSEEK_API_KEY"

如果能返回模型列表，说明网络没问题，问题在 Codex 配置上。如果 curl 一直卡着或者报连接超时，那么检查：

# DNS 解析 nslookup api.deepseek.com # 防火墙放行出方向 443 firewall-cmd --list-all # 本机能否 ping 通外网 ping -c 3 api.deepseek.com

Rocky Linux 默认 firewalld 对待出方向流量通常是放行的，但如果你在云主机上用了自定义安全组，出方向规则可能收得很紧。另外还有一点：如果代理环境变量设置过，Codex 会读取HTTP_PROXY之类的变量，影响请求；如果服务器不需要走代理，确认这些变量是空的：

env | grep -i proxy

有的话就unset掉，别让它干扰 Codex 的本地服务。

5. 验证链路与生产环境的使用建议

5.1 一条命令验证全链路

配置完先别急着上复杂任务，先跑一个简单的验证命令：

DEEPSEEK_API_KEY="sk-xxx" codex --profile deepseek \ "读取当前目录下的 README.md，用三句话概括项目用途"

如果能够正常输出回答，说明整条链路已经通了。为了确认请求真的走的是 DeepSeek 而不是官方，我一般会加一个--debug参数再看一眼请求日志：

codex --profile deepseek --debug "你好"

日志里会显示实际请求的 base_url 和模型名。确认 base_url 是api.deepseek.com、模型是deepseek-v4-pro，才算真正确认链路正确。

5.2 调整超时、并发与日志级别

Codex 在长时间跑任务时，可能因为模型推理时间过长导致请求超时。不同版本对超时参数的命名不太一样，我用的版本里可以通过环境变量控制日志级别和超时行为：

export CODEX_LOG_LEVEL=debug export CODEX_MAX_TURNS=20

CODEX_MAX_TURNS限制单次任务的对话轮数，防止它无限循环。这在 CI 场景里很重要，没有限制的话，一个不收敛的 agent 可能把所有资源吃光。

多个任务并发跑也是一个常见的隐藏问题。Codex 的本地服务默认绑定本地端口，如果你开多个 Codex 进程同时跑，偶发会出现端口被占用或本地代理状态互相干扰的情况。我的做法是同一台机器上同时只跑一个 Codex 长任务，短任务可以串行执行。真要并发，用 Docker 容器隔离再跑。

5.3 在 VSCode 与 CI 脚本中调用 Codex 的实践

VSCode 里使用这套方案我推荐两种方式。

第一种，Remote-SSH 连上 Rocky Linux 服务器，直接在集成终端里跑codex。这样既能享受 VSCode 的编辑器体验，又不需要额外装插件。

第二种，如果你希望在编辑器里和 Codex 对话，可以装第三方的 Codex 插件。但要注意：插件通常内置了自己的 OpenAI 配置，不一定读取你在服务器上的~/.codex/config.toml。我实测下来，最稳的还是终端方案，插件的主要问题是配置路径不透明，出了问题反而难排查。

CI 脚本里的用法相对直接，以 GitHub Actions 或 GitLab CI 为例：

- name: 用 codex 做代码评审 env: DEEPSEEK_API_KEY: ${{ secrets.DEEPSEEK_API_KEY }} run: | codex --profile deepseek "review the diff in this MR, point out bugs"

注意在 CI 里不要把 API key 写死在脚本里，走 secrets 或者环境变量注入。另外输出结果最好加上--json选项，方便后续解析。

6. 一些我踩过之后才明白的小细节

最后分享几个零碎的实战细节，都是我反复踩过坑之后才刻进脑子里的。

第一，修改 config.toml 之后，不需要重启任何服务。Codex 每次执行时都会重新读取配置，改完直接再跑一条命令就行。这一点比很多需要 reload 的服务友好多了。

第二，不要在配置文件里直接写明文 API Key。配置env_key指向环境变量是更安全的方式。如果担心环境变量在 Shell session 之间丢失，写到/etc/profile.d/deepseek.sh里，加上权限控制。一旦 key 泄露，立即去控制台吊销并重新生成，别心存侥幸。

第三，版本问题。Codex CLI 更新很快，配置字段和默认行为经常变化。我在网上看到很多过时的教程，照着配置后报各种字段不认识的错。如果你遇到类似问题，优先看官方文档里的 Configuration 章节，以你安装版本的 schema 为准。快速查看配置解析结果的方法：

codex --doc config.toml

这条命令会输出当前版本支持的配置字段说明，比任何博客都权威。

第四，关于模型能力边界。DeepSeek-V4-Pro 在代码理解上表现相当好，但它无法替代你在生产环境的验证环节。Codex 可能基于模型生成看似合理的改动，但真正上线前，测试必须跑过才算数。我在使用中一直坚持：Codex 负责提方案和初步实现，我负责 review 和验证，绝不无脑接受所有改动。这样用下来，这套组合的准确率才真正可接受。