Codex CLI 的下载安装配置我前前后后在不同机器上折腾了不下十次踩过的坑比代码行数还多。2026 年 10 月这版发布之后安装逻辑和模型选择又有不少变化网上很多教程已经过时了。这篇文章就把我自己最新的安装配置流程完整捋一遍从环境准备到最终跑通第一句对话全程无删减。无论你是刚接触 AI 编程工具的新手还是想从 IDE 插件切换到终端工作流的资深开发者照着做基本不会卡壳。1. 先搞清楚Codex CLI 到底是什么1.1 一句话理解 Codex CLICodex CLI 是运行在终端里的 AI 编程助手直接集成进 Shell 环境。你可以在命令行里用自然语言描述需求比如“把这个 JSON 文件转成 CSV 并且统计每列的平均值”它就能直接生成代码、自动修改项目文件、执行命令甚至根据运行结果继续迭代。2026 年 10 月这次更新核心变化有三点默认模型升级到了 GPT-5-Codex 系列写代码的准确率和多轮对话一致性相比前代有明显提升模型配置方式调整为统一走config.toml文件管理环境变量、模型供应商、参数设置都可以集中维护安装包重新整理了发布渠道npm 和 Homebrew 两条路线都能拿到同一版本不再存在渠道差异对刚接触的人来说最直接的价值就是不用再在浏览器和编辑器之间来回切换直接在终端里描述需求Codex 会把活儿干完。对有经验的开发者来说它能显著缩短写样板代码、修 bug、跑测试这类重复劳动的时间。1.2 适合谁用解决什么问题我个人觉得 Codex CLI 适合三类人第一类是想降低编程门槛的学习者。你不需要先精通语法才能写程序只要能把需求说清楚Codex 会先帮你搭出框架你通过阅读和分析它写的代码来学习效率比死磕教程高很多。第二类是日常要处理大量脚本、文本转换、数据处理但不想开 IDE 的开发者。CLI 工具天然轻量开一个终端就能干活不需要等编辑器加载。第三类是做项目原型验证的人。遇到临时需求比如“写个脚本检查一下这个目录下所有文件是否都存在”直接丢给 Codex一分钟就能得到可用结果。不过要注意Codex CLI 不是全自动的魔法棒。它生成代码后需要你审核、确认、批准执行权限控制和安全边界是它设计得很重的一部分这也是好事情——毕竟让 AI 直接改你电脑上的文件总要有个把关环节。2. 安装前的准备工作环境、账号和选型2.1 运行环境要求安装前先确认机器满足基本条件。Windows 用户建议优先用 WSL 2 环境原生 CMD 或 PowerShell 下会出现很多兼容问题。macOS 和主流 Linux 发行版基本开箱可用。需要提前装好的东西Node.js 20 或更高版本推荐 22 LTS实测最稳Git用于 Clone 项目、版本管理场景一个终端工具macOS 用户可以用系统自带 Terminal也可以装一个更顺手的终端应用检查 Node.js 版本的命令是node -v如果输出版本号但低于 20建议先升级。我遇到过很多次因为 Node 版本太老导致安装失败的情况报错信息含糊得让人抓狂最后都是升级 Node 环境解决的。2.2 OpenAI 账号和 API Key 准备Codex CLI 的认证方式有两种ChatGPT 账号登录和 API Key 认证。ChatGPT 登录方式适合日常交互使用执行codex login之后会跳转浏览器完成授权会在本地保存会话凭证后续使用不需要反复登录。API Key 方式适合脚本自动化、CI/CD 流程、或者不想走浏览器授权的场景。执行codex login --api-key然后粘贴密钥即可。API Key 在平台后台生成生成后务必立即保存因为关闭页面后不会再展示完整密钥。两种认证方式可以共存配置文件里可以指定当前使用哪一种。我个人的习惯是日常开发用 ChatGPT 登录自动化任务单独建一个 API Key 并配置短时效环境变量避免密钥长期暴露。2.3 安装方式选型三种路线对比官方提供的安装渠道有三个选择哪一个取决于你的系统和习惯。安装方式适用系统优点缺点npm 全局安装所有平台安装快直接用 Node 生态管理版本需要 Node.js 环境支持Homebrew 安装macOS / Linux贴近系统包管理习惯升级方便仓库更新可能比 npm 慢一点预编译二进制包macOS / Linux无需依赖 Node.js独立运行升级需要手动替换文件我推荐大多数用户优先用 npm 方式原因很简单Codex CLI 与 Node 生态绑定紧密npm 渠道总是最先发布新版本。Homebrew 也稳但如果你需要第一时间拿到新特性npm 最快。二进制包适合没有 Node.js 环境的生产服务器或无网络安装场景。2.4 安装前的最后检查动手安装前把这几件事都确认好能省下后面排查问题的宝贵时间终端能不能正常联网ping一个常用域名测试Node.js 版本达标node -v确认输出正常系统权限macOS 和 Linux 用户确认对/usr/local或/opt/homebrew有写权限磁盘空间至少留出 500MBCodex CLI 本身不大但它依赖的模型缓存和临时文件需要空间我之前在一台配置比较低的旧机器上安装Node 版本是 18npm 装完执行codex --version直接报错花了一晚上排查才发现是版本兼容问题。升级 Node 到 22 之后一切恢复正常。所以环境检查真的别跳过。3. Codex CLI 完整安装流程3.1 方式一npm 安装全步骤打开终端执行npm install -g openai/codex安装过程会输出一堆进度信息最后看到类似 added 200 packages in 15s 的字样就是成功了。安装完成后立刻验证版本codex --version正常会输出类似codex 0.38.0这里有个细节容易踩坑如果你之前安装过旧版本npm 全局包可能出现缓存问题。建议先执行npm cache clean --force再执行npm install -g openai/codexlatest强制装最新版。3.2 方式二Homebrew 安装全步骤macOS 用户如果更习惯用 Homebrew 管理软件可以直接brew install codex更新的时候执行brew update brew upgrade codexHomebrew 方式的验证命令和 npm 一样执行codex --version确认输出。有个细节Homebrew 安装路径可能和 npm 不一样如果系统提示找不到codex命令检查一下 Homebrew 的 bin 目录是否在 PATH 环境变量里通常路径是/opt/homebrew/bin或/usr/local/bin。3.3 方式三预编译二进制包安装这种方式的步骤比较直白从官方版本发布页下载对应系统的压缩包解压后把可执行文件放到PATH包含的目录里。# 示例Linux amd64 wget 下载地址 tar -xzf codex.tar.gz sudo mv codex /usr/local/bin/注意替换实际的版本号和架构标识。放好后执行codex --version确认能识别。3.4 登录认证操作细节安装验证通过后接下来是认证环节。执行codex login如果是 ChatGPT 登录方式终端会显示一个授权链接和等待提示用浏览器打开链接完成登录后回到终端就能看到登录成功的信息。整个过程和第三方应用通过 GitHub 登录网站的逻辑一样。如果是 API Key 方式codex login --api-key执行后会提示输入密钥粘贴后回车。这里有一个安全细节粘贴密钥时终端不会明文显示输入内容是正常现象不要以为自己没输进去。登录成功后~/.codex 目录下会生成 auth.json里面保存了会话所需的凭证信息。我对 auth.json 的处理原则是不加入版本管理仓库、不给无关应用读取权限、定期检查是否存在异常凭证。3.5 第一句对话验证核心功能认证通过后执行一个最基础的测试请求codex 写一个Python脚本打印当前系统时间和日期首次执行会经历几个阶段Codex 启动并初始化显示计划解释它打算如何完成任务展示它将执行的命令等待审批默认无--full-auto参数时执行命令前会询问确认输出结果并生成代码文件看到这样的完整交互过程说明安装彻底成功了。这里必须说一个我亲测的重要经验第一次运行时 Codex 会请求执行 Shell 命令的权限建议选择“允许本次”而不要直接选择“总是允许”。因为刚开始你不清楚它会在什么目录下做什么操作通过几次观察后再决定是否放开权限。安全习惯要从第一句对话就养好。4. 配置详解让 Codex 真正顺手4.1 配置文件结构总览Codex CLI 的配置文件使用 TOML 格式位置在~/.codex/config.toml。这个文件集中管理模型选择、供应商、行为参数等关键设置。一个典型配置示例model gpt-5-codex model_provider openai [model_providers.openai] name OpenAI [model_providers.azure] name Azure OpenAI base_url https://your-endpoint.openai.azure.com/ env_key AZURE_OPENAI_API_KEY配置的优先级从高到低是命令行参数 配置文件 环境变量默认值。也就是说你在终端里临时指定的模型参数会覆盖配置文件里的默认值这个机制在切换模型时很实用。4.2 模型选择与行为参数当前版本的默认模型是gpt-5-codex大多数场景下直接用默认值就行。如果你有特殊需求可以临时切换codex --model gpt-5-codex 描述你的需求行为参数方面有几个值得单独说明model_prompt write指定模型以代码生成为核心任务的模式temperature参数控制回答随机性写代码场景建议保持默认追求稳定性top_p参数与 temperature 作用类似一般不需要改示例model gpt-5-codex model_prompt write temperature 0.2 top_p 0.9把temperature调低模型输出会更保守、更稳定适合重构代码这类需要精确性的任务。如果你在探索性编码可以适当调高让模型给出更多样化的尝试方案。4.3 AGENTS.md项目的“操作说明书”AGENTS.md 是 Codex CLI 支持的项目级指令文件相当于给 AI 的一份项目操作说明书。你想让 Codex 在项目里遵循特定规范时就把规则写进这个文件。合理的 AGENTS.md 应该包含# 项目结构说明 - 业务代码放在 src/ 目录 - 测试代码放在 tests/ 目录 # 编码规范 - Python 代码使用类型注解 - 缩进统一为 4 空格 - 所有公共函数必须有 docstring # 操作约定 - 不要修改 migration 文件 - 测试使用 pytest 运行 - 提交前必须运行 lint我建议把项目里“人尽皆知的潜规则”都写进去AI 对这些规则了解得越充分输出就越贴合项目实际。4.4 MCP 服务器接入扩展能力边界MCPModel Context Protocol是让 Codex 接入外部工具和数据源的协议。一个典型配置[mcp_servers.filesystem] command npx args [-y, modelcontextprotocol/server-filesystem, /path/to/allowed/dir]接入 MCP 后Codex 可以调用外部工具、查询数据库、操作文件系统等。这个功能适合有复杂项目需求的场景比如让 Codex 直接查询某个 API 服务的实时数据或者读取指定目录下的日志文件再定位问题。4.5 权限模式选择安全与效率的平衡Codex 提供了多档权限控制模式操作权限由低到高默认询问模式每次执行命令前都确认最安全但频繁确认影响效率白名单模式只允许执行你预先批准的常用命令平衡安全和效率--full-auto模式全自动执行不询问适合明确信任的场景--dangerously-bypass-approvals模式跳过所有确认仅建议在一次性容器环境使用我个人常用的配置是在配置文件中设置白名单规则[approval_policy] - name ls operation run - name cat operation run这样像ls、cat之类的只读命令不会频繁打扰我而rm、sudo这类高风险操作每次都会确认。4.6 环境变量与供应商切换如果使用多个供应商可以通过环境变量动态切换密钥。举个例子默认使用OPENAI_API_KEY对接某些兼容服务时可以临时指定export OPENAI_API_KEY你的密钥 codex 执行任务配置文件也同样支持多供应商切换用model_provider字段指定使用哪个服务。实测中这种配置对于需要在多个模型服务之间切换的开发者来说非常方便不用反复改代码切个配置就行。5. 实操演示从需求到产出全过程5.1 场景需求处理日志文件我现在用一个最常见的实战场景来演示假设app.log文件里混合着 INFO、WARN、ERROR 三种级别的日志我想统计每种级别的数量并输出错误级别日志的行号。在终端输入codex 统计app.log中INFO、WARN、ERROR级别的日志数量并输出所有ERROR日志的行号Codex 的响应会有几个阶段值得说明一下。5.2 计划生成与输出解析Codex 会先展示它的计划类似计划 1. 使用grep命令统计各级别日志数量 2. 使用grep命令查找ERROR日志并显示行号这个阶段的输出体现了模型的推理过程建议仔细看一下。如果计划和你预期不符你可以在这一步打断并修正需求避免它做无用功。5.3 审批执行与结果输出计划确认后Codex 会请求执行命令。此时终端进入交互模式? 是否允许执行该命令? (Y/n)选择允许后命令执行并输出结果INFO: 125 WARN: 23 ERROR: 7 5: ERROR: 连接超时 18: ERROR: 用户认证失败如果对这个结果不满意可以继续提要求把这些统计结果写入一个JSON文件包含生成时间Codex 会接着生成 Python 脚本执行并生成log_stats.json。整个过程中代码生成、命令执行、结果写入都由它完成你要做的只是描述需求、审阅计划、批准执行。5.4 多轮对话迭代代码CLI 工具支持多轮迭代这是它比一次性脚本生成工具优势明显的地方。比如刚才生成的脚本可能不够健壮你可以继续输入给脚本加上文件不存在时抛出自定义异常并支持通过命令行参数指定日志文件路径Codex 会在原有脚本基础上增量修改而不是重新生成一份全新的文件。它会理解上下文、读取现有代码、针对性地补全。实测下来这种迭代方式的准确性比重新描述一遍需求高很多。5.5 我实际使用中的几条经验首先是需求描述尽量具体告诉 Codex“做什么”的同时也告诉它“不要做什么”比如“不要删除原始文件”能有效避免意外操作。其次是审阅批准非只读命令先仔细看计划再确认尤其涉及文件删除、覆盖、权限修改的操作。等对 Codex 的执行风格有把握之后再渐进式放开权限。最后是版本记录代码生成之后如果还需要进一步调整建议初始化一个 Git 仓库并频繁提交。这样任何一轮修改不符合预期都能快速回滚。6. 常见问题排查与速查配置6.1 认证失败或提示 unauthorized执行codex login后报认证失败最可能的原因是浏览器授权回调没有完成。排查顺序如下确认浏览器页面是否显示“授权成功”如果没有重新执行codex login查看~/.codex/auth.json是否存在如果存在但格式异常删除后重新登录检查系统时间是否正确时间偏差过大会导致 token 校验失败API Key 方式认证失败时重点检查是不是复制了多余的空白字符。我见过不少人包括我自己粘贴密钥时带了换行符导致认证一直过不去。6.2 codex 命令找不到命令行找不到codex通常是安装路径不在 PATH 环境变量里。诊断思路which codex如果which没有输出说明 PATH 里没有包含安装路径。npm 全局安装的路径通常在 Node.js 安装目录的 bin 下Homebrew 安装的路径通常是/opt/homebrew/bin或/usr/local/bin。把这个路径添加进.zshrc或.bashrc然后重新加载export PATH$PATH:/opt/homebrew/bin source ~/.zshrcmacOS 用户特别容易遇到这个问题新版系统对终端默认环境的 PATH 处理不太一样导致全局命令一直找不到。6.3 模型响应慢或超时响应慢的原因主要有两类网络问题和模型负载问题。先检查网络连通性确认终端能够正常访问外部网络。再看模型选择如果走了自定义模型供应商但密钥没有正确配置请求会卡在认证环节。排查时打开调试模式能快速定位codex --verbose 测试请求另外如果是公司网络或校园网环境网络出口策略也容易影响连接稳定性这类情况要联系本地的网络管理员确认终端访问权限。6.4 命令执行权限被频繁拒绝Codex 频繁请求审批或者反过来一直拒绝你让它执行命令的请求多半是审批策略配置的问题。在config.toml里追加常用只读命令的白名单[approval_policy] - name ls operation run - name cat operation run - name grep operation run注意白名单机制越精细越好只放明确安全的命令。像rm、sudo、mv这种操作即使麻烦也值得每次确认。6.5 常用配置速查表# 基本配置 model gpt-5-codex model_provider openai model_prompt write # 供应商配置 [model_providers.openai] name OpenAI [model_providers.azure] name Azure OpenAI base_url https://your-endpoint.openai.azure.com/ env_key AZURE_OPENAI_API_KEY # 审批策略 [approval_policy] - name ls operation run - name cat operation run6.6 卸载与清理残留如果因为某些原因需要卸载也要清理干净。npm 方式npm uninstall -g openai/codex然后清理配置目录rm -rf ~/.codex注意~/.codex里面保存着认证凭证和模型缓存删除前确认不再需要这些数据。如果只是暂时不用重命名目录留作备份也能达到类似效果。写在最后安装配置这块很多问题的根源其实不在工具本身而在环境细节Node 版本不对、PATH 没配好、认证流程中断这些占了大多数。我个人的体会是不管遇到什么报错先静下来梳理一下自己的操作链路从环境检查到认证流程逐项排查比盲目重装有效得多。最后再分享一个小技巧日常使用中如果发现 Codex 的行为方式在某些项目里不太符合预期优先检查项目的 AGENTS.md 是否写清楚规则。它的行为很大程度受这个文件影响把项目约束描述得越具体用起来越顺手。这套配置流程走通之后后续的版本升级基本就是例行公事希望这篇文章能帮你少走一些我走过的弯路。