最近我身边问Codex的人明显多了起来。这里说的不是很多年前那个代码补全插件而是现在这个跑在终端里的AI编程助手Codex CLI它和Claude Code一起成了开发圈里讨论热度最高的两个命令行AI工具。Codex的特点是直接接入你的本地环境在终端里读取代码、修改文件、执行命令像一个真正坐在你旁边帮你写代码的同事。这一篇是Codex快速入门系列的第二篇主题非常明确命令行安装与使用。我会从环境准备、安装方式、登录鉴权、日常用法到实战案例一步一步带你把它跑起来。如果你已经装到一半卡住了直接跳到后面的速查表大部分坑都在里面。1. 开工之前的准备工作环境与终端1.1 Codex到底依赖哪些基础环境Codex是一个命令行工具它不像IDE插件那样需要一个完整的图形界面但它对运行时环境有自己的要求。我实测下来下面这几项是必须的Node.js 18或更高版本。这不是可选项Codex的npm包依赖Node的现代特性版本太低会直接装不上或者装上了启动就报错。我建议直接装Node.js 20 LTS目前稳定性和生态兼容性都最好。Git。Codex在做代码修改时经常会查看git status、git diff它需要借助git来了解文件变更情况。如果你所在的项目还没用git我也强烈建议先git init不然Codex很难判断它改了哪些内容回滚也会很麻烦。一个能正常连网的终端环境。这个后面会专门讲。很多人会问我电脑上已经装了VSCode还需要额外装Node吗答案是需要。VSCode自带的是编辑器运行环境和命令行工具是两回事。最简单的判断方法是在终端里执行node -v能输出版本号就说明Node没问题。1.2 为什么终端选型这么重要Windows用户如果还在用老式cmd窗口我建议立刻换成Windows Terminal或PowerShell。理由有三第一Codex的彩色输出和老cmd兼容性很一般容易出现文字错位、颜色丢失第二交互式会话需要支持快捷键老cmd的体验非常掉价第三Windows Terminal支持标签页你可以一边开Codex会话一边开另一个终端跑git命令效率完全不一样。macOS用户系统自带的Terminal其实够用但我个人更推荐iTerm2毕竟分屏、搜索、历史回放都更顺手。这些工具不影响Codex本身的功能但会直接影响你每天的使用心情别在这上面省时间。1.3 追加一条先查旧版本再动手在正式安装前我强烈建议先执行一条检查命令where codex # Windows which codex # macOS/Linux为什么要先查因为很多人电脑上可能已经装过同名工具或者装过早期版本的Codex如果不清理干净新装的codex可能会被PATH里排在前面的旧版本覆盖导致你明明装了新版跑出来还是旧行为。这个坑我踩过不止一次。如果没有输出说明当前没有同名可执行文件可以放心安装。如果有输出仔细看一下路径是否可疑比如不在npm目录、不在系统标准路径下先处理掉再继续。2. 三种安装方式按需求选一种2.1 npm全局安装主流首选npm install -g openai/codex这是官方推荐的安装方式也是我目前最推荐的方式。安装完成后直接运行codex --version验证一下。为什么推荐npm三个原因升级简单。官方发布新版你只需要执行npm update -g openai/codex一步到位。用二进制包的话你得手动下载、解压、替换过程繁琐且容易出错。回滚方便。如果某个新版本引入了问题用npm install -g openai/codex上一版本号就能切回去。社区生态好。Codex的配置、插件、相关工具基本都围绕npm包来做用npm安装能少踩很多兼容性坑。npm安装时偶尔会遇到下载超时可以设置更长的超时时间npm install -g openai/codex --fetch-timeout6000002.2 Homebrew安装macOS用户的选择macOS用户也可以直接brew install codexHomebrew会帮你管理好可执行文件、依赖和升级brew upgrade codex就能更新。如果你平时已经习惯了用Homebrew管理开发工具这种方式最自然。需要提醒的是npm和Homebrew这两条路不要混着走。我之前在一台Mac上先用了npm后来又手痒用brew装了一个结果两个版本路径不同系统调用时经常出现诡异问题。后来我把其中一个卸载干净才恢复正常。2.3 下载二进制包最干净的环境如果你不想依赖Node.js或者公司机器权限管控严格可以直接从GitHub Releases页面下载对应平台的压缩包。Windows下载win-x64的zipmacOS下载darwin-arm64或darwin-x64的tar.gzLinux下载linux-x64的压缩包。解压之后把codex可执行文件放到一个你习惯放工具的目录比如WindowsC:\tools\codexmacOS/Linux/usr/local/bin或~/bin然后把该目录加入PATH。以Windows为例在系统环境变量里的PATH项追加一行C:\tools\codex保存后重开终端就能用codex命令了。这个方式的缺点是升级全靠手动并且没有包管理器帮你处理依赖冲突。优点是我见过最干净的部署方式适合对系统环境有洁癖的工程师。我来把三种方式整理成一张表方便你对照安装方式命令/操作适合场景升级方式npmnpm install -g openai/codex绝大多数用户npm update -g openai/codexHomebrewbrew install codexmacOS/Linux用户brew upgrade codex二进制包手动下载解压、配置PATH无Node环境、追求干净手动替换文件2.4 安装之后的验证无论你用了哪种方式装完都建议跑这两步codex --version codex --helpcodex --version确认版本号codex --help能看到全部子命令login、exec、logout等。如果这两条都正常说明安装这关已经过了。如果codex命令找不到不用慌99%是PATH问题。Windows用户检查npm全局目录是否在PATH里用npm config get prefix查macOS/Linux用户检查/usr/local/bin或~/.npm-global/bin是否在PATH里。3. 登录、鉴权与模型接入3.1 第一次login的完整流程安装完成后第一次使用要先登录。直接运行codex login这个命令会生成一个一次性授权链接自动打开浏览器让你登录ChatGPT账号并确认授权。浏览器里确认之后会显示一个授权码把它复制回终端粘贴看到登录成功的提示就完成了。如果你在远程服务器上工作终端里没有浏览器同样可以用codex login它会把授权链接显示在终端里你可以在本地电脑的浏览器打开链接完成授权然后把授权码粘贴回服务器终端。注意授权码有效期一般不长操作太慢会过期过期了重新执行一次codex login就好。登录完成后Codex会在本地配置目录里生成一个auth.json里面保存了后续请求所需的认证信息。Windows路径一般是%USERPROFILE%\.codex\auth.jsonmacOS/Linux是~/.codex/auth.json。3.2 auth token报错的排查思路有一个非常典型的错误codex auth token is unavailable。这个我遇到过很多次总结下来三种最常见的原因登录缓存过期但本地文件还残留着旧信息多账号切换导致token错乱终端环境变量里设置了一些和认证冲突的内容处理顺序我给一个标准操作先执行codex logout清理旧登录状态再执行codex login重新登录如果还是不行手动删除auth.json然后重新登录如果依然报错检查终端的环境变量里有没有OPENAI_API_KEY或类似的键值如果有确认它是不是正确的Key或者清掉后重试删除auth.json前记得做好备份虽然它的内容可以重新生成但万一你里面还配了其他服务的token呢。3.3 接入第三方模型以DeepSeek为例Codex默认连接OpenAI的模型服务但很多朋友更习惯用自己的模型API比如DeepSeek。这个是完全可以的原理就是让Codex把请求发到你指定的API服务端点。在Codex的配置文件~/.codex/config.toml里可以这样配置model deepseek-chat model_provider deepseek [model_providers.deepseek] name DeepSeek base_url https://api.deepseek.com/v1 env_key DEEPSEEK_API_KEY注意这里的关键点model对应的是你在模型平台开通的模型名称要写平台给的真实模型名base_url是这个模型平台的API接入地址进入控制台就能找到env_key是环境变量的名字Codex会在启动时读取这个变量作为API Key推荐这种方式别把密钥明文写进config文件设置好之后还需要先把DEEPSEEK_API_KEY这个环境变量配好。Windows在系统环境变量里新增macOS/Linux写进~/.zshrc或~/.bashrc然后重开终端生效。配置完成之后运行codex它就会通过你配置的模型服务来响应对话了。3.4 配置文件里常见的几个坑配置config.toml时最容易犯的错有三个第一模型名写错。比如报the gpt-5.6-sol model is not supported when using codex这种错误99%是模型名写了一个不存在的型号。解决方案只有一个去模型平台控制台复制真实的模型名别凭记忆填。第二多写了不该有的参数。有些朋友从网上抄了半截配置把provider的name写错或漏了Codex可能直接启动失败或者在日志里提示找不到provider。配置文件的缩进和键名是有规则的建议直接用官方文档给的模板改不要自己乱加。第三改了配置忘了验证。改完config.toml之后建议先运行codex --version确认还能正常启动再跑一句最简单的codex exec 你好看看能不能通。4. 命令行Codex的日常用法4.1 交互模式最常用的聊天式编程最简单的用法在项目目录下直接运行codex进入交互会话后你可以像聊天一样向它描述任务。比如“读一下这个项目的README和src目录告诉我整体架构是什么”“给utils.py里的函数写单元测试”“帮我查一下这个报错是怎么回事”。Codex的特点在于它是真正能操作项目的。你在对话里说“把排序算法改成快排”它不只是给你一段代码而是会直接修改对应文件然后告诉你改了哪里、为什么这么改。它对当前目录的文件有感知能力这也是交互式命令行相比普通聊天工具最核心的差别。会话中几个实用操作/quit退出会话输入/help查看可用命令对它的回答不满意让它重新解释或者直接说“换一种方案”4.2 exec非交互模式脚本和自动化的好帮手除了交互模式Codex还提供了exec子命令适合一次性任务。格式codex exec 把当前目录所有jpg图片压缩到原来的一半大小 codex exec --full-auto 运行测试如果失败就修复不带--full-auto时它每执行一个关键步骤都会停下来征求你的确认适合谨慎场景。带--full-auto时Codex会自主执行后续操作直到任务完成或遇到它判断不了的决策。这个参数很好用但风险也高建议只在有git版本控制和测试覆盖的项目里使用。我试过把它接到项目里做自动化每周让Codex读一遍git log自动生成本周变更摘要。虽然摘要风格还需要人工微调但比我自己翻commit记录省了太多时间。4.3 核心参数速查表不同版本的参数名可能有细微差异以codex --help输出为准。常用的这些先混个脸熟参数作用使用场景--cd 目录指定项目目录不在项目根目录工作时--model 模型名临时切换模型临时试用不同模型不改配置--full-auto全自动执行不逐条确认自动化、CI场景-s/--sandbox沙箱模式限制执行系统命令敏感环境、不熟悉的项目--help查看全部参数记不住参数时4.4 我自己的实操工作流实际用下来我觉得最有价值的工作流不是让Codex一次生成一大段代码而是把它当成一个“熟悉代码的结对搭子”。我的节奏是这样的进入一个陌生仓库先跑codex exec 分析项目结构并输出技术栈摘要花两分钟让Codex把项目整体情况讲清楚打开交互模式给它一个具体到文件、具体到函数的需求比如“在src/api.ts里新增获取用户订单的接口风格参照现有代码”Codex改完后我要做的是git diff复查看看改动是否符合预期有没有引入明显问题有疑问直接在会话里追问让它解释为什么这么改很多时候它能给出比注释更详细的理由最后让它跑一遍测试确认不影响已有功能这套流程的核心原则是让Codex动手自己动脑。它替你省掉的是敲代码、查文档、debug的时间但代码是否符合项目规范、是否要合并这些最终判断永远在你手里。5. 实战用Codex写一个图片压缩脚本5.1 需求与准备纸上谈兵没意思我带大家走一遍真实过程。需求很朴素我手头有个目录里面200多张截图共1.2GB要批量压缩后发出去。手工用Photoshop处理显然不现实写脚本是最合适的。先创建一个项目目录并初始化gitmkdir image-compressor cd image-compressor git init之所以先git init是让Codex在修改文件时能准确看到变更也方便我们随时回滚。5.2 生成脚本的过程然后我运行codex exec 写一个Python脚本遍历当前目录的jpg和png图片输出到compressed目录长边最大1920px保留EXIF信息压缩质量85带进度显示。使用Pillow。Codex会先浏览一下当前目录发现这是一个空项目然后开始写脚本。它生成的代码大致是这样的import os from pathlib import Path from PIL import Image SRC_DIR Path(.) OUT_DIR Path(compressed) MAX_EDGE 1920 QUALITY 85 SUFFIXES {.jpg, .jpeg, .png} def compress_image(src: Path) - None: with Image.open(src) as img: exif img.info.get(exif) original img.copy() if img.mode in (RGBA, P, LA): img img.convert(RGB) img.thumbnail((MAX_EDGE, MAX_EDGE), Image.LANCZOS) rel src.resolve().relative_to(SRC_DIR.resolve()) out OUT_DIR / rel out.parent.mkdir(parentsTrue, exist_okTrue) img.save(out, qualityQUALITY, optimizeTrue, exifexif) print(fcompressed: {src.name}) if __name__ __main__: imgs [p for p in SRC_DIR.rglob(*) if p.suffix.lower() in SUFFIXES] print(ffound {len(imgs)} images) for p in imgs: compress_image(p) print(done)注意几个细节Pillow的thumbnail方法会自动保持宽高比exifexif可以保留照片信息optimizeTrue会让文件进一步变小。这些是Codex根据需求自动判断出来的我只需要在预览代码时确认是否符合预期。5.3 验证、修正与运行脚本生成后Codex会尝试运行这时大概率会报ModuleNotFoundError: No module named PIL。它会在终端里提示你安装依赖我建议不要直接答应先手动建虚拟环境python -m venv .venv source .venv/bin/activate # Windows: .venv\Scripts\activate pip install pillow然后再告诉Codex“继续”它会重新运行脚本。整个过程下来Codex自己去发现了错误、提示了原因、等待你处理然后继续这种闭环体验正是命令行AI工具的魅力所在。6. 安装使用中的高频问题速查6.1 Windows环境特有的坑Windows用户最容易遇到的情况就是“命令能查版本但真正跑不起来”。具体现象是codex --version正常运行codex却提示找不到命令或者窗口一闪而过。原因通常是PATH配置有问题。Windows的命令行环境里PowerShell和cmd读到的PATH不一定完全一致npm安装目录如果没有被正确加进PATH就会出现这种“有时能行、有时不行”的情况。解决办法在PowerShell里执行where codex看实际调用的是哪个路径执行npm config get prefix得到npm全局目录把该目录加入系统环境变量PATH完全关闭终端再重开另外Windows下安装Node时如果选了“自动添加到PATH”一般问题不大。但如果选了自定义安装路径就要手动确认PATH。6.2 登录与token问题auth token is unavailable这个报错在Windows和macOS上都可能出现但处理思路是一样的先执行codex logout清状态删除auth.json再重新登录。如果该问题反复出现建议大家检查系统时间是不是准的时间偏差太大会导致token验证失败这个冷门原因很容易被忽略。6.3 模型与接入问题the gpt-5.6-sol model is not supported when using codex这种报错基本可以肯定是模型名或者provider配置出了偏差。处理的时候不要只看model那一行也要核对[model_providers.xxx]的名称是否与model_provider xxx完全一致。大小写、拼写都不能错。6.4 网络与本地服务问题使用中偶尔会遇到长连接异常比如Codex一直在“正在重新连接”或者出现本地转发服务报错。这种问题多半是本地服务端口被占用、终端网络环境异常或者安全软件拦截了进程。我的处理办法是退出所有codex进程检查本机有没有其他程序占用了常见端口把它们结束掉关闭可能拦截命令行的安全软件重开终端重新运行codex如果还是不行就换一个网络环境验证排除系统层面的干扰因素。6.5 通用排查建议遇到问题先别急着重装。Codex的报错信息一般会给到足够线索按照“环境变量 → 配置文件 → 网络连接”的顺序排查大部分问题都能在十分钟内解决。重装是最后的手段因为重装通常解决不了PATH和配置的问题只会浪费时间。我把最常见的几类问题整理成速查表贴在这里方便你直接对照问题现象常见原因处理建议codex --version正常但运行无反应PATH不一致或多版本冲突用where/which定位可执行文件统一PATHauth token is unavailable登录缓存过期/系统时间不准logout后重新login必要时删auth.json一直显示正在重新连接网络连接异常检查网络与环境变量看端口占用模型不支持报错模型名/provider配置错误核对config.toml用真实模型名本地转发服务报错端口占用/软件拦截退出进程重开终端检查端口npm安装未完成网络下载超时设置--fetch-timeout重试最后说点实在的。Codex这套命令行工具安装本身并不难真正的门槛在于你平时有没有在终端里工作的习惯。如果你每天都和命令行打交道装好、登录、配置完它能给你带来的效率提升是非常明显的尤其是那种需要快速理解陌生项目、批量改造代码、补测试的场景。如果你还不太习惯终端建议先拿一个很小的个人项目来练手让Codex帮你做点简单的重复劳动慢慢建立信任。我的经验是别指望它一次写对但可以指望它在你指出问题之后一次次改对这个反复打磨的过程才是它真正的价值所在。