Codex 安装与使用教程这些年一直随着版本更新而变化很多新手卡住的地方其实不在代码本身而在第一步到底该安装哪个 Codex、要不要装 Node.js、登录用什么账号、模型怎么选。这篇文章围绕 Codex CLI 这条主线从概念、环境准备、安装、登录、实战到排查完整走一遍。如果你是一个刚开始接触 Codex 的开发者或者想在 Windows 上把 Codex 跑起来但被各种报错拦住这篇文章可以按顺序直接操作。1. Codex 是什么从聊天补全到自动执行编码任务1.1 Codex 解决什么问题Codex 是一类 AI 编程工具的统称在 OpenAI 的语境下Codex 不再只是“文本框里帮你补全代码”的插件而是一个能直接读取项目文件、修改代码、执行终端命令并观察结果的编码智能体。你给它一句自然语言需求比如“帮我把登录接口改成 JWT 认证”它会先查看项目结构分析相关文件然后生成改动方案修改代码甚至运行测试来验证结果。这个过程和传统 AI 聊天工具最大的区别在于它不只是给你一段代码片段而是围绕整个项目上下文工作。你可以把它理解成一个坐在你电脑前、能操作终端和文件系统的开发助手。正因如此Codex 的使用门槛也比普通代码补全工具高它需要安装命令行工具、配置模型接口、理解交互流程还需要你控制好权限审批。1.2 CLI、IDE 扩展和桌面客户端怎么选Codex 有几种使用形态新手最先要搞清楚区别。形态运行环境适合人群特点Codex CLI终端跨平台想用命令行控制任务的开发者功能完整能操作系统命令适合自动化场景VS Code 扩展Visual Studio Code习惯在编辑器里工作的人与编辑器集成左侧面板操作切换上下文方便桌面客户端独立窗口不想接触命令行的用户通常封装了 CLI界面对新手友好但依赖 CLI 安装正确实际项目中最核心、也最能体现 Codex 能力的是 Codex CLI。IDE 扩展和桌面客户端通常只是换了入口最终底层调用的还是同一套命令和配置。所以这篇教程以 Codex CLI 为主先把底层链路跑通再去用扩展和桌面版就会轻松很多。1.3 Codex 的执行链路对话、改文件、跑命令、看结果Codex 并不是一锤子买卖。它执行一个任务时通常遵循这样的循环接收你的自然语言指令。读取当前项目目录里的文件理解代码结构。生成修改方案例如新增文件、修改函数、删除无用依赖。在你审批后实际应用文件改动。如果需要执行终端命令比如运行测试、安装依赖、启动服务。观察命令输出根据结果决定是否需要继续修改。这个链路里最关键的是“审批”和“沙箱”。代码改动和命令执行都有风险所以 Codex 默认不会偷偷执行任意命令而是给你看它准备做什么你确认之后才执行。这也意味着新人使用 Codex 的第一步不是急着写需求而是先理解它的交互规则哪些操作需要你批准哪些操作会直接执行以及如何在出错时停止。2. 安装前的环境准备先确认 Node.js、Shell 和接口信息2.1 系统要求与 Node.js 版本Codex CLI 在 Windows、macOS、Linux 上都可以运行但它依赖 Node.js 运行时。不同版本的 Codex 对 Node.js 版本要求不太一样当前主流安装方式要求 Node.js 18 或更高版本建议使用 Node.js 20 LTS 或 Node.js 22 LTS。如果你安装版本较新却使用很老的 Node.js常见的报错是找不到某个现代语法或模块比如ERR_UNKNOWN_FILE_EXTENSION、SyntaxError: Unexpected token。所以安装之前先检查系统里是不是已经存在正确的 Node.js。硬件要求不算高普通开发机能跑。内存建议 8GB 以上因为 Codex 在极少数情况下会启动本地服务或调试进程磁盘空间预留 500MB 以上主要给 npm 全局包和缓存。2.2 安装 Node.js 并在终端里验证以 Windows 为例去 Node.js 官网下载 LTS 版本安装包安装时保持默认配置即可。macOS 如果安装了 Homebrew可以使用brew install node。Linux 发行版可以使用apt install nodejs npm或dnf install nodejs npm但系统源里的版本可能较老安装后要重点确认版本号。安装完成后打开终端执行node -v npm -v正常应该输出两个版本号例如v20.18.0 10.8.2如果提示node: command not found说明 Node.js 没有加入 PATH。Windows 上安装后通常会自动配置但旧终端窗口不会刷新需要重开一个终端。Linux 上使用apt安装后可能需要重新登录终端会话。2.3 Windows 用户先决定运行环境Windows 上有两种常见运行方式直接在 PowerShell 或 CMD 里安装运行。使用 WSL2Windows Subsystem for Linux安装在 Ubuntu 环境里运行。两种方式都可以但优先级建议 WSL2。原因在于 Codex CLI 默认会在沙箱环境中执行命令Windows 原生环境下沙箱对文件系统和命令的限制粒度不够一致更容易出现路径转换、命令权限、进程中断等问题。WSL2 里看起来更像服务器环境后续接第三方模型、跑测试脚本、操作 Linux 命令都更顺畅。如果你电脑上还没有 WSL2可以在管理员 PowerShell 中执行wsl --install安装后重启按提示设置 Linux 用户和密码。之后在 WSL 终端里执行 Node.js 安装再安装 Codex能绕开不少 Windows 原生环境的坑。2.4 准备接口信息官方账号或第三方兼容服务Codex 需要模型服务端来处理请求所以安装之前要想清楚用哪一种官方账号通过codex login登录 OpenAI 账号或提供OPENAI_API_KEY。第三方 OpenAI 兼容接口例如 DeepSeek 等国产模型服务它们提供兼容接口只需要配置接口地址、密钥和模型名。如果是官方账号你需要准备好账号和登录环境。如果是第三方兼容接口提前准备好三个信息配置项示例作用接口地址https://api.deepseek.com告诉 Codex 请求发到哪里API Keysk-xxxxxxxx身份认证模型名deepseek-chat指定使用哪个模型注意不是所有 OpenAI 兼容接口都能完美支持 Codex 的完整工具调用。Codex 会发送一系列复杂请求比如修改文件、执行命令、返回结构化结果。如果模型服务端不兼容会出现请求 400 或模型不支持等错误。初次使用时建议先用官方模型跑通流程再切换第三方接口。3. Codex CLI 安装npm 一行命令加三项检查3.1 全局安装 openai/codex确认 Node.js 已经安装后在终端执行全局安装npm install -g openai/codex执行过程中npm 会下载 Codex 包及其依赖通常需要几分钟。看到类似下面的输出说明安装成功added 220 packages in 45s这里有两个常见问题。第一如果你在 Windows 上安装时提示权限不足或者包目录无法写入不要直接使用sudo强行装到系统目录而是检查 npm 全局目录是否配置正确。第二如果你使用 WSL2需要在 WSL 内部安装 Node.js再执行 npm 安装。不要只在 Windows 原生环境里装一次又在 WSL 里用codex命令两者不能直接互通。3.2 验证 codex 命令是否可用安装完成之后验证命令codex --version codex --helpcodex --version会输出版本号例如0.x.x。codex --help会列出子命令和常见参数。如果你看到codex: command not found需要定位 npm 全局包路径。执行npm prefix -gWindows 上全局路径通常在C:\Users\你的用户名\AppData\Roaming\npmLinux/macOS 上通常在/usr/local或$HOME/.npm-global。确认这个目录已经在 PATH 里如果没有需要手动添加环境变量。3.3 npm 下载慢或安装失败怎么办npm 默认从官方源下载网络不稳定时经常失败。可以使用国内镜像源不建议把镜像源固化到全局配置用--registry参数临时指定更安全npm install -g openai/codex --registryhttps://registry.npmmirror.com如果你想使用固定镜像源执行npm config set registry https://registry.npmmirror.com之后安装npm install -g openai/codex如果安装过程中出现依赖编译报错比如node-gyp相关错误通常是因为缺少 C 编译工具链。Windows 上安装 Visual Studio Build ToolsLinux 上安装build-essential然后再试。Codex 的大部分依赖是 JavaScript 包不需要编译但个别环境可能出现原生模块下载失败。3.4 学习环境与生产环境的安装差异学习环境里安装 Codex 的目的是快速跑通可以接受最新版本和默认配置。但生产环境里使用 Codex 时建议固定 Codex 版本不要每次自动升级。把全局安装改成项目级安装或者使用npx openai/codex锁定版本。记录 Codex 版本与 Node.js 版本、模型接口版本的对应关系。不要在生产环境直接使用--full-auto应该保留人工审批机制。Codex 目前版本迭代很快不同版本之间的参数、配置字段、错误提示都可能变化。安装完成后先记录一下版本号后续查资料和看文档时优先参考当前版本对应内容。4. 登录和模型配置一个账号还是开放接口4.1 官方登录codex login 与浏览器授权安装完成后第一次使用前需要完成登录。官方账号登录最简单的方式是codex login执行后Codex 会尝试打开浏览器进入账号授权页面。你登录账号并确认授权后终端会显示登录成功。如果你的环境没有浏览器或者不方便打开浏览器Codex 会输出一个链接和一个设备码你可以在另一台设备上打开链接并输入设备码完成授权。登录成功后Codex 会把凭证保存在本地配置目录里默认是~/.codex。之后使用的时候不需要每次重新登录。4.2 使用 API Key 直接设置环境变量如果你不想走浏览器授权流程也可以直接使用 API Key。设置环境变量export OPENAI_API_KEYsk-xxxxxxxxWindows PowerShell 里使用$env:OPENAI_API_KEYsk-xxxxxxxx设置之后启动 Codex 时它优先读取环境变量。实际项目中API Key 属于敏感信息不要写进 git 仓库不要写进公开的配置示例。推荐使用.env文件或 CI/CD 的密钥管理功能并在本地加载。4.3 接入 DeepSeek 等 OpenAI 兼容接口第三方兼容接口的配置思路是告诉 Codex 把请求发到哪个地址、用什么密钥、用哪个模型。以 DeepSeek 为例命令行方式如下export OPENAI_BASE_URLhttps://api.deepseek.com export OPENAI_API_KEYsk-深度求索的密钥 export OPENAI_MODELdeepseek-chat codexPowerShell 中对应写成$env:OPENAI_BASE_URLhttps://api.deepseek.com $env:OPENAI_API_KEYsk-深度求索的密钥 $env:OPENAI_MODELdeepseek-chat codex执行codex后Codex 不再默认走官方模型而是把请求发送到 DeepSeek 的接口。不同服务商的接口地址后缀格式可能不同有的需要在地址后加/v1有的不需要以服务商文档为准。这里有一个重要提示OPENAI_MODEL的值必须是接口服务商支持的模型名。例如 DeepSeek 提供的模型名通常为deepseek-chat或deepseek-reasoner而不是 Codex 官方模型名。如果写错模型名请求会在服务端被拒绝。4.4 config.toml 里需要知道的字段Codex 的配置目录默认是~/.codex配置文件为config.toml。这个文件可以设置默认模型例如model gpt-5-codex如果你想设置不同的 provider可以写model_provider deepseek但不同 Codex 版本对model_provider的字段要求和配置嵌套方式有所差异不建议新手直接照搬网上的复杂示例。更稳妥的方式是先用环境变量跑通再根据实际版本阅读codex --help或官方文档确认配置写法。如果你使用环境变量方式需要注意环境变量的优先级问题。有时候你已经设置了第三方接口的环境变量但config.toml里还留着官方模型名Codex 可能优先读取配置文件里的模型导致接口请求发到了官方地址却带着第三方密钥最终报 401 或模型不存在。4.5 登录状态和会话维护Codex 的会话记录通常保存在~/.codex/sessions或类似目录。你可以使用codex resume恢复上一次会话继续之前没有完成的任务。这个功能对多轮修改很有用。如果登录状态过期请求会提示认证失败。可以先执行codex login重新登录或者检查OPENAI_API_KEY是否还有效。第三方接口的 Key 过期后Codex 不会自动告诉你只会出现 401 或 403此时应该去服务商后台确认 Key 状态。5. 第一个实战让 Codex 完成一个编码任务5.1 最小用法交互式对话在任意项目目录里执行codex 帮我在当前目录创建一个 Python 脚本读取 data.csv 中的数字列并求和Codex 会进入交互模式先展示分析过程和计划然后生成文件改动。你需要根据提示审批操作。如果只是想在非交互环境跑一条自动化任务可以使用exec子命令codex exec 帮我把 README.md 改成中英双语exec模式适合在脚本或 CI 里使用它不会等待你反复输入而是执行完就退出。学习阶段优先使用交互模式因为你需要看清每一步操作。5.2 实战一从零生成一个 Python 脚本先创建一个空目录mkdir codex-demo cd codex-demo然后启动 Codexcodex 写一个 Python 脚本读取当前目录下的 data.csv把第一列数字求和结果输出到终端如果 data.csv 还不存在Codex 通常会在计划里提示你并生成脚本。如果它直接创建脚本会显示新增的文件路径和内容。执行完成后你可以在当前目录看到新的.py文件。Codex 还会询问是否需要运行这个脚本你可以同意它在沙箱里执行。如果运行失败Codex 会根据报错继续调整代码。5.3 实战二让 Codex 修复代码里的 Bug新建一个文件bug.py内容写一个有问题的函数def add_values(values): total 0 for i in range(len(values)): total values[i 1] return total然后在项目目录执行codex bug.py 会越界报错请修复它并补一个测试Codex 会分析values[i 1]的边界问题建议改成遍历元素本身或者修正索引。随后它会修改文件并创建测试文件。你可以检查 diff确认它没有把业务逻辑改坏。这里要注意Codex 是概率模型它生成的修复不一定完全正确。实际项目里一定要让 Codex 解释为什么这样修复并要求它运行测试验证。不要直接使用未经审查的代码。5.4 常用命令和参数速查命令/参数用途注意事项codex 描述进入交互模式执行一个任务适合学习阶段操作透明codex exec 描述非交互方式执行任务适合脚本和自动化codex resume恢复上次会话适合长任务续做codex login登录官方账号需要浏览器或设备码codex logout退出登录切换账号时使用--model 模型名临时指定模型优先级高于默认配置--sandbox开启沙箱默认行为受限执行--full-auto自动审批所有操作风险高新手慎用参数清单以当前版本的codex --help输出为准。不同版本对参数的命名和默认值有调整不要拿一年前的命令硬套。6. 在 VS Code 中使用 Codex6.1 安装官方插件在 VS Code 扩展市场里搜索Codex找到 OpenAI 官方扩展并安装。安装后左侧活动栏会出现 Codex 图标。插件通常复用 CLI 的登录状态前提是 CLI 已经安装并且登录成功。如果在插件里看不到登录状态可以检查 VS Code 的集成终端里codex --version是否能正常运行。如果命令不存在插件也可能找不到底层 CLI所以先保证命令行环境没有问题。6.2 在编辑器里执行任务在 VS Code 中打开一个项目点击 Codex 图标在输入框里描述需求。例如给当前项目添加一个 .gitignore忽略 node_modules 和 dist 目录Codex 会在编辑器里显示修改建议。你可以选择接受或拒绝。相比命令行编辑器里查看 diff 更直观适合处理文件改动较多的代码重构任务。6.3 编辑器模式下的注意事项编辑器模式虽然方便但不要忽略权限控制。在编辑器里执行 Codex 的任务同样会触发文件写入和终端命令。确认项目目录的信任状态、Codex 插件的配置和审批策略避免让 Codex 在未授权状态下改动整个项目。如果项目很大例如包含几十万行代码的仓库首次加载上下文会消耗较多时间和 token。建议先在终端任务里把范围缩小比如先让 Codex 查看某个子目录再生成修改。不要一上来就让它在整个仓库里搜索“所有 TODO”。7. 常见问题排查链路从登录到接口请求逐层定位7.1 codex 命令找不到现象输入codex提示command not found。优先检查 Node.js 是否安装成功node -v npm -v然后检查 npm 全局目录npm prefix -gWindows 上把%APPDATA%\npm加入 PATH 并重新打开终端。WSL 里检查的是 Linux 的 PATH不是 Windows 的 PATH。如果刚安装完先重启终端再测试。7.2 登录失败和浏览器无法打开现象执行codex login后浏览器没有自动打开或者打开后页面一直转圈。先看终端输出里有没有设备码和链接。如果有使用另一台设备打开链接输入设备码完成授权。如果没有任何输出检查环境变量是否残留了旧的OPENAI_API_KEY它可能会干扰登录流程。也可以先清理本地登录状态codex logout codex login7.3 请求 401、429 和模型不支持错误现象可能原因检查方向401 UnauthorizedAPI Key 无效或过期检查环境变量、服务商后台429 Too Many Requests限流或额度不足检查额度、等待或降频400 model not found模型名不存在检查模型名和服务商支持列表model is not supported模型与接口不匹配检查OPENAI_MODEL和接口地址热词中经常出现的the gpt-5.6-sol model is not supported when using codex with a...这类报错本质就是模型名不匹配。Codex 请求服务端时服务端发现配置的模型不是它支持的模型。解决办法是确认当前使用的接口服务商支持哪些模型并把OPENAI_MODEL改成正确名称。不要相信网上随意写出的模型名以服务商官方文档为准。7.4 CC Switch 配置后接口报本地转发服务失败很多用户使用 CC Switch 来管理不同的模型接口配置然后通过它启动 Codex。这时如果出现类似“local proxy failed while handling codex endpoint /responses”的提示说明 CC Switch 的本地转发服务没有正常工作。排查顺序如下检查 CC Switch 是否真的启动了托盘图标是否正常。检查它绑定的本地端口有没有被占用例如 36713 或其他端口。检查配置里的接口地址是否正确是否少了/v1后缀。检查 API Key 是否填写正确。检查 Codex 的环境变量是否指向了 CC Switch 的本地端口。这里的原理是CC Switch 会启动一个本地服务把 Codex 发往本地的请求再转发到真正的模型接口。本地服务一旦失败Codex 就会收到无法处理请求的报错。遇到这个问题时不要反复重装 Codex先检查本地转发服务本身。7.5 沙箱执行命令失败Codex 默认会在沙箱里执行命令。如果命令需要访问当前工作目录之外的文件比如读取/etc下的配置或者需要安装全局依赖沙箱可能拒绝执行。此时可以检查报错内容是否提示目录不可访问。把项目切换到 WSL2 环境再试。适当使用全权限模式但必须手动审批每一步操作。把需要执行的命令拆得更小避免一个命令里包含多个高权限操作。不要因为嫌审批麻烦就直接开--full-auto。Codex 的执行能力越强误操作造成的影响也越大。7.6 排查顺序总结表出现问题的环节第一检查项第二检查项第三检查项安装失败Node.js 版本npm 镜像源编译工具链登录失败网络和账号浏览器/设备码缓存和旧 Key请求报错接口地址模型名API Key本地转发失败CC Switch 是否启动端口占用接口配置沙箱失败目录权限环境差异审批策略8. 最佳实践安全、效率和下一步练习8.1 使用 Codex 前检查清单每次在项目里使用 Codex 之前可以按下面这个清单做一次环境确认Node.js 版本满足 Codex 要求。codex --version能正常输出。登录状态有效或环境变量里配置了正确 Key。当前工作目录是目标项目不是根目录或系统目录。重要改动已经提交到 Git或者有备份分支。已明确 Codex 使用哪个模型、哪个接口地址。没有残留其他工具的接口环境变量避免配置冲突。沙箱处于开启状态危险命令不会被自动执行。这个清单在切换项目、切换模型、升级版本时尤其有用。8.2 生产环境里的安全底线把 Codex 引入生产环境要把握几条底线第一API Key 不要写进config.toml也不要写进 git 仓库。使用环境变量或密钥管理服务并定期轮换。第二保留命令审批。工作流里尽量不要用--full-auto即使使用也要限定在隔离的 CI 沙箱或预览环境里。第三给 Codex 设置“能做和不能做”的边界。比如禁止同时修改多个微服务禁止自动执行rm -rf类命令禁止直接修改生产数据库。Codex 本身没有主观判断力边界要由工程规范来约束。第四对 Codex 的改动要做代码审查。AI 生成的代码同样需要走 PR、Review、CI 流程不能因为生成速度快就跳过质量门禁。8.3 新手练习路径和常用资料判断方法新手不要一开始就尝试复杂项目建议按这个顺序练习让 Codex 在空目录里创建一个小脚本。让 Codex 读取一个现有文件并修改函数。让 Codex 写测试并运行测试。让 Codex 分多次任务完成一个小项目例如一个带命令行参数的工具。再尝试接入第三方模型接口对比不同模型的代码生成效果。在搜索 Codex 资料时注意判断信息是否过时。Codex 的安装命令、配置字段、模型名称都变化较快。看到老的配置示例时先跑通最小流程再决定是否使用。优先参考官方文档、当前版本的codex --help输出以及和当前版本接近的社区文章。Codex 的价值不在于替你写多少行代码而在于把“描述需求、执行工具、验证结果”这条链路自动化。先把安装和登录跑通再逐步学会审批和约束它才能真正成为一个可控的编码助手而不是一个偶尔能生成代码、偶尔又制造混乱的黑盒。 Codex 安装与使用教程这些年一直随着版本更新而变化很多新手卡住的地方其实不在代码本身而在第一步到底该安装哪个 Codex、要不要装 Node.js、登录用什么账号、模型怎么选。这篇文章围绕 Codex CLI 这条主线从概念、环境准备、安装、登录、实战到排查完整走一遍。如果你是一个刚开始接触 Codex 的开发者或者想在 Windows 上把 Codex 跑起来但被各种报错拦住这篇文章可以按顺序直接操作。1. Codex 是什么从聊天补全到自动执行编码任务1.1 Codex 解决什么问题Codex 是一类 AI 编程工具的统称在 OpenAI 的语境下Codex 不再只是“文本框里帮你补全代码”的插件而是一个能直接读取项目文件、修改代码、执行终端命令并观察结果的编码智能体。你给它一句自然语言需求比如“帮我把登录接口改成 JWT 认证”它会先查看项目结构分析相关文件然后生成改动方案修改代码甚至运行测试来验证结果。这个过程和传统 AI 聊天工具最大的区别在于它不只是给你一段代码片段而是围绕整个项目上下文工作。你可以把它理解成一个坐在你电脑前、能操作终端和文件系统的开发助手。正因如此Codex 的使用门槛也比普通代码补全工具高它需要安装命令行工具、配置模型接口、理解交互流程还需要你控制好权限审批。1.2 CLI、IDE 扩展和桌面客户端怎么选Codex 有几种使用形态新手最先要搞清楚区别。形态运行环境适合人群特点Codex CLI终端跨平台想用命令行控制任务的开发者功能完整能操作系统命令适合自动化场景VS Code 扩展Visual Studio Code习惯在编辑器里工作的人与编辑器集成左侧面板操作切换上下文方便桌面客户端独立窗口不想接触命令行的用户通常封装了 CLI界面对新手友好但依赖 CLI 安装正确实际项目中最核心、也最能体现 Codex 能力的是 Codex CLI。IDE 扩展和桌面客户端通常只是换了入口最终底层调用的还是同一套命令和配置。所以这篇教程以 Codex CLI 为主先把底层链路跑通再去用扩展和桌面版就会轻松很多。1.3 Codex 的执行链路对话、改文件、跑命令、看结果Codex 并不是一锤子买卖。它执行一个任务时通常遵循这样的循环接收你的自然语言指令。读取当前项目目录里的文件理解代码结构。生成修改方案例如新增文件、修改函数、删除无用依赖。在你审批后实际应用文件改动。如果需要执行终端命令比如运行测试、安装依赖、启动服务。观察命令输出根据结果决定是否需要继续修改。这个链路里最关键的是“审批”和“沙箱”。代码改动和命令执行都有风险所以 Codex 默认不会偷偷执行任意命令而是给你看它准备做什么你确认之后才执行。这也意味着新人使用 Codex 的第一步不是急着写需求而是先理解它的交互规则哪些操作需要你批准哪些操作会直接执行以及如何在出错时停止。2. 安装前的环境准备先确认 Node.js、Shell 和接口信息2.1 系统要求与 Node.js 版本Codex CLI 在 Windows、macOS、Linux 上都可以运行但它依赖 Node.js 运行时。不同版本的 Codex 对 Node.js 版本要求不太一样当前主流安装方式要求 Node.js 18 或更高版本建议使用 Node.js 20 LTS 或 Node.js 22 LTS。如果你安装版本较新却使用很老的 Node.js常见的报错是找不到某个现代语法或模块比如ERR_UNKNOWN_FILE_EXTENSION、SyntaxError: Unexpected token。所以安装之前先检查系统里是不是已经存在正确的 Node.js。硬件要求不算高普通开发机能跑。内存建议 8GB 以上因为 Codex 在极少数情况下会启动本地服务或调试进程磁盘空间预留 500MB 以上主要给 npm 全局包和缓存。2.2 安装 Node.js 并在终端里验证以 Windows 为例去 Node.js 官网下载 LTS 版本安装包安装时保持默认配置即可。macOS 如果安装了 Homebrew可以使用brew install node。Linux 发行版可以使用apt install nodejs npm或dnf install nodejs npm但系统源里的版本可能较老安装后要重点确认版本号。安装完成后打开终端执行node -v npm -v正常应该输出两个版本号例如v20.18.0 10.8.2如果提示node: command not found说明 Node.js 没有加入 PATH。Windows 上安装后通常会自动配置但旧终端窗口不会刷新需要重开一个终端。Linux 上使用apt安装后可能需要重新登录终端会话。2.3 Windows 用户先决定运行环境Windows 上有两种常见运行方式直接在 PowerShell 或 CMD 里安装运行。使用 WSL2Windows Subsystem for Linux安装在 Ubuntu 环境里运行。两种方式都可以但优先级建议 WSL2。原因在于 Codex CLI 默认会在沙箱环境中执行命令Windows 原生环境下沙箱对文件系统和命令的限制粒度不够一致更容易出现路径转换、命令权限、进程中断等问题。WSL2 里看起来更像服务器环境后续接第三方模型、跑测试脚本、操作 Linux 命令都更顺畅。如果你电脑上还没有 WSL2可以在管理员 PowerShell 中执行wsl --install安装后重启按提示设置 Linux 用户和密码。之后在 WSL 终端里执行 Node.js 安装再安装 Codex能绕开不少 Windows 原生环境的坑。2.4 准备接口信息官方账号或第三方兼容服务Codex 需要模型服务端来处理请求所以安装之前要想清楚用哪一种官方账号通过codex login登录 OpenAI 账号或提供OPENAI_API_KEY。第三方 OpenAI 兼容接口例如 DeepSeek 等国产模型服务它们提供兼容接口只需要配置接口地址、密钥和模型名。如果是官方账号你需要准备好账号和登录环境。如果是第三方兼容接口提前准备好三个信息配置项示例作用接口地址https://api.deepseek.com告诉 Codex 请求发到哪里API Keysk-xxxxxxxx身份认证模型名deepseek-chat指定使用哪个模型注意不是所有 OpenAI 兼容接口都能完美支持 Codex 的完整工具调用。Codex 会发送一系列复杂请求比如修改文件、执行命令、返回结构化结果。如果模型服务端不兼容会出现请求 400 或模型不支持等错误。初次使用时建议先用官方模型跑通流程再切换第三方接口。3. Codex CLI 安装npm 一行命令加三项检查3.1 全局安装 openai/codex确认 Node.js 已经安装后在终端执行全局安装npm install -g openai/codex执行过程中npm 会下载 Codex 包及其依赖通常需要几分钟。看到类似下面的输出说明安装成功added 220 packages in 45s这里有两个常见问题。第一如果你在 Windows 上安装时提示权限不足或者包目录无法写入不要直接使用sudo强行装到系统目录而是检查 npm 全局目录是否配置正确。第二如果你使用 WSL2需要在 WSL 内部安装 Node.js再执行 npm 安装。不要只在 Windows 原生环境里装一次又在 WSL 里用codex命令两者不能直接互通。3.2 验证 codex 命令是否可用安装完成之后验证命令codex --version codex --helpcodex --version会输出版本号例如0.x.x。codex --help会列出子命令和常见参数。如果你看到codex: command not found需要定位 npm 全局包路径。执行npm prefix -gWindows 上全局路径通常在C:\Users\你的用户名\AppData\Roaming\npmLinux/macOS 上通常在/usr/local或$HOME/.npm-global。确认这个目录已经在 PATH 里如果没有需要手动添加环境变量。3.3 npm 下载慢或安装失败怎么办npm 默认从官方源下载网络不稳定时经常失败。可以使用国内镜像源不建议把镜像源固化到全局配置用--registry参数临时指定更安全npm install -g openai/codex --registryhttps://registry.npmmirror.com如果你想使用固定镜像源执行npm config set registry https://registry.npmmirror.com之后安装npm install -g openai/codex如果安装过程中出现依赖编译报错比如node-gyp相关错误通常是因为缺少 C 编译工具链。Windows 上安装 Visual Studio Build ToolsLinux 上安装build-essential然后再试。Codex 的大部分依赖是 JavaScript 包不需要编译但个别环境可能出现原生模块下载失败。3.4 学习环境与生产环境的安装差异学习环境里安装 Codex 的目的是快速跑通可以接受最新版本和默认配置。但生产环境里使用 Codex 时建议固定 Codex 版本不要每次自动升级。把全局安装改成项目级安装或者使用npx openai/codex锁定版本。记录 Codex 版本与 Node.js 版本、模型接口版本的对应关系。不要在生产环境直接使用--full-auto应该保留人工审批机制。Codex 目前版本迭代很快不同版本之间的参数、配置字段、错误提示都可能变化。安装完成后先记录一下版本号后续查资料和看文档时优先参考当前版本对应内容。4. 登录和模型配置一个账号还是开放接口4.1 官方登录codex login 与浏览器授权安装完成后第一次使用前需要完成登录。官方账号登录最简单的方式是codex login执行后Codex 会尝试打开浏览器进入账号授权页面。你登录账号并确认授权后终端会显示登录成功。如果你的环境没有浏览器或者不方便打开浏览器Codex 会输出一个链接和一个设备码你可以在另一台设备上打开链接并输入设备码完成授权。登录成功后Codex 会把凭证保存在本地配置目录里默认是~/.codex。之后使用的时候不需要每次重新登录。4.2 使用 API Key 直接设置环境变量如果你不想走浏览器授权流程也可以直接使用 API Key。设置环境变量export OPENAI_API_KEYsk-xxxxxxxxWindows PowerShell 里使用$env:OPENAI_API_KEYsk-xxxxxxxx设置之后启动 Codex 时它优先读取环境变量。实际项目中API Key 属于敏感信息不要写进 git 仓库不要写进公开的配置示例。推荐使用.env文件或 CI/CD 的密钥管理功能并在本地加载。4.3 接入 DeepSeek 等 OpenAI 兼容接口第三方兼容接口的配置思路是告诉 Codex 把请求发到哪个地址、用什么密钥、用哪个模型。以 DeepSeek 为例命令行方式如下export OPENAI_BASE_URLhttps://api.deepseek.com export OPENAI_API_KEYsk-深度求索的密钥 export OPENAI_MODELdeepseek-chat codexPowerShell 中对应写成$env:OPENAI_BASE_URLhttps://api.deepseek.com $env:OPENAI_API_KEYsk-深度求索的密钥 $env:OPENAI_MODELdeepseek-chat codex执行codex后Codex 不再默认走官方模型而是把请求发送到 DeepSeek 的接口。不同服务商的接口地址后缀格式可能不同有的需要在地址后加/v1有的不需要以服务商文档为准。这里有一个重要提示OPENAI_MODEL的值必须是接口服务商支持的模型名。例如 DeepSeek 提供的模型名通常为deepseek-chat或deepseek-reasoner而不是 Codex 官方模型名。如果写错模型名请求会在服务端被拒绝。4.4 config.toml 里需要知道的字段Codex 的配置目录默认是~/.codex配置文件为config.toml。这个文件可以设置默认模型例如model gpt-5-codex如果你想设置不同的 provider可以写model_provider deepseek但不同 Codex 版本对model_provider的字段要求和配置嵌套方式有所差异不建议新手直接照搬网上的复杂示例。更稳妥的方式是先用环境变量跑通再根据实际版本阅读codex --help或官方文档确认配置写法。如果你使用环境变量方式需要注意环境变量的优先级问题。有时候你已经设置了第三方接口的环境变量但config.toml里还留着官方模型名Codex 可能优先读取配置文件里的模型导致接口请求发到了官方地址却带着第三方密钥最终报 401 或模型不存在。4.5 登录状态和会话维护Codex 的会话记录通常保存在~/.codex/sessions或类似目录。你可以使用codex resume恢复上一次会话继续之前没有完成的任务。这个功能对多轮修改很有用。如果登录状态过期请求会提示认证失败。可以先执行codex login重新登录或者检查OPENAI_API_KEY是否还有效。第三方接口的 Key 过期后Codex 不会自动告诉你只会出现 401 或 403此时应该去服务商后台确认 Key 状态。5. 第一个实战让 Codex 完成一个编码任务5.1 最小用法交互式对话在任意项目目录里执行codex 帮我在当前目录创建一个 Python 脚本读取 data.csv 中的数字列并求和Codex 会进入交互模式先展示分析过程和计划然后生成文件改动。你需要根据提示审批操作。如果只是想在非交互环境跑一条自动化任务可以使用exec子命令codex exec 帮我把 README.md 改成中英双语exec模式适合在脚本或 CI 里使用它不会等待你反复输入而是执行完就退出。学习阶段优先使用交互模式因为你需要看清每一步操作。5.2 实战一从零生成一个 Python 脚本先创建一个空目录mkdir codex-demo cd codex-demo然后启动 Codexcodex 写一个 Python 脚本读取当前目录下的 data.csv把第一列数字求和结果输出到终端如果 data.csv 还不存在Codex 通常会在计划里提示你并生成脚本。如果它直接创建脚本会显示新增的文件路径和内容。执行完成后你可以在当前目录看到新的.py文件。Codex 还会询问是否需要运行这个脚本你可以同意它在沙箱里执行。如果运行失败Codex 会根据报错继续调整代码。5.3 实战二让 Codex 修复代码里的 Bug新建一个文件bug.py内容写一个有问题的函数def add_values(values): total 0 for i in range(len(values)): total values[i 1] return total然后在项目目录执行codex bug.py 会越界报错请修复它并补一个测试Codex 会分析values[i 1]的边界问题建议改成遍历元素本身或者修正索引。随后它会修改文件并创建测试文件。你可以检查 diff确认它没有把业务逻辑改坏。这里要注意Codex 是概率模型它生成的修复不一定完全正确。实际项目里一定要让 Codex 解释为什么这样修复并要求它运行测试验证。不要直接使用未经审查的代码。5.4 常用命令和参数速查命令/参数用途注意事项codex 描述进入交互模式执行一个任务适合学习阶段操作透明codex exec 描述非交互方式执行任务适合脚本和自动化codex resume恢复上次会话适合长任务续做codex login登录官方账号需要浏览器或设备码codex logout退出登录切换账号时使用--model 模型名临时指定模型优先级高于默认配置--sandbox开启沙箱默认行为受限执行--full-auto自动审批所有操作风险高新手慎用参数清单以当前版本的codex --help输出为准。不同版本对参数的命名和默认值有调整不要拿一年前的命令硬套。6. 在 VS Code 中使用 Codex6.1 安装官方插件在 VS Code 扩展市场里搜索Codex找到 OpenAI 官方扩展并安装。安装后左侧活动栏会出现 Codex 图标。插件通常复用 CLI 的登录状态前提是 CLI 已经安装并且登录成功。如果在插件里看不到登录状态可以检查 VS Code 的集成终端里codex --version是否能正常运行。如果命令不存在插件也可能找不到底层 CLI所以先保证命令行环境没有问题。6.2 在编辑器里执行任务在 VS Code 中打开一个项目点击 Codex 图标在输入框里描述需求。例如给当前项目添加一个 .gitignore忽略 node_modules 和 dist 目录Codex 会在编辑器里显示修改建议。你可以选择接受或拒绝。相比命令行编辑器里查看 diff 更直观适合处理文件改动较多的代码重构任务。6.3 编辑器模式下的注意事项编辑器模式虽然方便但不要忽略权限控制。在编辑器里执行 Codex 的任务同样会触发文件写入和终端命令。确认项目目录的信任状态、Codex 插件的配置和审批策略避免让 Codex 在未授权状态下改动整个项目。如果项目很大例如包含几十万行代码的仓库首次加载上下文会消耗较多时间和 token。建议先在终端任务里把范围缩小比如先让 Codex 查看某个子目录再生成修改。不要一上来就让它在整个仓库里搜索“所有 TODO”。7. 常见问题排查链路从登录到接口请求逐层定位7.1 codex 命令找不到现象输入codex提示command not found。优先检查 Node.js 是否安装成功node -v npm -v然后检查 npm 全局目录npm prefix -gWindows 上把%APPDATA%\npm加入 PATH 并重新打开终端。WSL 里检查的是 Linux 的 PATH不是 Windows 的 PATH。如果刚安装完先重启终端再测试。7.2 登录失败和浏览器无法打开现象执行codex login后浏览器没有自动打开或者打开后页面一直转圈。先看终端输出里有没有设备码和链接。如果有使用另一台设备打开链接输入设备码完成授权。如果没有任何输出检查环境变量是否残留了旧的OPENAI_API_KEY它可能会干扰登录流程。也可以先清理本地登录状态codex logout codex login7.3 请求 401、429 和模型不支持错误现象可能原因检查方向401 UnauthorizedAPI Key 无效或过期检查环境变量、服务商后台429 Too Many Requests限流或额度不足检查额度、等待或降频400 model not found模型名不存在检查模型名和服务商支持列表model is not supported模型与接口不匹配检查OPENAI_MODEL和接口地址热词中经常出现的the gpt-5.6-sol model is not supported when using codex with a...这类报错本质就是模型名不匹配。Codex 请求服务端时服务端发现配置的模型不是它支持的模型。解决办法是确认当前使用的接口服务商支持哪些模型并把OPENAI_MODEL改成正确名称。不要相信网上随意写出的模型名以服务商官方文档为准。7.4 CC Switch 配置后接口报本地转发服务失败很多用户使用 CC Switch 来管理不同的模型接口配置然后通过它启动 Codex。这时如果出现类似“local proxy failed while handling codex endpoint /responses”的提示说明 CC Switch 的本地转发服务没有正常工作。排查顺序如下检查 CC Switch 是否真的启动了托盘图标是否正常。检查它绑定的本地端口有没有被占用例如 36713 或其他端口。检查配置里的接口地址是否正确是否少了/v1后缀。检查 API Key 是否填写正确。检查 Codex 的环境变量是否指向了 CC Switch 的本地端口。这里的原理是CC Switch 会启动一个本地服务把 Codex 发往本地的请求再转发到真正的模型接口。本地服务一旦失败Codex 就会收到无法处理请求的报错。遇到这个问题时不要反复重装 Codex先检查本地转发服务本身。7.5 沙箱执行命令失败Codex 默认会在沙箱里执行命令。如果命令需要访问当前工作目录之外的文件比如读取/etc下的配置或者需要安装全局依赖沙箱可能拒绝执行。此时可以检查报错内容是否提示目录不可访问。把项目切换到 WSL2 环境再试。适当使用全权限模式但必须手动审批每一步操作。把需要执行的命令拆得更小避免一个命令里包含多个高权限操作。不要因为嫌审批麻烦就直接开--full-auto。Codex 的执行能力越强误操作造成的影响也越大。7.6 排查顺序总结表出现问题的环节第一检查项第二检查项第三检查项安装失败Node.js 版本npm 镜像源编译工具链登录失败网络和账号浏览器/设备码缓存和旧 Key请求报错接口地址模型名API Key本地转发失败CC Switch 是否启动端口占用接口配置沙箱失败目录权限环境差异审批策略8. 最佳实践安全、效率和下一步练习8.1 使用 Codex 前检查清单每次在项目里使用 Codex 之前可以按下面这个清单做一次环境确认Node.js 版本满足 Codex 要求。codex --version能正常输出。登录状态有效或环境变量里配置了正确 Key。当前工作目录是目标项目不是根目录或系统目录。重要改动已经提交到 Git或者有备份分支。已明确 Codex 使用哪个模型、哪个接口地址。没有残留其他工具的接口环境变量避免配置冲突。沙箱处于开启状态危险命令不会被自动执行。这个清单在切换项目、切换模型、升级版本时尤其有用。8.2 生产环境里的安全底线把 Codex 引入生产环境要把握几条底线第一API Key 不要写进config.toml也不要写进 git 仓库。使用环境变量或密钥管理服务并定期轮换。第二保留命令审批。工作流里尽量不要用--full-auto即使使用也要限定在隔离的 CI 沙箱或预览环境里。第三给 Codex 设置“能做和不能做”的边界。比如禁止同时修改多个微服务禁止自动执行rm -rf类命令禁止直接修改生产数据库。Codex 本身没有主观判断力边界要由工程规范来约束。第四对 Codex 的改动要做代码审查。AI 生成的代码同样需要走 PR、Review、CI 流程不能因为生成速度快就跳过质量门禁。8.3 新手练习路径和常用资料判断方法新手不要一开始就尝试复杂项目建议按这个顺序练习让 Codex 在空目录里创建一个小脚本。让 Codex 读取一个现有文件并修改函数。让 Codex 写测试并运行测试。让 Codex 分多次任务完成一个小项目例如一个带命令行参数的工具。再尝试接入第三方模型接口对比不同模型的代码生成效果。在搜索 Codex 资料时注意判断信息是否过时。Codex 的安装命令、配置字段、模型名称都变化较快。看到老的配置示例时先跑通最小流程再决定是否使用。优先参考官方文档、当前版本的codex --help输出以及和当前版本接近的社区文章。Codex 的价值不在于替你写多少行代码而在于把“描述需求、执行工具、验证结果”这条链路自动化。先把安装和登录跑通再逐步学会审批和约束它才能真正成为一个可控的编码助手而不是一个偶尔能生成代码、偶尔又制造混乱的黑盒。 
