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 codexHomebrew 安装的好处是卸载、升级和管理都统一。缺点是包的更新速度可能比 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 --onelinegit status 看哪些文件被新增或修改git diff 看具体代码变更内容git log 看 Codex 是否自动创建了提交记录。如果它没有自动提交你可以自己提交。第一次实战的验收标准应该是脚本能运行输出文件内容正确原目录的文件没有被误删。只要满足这三条