OpenAI Codex CLI 完全上手指南：把 AI 编程助手装进终端

同事在用 Cursor 写代码，你在旁边看着羡慕——

官方下载地址：https://github.com/openai/codex（通过 npm 安装：npm install -g @openai/codex）

但你不知道的是，有一个更极客、更自由的玩法，它不需要 GUI，不依赖任何 IDE，直接在终端里跑，还能读写你的本地文件、执行系统命令。你可以直接让它帮你写完一个脚本然后自动运行——全程不离开终端。

这个工具叫 Codex CLI，是 OpenAI 开源的终端 AI 编程代理。它和 Copilot、Cursor 不是同类产品，它更像一个"住在终端里的程序员"——你描述需求，它动手实现，从写代码到执行，一气呵成。

中国用户想真正跑起来，还差一个关键步骤：换掉官方 API 入口。这篇文章会手把手带你完成全部配置。

第一章：Codex CLI 是什么，为什么值得折腾？

先搞清楚定位，避免和现有工具混淆。

它不是 Copilot，不是 Cursor

Codex CLI 的核心差异在于本地控制权：它不只是"生成代码给你看"，而是真的可以在你的机器上执行命令、修改文件、读取项目结构，然后把结果反馈给你。这对脚本自动化场景来说，是质的飞跃。

它的典型使用姿势

你：帮我把这个目录下所有 .log 文件按日期归档到子文件夹
Codex：（分析目录结构 → 生成脚本 → 请求你确认 → 执行 → 报告结果）

整个过程在终端里完成，不需要打开任何 GUI。对于习惯命令行的开发者，这个工作流极其顺滑。

第二章：安装与环境准备

前置要求

• Node.js 版本：需要 v18.0.0 或以上（推荐 v20 LTS）
• npm 版本：v8+

检查你当前的版本：

node --version
npm --version

如果版本不对，推荐用 nvm 管理 Node 版本：

# 安装 nvm（macOS/Linux）
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash

# 安装并切换到 Node 20
nvm install 20
nvm use 20

安装 Codex CLI

npm install -g @openai/codex

或者不想全局安装，用 npx 临时运行：

npx @openai/codex

中国用户三大卡点

卡点 1：npm 下载慢甚至超时

# 一行切换到淘宝镜像源
npm config set registry https://registry.npmmirror.com

卡点 2：Node 版本过低报错

报错信息：SyntaxError: Unexpected token '??='

修复：nvm install 20 && nvm use 20，然后重新安装。

卡点 3：全局安装权限报错（macOS）

报错信息：EACCES: permission denied

修复：sudo npm install -g @openai/codex，或者更优雅的方案是配置 npm 全局目录到用户目录下（避免以后每次都 sudo）：

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

安装验证 ✅

codex --version

看到版本号输出，说明安装成功。

第三章：接入 8848AI API 中转——中国用户的核心配置

这是全文最重要的章节。官方文档不会告诉你，在中国直接连 api.openai.com 会稳定报错。配完这一步，后面所有操作都和境外用户完全一样。

为什么需要 API 中转？

OpenAI 官方 API 在国内无法直连，即使挂了代理也经常不稳定，尤其是 Codex CLI 这类需要持续对话的场景，连接中断会导致任务失败。

API 中转服务的原理是：在国内可访问的服务器上做一层转发，你的请求发到中转地址，中转服务帮你转发到 OpenAI，返回结果。对 Codex CLI 来说，只需要把 API 地址换掉，其他一切不变。

配置方式一：.env 文件（推荐用于项目级配置）

在你的工作目录下创建 .env 文件：

# .env
OPENAI_API_BASE=https://api.884819.xyz/v1
OPENAI_API_KEY=你的Key

配置方式二：Shell 永久配置（推荐用于全局生效）

# 写入 ~/.zshrc 或 ~/.bashrc
export OPENAI_API_BASE="https://api.884819.xyz/v1"
export OPENAI_API_KEY="你的Key"

# 立即生效
source ~/.zshrc

本文所有实战演示均通过 8848AI API 中转服务完成测试，国内直连稳定，支持 OpenAI 全系模型。

配置地址：api.884819.xyz，注册后即可获取 API Key，新用户注册即送体验额度

如果你还没有 Key，现在去注册，5 分钟后回来继续跟着做。

验证连通性

配置完成后，跑一条测试命令确认连接正常：

curl https://api.884819.xyz/v1/models \
  -H "Authorization: Bearer $OPENAI_API_KEY"

如果返回一个模型列表的 JSON，说明配置成功 ✅

然后启动 Codex CLI：

codex

第一次启动会进入交互式配置向导，选择你的默认模型（推荐先选 gpt-5.4），配置完成即可开始使用。

第四章：终端编码实战——5 个真实场景演示

环境配好了，直接上手。以下 5 个场景从简单到复杂，每个都给出完整的 Prompt 和命令。

场景 1：生成一个爬虫脚本

Prompt：

帮我写一个 Python 脚本，爬取 https://example.com 的所有文章标题和链接，
保存到 articles.csv，用 requests + BeautifulSoup 实现，加上异常处理

命令：

codex "帮我写一个 Python 脚本，爬取 https://example.com 的所有文章标题和链接，保存到 articles.csv，用 requests + BeautifulSoup 实现，加上异常处理"

Codex 会生成完整脚本，询问你是否直接写入文件并执行。确认后，articles.csv 自动生成 ✅

场景 2：自动重构一段烂代码

把需要重构的文件放在当前目录，然后：

Prompt：

读取 utils.py，帮我重构这个文件：
1. 把重复逻辑抽成函数
2. 变量名改成有意义的英文命名
3. 加上类型注解
4. 保持原有功能不变，重构完直接覆盖原文件

codex "读取 utils.py，帮我重构这个文件：把重复逻辑抽成函数，变量名改成有意义的英文命名，加上类型注解，保持原有功能不变，重构完直接覆盖原文件"

Codex 会先读取文件内容，展示重构方案，确认后写入 ✅

场景 3：批量重命名文件

Prompt：

把当前目录下所有 "IMG_XXXX.jpg" 格式的文件，
按照文件修改时间重命名为 "2024-01-15_001.jpg" 这样的格式，
先预览要改哪些文件，我确认后再执行

codex "把当前目录下所有 IMG_XXXX.jpg 格式的文件，按照文件修改时间重命名为 2024-01-15_001.jpg 这样的格式，先预览要改哪些文件，我确认后再执行"

这个场景完美体现了 Codex CLI 的优势：它会先列出预览清单，等你确认，再批量执行——比手写 shell 脚本安全得多 ✅

场景 4：读取本地 CSV 生成数据分析脚本

Prompt：

读取 sales_data.csv，帮我生成一个数据分析脚本：
1. 统计每个月的销售总额
2. 找出销售额最高的前 5 个产品
3. 用 matplotlib 画一张月度趋势折线图，保存为 report.png
4. 用 pandas 实现，脚本保存为 analyze.py 并直接运行

codex "读取 sales_data.csv，生成数据分析脚本：统计每月销售总额、找出TOP5产品、用matplotlib画月度趋势图保存为report.png，用pandas实现，保存为analyze.py并运行"

Codex 会自动检查你是否安装了 pandas 和 matplotlib，如果没有还会提示你安装 ✅

场景 5：在项目目录里自动补全单元测试

Prompt：

分析 src/ 目录下的所有 Python 文件，
找出没有对应测试文件的函数，
用 pytest 风格帮我生成单元测试，
测试文件放到 tests/ 目录，命名规则是 test_原文件名.py

codex "分析 src/ 目录下所有 Python 文件，找出没有测试覆盖的函数，用 pytest 风格生成单元测试，放到 tests/ 目录，命名为 test_原文件名.py"

这个场景是 Codex CLI 真正的杀手级用法——它能理解整个项目结构，而不只是处理单个文件 ✅

第五章：避坑指南与进阶配置

高频问题解答

Q：Token 超限怎么办？

长对话或大文件会触发 Token 限制。解决方案：

1. 用 --model o4-mini 切换到更小的模型，上下文窗口相同但成本更低
2. 把大文件拆分，分段处理
3. 用 --no-context 参数关闭历史上下文（适合独立任务）

Q：沙箱模式（--sandbox）什么时候必须开？

当你让 Codex 执行涉及删除、覆盖、系统级操作的命令时，强烈建议开启：

codex --sandbox "删除所有临时文件"

沙箱模式下，Codex 会把所有文件操作限制在一个隔离环境里，不会真正修改你的系统。

Q：如何指定模型版本控制成本？

# 复杂任务用 gpt-5.4，效果最好
codex --model gpt-5.4 "重构整个项目架构"

# 简单任务用 o4-mini，成本约为 gpt-5.4 的 1/5 左右
codex --model o4-mini "帮我写一个 hello world"

成本参考（估算）： 一个典型的"生成 50 行 Python 脚本"任务，gpt-5.4 消耗约 800-1200 Token，o4-mini 消耗类似但单价更低，适合高频简单任务。具体以实际账单为准。

生产级推荐配置模板

在项目根目录创建 codex.config.json：

{
  "model": "gpt-5.4",
  "approvalMode": "suggest",
  "sandbox": false,
  "contextFiles": [
    "README.md",
    "src/",
    "package.json"
  ],
  "systemPrompt": "你是一个资深 Python 工程师，代码风格遵循 PEP8，所有函数必须加类型注解和 docstring。"
}

• approvalMode: "suggest"：Codex 提建议，你手动确认每一步（最安全）
• approvalMode: "auto"：自动执行（适合你完全信任的批处理任务）
• contextFiles：告诉 Codex 优先读取这些文件来理解项目背景

写在最后

想象一下，下次接到一个重复性的文件处理任务——整理日志、批量格式转换、给老项目补测试——你打开终端，三句话描述需求，Codex 跑完，你去喝咖啡。

这不是未来，今天就能实现。

Codex CLI 的学习曲线其实不陡，最难的部分是"相信它能做到"。当你第一次看着它自己读文件、自己写脚本、自己执行完报告结果，那种感觉会让你重新定义"编程效率"这四个字。

Codex CLI 的能力边界，其实远不止"写代码"。

下一篇，我们会把它和 Shell 脚本 + GitHub Actions 结合起来，搭建一条"需求描述 → AI 生成代码 → 自动测试 → 自动部署"的全自动流水线——真正意义上的 AI 驱动的 DevOps。

关注 8848AI，不要错过。

8848AI 平台信息

• 网址：api.884819.xyz
• 注册方式：用户名 + 密码直接注册，无需邮箱验证

• **新用户新用户注册即送体验额度。

• 无月租、无订阅，按量付费

本文由8848AI原创，转载请注明出处。关注8848AI，带你从零开始学AI。

AI编程 #CodexCLI #OpenAI #终端开发 #8848AI #AI工具 #开发者工具 #编程效率