Codex CLI 是 OpenAI 提供的命令行编程助手它把 GPT 系列模型的能力放到终端里让开发者可以直接在项目目录中描述任务、生成代码、修改文件并执行命令。真正用起来之后你会发现Codex 的价值不只是“能聊天”而是它能按当前项目的上下文完成任务改完代码还能给你一个可审查的 diff。这套能力放到本地开发环境里比在网页对话框里复制粘贴代码要顺手得多。不过 Codex 的安装和配置并不是一条命令就能彻底解决的。它的登录方式、模型名称、代理设置、配置文件位置、WSL 网络模式都可能在不同版本里发生变化。这篇文章以 Codex CLI 的最小可用安装为主线从环境准备、npm 安装、登录认证、模型配置、任务执行一路讲到常见报错排查。目标是让读者在一台干净的开发机上按照顺序操作能把 Codex CLI 跑起来并理解每一步在做什么。需要特别说明的是这篇文章不做任何关于“白嫖”的承诺也不会教怎么绕过付费或配额限制。Codex 是 OpenAI 的收费能力实际费用以官方定价和你账号的额度为准。不同版本对模型的支持范围也不同网上流传的一些模型标识比如gpt-5.6-sol并不一定存在于当前版本的官方支持列表中配置时要以官方文档和工具自身输出的模型列表为准。1. 先弄清楚 Codex CLI 是什么以及它解决什么问题1.1 一句话理解 Codex CLICodex CLI 是一个运行在终端里的 AI 编程代理。你给它一个任务描述它会读取当前目录下的文件调用模型推理生成代码修改方案然后帮你创建文件、修改文件、执行测试命令。整个过程不是简单的“问一句答一句”而是围绕一个代码库上下文连续工作。类比一下网页版 ChatGPT 更像是“对话式百科全书”而 Codex CLI 更像是“坐在你终端里的协作者”。它能调用git diff查看改动能运行测试能把错误输出反馈给模型让模型继续调整。这种闭环能力是普通网页对话很难做到的。1.2 为什么要在终端里使用 Codex在终端使用 Codex 有几个典型场景项目级任务比如“重构这个模块的错误处理逻辑”“给这个接口补充单元测试”模型能直接读取项目文件而不是只靠你粘贴的片段。Git 工作流集成Codex 可以生成 git commit 信息可以查看当前改动可以在提交前让你 review diff。自动化执行如果配置了自动批准模式Codex 可以连续执行命令直到任务完成适合批量重构或修 bug。本地隐私控制很多操作可以发生在本地代码库中你决定保留哪些改动。在学习环境里Codex 是练习“AI 辅助开发”工作流的很好入口。而在生产环境里它更像一个需要严格权限控制、人工 review 的辅助工具而不是无脑执行的自动化脚本。1.3 模型的兼容性问题要提前知道Codex CLI 本身是一个客户端工具它需要调用 OpenAI 的模型服务。不同版本的 Codex CLI 支持不同的模型列表而且模型命名也会变化。安装之后建议先执行codex --help或codex models查看当前版本支持的模型标识不要直接照搬网上的模型名称。有些第三方教程会把模型标识写成gpt-5.6-sol之类这种标识在当前版本中很可能不被支持。配置了不存在的模型名调用时会直接报错而且报错信息往往不会明确告诉你“哪个名字才是对的”只会提示这个模型不被支持。后面排错部分会专门展开。2. 安装之前的准备工作Node.js、Git、Python 和网络环境2.1 环境要求总览在开始安装 Codex CLI 之前建议先确认开发机上的基础工具版本。下面的表格是常见的安装条件具体版本要求要以你安装的 Codex 版本为准。工具建议用途检查命令备注Node.js通过 npm 安装 Codex CLInode -v建议安装长期支持版本LTSnpm管理 Codex 依赖npm -v随 Node.js 一起安装Git代码版本管理Codex 会调用它查看 diffgit --version需要配置 user.name 和 user.emailPython执行部分脚本任务非必须python --version如果本地项目用 Python建议提前装好网络连接访问 OpenAI 服务见下方说明需要确保终端能正常访问目标域名不要把这一步骤省略。很多人后面遇到“装不上”“登录失败”“代理报错”往往不是 Codex 的问题而是 Node.js 版本太旧、Git 没配置用户信息、或者环境变量里的代理设置不对。2.2 安装并验证 Node.js在 Linux 或 macOS 上最常见的安装方式是使用 Node 版本管理工具比如nvm。Windows 上则可以直接安装 Node.js 官方安装包。# 检查是否已经安装 Node.js node -v # 检查 npm 是否可用 npm -v如果是全新机器先安装 nvm再安装指定版本的 Node.js# 安装 nvm 后重新打开终端 curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash # 重新加载 shell 配置 source ~/.bashrc # 如果使用 zsh则 source ~/.zshrc # 安装 Node.js LTS 版本 nvm install --lts nvm use --lts注意如果node -v能输出版本号但npm -v报错优先检查 Node.js 安装路径和系统 PATH 环境变量。不要急着重装系统。2.3 初始化 Git 用户信息Codex 在生成代码和查看 diff 时经常会调用 Git 命令。如果 Git 没有配置用户信息部分和提交相关的操作可能报错。git config --global user.name your-name git config --global user.email your-emailexample.com # 验证配置是否生效 git config --global --list这里的关键点是Codex 本身不替你决定提交内容它只是辅助生成代码和查看变更最终是否提交、提交到什么分支仍然由你控制。2.4 提前检查本地代理和 WSL 网络模式Codex CLI 需要访问 OpenAI 的 API如果你的开发环境使用本地代理需要先确认终端环境变量里的代理配置是否正确。常见问题有两类第一类是代理配置整体没生效。检查方式如下# 查看终端是否设置了代理环境变量 echo $HTTP_PROXY echo $HTTPS_PROXY echo $ALL_PROXY # 测试目标服务是否可达命令根据你的网络环境调整 curl -I https://api.openai.com第二类是 WSL 下的特殊问题。当你在 WSL 里运行 Codex而代理运行在 Windows 宿主机上时WSL 的 NAT 网络模式不会自动把 localhost 代理镜像到 WSL 内。你会看到类似这样的提示WSL: 检测到 localhost 代理配置,但未镜像到 WSL。NAT 模式下的 WSL 不支持 localhost 代理这个问题需要在 WSL 的配置文件.wslconfig中开启镜像网络模式或者在 WSL 里单独设置代理地址。关于 WSL 的排错下面有专门一节这里先提醒你不要忽略这条提示。3. 使用 npm 安装 Codex CLI 并完成登录3.1 安装 Codex CLICodex CLI 常见安装方式是通过 npm 全局安装。在终端执行npm install -g openai/codex安装结束后检查版本codex --version如果codex命令找不到常见原因是 npm 全局安装目录不在系统 PATH 中。可以执行下面的命令查看 npm 全局目录并把目录加入 PATHnpm config get prefix # 输出目录例如 /usr/local 或 C:\Users\you\AppData\Roaming\npm之后把该目录下的 bin 目录加入 PATH。Windows 下通常会自动配置Linux 下需要手动在~/.bashrc或~/.zshrc中追加 export。注意安装过程如果出现权限报错不要直接执行sudo npm install -g。推荐先修复 npm 全局目录权限或者使用 Node 版本管理工具重新安装 Node.js。3.2 登录认证Codex CLI 需要认证后才能调用模型服务。执行codex login按提示选择登录方式。一般有两种通过浏览器登录你的 OpenAI 账号授权 Codex CLI 访问。使用 API Key 登录适合有独立 API Key 的开发者。浏览器方式会在本地启动一个临时服务等待浏览器回调。回调成功后终端会提示登录完成。API Key 方式则会要求你输入 key并写入本地配置文件。登录完成后建议用一个小命令验证认证状态# 输出当前登录账号或配置信息具体子命令以 codex --help 为准 codex whoami如果该子命令不存在可以使用codex --help查看当前版本支持的命令。3.3 登录后的常见状态检查经常有人登录后以为万事大吉结果执行任务时报 401 或超时。建议做两件事第一确认登录信息确实写入到了配置文件中。配置文件的常见位置是用户主目录下的~/.codex/目录里面可能有config.toml、auth.json等文件。不同版本文件名会有差异以实际生成为准。第二确认环境变量里没有覆盖认证信息。某些第三方工具或脚本会在.bashrc里设置OPENAI_API_KEY如果这个 key 已经失效即使你重新执行了codex login请求仍可能走环境变量里的旧 key。3.4 升级与卸载Codex CLI 的版本更新比较频繁想升级到最新版时执行npm update -g openai/codex卸载npm uninstall -g openai/codex这里要注意升级后老的任务配置不一定兼容。如果升级后出现奇怪的报错优先查看codex --help的默认行为是否变化并检查配置文件是否有废弃字段。4. 配置模型、本地代理和项目级参数4.1 配置文件先要找到位置Codex CLI 的配置一般在用户主目录的~/.codex/下。常见形式是config.toml不过新版本可能出现 JSON 或其他格式。安装后可以通过codex --help或官方文档确认配置文件位置。下面展示一个config.toml的最小结构用于说明思路。实际字段名以你安装版本的帮助文档为准# 模型相关配置示例实际字段名以版本为准 model gpt-5-codex model_provider openai # 是否自动批准工具执行 approval_policy on-request不同版本字段差异很大不要在没确认前照抄网上的配置。推荐方式是在项目根目录执行codex init让它生成一份默认配置再在默认配置之上修改。4.2 模型选择和模型名称模型名称是 Codex 配置里最容易踩坑的地方。不同版本支持以下类型的模型标识但具体名称要看官方文档面向代码任务的专用模型比如gpt-5-codex或codex-mini。通用 GPT 模型这类模型可能可用但不一定被当前 Codex 版本支持。第三方中转或本地模型服务这种需要额外的model_provider配置。如果配置了不在支持列表里的模型名称调用时会报类似下面的错误the gpt-5.6-sol model is not supported when using codex with a...遇到这种报错不要继续排查网络和代理先检查配置文件里的 model 字段改成当前版本支持的模型。查看支持列表的方式# 查看当前 Codex 支持的命令和选项 codex --help # 如果存在 models 子命令查看模型列表 codex models如果models子命令不存在直接查阅官方文档不要相信第三方教程里的模型名。4.3 本地代理配置当你的开发环境需要走本地代理访问外网时Codex 默认会读取系统的 HTTP 代理环境变量。常见配置方式如下export HTTP_PROXYhttp://127.0.0.1:7890 export HTTPS_PROXYhttp://127.0.0.1:7890 export ALL_PROXYhttp://127.0.0.1:7890如果你使用代理切换工具切换后环境变量不一定自动更新需要重启终端或者在启动 Codex 前手动 source 配置文件。还有一种情况是代理工具本身失败例如报错cc switch local proxy failed while handling codex endpoint /responses这种报错意味着 Codex 在调用/responses接口时本地代理没有正确转发。排查重点不是 Codex而是代理服务是否正常运行、端口是否被占用、代理进程是否退出。4.4 项目级配置与.gitignore在项目根目录执行codex init后会生成项目级配置文件。推荐做三件事第一把配置文件中的敏感信息检查一遍确保没有明文写入 API Key。API Key 只应该放在用户主目录的配置中项目目录里不要保存密钥。第二在.gitignore里加上 Codex 可能生成的临时文件避免把会话记录或本地状态提交到仓库。第三在项目根目录维护一个描述项目结构、命令约定的说明文件Codex 读取后会利用它理解项目上下文。这个文件内容可以参考# 项目命令约定 - 安装依赖npm install - 运行测试npm test - 构建npm run build # 代码风格 - 使用 TypeScript - 缩进使用两个空格 - 不要使用 any这里面的信息越具体Codex 生成的代码越贴近项目实际。5. 用最小任务跑通 Codex 的完整工作流5.1 准备一个最小实验项目学习阶段不建议直接在真实项目上让 Codex 自动改代码。先建一个最小项目验证安装是否正确、认证是否可用、配置是否生效。mkdir codex-test cd codex-test git init # 创建一个小文件 cat index.js EOF function add(a, b) { return a b; } console.log(add(1, 2)); EOF然后在这个目录下初始化 Codexcodex initcodex init会生成项目级配置让你在测试阶段就把模型的执行范围限制在当前目录避免误操作其他路径。5.2 执行第一个任务并观察输出用一条最明确的任务测试 Codex 是否能读取文件并修改代码codex 给 index.js 增加一个 subtract 函数并导出 add 和 subtract执行过程中观察两点第一Codex 是否读取了当前目录下的文件。如果它完全不知道index.js存在说明上下文配置有问题可能要检查工作目录是否设置正确。第二Codex 是否生成文件修改。完成后查看git diffgit diff如果任务执行成功你会看到index.js的变更。这个阶段不要急着git commit先人工检查生成的代码是否正确。注意Codex 生成代码只是辅助不意味着代码逻辑一定正确。实际项目中所有变更都要经过代码审查和测试验证。5.3 理解批准模式和自动执行模式Codex 执行命令时需要决定是否允许工具自动运行。常见策略有几种策略行为适用场景on-request每次执行前询问你学习阶段、生产环境推荐on-failure仅在失败时询问调试简单任务on-plan计划生成后询问多步骤任务前需要确认自动执行不询问直接执行命令只建议在隔离的测试环境使用初次使用建议保持默认的询问模式。不要让 Codex 在无审查环境下自动执行可能修改文件、删除文件、执行网络请求的命令。6. 常见报错与排查链路6.1 报错cc switch local proxy failed while handling codex endpoint /responses这个报错集中出现在使用了本地代理切换工具的开发环境里。现象是 Codex 执行任务时在请求/responses接口时失败随后终端输出代理切换失败信息。排查顺序检查代理进程是否还在运行。代理工具退出后端口就不会再监听。检查环境变量是否指向正确的地址和端口。很多代理工具的默认端口不是 7890需要看工具界面实际端口。检查 Codex 配置文件里是否含有覆盖环境变量的 proxy 参数。临时清空代理环境变量看直连是否正常。如果直连正常说明问题出在本地代理转发链路。# 关闭代理环境变量后重试 unset HTTP_PROXY unset HTTPS_PROXY unset ALL_PROXY codex 输出 hello如果以上都排查过仍然失败换成其他 CLI 工具测试本地代理是否正常比如curl -I https://api.openai.com。Codex 只是客户端问题大概率出现在系统代理链路。6.2 报错model is not supported完整报错往往长这样the gpt-5.6-sol model is not supported when using codex with a...原因很简单配置文件里写了一个当前版本不支持的模型标识。可能是第三方教程里的过时信息也可能是不存在的模型名称。处理方式# 查看配置文件 cat ~/.codex/config.toml # 修改 model 字段为当前版本支持的模型 # 例如model gpt-5-codex如果不确定哪些模型可用先查阅官方文档或者把 model 字段删掉让 Codex 使用默认模型。不建议使用来路不明的第三方模型标识因为这在企业生产环境中会带来不可控的行为差异。6.3 报错登录超时或认证失败登录时常见的失败包括浏览器一直不回调、登录成功但请求时报 401。排查顺序确认终端通知、浏览器授权页面是否已经允许。检查OPENAI_API_KEY环境变量是否覆盖了登录 token。重新登录一次登录后立即执行一个最小任务。查看~/.codex/目录下认证文件是否生成。如果认证文件存在但请求仍然 401说明 token 失效或账号权限不足。此时重新登录并检查账号是否有可用的模型访问权限。6.4 报错WSL 检测到 localhost 代理配置未镜像这个报错在 WSL 环境比较常见。代理运行在 Windows 宿主机上而 WSL 运行在 NAT 网络模式下WSL 里的localhost并不指向 Windows 宿主机。解决方案一在 Windows 用户目录下创建或修改.wslconfig启用镜像网络模式然后重启 WSL。[wsl2] networkingModemirrored重启 WSLwsl --shutdown然后在 WSL 终端中重新进入项目目录。解决方案二在 WSL 内手动设置代理为 Windows 宿主机的 IP。如果你在wsl hostname -I以外难以确定宿主机 IP可以在 WSL 里查看/etc/resolv.conf中的 nameserver或直接在 Windows PowerShell 里查看 IP 地址然后在 WSL 中 export。export HTTP_PROXYhttp://windows-host-ip:proxy-port export HTTPS_PROXYhttp://windows-host-ip:proxy-port需要注意WSL 的.wslconfig修改后必须完整重启 WSL 才能生效。轻量关闭当前终端窗口不会重新加载该配置。6.5 通用排查顺序清单遇到任何 Codex 运行问题都建议按下面的顺序排查而不是直接搜索报错信息排查层级检查内容参考命令或文件1Node.js / npm 版本node -v、npm -v2Codex 是否安装成功codex --version3登录状态codex whoami或ls ~/.codex/4环境变量覆盖env | grep -i proxy、env | grep -i openai5模型名称是否支持codex models或官方文档6代理是否正常curl -I https://api.openai.com7WSL 网络模式.wslconfig中 networkingMode 设置8项目上下文当前目录是否正确codex init是否执行7. 生产环境使用建议与最佳实践7.1 学习环境与生产环境要分开学习环境可以快速试错比如可以允许 Codex 自动执行命令、生成临时文件、修改测试目录的代码。生产环境必须严格控制审批策略原则上建议只使用on-request模式。下面的表格帮助区分两个环境的差异维度学习环境生产环境模型选择默认模型即可确认模型版本和能力避免模型变更影响行为审批策略可以放开自动执行保持人工确认代码审查可以不严格必须 review diff 后再提交密钥安全本地测试禁止写入项目仓库操作范围隔离目录限制到指定项目路径日志记录观察终端输出记录任务输入输出便于追溯生产环境最大的风险不是 AI 生成代码出错而是开发者没有做人工审查就让 AI 生成的代码合入主干。建议养成一个习惯每次 Codex 完成任务后先看git diff再决定是否提交。7.2 工程化使用建议在实际项目里推荐把 Codex 当作“结对编程助手”而不是“自动提交机器”。下面几条实践可以直接落地在项目根目录维护AGENTS.md或类似说明文件把编码规范、命令行命令、目录结构写清楚。Codex 读取后生成代码更贴近项目实际。每次任务只做一件事。任务描述越具体生成代码越可控。例如“给src/utils/date.ts增加格式化函数并用vitest补一条测试”就比“优化工具类”更清晰。让 Codex 生成代码后立刻运行测试。Codex 可以执行测试命令也可以主动报告失败结果但“测试是否通过”最终要以实际输出为准。不要用 Codex 处理包含敏感信息的文件比如.env、生产数据库配置文件。这些文件要么从上下文排除要么不要让 Codex 读取。提交前把多个小改动拆成不同提交方便回滚。不要把 AI 生成的十几处改动揉进一个 commit。7.3 安全与权限注意事项Codex 有读取和修改文件的能力因此安全上要提前设防第一项目目录边界。在项目目录里执行codex init后Codex 默认只在当前项目范围内操作。不要把工作任务放在用户主目录以免它读取到无关的敏感配置。第二环境变量保护。不要在任何 Codex 配置或对话上下文中粘贴 API Key、数据库密码、云服务密钥。第三网络请求控制。Codex 可以执行命令行工具如果任务描述里包含“下载依赖”“拉取远程代码”实际上会触发网络请求。生产环境需要在网络策略层面对允许执行的命令做约束或者保持人工审批。7.4 上下文长度和使用成本控制Codex 调用模型是按 token 计费的。任务描述越长、上下文文件越多、对话轮数越多成本越高。常见控制方法把项目上下文文件控制在必要的范围内。不要让它递归扫描整个 monorepo。任务描述里明确“不用读哪些文件”减少无关上下文。一个小任务失败后不要反复让 Codex“再试一次”十几次。先把问题定位清楚再让它修改。使用代码检索或文件列表方式告诉 Codex 应该看哪些文件而不是让它自己扫一遍全目录。这些习惯不仅能省钱更重要的是能提高生成质量。模型在上下文里塞入过多无关内容后注意力会被稀释生成结果的稳定性反而下降。8. 延伸方向与后续学习8.1 从 Codex CLI 到 Agentic 工作流Codex CLI 只是 AI 辅助开发的一个入口。它背后的模型能力和工具调用机制正在催生更完整的 Agentic 工作流AI 不只帮你写代码还能帮你查文档、执行测试、分析日志、修复 bug。学习 Codex 的过程中重点理解它如何利用“读取上下文、生成代码、执行命令、反馈结果”这个循环这个思路可以迁移到其他 AI 编程工具上。8.2 与 Git 工作流结合建议在真实项目中先练习两条 Git 工作流让 Codex 生成代码你负责git add和git commit。让 Codex 辅助生成 commit message但提交前检查是否准确描述了改动。当你对 Codex 的输出质量有了判断力之后再尝试更复杂的“分支内自动修复”流程。核心原则不变AI 提议人来确认。8.3 下一步学习材料如果 Codex 的核心流程你已经跑通下一步可以看这几个方向Codex 官方文档中的配置文件字段说明不同版本的字段变化都是从这里来的。Codex 示例项目仓库里面有大量真实任务演示。排查网络问题的通用方法包括环境变量、代理、端口连通性。这部分知识属于基础功不只是 Codex 用得上。其他 AI 编程工具的对比比如 Claude Code 等。理解不同工具的“上下文管理”“审批策略”“工具调用范围”差异比只会一条安装命令更有价值。Codex CLI 的安装和配置并不复杂但它把“下载工具”和“真正用好工具”分得很清楚。本文的核心路径可以浓缩成一句话环境先检查版本先确认模型按支持列表配置生产环境保持人工审批排错先看环境变量和代理链路。学习阶段建议在隔离目录里反复练习“描述任务、生成代码、查看 diff、运行测试”这四步。等你能稳定判断 Codex 输出的代码是否符合预期再把它接入日常开发工作流。所有 AI 辅助开发工具都一样模型负责生成质量责任仍然在开发者身上。