Codex 命令行 AI 编程助手：从安装到实战的完整指南

Codex 是 OpenAI 推出的命令行 AI 编程助手。它能在你的项目目录里直接读取代码文件，按照自然语言指令生成代码修改、执行终端命令、查看日志，并把改动写入磁盘或提交到 Git。这篇文章面向刚接触 Codex 的开发者，按安装、登录、第一个实战、日常用法、配置、排错的完整链路展开。

网上经常看到“2026 最新 Codex 教程”这种标题，但我的建议是：年份不是重点。Codex 迭代很快，今天用的安装命令，下个月可能变成旧命令；真正能复用的是思路和排查顺序。下面从零开始拆一遍。

1. 装之前先搞清楚：Codex 是什么、解决什么问题、需要什么条件

1.1 Codex 到底解决什么问题

如果你用过网页版 ChatGPT 写代码，流程一般是：把代码复制进去，它给你一段结果，你再贴回编辑器。这种模式在单文件、小片段场景下够用，但一旦涉及多文件项目，就很麻烦。Codex 做的事情是把 AI 放进你的本地环境里：

• 读取当前目录下的文件树和文件内容；
• 根据需求直接生成代码补丁；
• 执行终端命令，比如运行测试、查看日志、创建目录；
• 修改完成后用 Git 记录改动。

所以它的核心价值不是“帮你写一段代码”，而是“帮你在真实项目里完成一次改动”。这个区别很重要。

1.2 它和网页版 AI 工具有哪些区别

同样是 AI 编程，不同产品形态差别很大。插件类工具通常在编辑器里给你补全和建议，你负责点击接受；网页端聊天工具只负责生成文本，不接触你的本地环境。Codex 更像一个能执行任务的终端同事：它能看到当前目录，能调用命令，能直接改文件。

这对哪些人最有用？对已经习惯命令行、在终端里完成日常开发的人最有用。你不需要切换页面，不需要复制粘贴，一条指令进去，改动直接落在本地文件系统里。

1.3 运行 Codex 需要哪些基础条件

这里先给出一个最小环境清单，避免你装到一半才发现缺东西：

• 操作系统：macOS、Linux、Windows 都可以，Windows 上推荐使用 WSL 或原生终端，命令兼容性更好；
• Node.js：一般需要 18 及以上版本，npm 会随 Node.js 一起安装；
• Git：建议安装并完成基础配置，因为 Codex 修改代码后可能会自动创建 Git 提交；
• 账号或 API Key：二选一即可，登录方式不同，后面会单独讲；
• 网络条件：Codex 的模型请求要访问其接口服务，网络不通畅会直接影响登录和响应；
• 磁盘空间：命令行程序本身占用不大，几百 MB 足够，但项目依赖、日志、模型缓存会逐渐增加。

这里有个容易误解的地方：很多人以为 Codex 像本地大模型一样需要 GPU、需要几十 GB 显存。其实不需要。Codex 在本地主要处理文件和命令调度，真正的推理发生在云端模型接口上。所以低配置笔记本完全可以跑，慢也主要慢在网络响应，而不是本地算力。

2. 环境准备：Node.js、npm、Git 一次配齐

2.1 Node.js 与 npm 的安装和验证

Codex 的官方安装方式以 npm 为主，所以第一步是把 Node.js 环境装好。

选择安装包时，建议直接下载官网的 LTS 版本。LTS 代表长期维护版本，稳定性更好，没必要追求最新大版本。安装过程中，Windows 用户要特别注意勾选“Add to PATH”，否则安装完成后敲 node 命令会提示找不到。

安装完成后，重新打开一个终端，输入：

node -v npm -v

能正常输出版本号，说明 Node.js 和 npm 已经进入 PATH。如果提示 “node 不是内部或外部命令”，优先确认 PATH 是否配置成功，而不是重新安装。

2.2 Git 安装和基础配置

Codex 在生成代码或修改文件后，经常会把改动提交到 Git。如果系统里没有 Git，或者 Git 没有配置用户信息，提交就会失败。

安装 Git 后，执行 git --version 确认版本。然后配置用户名和邮箱：

git config --global user.name "你的名字" git config --global user.email "你的邮箱@example.com"

这一步很容易被跳过。很多新手在 Codex 运行到一半时，看到 “Author identity unknown” 或类似报错，就是因为没有配置 user.name 和 user.email。提前配好能省掉一个常见卡点。

2.3 其他运行时和目录规划

Codex 本身不依赖 Python，但它生成的代码可能会用到 Python、Node、Go、Rust 等运行时。你不需要把所有语言都装一遍，按你准备测试的项目类型来装就行。

如果你只是跟着本文先跑通流程，我建议装一个 Python 3.10 以上版本。因为很多演示任务用 Python 写最简单，比如处理文件、批量重命名、生成 CSV。

目录规划上，建议单独创建一个测试目录，不要直接在系统目录、项目根目录或服务器生产目录里做第一次测试。一个隔离的目录能让你放心观察 Codex 的改动，也能避免它访问到不该访问的文件。

3. 安装 Codex 的常用方式与版本选择

3.1 使用 npm 全局安装

环境准备好之后，安装 Codex 最常用的方式就是 npm 全局安装：

npm install -g @openai/codex

安装完成后，执行：

codex --version

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

如果在 Linux 或 macOS 下遇到权限报错，可能是 npm 全局目录归 root 所有。你可以用 sudo 安装，也可以配置 npm 的全局目录。我更推荐使用 nvm 或 fnm 管理 Node.js 版本，这样可以避免把 npm 全局目录放在系统保护目录里。

3.2 使用 Homebrew 安装

macOS 用户如果已经习惯使用 Homebrew，可以执行：

brew install codex

Homebrew 安装的好处是卸载、升级和管理都统一。缺点是包的更新速度可能比 npm 慢一些。两种方式选一种即可，不需要同时装。

3.3 官方安装包和桌面应用

部分版本还会提供官方安装包或桌面应用。桌面应用的交互更贴近图形界面，适合不太想碰命令行的新手。

但我的建议是：即使安装了桌面版，也最好把命令行版跑通。因为很多真实使用场景，比如在远程服务器、CI 流水线、自动化脚本里调用 Codex，都需要命令行能力。桌面版可以作为补充，不能完全替代 CLI。

3.4 版本更新与“最新教程”怎么理解

Codex 的版本更新频率不低。你会发现网上教程里的命令和实际命令偶尔对不上，这很正常。遇到这种情况，先不要怀疑安装错了，而是执行：

codex --help

或者去官网查看当前版本的文档。所谓“2026 最新教程”，在软件迭代面前只是一个时间标记。真正重要的是掌握“查看帮助、确认版本、按文档执行”的方法。

4. 登录与鉴权：账号登录和 API Key 两种方式怎么选

4.1 方式一：ChatGPT 账号登录

安装完成后，执行：

codex login

它会尝试打开浏览器，跳转到官网进行授权。你在浏览器里确认登录后，终端会显示登录成功或类似提示。

如果浏览器没有自动弹出，不要慌。终端里通常会给出一个完整 URL，手动复制到浏览器里访问即可。需要注意的是，登录会话信息会保存在本地的配置目录里，比如 ~/.codex/auth.json。这个文件相当于你的登录凭证，不要分享给别人，也不要提交进 Git。

4.2 方式二：设置 API Key

如果你不使用账号登录，而是希望通过 API Key 调用模型接口，可以先生成一个 API Key，然后把它写入环境变量。

在 Linux 或 macOS 下：

export OPENAI_API_KEY="你的 key"

在 Windows PowerShell 下：

$env:OPENAI_API_KEY="你的 key"

如果希望长期生效，可以把 export 那行写入 ~/.bashrc、~/.zshrc 或系统环境变量。不要直接写在项目代码里，更不要提交到 Git 仓库。否则一旦仓库泄露，Key 就相当于公开了。

4.3 登录成功之后怎么看

登录或 Key 配置完成后，最直接的验证方式是直接运行 codex，进入交互界面。如果没有要求再次登录，说明鉴权已经生效。

如果你不确定当前登录状态，可以查看配置目录下的 auth.json 是否存在，或者检查环境变量是否被当前终端加载：

echo $OPENAI_API_KEY

如果输出为空，说明环境变量没设置成功，检查 export 语句和终端是否已经重新加载。

4.4 免费套餐、订阅套餐与 API Key 费用

关于费用，我不建议依赖教程里的数字。账号套餐、API 价格都会调整，而且不同地区的结算方式可能不同。你需要自己去官网查看当前价格页，尤其是 API 按量计费时，模型单价、上下文长度、缓存策略都会影响最终费用。

一个比较稳妥的习惯是：第一次测试时使用默认配置，任务规模控制在单文件、小数据量。跑通之后再考虑批量任务。这样即使产生费用，也只会是很小的一笔。

5. 第一个实战：从空目录开始跑通一条任务

5.1 创建测试项目

先创建一个干净的测试目录：

mkdir codex-demo cd codex-demo

如果目录是空的，Codex 面对的就是一个全新项目，它需要从零开始创建代码。这比“在已有复杂项目里改代码”更适合第一次体验。

5.2 在交互模式下让 Codex 写脚本

在目录里执行：

codex

进入交互界面后，用中文描述任务。比如：

“写一个 Python 脚本，把当前目录下所有 .log 文件按文件大小从大到小排序，统计每个文件的行数，输出到 summary.csv。”

Codex 会先给出执行计划，然后创建文件、写入代码。如果它想执行 python 命令，交互界面会询问你是否允许。第一次测试时，我建议不要直接点全部允许，而是先看它要执行什么命令，再逐个确认。

这里有一个很重要的原因：Codex 的执行能力延伸到了本机环境，它不只是“写代码”给你看，还会“跑代码”给你看。如果它执行的是一个你不理解的命令，后果很难预测。所以在测试阶段保持确认，能帮你建立基本的控制感。

5.3 用非交互模式快速执行单次任务

如果你已经确认基本流程没问题，可以使用非交互模式，直接传一条指令：

codex exec "给当前目录下的 app.py 增加 try-except 日志，不要改变原有接口"

这个模式适合单次任务、自动化脚本和 CI 集成，不需要进入交互界面。具体子命令名可能随版本变化，执行 codex --help 能看到当前版本支持的写法。

5.4 验证输出和 Git 提交

任务执行完后，不要只看 AI 在终端里的文字回答，关键要看文件系统发生了什么：

git status git diff git log --oneline

• git status 看哪些文件被新增或修改；
• git diff 看具体代码变更内容；
• git log 看 Codex 是否自动创建了提交记录。

如果它没有自动提交，你可以自己提交。第一次实战的验收标准应该是：脚本能运行，输出文件内容正确，原目录的文件没有被误删。只要满足这三条