当前位置：首页 > news >正文

Codex CLI全链路实战：离线安装、中文配置与DeepSeek适配

news 2026/7/8 18:56:33

1. 这不是“Codex教程”，而是你真正需要的 Codex 全链路实践手册

Codex 这个词最近在开发者圈子里反复刷屏，但很多人点开搜索结果后发现：要么是零散的几行命令截图，要么是英文文档的机械翻译，再或者干脆是把 GitHub README 直接扔进翻译器生成的“中文文档”。我去年下半年开始系统性地把 Codex 集成进我们团队的三个主力项目里——一个金融风控规则引擎、一个制造业设备日志分析平台、还有一个教育类 SaaS 的智能助教模块。过程中踩过的坑、调通的参数、绕开的依赖陷阱，比任何“官方教程”都实在。今天这篇内容，不讲概念，不堆术语，只说你打开终端、新建文件夹、准备敲命令时，最需要知道的那几件事。核心关键词就三个：Codex、中文文档、实战配置。它适合三类人：刚听说 Codex 想快速上手的初级工程师；被“Codex 设置中文不生效”卡住半天的中级开发者；还有正在评估是否要把 Codex 接入现有 MySQL 或 Git 工作流的技术负责人。你不需要提前装好任何东西，也不用担心环境冲突——我会从第一行curl命令开始，带你走完从下载、离线安装、CLI 初始化、到接入 DeepSeek-v4-pro 模型的完整闭环。所有步骤都经过 Ubuntu 22.04、macOS Sonoma 和 Windows WSL2 三端实测，配置项全部带计算依据，错误提示全部附带定位逻辑。这不是一份“能用就行”的速查表，而是一份你愿意存在本地、随时打开、直接复制粘贴执行的生产级操作手册。

2. Codex 是什么？先破除三个最危险的认知误区

很多教程一上来就甩出“Codex 是 OpenAI 的代码生成模型”这种定义，这就像告诉你“汽车是一种交通工具”一样正确但毫无价值。在真实工程场景中，Codex 的角色远比“模型”复杂得多。我见过太多团队因为没搞清它的本质，在部署阶段直接推倒重来。这里必须先划清三条红线。

2.1 误区一：“Codex = 一个可下载的 .exe 或 .dmg 安装包”

这是搜索热词里“codex下载”“codex离线安装包”“codex安装包”高频出现的根本原因。但事实是：Codex 本身没有独立二进制分发形态。你在网上找到的所有“Codex 安装包”，99% 是三种东西的混合体：（1）基于 Codex 模型权重封装的 Web UI（如某些魔改版 CodeSandbox）；（2）集成了 Codex API 调用逻辑的 IDE 插件（比如 VS Code 的某个第三方扩展）；（3）更常见的是——根本就是名字撞车的其他开源项目（例如一个叫 codex 的 Python 文档生成工具）。真正的 Codex 模型权重，自 2023 年起已不再向公众开放下载，OpenAI 官方仅通过 API 提供服务。所以当你看到“codex安装教程”时，首先要问一句：这个教程到底是在装什么？是装一个调用 API 的客户端？还是在配一个本地模型服务？抑或只是在装一个前端界面？不厘清这点，后续所有操作都是空中楼阁。我们团队最初就栽在这上面——花了三天时间调试一个号称“本地运行 Codex”的 Docker 镜像，最后发现它底层调用的仍是云端 API，所谓的“本地”只是指前端页面跑在本地。

2.2 误区二：“Codex 中文文档 = 英文文档的逐字翻译”

搜索热词里“codex中文文档”“agentscope中文文档”“cesium中文文档”并列出现，说明开发者对中文资料有强烈渴求。但现实很骨感：Codex 官方从未发布过任何中文版文档。所有标榜“中文文档”的内容，基本分两类：一类是社区志愿者维护的非官方翻译，质量参差不齐，且严重滞后——比如 OpenAI 官网 API 文档已更新到 v1.25，而某中文站还停留在 v1.12，关键参数temperature的默认值变更都没同步；另一类则是“伪中文文档”，即把英文原文丢给机器翻译，然后不做任何技术校验。我亲自对比过五个主流“Codex 中文教程”网站，发现它们在解释max_tokens参数时，有四个把单位错译成“字符”，而实际单位是“token”（一个 token 可能是一个汉字、一个标点、甚至一个空格）。这种错误在处理中文时会直接导致 API 调用失败率飙升。所以，所谓“Codex 中文文档”，本质上是你自己构建的一套知识映射体系：左边是英文原意，右边是你在中文语境下理解的准确含义，中间用你的真实项目案例去验证。后面我会给出一套可落地的“双语对照自查表”，帮你绕过所有翻译陷阱。

2.3 误区三：“Codex 接入 = 把 API Key 往配置文件里一填就完事”

这是“codex接入deepseek”“codex配置第三方api”这类热词背后最典型的认知偏差。Codex 的 API 设计天然适配英文编程生态（Python/JS 主流库、GitHub 仓库结构、Stack Overflow 问答风格），当你要把它接入 DeepSeek-v4-pro 这类国产大模型时，问题立刻浮出水面。最典型的是三处断层：（1）Prompt 工程断层：Codex 的 system prompt 默认假设用户用英文提问，而 DeepSeek-v4-pro 的中文指令微调更优，直接套用 Codex 的 prompt 模板，中文生成质量下降 40% 以上；（2）Token 计算断层：Codex 的 tokenizer 对英文单词切分精准，但对中文是按字切分，而 DeepSeek 使用的 Qwen tokenizer 是按词+字混合切分，同样一段 200 字的中文需求描述，Codex 计算为 320 tokens，DeepSeek 实际消耗 480 tokens，超限报错频发；（3）错误处理断层：Codex API 返回的429 Too Many Requests错误，其 retry-after 头部是秒级，而 DeepSeek 的同类错误返回的是毫秒级，不重写重试逻辑，你的服务会在高峰期雪崩。这些都不是改个 URL 就能解决的，而是要深入 SDK 源码层做适配。后面实操环节，我会带着你一行行修改codex-cli的请求构造器，把这三处断层彻底焊死。

3. 从零开始：Codex CLI 的离线安装与中文环境初始化

既然 Codex 本身不可下载，那我们真正要安装的，是它的官方命令行工具codex-cli。这个工具是 OpenAI 官方维护的轻量级客户端，作用是把你在终端输入的自然语言指令，转换成标准 API 请求，并格式化输出结果。它的优势在于：无 GUI 依赖、可脚本化、支持离线配置、且源码完全公开（GitHub 上 star 超过 12k）。下面所有步骤，我都已在 Ubuntu 22.04（Linux）、macOS Sonoma（ARM64）、Windows 11 + WSL2（Ubuntu 22.04）三环境实测通过，命令可直接复制粘贴。

3.1 环境预检：为什么必须用 Node.js 18.x 而不是最新版？

codex-cli的package.json明确声明了"engines": {"node": ">=18.0.0"}。这看起来是个宽松要求，但实际踩坑极多。我测试过 Node.js 20.12 和 21.7 两个版本，均在npm install -g codex-cli步骤报错，错误信息为Error: Cannot find module 'node:fs'。根源在于codex-cli依赖的底层库@openai/nodejs使用了 Node.js 18 引入的node:协议前缀（如require('node:fs')），而该协议在 Node.js 20+ 中虽仍支持，但部分子模块的加载路径发生了变化。更关键的是，Node.js 21 是实验性版本，其 V8 引擎对 Promise 链的处理与 18.x 存在细微差异，导致codex-cli内部的异步重试逻辑失效。因此，强制锁定 Node.js 18.19.1 是唯一稳定方案。安装方式如下：

# Ubuntu/WSL2 curl -fsSL https://deb.nodesource.com/setup_lts.x | sudo -E bash - sudo apt-get install -y nodejs # 验证版本 node -v # 必须输出 v18.19.1 npm -v # 必须输出 9.9.0（Node.js 18.19.1 对应的 npm 版本）

# macOS (使用 Homebrew) brew install node@18 echo 'export PATH="/opt/homebrew/opt/node@18/bin:$PATH"' >> ~/.zshrc source ~/.zshrc node -v # v18.19.1

提示：不要用 nvm 管理多个 Node 版本。codex-cli在全局安装时会读取当前 shell 的node命令路径，nvm 的版本切换机制可能导致 CLI 启动时加载错误的 Node 运行时，引发难以排查的ERR_MODULE_NOT_FOUND错误。直接用系统包管理器安装固定版本，是最稳妥的选择。

3.2 离线安装：如何在无外网的生产服务器上部署？

“codex离线安装包”是运维同事最常提的需求。codex-cli本身不提供离线安装包，但我们可以构建一个可移植的离线安装包。核心思路是：在一台有网络的机器上，下载所有依赖并打包，再拷贝到目标服务器解压安装。具体步骤如下：

# 步骤1：在联网机器上创建临时工作目录 mkdir /tmp/codex-offline && cd /tmp/codex-offline # 步骤2：使用 npm pack 打包 codex-cli 及其所有依赖 npm install -g codex-cli npm pack codex-cli --production # 此命令会生成一个 codex-cli-*.tgz 文件，包含 CLI 本体及 runtime 依赖 # 步骤3：手动下载并打包关键 peer dependencies # codex-cli 依赖 @openai/nodejs，但 npm pack 不会自动包含 peer deps npm install @openai/nodejs@4.29.0 tar -czf openai-nodejs-deps.tgz node_modules/@openai # 步骤4：合并打包 tar -czf codex-offline-bundle.tgz codex-cli-*.tgz openai-nodejs-deps.tgz # 步骤5：将 codex-offline-bundle.tgz 拷贝到目标服务器 scp codex-offline-bundle.tgz user@prod-server:/opt/codex/

在目标服务器（无外网）上执行：

cd /opt/codex tar -xzf codex-offline-bundle.tgz # 安装 codex-cli 本体（注意：-g 全局安装需 root 权限） sudo npm install -g ./codex-cli-*.tgz # 安装 peer dependencies 到全局 node_modules sudo npm install -g ./openai-nodejs-deps.tgz # 验证安装 codex --version # 输出 1.2.4（当前最新稳定版）

注意：此离线包仅包含运行时依赖，不包含开发依赖（如测试框架）。如果你需要在离线环境调试codex-cli源码，需额外打包devDependencies，但生产环境完全不需要。另外，@openai/nodejs@4.29.0这个版本号必须严格匹配，因为codex-cli的package-lock.json锁定了该版本，版本不一致会导致TypeError: Cannot read properties of undefined类错误。

3.3 中文环境初始化：为什么`codex configure`之后中文仍不生效？

这是搜索热词“codex设置中文不生效”背后最普遍的问题。codex-cli的configure命令只负责设置 API Key 和基础 endpoint，它根本不处理语言偏好。中文支持是通过两个隐藏机制实现的：（1）HTTP 请求头中的Accept-Language；（2）Prompt 中的显式语言指令。codex-cli默认不发送Accept-Language头，且其内置 Prompt 模板是纯英文的。解决方案是创建一个自定义配置文件.codexrc，并重写默认 Prompt。

首先，创建配置文件：

# 创建配置目录 mkdir -p ~/.config/codex # 生成初始配置（仅设置 API Key） codex configure --api-key your_actual_api_key_here # 编辑自定义配置 nano ~/.config/codex/config.json

将config.json修改为以下内容：

{ "api_key": "your_actual_api_key_here", "base_url": "https://api.openai.com/v1", "model": "gpt-4-turbo", "temperature": 0.3, "max_tokens": 2048, "headers": { "Accept-Language": "zh-CN,zh;q=0.9,en;q=0.8" }, "prompt_templates": { "default": "你是一名资深的全栈工程师，精通 Python、JavaScript 和 SQL。请用简体中文回答我的所有问题，代码块必须使用中文注释，技术术语首次出现时需附带英文原名（例如：函数（function））。我的问题是：{{input}}" } }

关键点解析：

"headers"字段是codex-cli的隐藏功能，官方文档未提及，但在源码src/config.ts的getHeaders()函数中有明确定义。添加Accept-Language头，能显著提升 API 服务端对中文响应的优先级。
"prompt_templates"是codex-cli的核心扩展点。default模板会覆盖所有未指定模板的请求。其中{{input}}是占位符，会被你输入的指令替换。这个模板强制模型以中文输出，并规范了注释和术语格式，实测可将中文回答的准确率从 68% 提升至 92%（基于我们内部 500 条测试用例的统计）。

实操心得：不要在codex configure交互式流程中输入中文 API Key。某些终端（如 Windows CMD）对 UTF-8 编码支持不佳，会导致 Key 中的特殊字符被截断或乱码，最终 API 调用返回401 Unauthorized。务必在config.json中手动编辑api_key字段，确保 Key 完整无误。

4. 核心能力实战：从单行指令到 MySQL/Git 自动化工作流

codex-cli的价值，绝不仅限于“帮我写个排序算法”。它的真正威力，在于把自然语言指令，无缝嵌入到你每天都在用的开发工作流中。下面我以三个高频场景为例，展示如何用 Codex 彻底重构你的日常操作：MySQL 表结构设计、Git 提交信息生成、以及 Cesium 地图可视化代码生成。每个例子都包含完整命令、参数详解、以及我在生产环境中优化后的最佳实践。

4.1 MySQL 安装配置与表结构生成：告别手写 DDL

搜索热词中“mysql安装配置教程”“mysql8.0安装教程”高居前列，说明 DBA 和后端工程师对数据库初始化仍有大量重复劳动。Codex 可以把“创建一个用户订单表，包含订单ID、用户ID、商品列表JSON、状态枚举、创建时间”这样的自然语言，直接转成可执行的 SQL。但关键在于：如何让生成的 SQL 符合你的生产规范？

首先，确保你的 MySQL 环境已就绪（Ubuntu 22.04 下安装 MySQL 8.0 的标准命令）：

sudo apt update sudo apt install mysql-server sudo mysql_secure_installation # 记录 root 密码，后续配置中要用到

接着，用 Codex 生成符合规范的建表语句。关键不是让它“生成 SQL”，而是让它“生成符合你团队规范的 SQL”。我们团队的规范是：（1）所有表名小写加下划线；（2）主键命名为id，类型为BIGINT UNSIGNED AUTO_INCREMENT；（3）JSON 字段必须加CHECK (column_name IS JSON)约束；（4）状态字段必须用ENUM且明确列出所有值。因此，指令不能是泛泛的“帮我建订单表”，而必须是：

codex "根据以下规范生成 MySQL 8.0 建表语句：1. 表名：user_order；2. 字段：id（BIGINT UNSIGNED AUTO_INCREMENT，主键），user_id（BIGINT NOT NULL），items（JSON，必须加 CHECK (items IS JSON) 约束），status（ENUM('pending','paid','shipped','delivered','cancelled') DEFAULT 'pending'），created_at（DATETIME DEFAULT CURRENT_TIMESTAMP）；3. 引擎：InnoDB；4. 字符集：utf8mb4；5. 排序规则：utf8mb4_unicode_ci。只输出纯 SQL，不要任何解释。"

执行后，你会得到类似这样的结果：

CREATE TABLE `user_order` ( `id` BIGINT UNSIGNED NOT NULL AUTO_INCREMENT PRIMARY KEY, `user_id` BIGINT NOT NULL, `items` JSON NOT NULL, `status` ENUM('pending','paid','shipped','delivered','cancelled') DEFAULT 'pending', `created_at` DATETIME DEFAULT CURRENT_TIMESTAMP, CHECK (items IS JSON) ) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_unicode_ci;

注意事项：Codex 生成的 SQL 默认不带反引号（），但在 MySQL 中，如果表名或字段名是关键字（如order`），不加反引号会报错。因此，我编写了一个简单的 Bash 函数，自动为所有标识符添加反引号：

# 将此函数加入 ~/.bashrc 或 ~/.zshrc codex-mysql() { local sql=$(codex "$1") echo "$sql" | sed -E 's/([a-zA-Z_][a-zA-Z0-9_]*)/`\1`/g' | sed 's/`(`)/\1/g' | sed 's/`(\))/\1/g' } # 使用：codex-mysql "帮我建用户表..."

这个函数用sed正则表达式，匹配所有由字母、数字、下划线组成的单词，并在其前后加上反引号，同时排除掉已有的括号。实测可 100% 覆盖 MySQL 关键字场景。

4.2 Git 提交信息自动化：用自然语言驱动版本控制

“git安装及配置教程”“github使用教程”常年霸榜，但很少有人关注提交信息（commit message）的质量。Codex 可以让你用一句话，生成符合 Conventional Commits 规范的、专业的提交信息。这不仅能提升代码审查效率，还能让git log变成一份可读性极强的项目演进报告。

首先，配置 Git 的prepare-commit-msg钩子，让每次git commit时自动调用 Codex：

# 创建钩子脚本 nano .git/hooks/prepare-commit-msg

写入以下内容：

#!/bin/bash # 获取当前分支名和暂存区变更摘要 BRANCH=$(git rev-parse --abbrev-ref HEAD) CHANGES=$(git diff --cached --name-only | head -n 5 | paste -sd ", " -) # 构造 Codex 指令 PROMPT="你是一名资深 Git 工程师。请根据以下信息生成一条符合 Conventional Commits 规范的英文提交信息：1. 当前分支：$BRANCH；2. 变更文件：$CHANGES；3. 要求：type 为 feat、fix、docs、style、refactor、test、chore 之一，scope 为变更涉及的主要模块（如 api、ui、db），subject 用现在时动词开头，长度不超过 50 字符，body 部分用中文详细说明变更原因和影响（不超过 100 字）。只输出纯文本，不要任何 markdown 格式。" # 调用 codex-cli 并写入 commit message 文件 codex "$PROMPT" > "$1"

赋予执行权限：

chmod +x .git/hooks/prepare-commit-msg

现在，当你执行git add . && git commit时，Git 会自动调用 Codex，生成类似这样的提交信息：

feat(api): add user authentication endpoint 为支持移动端登录，新增 JWT 认证接口 /api/v1/auth/login。后端使用 bcrypt 加密密码，前端需在 Authorization header 中携带 Bearer Token。

实操心得：这个钩子在首次使用时，可能会因网络延迟导致git commit卡住。解决方案是在钩子脚本中加入超时控制：

# 替换原钩子中的 codex 调用行为 timeout 10s codex "$PROMPT" > "$1" 2>/dev/null || echo "chore: commit message generation timeout, please write manually" > "$1"

timeout 10s确保 Codex 调用最多等待 10 秒，超时则写入一条提示信息，避免阻塞开发流程。这是我们在 CI/CD 流水线中强制推行的健壮性保障。

4.3 Cesium 中文文档与三维地图代码生成：从概念到可运行

“cesium中文文档”“bpmnjs中文文档”“fullcalendar中文文档”等热词，反映出前端工程师对复杂 JS 库的中文学习资源有迫切需求。Codex 的价值在这里尤为突出：它不仅能解释 Cesium 的 API，更能直接生成可运行的三维地图代码。

假设你需要在网页中加载一个 3D 地球，并在指定经纬度（116.4, 39.9，即北京）添加一个红色标记点。传统做法是翻阅 Cesium 官方文档，查找CesiumViewer、Entity、PointGraphics等类的用法，再拼凑代码。用 Codex，只需一行指令：

codex "生成一个完整的 HTML 页面，使用 CesiumJS 1.108 版本，创建一个 3D 地球视图，并在经纬度 (116.4, 39.9) 添加一个红色圆形标记点（直径 10 像素），标记点下方显示文字 '北京'。页面需包含所有必需的 CDN 链接、CSS 样式和 JavaScript 初始化代码。只输出纯 HTML，不要任何解释。"

执行后，你会得到一个开箱即用的 HTML 文件，其中关键的 JS 初始化代码如下：

const viewer = new Cesium.Viewer('cesiumContainer', { terrainProvider: Cesium.createWorldTerrain(), baseLayerPicker: false, homeButton: false, sceneModePicker: false, navigationHelpButton: false, animation: false, timeline: false, geocoder: false }); // 添加北京标记点 const position = Cesium.Cartesian3.fromDegrees(116.4, 39.9); viewer.entities.add({ position: position, point: { pixelSize: 10, color: Cesium.Color.RED, outlineColor: Cesium.Color.BLACK, outlineWidth: 2 }, label: { text: '北京', font: '14px sans-serif', fillColor: Cesium.Color.WHITE, outlineColor: Cesium.Color.BLACK, outlineWidth: 2, horizontalOrigin: Cesium.HorizontalOrigin.CENTER, verticalOrigin: Cesium.VerticalOrigin.BOTTOM, pixelOffset: new Cesium.Cartesian2(0, -15) } }); // 飞向北京 viewer.flyTo(viewer.entities, { offset: new Cesium.HeadingPitchRange(0, -1.5707963267948966, 5000000.0) });

关键细节：Codex 生成的代码中，flyTo的offset参数是经过精确计算的。-1.5707963267948966是-π/2弧度，即俯视角 90 度，确保地球正对用户；5000000.0是距离（米），对应约 5000 公里，这个数值能让北京区域在视口中占据最佳比例。这个计算过程，是 Codex 基于 Cesium 的坐标系和相机模型自动完成的，远超人工估算精度。

5. 深度集成：Codex CLI 与 DeepSeek-v4-pro 模型的全链路适配

搜索热词“codex接入deepseek”“codex deepseek-v4-pro”表明，越来越多团队希望用国产大模型替代 OpenAI 的 API，以降低成本、提升数据合规性。但这绝非简单地把base_url改成 DeepSeek 的地址。正如前面误区三所分析，这是一个涉及 Prompt、Token、Error Handling 的全链路改造。下面，我将手把手带你完成codex-cli的源码级适配，整个过程无需重新编译，只需修改配置和少量 JS 代码。

5.1 模型能力对齐：为什么不能直接替换 base_url？

DeepSeek-v4-pro 的 API 兼容 OpenAI 的格式，但存在关键差异：

差异点	OpenAI Codex	DeepSeek-v4-pro	Codex CLI 适配要点
Endpoint	`/v1/chat/completions`	`/v1/chat/completions`	一致，无需修改
System Prompt 位置	`messages[0].content`	`messages[0].content`	一致，无需修改
Temperature 默认值	`1.0`	`0.7`	必须在 config.json 中显式设为`0.7`，否则生成结果过于发散
Max Tokens 计算	基于 tiktoken	基于 Qwen tokenizer	必须重写`src/tokenizer.ts`，否则频繁`400 Bad Request`
Stream 响应格式	`data: {...}\n\n`	`data: {...}\n\n`	一致，无需修改
Rate Limit 错误码	`429`，`retry-after`头为秒	`429`，`retry-after`头为毫秒	必须重写`src/retry.ts`，否则重试逻辑失效

因此，“接入”不是配置，而是适配。核心改造点只有两个：Token 计算和重试逻辑。

5.2 Token 计算重写：解决中文超限的核心

codex-cli默认使用@dqbd/tiktoken库计算 token 数量，该库对英文精准，但对中文是按字切分。DeepSeek 使用的 Qwen tokenizer 是按词+字混合切分，同一段中文，两者计算结果相差可达 50%。我们必须替换 tokenizer。

首先，安装 Qwen tokenizer 的 Node.js 绑定：

npm install @qwen/tokenizer

然后，创建自定义 tokenizer 文件~/.config/codex/tokenizer.js：

const { QwenTokenizer } = require('@qwen/tokenizer'); // 初始化 Qwen tokenizer（自动下载模型文件） const tokenizer = new QwenTokenizer(); module.exports = { countTokens: (text) => { // Qwen tokenizer 的 encode 方法返回 token ID 数组 const tokens = tokenizer.encode(text); return tokens.length; }, truncateText: (text, maxTokens) => { // 截断逻辑：先编码，再解码前 maxTokens 个 token const tokens = tokenizer.encode(text); if (tokens.length <= maxTokens) return text; const truncatedTokens = tokens.slice(0, maxTokens); return tokenizer.decode(truncatedTokens); } };

最后，在config.json中启用自定义 tokenizer：

{ "api_key": "your_deepseek_api_key", "base_url": "https://api.deepseek.com/v1", "model": "deepseek-chat", "temperature": 0.7, "max_tokens": 2048, "tokenizer": "~/.config/codex/tokenizer.js" }

提示：@qwen/tokenizer会自动下载约 12MB 的 tokenizer 模型文件到node_modules/@qwen/tokenizer/models/。首次运行时会有短暂延迟，这是正常现象。后续调用将直接使用缓存。

5.3 重试逻辑重写：让服务在高峰期依然稳定

DeepSeek 的429错误返回的retry-after头部单位是毫秒，而codex-cli的默认重试器src/retry.ts期望的是秒。如果不修改，retry-after: 500会被当作“等待 500 秒”，导致服务长时间不可用。

创建~/.config/codex/retry.js：

// 重写 retry 逻辑，适配 DeepSeek 的毫秒级 retry-after module.exports = { shouldRetry: (error) => { return error.response?.status === 429; }, getDelay: (error, attemptNumber) => { const retryAfter = error.response?.headers?.['retry-after']; if (retryAfter) { // DeepSeek 返回的是毫秒，直接使用 return parseInt(retryAfter, 10); } // 指数退避作为兜底 return Math.pow(2, attemptNumber) * 1000; } };

并在config.json中引用：

{ "retry": "~/.config/codex/retry.js" }

现在，当你调用codex "用中文写一个快速排序算法"时，codex-cli会：

使用 Qwen tokenizer 精确计算输入文本的 token 数；
如果超过max_tokens，自动截断；
发送请求到 DeepSeek API；
如果收到429，读取retry-after头部，精确等待指定毫秒后重试。

整个链路完全透明，你只需关心自然语言指令本身。

6. 常见问题与排查技巧实录：那些官方文档不会告诉你的真相

在长达 8 个月的 Codex 生产环境实践中，我和团队记录了 137 个真实报错案例。下面精选 5 个最高频、最隐蔽、最易被忽略的问题，附上我的独家排查路径和根治方案。这些问题，99% 的“Codex 教程”都不会提及，但它们恰恰是决定你能否把 Codex 真正用起来的关键。

6.1 问题：`codex`命令在终端中找不到，但`npm list -g codex-cli`显示已安装

现象：which codex返回空，codex --version报错command not found，但npm list -g codex-cli显示codex-cli@1.2.4。

根因分析：npm install -g默认将可执行文件链接到/usr/local/bin（macOS/Linux）或C:\Users\<user>\AppData\Roaming\npm（Windows）。但你的PATH环境变量中可能没有包含这个路径。更隐蔽的情况是：你使用了sudo npm install -g，导致codex二进制文件的所有者是root，而你的普通用户账户没有执行权限（ls -l $(which codex)会显示-rwxr-xr-x 1 root root ...）。

排查步骤：

查找codex二进制文件的实际位置：npm bin -g
检查该路径是否在PATH中：echo $PATH | grep "$(npm bin -g)"
如果不在，将其加入~/.bashrc或~/.zshrc：export PATH="$(npm bin -g):$PATH"
如果权限问题，修复所有权：sudo chown -R $USER:$(id -gn $USER) $(npm bin -g)

根治方案：永远使用npm install -g而非sudo npm install -g。如果已用sudo安装，执行sudo chown -R $USER:$(id -gn $USER) /usr/local（macOS/Linux）或sudo chown -R $USER %APPDATA%\npm（Windows）。

6.2 问题：`codex configure`后，`codex`命令仍提示`API key is required`

现象：codex configure --api-key sk-xxx执行成功，但随后codex "hello"仍报错Error: API key is required。

根因分析：codex configure命令会将 API Key 写入~/.config/codex/config.json，但codex-cli在启动时，会按顺序检查多个配置源：（1）命令行--api-key参数；（2）环境变量OPENAI_API_KEY；（3）配置文件~/.config/codex/config.json。如果环境变量OPENAI_API_KEY被设为空字符串（export OPENAI_API_KEY=""），codex-cli会认为 API Key 为空，从而忽略配置文件。

排查步骤：