1. Codex 到底是什么先搞清楚它和聊天框的区别2026 年 9 月后台私信里问得最多的问题依然是 Codex 安装。其实这工具我已经在项目里用了大半年最近又帮两个完全没接触过命令行的同事从零开始把 Codex 装好并跑通了第一个任务。这篇就把完整过程写下来覆盖环境准备、CLI 和桌面版安装、登录、接入 DeepSeek以及我实际踩过的几个报错坑目标是让你照着敲一遍就能上手而不是看完一堆说明书然后原地发懵。在写安装命令之前我想先花两三分钟把 Codex 的定位说清楚。我见过太多人装完以后试了两句话就放下了原因不是工具不好用而是理解错了。Codex 不是一个网页版的 AI 写作助手它是 OpenAI 推出的编码智能体agent能直接在你电脑上读取文件、写文件、执行终端命令、运行测试。换句话说ChatGPT 网页版只负责“讲话”Codex 还会“动手”。后台那套运行逻辑大家通常叫它 agent harness它把一次编程任务拆成很多个小步骤自己判断下一步该读哪个文件、该跑哪条命令而不是像普通聊天窗口那样等你把上下文全部粘进去。1.1 它是怎么帮你干活的一个非常典型的场景你打开终端进入一个空目录输入codex然后说“帮我用 Python 写一个爬取博客文章列表的小脚本”它会先给你列一个简短计划然后开始建目录、安装依赖、创建文件、执行脚本。如果中途报错它会自己看错误日志再改代码再跑一遍。这个体验和“复制粘贴到 ChatGPT 里”完全是两回事因为你不再需要手动把每个文件内容粘进去Codex 自己掌握文件系统上下文。具体到能力边界Codex 大概能做这几类事读写项目里的文件新建、修改、删除都能触发在项目目录里执行终端命令比如npm test、python manage.py migrate调用外部工具链比如 Git、Docker、包管理器把多次尝试后的最终结果整理成清晰的改动说明。注意它不是你电脑上的万能遥控器。默认情况下Codex 的权限被限制在启动目录或你授权的 workspace 内不会随便去翻你桌面上的私人文件。这个限制后面会提到它是安全机制不是功能缺陷。1.2 2026 年的 Codex 常见形态现在 Codex 已经不止一个形态了。我建议你根据自己的操作习惯选一个主用入口其他的可以后面再补。下面这个表格是我个人理解的使用场景划分形态适合谁启动方式说明Codex CLI习惯终端操作、想写脚本自动化的人命令codex最核心的形态功能最完整Codex 桌面版不熟悉命令行、想开箱即用的新手双击桌面图标自带界面操作更直观VS Code 扩展主要写代码的人编辑器侧边栏不脱离 IDE边写边用我给你的建议是新手从桌面版起步但不要完全扔掉 CLI因为网上大部分教程、脚本、配置文件都是围绕 CLI 写的。你只要看得懂命令行后面排查问题会轻松很多。接下来就从环境准备开始一步一步走。2. 开工前的准备Node.js、Git、VS Code 一次装齐很多新手装 Codex 失败不是 Codex 本身的问题而是电脑里缺了依赖。Codex 安装虽然只有一条命令但它的运行环境涉及 Node.js 和 Git少一个都会在某个环节突然报错。所以我先带你把底座打好。2.1 先装 Node.jsCodex CLI 的运行底座Codex CLI 一般通过 npm 安装npm 是 Node.js 自带的包管理器所以第一步就是装 Node.js。到 Node.js 官网下载页选择 LTS 版本即可。LTS 意味着长期维护版本稳定性有保障不要贪新去下最新的 Current 版。Windows 用户选.msi安装包下载后双击一路下一步。安装路径尽量保持默认千万不要放到带中文或空格的目录里后面很容易出现路径解析问题。安装完成后打开一个新的终端窗口这一步很关键旧窗口不会自动刷新环境变量分别输入node -v npm -v能看到版本号输出说明 Node.js 装好了。如果提示node 不是内部或外部命令一般是 PATH 没生效。解决办法是重启终端或者手动把 Node.js 安装目录加到系统环境变量里。Windows 下默认安装路径通常是C:\Program Files\nodejs\把这个目录加到 Path 变量后重新打开终端即可。2.2 再装 Git很多自动化操作依赖它Codex 在克隆代码、查看 Git 状态、处理补丁时都会调用 Git。虽然你不一定直接用它但 Git 是底层依赖装好能省掉很多麻烦。Windows 用户去 Git 官网下载 Git for Windows安装时大部分配置保持默认。唯一要注意的是安装过程中有一个“Adjusting your PATH environment”的选项一定要选第二项Git from the command line and also from 3rd-party software。如果选了第一项Codex 在终端里可能找不到 Git 命令。装完后同样验证一下git --version能输出版本号就说明没问题。macOS 用户如果装了 Xcode Command Line Tools系统会自带 Git没装的话执行xcode-select --install即可。Linux 用户用各自发行版的包管理器安装比如sudo apt install git。2.3 顺手把 npm 源切成国内镜像这一步不是必须的但我建议每个国内用户都做。原因很简单npm 默认源在海外下载大一点的包时速度可能很慢甚至超时。国内有不少正规的 npm 镜像服务切换之后下载速度能快很多。把 npm 默认源切到国内镜像命令如下npm config set registry https://registry.npmmirror.com npm config get registry执行完第二条命令能返回刚才设置的地址说明切换成功。之后再用 npm 安装任何包都会走这个镜像。如果某一天安装 Codex 突然报 404很可能是镜像源还没来得及同步最新的 npm 包这时候切回官方源再装一次就行npm config set registry https://registry.npmjs.org3. 官方支持的安装方式我推荐你先用这一种环境准备好之后真正的主角终于登场了。Codex 官方提供了多种安装方式我按推荐程度从高到低排列你选一种适合自己的就行。3.1 方式一npm 全局安装 Codex CLI这是最常用、也最容易自动更新的方式。打开终端直接执行npm install -g openai/codex-g表示全局安装这样你在任何目录下都能直接使用codex命令。安装过程会输出一堆下载信息看到added字样基本就成功了。装完以后验证一下codex --version如果你看到版本号说明安装成功。如果提示codex 无法识别或command not found大概率是 npm 的全局安装目录不在系统的 PATH 里。Windows 下常见的全局目录是%APPDATA%\npmmacOS/Linux 下可能是/usr/local/bin或~/.npm-global。把这个目录加到 PATH 后重新打开终端即可。3.2 方式二Windows 桌面版安装Windows 用户如果不想碰命令行可以去 Codex 官网找到 Windows 桌面版下载入口下载安装包后双击安装。桌面版自带一套完整的运行环境不需要单独安装 Node.js对新手非常友好。安装完成后桌面上会有 Codex 的快捷方式。第一次打开会让你登录登录流程和 CLI 类似。这里有个小细节桌面版和 CLI 可以共存互不干扰。你完全可以在桌面版里写写简单的需求在 CLI 里跑自动化脚本两者共享同一个配置文件~/.codex/config.toml所以模型设置不会冲突。3.3 方式三macOS 使用 HomebrewmacOS 用户除了 npm 方式外也可以用 Homebrew 安装。如果你已经装了 Homebrew只需要执行brew install codex或者按官方文档添加适合当前版本的工具源。Homebrew 的好处是它会把相关依赖一起处理好升级也方便后续直接brew upgrade codex就能更新。Linux 用户同理可以去官方仓库查看对应的安装包但我个人还是建议 Linux 服务器上用 npm 方式因为更灵活也更容易配合 CI 流程。3.4 安装完成后最关键的一步登录认证安装只是第一步真正让 Codex 跑起来的是登录认证。运行codex login终端会显示一个链接和一个授权码。浏览器打开链接把授权码填进去选择用 ChatGPT 账号授权即可。授权成功后回到终端就能看到登录成功的提示。如果你习惯用 API Key也可以直接用下面的方式登录codex login --api-key然后粘贴你的 API Key。这里要区分一下两种认证方式的差别ChatGPT 账号登录走的是订阅套餐额度API Key 走的是按 token 计费。对于新手我建议先用 ChatGPT 账号体验跑通流程后再考虑 API Key。无论用哪种方式都要记住不要把 API Key 提交到 Git 仓库里尤其是公开仓库否则别人拿到你的 Key 就能随意调用接口产生不必要的费用。4. 上手实操跑通一次完整的编码任务登录成功后Codex 就算正式能用了。很多新手到这一步就卡住了因为不知道第一句话该说什么。别急我带你跑一个最经典的“用 Python 写爬虫”任务把交互式和非交互式的用法都过一遍。4.1 交互式命令行第一次对话找一个空目录打开终端进入这个目录然后输入codex几秒钟后你会进入一个交互式界面类似终端里的聊天窗口。输入帮我在当前目录下写一个 Python 爬虫抓取某个公开博客的文章标题和发布时间保存为 csv 文件Codex 会先列出一个执行计划然后开始创建文件、安装必要的依赖库。每一步执行前它会请求你的确认。这里新手容易紧张以为是不是出问题了。其实不是这是 Codex 的安全控制机制在执行会改变系统的命令前需要经过你同意。看到提示后按回车确认Codex 就会继续干活。整个过程中你可以随时输入新的要求打断它比如“改用 requests 而不是 httpx”“结果里再加一个 url 字段”。这种边做边改的体验比传统的“把需求写完整再让工具执行”舒服很多。交互模式里还有几个实用快捷键CtrlC可以中断当前任务CtrlD退出 Codex输入exit也能退出。如果你不确定当前有哪些模型可用输入/model会列出账号支持的模型列表这个功能在排查模型报错时特别有用。4.2 非交互模式codex exec 批量执行如果每次都要进入交互模式那自动化就无从谈起了。Codex 提供了exec子命令可以在命令行直接指定任务执行完自动退出codex exec 给当前项目补充一个 README.md包含安装和运行说明这个模式下Codex 会在后台自动执行任务不会跟你反复确认适合你已经信任的目录或在 CI 脚本里使用。我平时最常用的几个参数是codex exec --sandbox workspace-write 修复 tests 目录下的失败用例 codex exec --skip-git-repo-check 检查当前目录里的 Python 文件风格--sandbox用来控制权限范围workspace-write表示只允许改动当前工作区--skip-git-repo-check用在非 Git 仓库目录避免 Codex 反复提醒你初始化版本控制。执行完以后在命令后面加上-o参数可以把输出保存到文件方便写定时任务时留日志。4.3 配置文件 config.toml 的日常调整Codex 的配置集中在~/.codex/config.toml。拿文本编辑器打开这个文件你会看到类似下面的内容model gpt-5.2-codex model_provider openai sandbox_mode workspace-write这里的model是主模型决定 Codex 的推理质量。OpenAI 官方会不定期更新模型名如果你默认配置里的模型在你账号下不可用就改成当前可用的模型。sandbox_mode有三个常见值read-only只允许读取文件workspace-write允许修改当前工作区danger-full-access允许任意操作。新手建议保持workspace-write既够用又不会把系统搞乱。4.4 VS Code 里用 Codex边写边改如果你平时主要写代码我更推荐安装 VS Code 的 Codex 扩展。安装后在侧边栏会多出一个 Codex 面板你可以直接在里面输入任务也可以选中报错代码后右键选择让 Codex 处理。它能看到当前打开的项目文件理解上下文能力比纯命令行更好一些。实际使用中我习惯把 VS Code 扩展和 CLI 搭配起来日常小改动用扩展批量脚本任务用 CLI。两边共用配置后你会发现同一个项目里两个入口看到的模型、权限完全一致不会出现“这边能用那边不能”的情况。5. 国内进阶玩法把 Codex 接到 DeepSeek装好、登录好你已经在用 Codex 了。但对不少国内用户来说还有一个很现实的问题ChatGPT 账号的订阅和网络环境未必那么顺手。这时候有一条国内开发者很喜欢的路——把 Codex 的后台模型替换成 DeepSeek。Codex 本身支持自定义模型提供商接 DeepSeek 以后操作界面和流程不变但底层跑的是 DeepSeek 的模型成本更低国内访问也更顺畅。5.1 为什么要“换模型”其实很简单Codex 的核心价值是那套能自己调工具、改代码的 agent 机制它相当于一个“手脚灵活的躯体”。模型相当于大脑大脑可以选择不同的供应商。DeepSeek 是国产开源模型里综合能力很强的选手写代码、做重构、解释报错都不含糊而且 API 价格对个人开发者非常友好。所以对于国内个人开发者尤其是处于学习阶段的新手把 Codex 接到 DeepSeek 是一个兼顾体验和成本的方案。你不用完全依赖 OpenAI 的订阅也不用担心海外支付渠道的问题只要有一个 DeepSeek 的 API Key就能在同样的 Codex 操作流程里继续干活。5.2 修改 config.toml 接入 DeepSeek打开~/.codex/config.toml在文件里加入一个自定义 provider然后把默认模型指向它。我实际跑通的配置如下model deepseek-chat model_provider deepseek [model_providers.deepseek] name DeepSeek base_url https://api.deepseek.com/v1 env_key DEEPSEEK_API_KEY接着设置环境变量。macOS/Linux 在终端里执行export DEEPSEEK_API_KEYsk-你的密钥Windows PowerShell 用户执行$env:DEEPSEEK_API_KEYsk-你的密钥设置完以后重新启动 Codex再执行codex进入交互模式它就会用 DeepSeek 模型来响应。你可以随便问一句“用 Python 写一个二分查找”看看返回质量是否符合预期。如果你想把 DeepSeek 作为无条件默认模型就把model_provider openai改为model_provider deepseek。如果只是临时想切换不用改文件在执行命令时加参数codex exec --model-provider deepseek 解释这段代码5.3 接入 DeepSeek 后要注意什么接入过程虽然简单但有几个坑我得提前告诉你DeepSeek 的接口地址一定要写对base_url结尾是/v1不要漏掉否则认证会失败。不同模型的工具调用能力有差异。Codex 这类智能体非常依赖模型能不能正确调用工具如果你的 DeepSeek 模型版本太旧可能会出现“模型说了要做但迟迟不动手”的情况。遇到这种问题先升级到 DeepSeek 最新版模型。成本不要只看单次价格。DeepSeek 便宜但智能体会反复调用多次容易比你预期的 token 消耗更多。个人体验下来日常任务影响不大但如果让 Codex 全自动跑一个大型重构还是要留意账户余额变化。我用 DeepSeek 跑了快两个月的日常开发最大的体会是“作为默认模型非常够用”。一些小脚本、注释、单元测试DeepSeek 的处理速度和准确度都不错。遇到特别复杂的架构设计、跨模块重构我再手动切回 OpenAI 模型两边互补既省钱又不损失质量。6. 新手最容易掉进去的坑报错定位与处理方法最后这部分我把自己和身边同事实际踩过的坑整理成一个排查手册。Codex 本身迭代很快网上教程的配置可能早就过时了但排查思路是通用的。遇到问题不要一上来就重装先按下面的顺序定位。6.1 遇到 “cc switch local ... codex endpoint /responses” 的处理这是最近不少人问过的一个报错。现象是执行codex命令时日志里出现类似cc switch local ... failed while handling codex endpoint /responses的提示然后任务被迫中断。第一次遇到我也被绕晕过。拆开看前半段是 Codex 在启动时切换本地运行状态失败后半段是它去调用/responses接口时没有拿到预期响应。换句话说这不一定是 Codex 安装坏了而是它向外发请求时没有走通或者本地运行环境被什么东西干扰了。我的排查顺序是这样的完全退出 Codex 进程重新启动一次排除偶发状态残留。检查系统防火墙或安全软件看是否拦截了终端程序和 Codex 相关进程。Windows 自带的防火墙偶尔会误拦Mac 上则要检查是否有权限弹窗没被处理。查看 hosts 文件有没有被其他工具改成奇怪的条目。如果之前用过什么网络优化工具它篡改 hosts 后可能会让 Codex 的域名指向错误地址。换一个网络环境再试。比如从公司网络切到手机热点或者从 Wi-Fi 切到有线网络。很多内部网络会做访问控制导致 Codex 的服务端连接异常。重新执行codex login刷新登录凭证。按这个顺序处理大部分情况都能解决。真正需要重装 Codex 的情况反而很少。6.2 模型报错The gpt-5.6-sol model is not supported这个报错在切换模型后特别常见。官方原话是The gpt-5.6-sol model is not supported when using Codex with a ChatGPT acc意思是当前 ChatGPT 账号不支持使用gpt-5.6-sol这个模型。它跟安装无关纯粹是账号权限和模型名不匹配的问题。解决办法分两种情况。如果你用的是 ChatGPT 账号登录就在config.toml里把model改成账号确实支持的模型。不确定的话直接在交互模式里输入/model它会列出当前账号可用的模型列表照着列表选一个填进去就行。如果你用的是 API Key优先确认 Key 对应的组织是否有权限访问指定的模型。有些 Key 是从老项目里继承下来的模型权限可能被限制在很小的范围。这时候去后台生成一个新的 Key或者改用一个默认支持模型的名字再试。还有一种情况是官方更新了模型名旧教程里的名字已经下线。遇到这种问题直接去 Codex 官方文档或 changelog 里查最新的模型列表比我这里写的任何具体名字都靠谱。6.3 桌面版打开就白屏、闪退桌面版虽然对新手友好但偶尔也会抽风。我遇到过的原因无非这几类系统版本太旧。Codex 桌面版对 Windows 和 macOS 的最低版本有要求太老的操作系统跑不起来。缺少系统运行库。Windows 下常见的是 VC 运行库缺失去微软官网装最新的 Microsoft Visual C Redistributable 通常能解决。配置文件损坏。如果你之前用过旧版 Codex~/.codex目录里可能残留了不兼容的配置。先把config.toml备份一份然后把整个.codex目录改名成.codex.bak再重新登录试试。杀毒软件误杀。Windows Defender 或其他安全软件可能会把 Codex 的主程序当成可疑文件隔离需要到隔离区里恢复并加入信任名单。桌面版闪退还有一种可能就是磁盘空间不足。Codex 在运行时会写日志和临时文件空间满了就会出现各种奇怪行为。清理一下磁盘缓存再启动往往就好了。6.4 登录不上、登录后一直没反应登录流程卡住也是问得比较多的问题。这里有一个通用套路如果你点开登录链接以后页面一直转圈先换一个浏览器试试或者用无痕模式重新打开链接。浏览器插件广告拦截、脚本管理很容易干扰授权页面的跳转无痕模式能避开大部分插件问题。如果授权页能打开但回到终端发现还是没反映可以检查一下系统时间。别笑这个问题我真实遇到过。系统时间跟实际时间偏差过大时HTTPS 握手会失败登录请求自然无法完成。校准系统时间后重新登录即可。如果登录后提示OpenAI account is not allowed之类的错误基本可以确定是账号本身的权限问题需要检查当前账号是否有 Codex 使用权限。免费账号与付费账号在可用模型和功能上是有差异的申请一个对应套餐或换成 API Key 登录问题一般就能解决。6.5 高频问题速查表现象常见原因处理动作codex命令找不到npm 全局目录不在 PATH手动添加 npm 全局目录到系统 PATH安装过程卡住或超时npm 源访问慢切换 npm 国内镜像源后重试执行任务时一步一确认沙箱权限设置为逐次确认在 config.toml 中调整 sandbox_mode模型报 not supported模型与账号权限不匹配进入交互模式用/model选择可用模型桌面版启动白屏配置文件损坏或系统库缺失备份配置后重置.codex目录更新运行库登录授权后终端没反应浏览器插件或系统时间问题切无痕模式、校准系统时间后重新登录最后再分享一个个人习惯不管新装哪个版本我都会先在临时目录里跑一个完整的“从零创建项目”流程。这样既不污染正经代码库又能快速确认工具链是否真的通畅。“能跑通”和“看起来很能跑”之间差的往往就是这个最小实验。Codex 版本更新很快配置写法可能过一两个月就有变化但只要你掌握了排查思路以后遇到任何新报错都不会慌。
1. Codex 到底是什么先搞清楚它和聊天框的区别2026 年 9 月后台私信里问得最多的问题依然是 Codex 安装。其实这工具我已经在项目里用了大半年最近又帮两个完全没接触过命令行的同事从零开始把 Codex 装好并跑通了第一个任务。这篇就把完整过程写下来覆盖环境准备、CLI 和桌面版安装、登录、接入 DeepSeek以及我实际踩过的几个报错坑目标是让你照着敲一遍就能上手而不是看完一堆说明书然后原地发懵。在写安装命令之前我想先花两三分钟把 Codex 的定位说清楚。我见过太多人装完以后试了两句话就放下了原因不是工具不好用而是理解错了。Codex 不是一个网页版的 AI 写作助手它是 OpenAI 推出的编码智能体agent能直接在你电脑上读取文件、写文件、执行终端命令、运行测试。换句话说ChatGPT 网页版只负责“讲话”Codex 还会“动手”。后台那套运行逻辑大家通常叫它 agent harness它把一次编程任务拆成很多个小步骤自己判断下一步该读哪个文件、该跑哪条命令而不是像普通聊天窗口那样等你把上下文全部粘进去。1.1 它是怎么帮你干活的一个非常典型的场景你打开终端进入一个空目录输入codex然后说“帮我用 Python 写一个爬取博客文章列表的小脚本”它会先给你列一个简短计划然后开始建目录、安装依赖、创建文件、执行脚本。如果中途报错它会自己看错误日志再改代码再跑一遍。这个体验和“复制粘贴到 ChatGPT 里”完全是两回事因为你不再需要手动把每个文件内容粘进去Codex 自己掌握文件系统上下文。具体到能力边界Codex 大概能做这几类事读写项目里的文件新建、修改、删除都能触发在项目目录里执行终端命令比如npm test、python manage.py migrate调用外部工具链比如 Git、Docker、包管理器把多次尝试后的最终结果整理成清晰的改动说明。注意它不是你电脑上的万能遥控器。默认情况下Codex 的权限被限制在启动目录或你授权的 workspace 内不会随便去翻你桌面上的私人文件。这个限制后面会提到它是安全机制不是功能缺陷。1.2 2026 年的 Codex 常见形态现在 Codex 已经不止一个形态了。我建议你根据自己的操作习惯选一个主用入口其他的可以后面再补。下面这个表格是我个人理解的使用场景划分形态适合谁启动方式说明Codex CLI习惯终端操作、想写脚本自动化的人命令codex最核心的形态功能最完整Codex 桌面版不熟悉命令行、想开箱即用的新手双击桌面图标自带界面操作更直观VS Code 扩展主要写代码的人编辑器侧边栏不脱离 IDE边写边用我给你的建议是新手从桌面版起步但不要完全扔掉 CLI因为网上大部分教程、脚本、配置文件都是围绕 CLI 写的。你只要看得懂命令行后面排查问题会轻松很多。接下来就从环境准备开始一步一步走。2. 开工前的准备Node.js、Git、VS Code 一次装齐很多新手装 Codex 失败不是 Codex 本身的问题而是电脑里缺了依赖。Codex 安装虽然只有一条命令但它的运行环境涉及 Node.js 和 Git少一个都会在某个环节突然报错。所以我先带你把底座打好。2.1 先装 Node.jsCodex CLI 的运行底座Codex CLI 一般通过 npm 安装npm 是 Node.js 自带的包管理器所以第一步就是装 Node.js。到 Node.js 官网下载页选择 LTS 版本即可。LTS 意味着长期维护版本稳定性有保障不要贪新去下最新的 Current 版。Windows 用户选.msi安装包下载后双击一路下一步。安装路径尽量保持默认千万不要放到带中文或空格的目录里后面很容易出现路径解析问题。安装完成后打开一个新的终端窗口这一步很关键旧窗口不会自动刷新环境变量分别输入node -v npm -v能看到版本号输出说明 Node.js 装好了。如果提示node 不是内部或外部命令一般是 PATH 没生效。解决办法是重启终端或者手动把 Node.js 安装目录加到系统环境变量里。Windows 下默认安装路径通常是C:\Program Files\nodejs\把这个目录加到 Path 变量后重新打开终端即可。2.2 再装 Git很多自动化操作依赖它Codex 在克隆代码、查看 Git 状态、处理补丁时都会调用 Git。虽然你不一定直接用它但 Git 是底层依赖装好能省掉很多麻烦。Windows 用户去 Git 官网下载 Git for Windows安装时大部分配置保持默认。唯一要注意的是安装过程中有一个“Adjusting your PATH environment”的选项一定要选第二项Git from the command line and also from 3rd-party software。如果选了第一项Codex 在终端里可能找不到 Git 命令。装完后同样验证一下git --version能输出版本号就说明没问题。macOS 用户如果装了 Xcode Command Line Tools系统会自带 Git没装的话执行xcode-select --install即可。Linux 用户用各自发行版的包管理器安装比如sudo apt install git。2.3 顺手把 npm 源切成国内镜像这一步不是必须的但我建议每个国内用户都做。原因很简单npm 默认源在海外下载大一点的包时速度可能很慢甚至超时。国内有不少正规的 npm 镜像服务切换之后下载速度能快很多。把 npm 默认源切到国内镜像命令如下npm config set registry https://registry.npmmirror.com npm config get registry执行完第二条命令能返回刚才设置的地址说明切换成功。之后再用 npm 安装任何包都会走这个镜像。如果某一天安装 Codex 突然报 404很可能是镜像源还没来得及同步最新的 npm 包这时候切回官方源再装一次就行npm config set registry https://registry.npmjs.org3. 官方支持的安装方式我推荐你先用这一种环境准备好之后真正的主角终于登场了。Codex 官方提供了多种安装方式我按推荐程度从高到低排列你选一种适合自己的就行。3.1 方式一npm 全局安装 Codex CLI这是最常用、也最容易自动更新的方式。打开终端直接执行npm install -g openai/codex-g表示全局安装这样你在任何目录下都能直接使用codex命令。安装过程会输出一堆下载信息看到added字样基本就成功了。装完以后验证一下codex --version如果你看到版本号说明安装成功。如果提示codex 无法识别或command not found大概率是 npm 的全局安装目录不在系统的 PATH 里。Windows 下常见的全局目录是%APPDATA%\npmmacOS/Linux 下可能是/usr/local/bin或~/.npm-global。把这个目录加到 PATH 后重新打开终端即可。3.2 方式二Windows 桌面版安装Windows 用户如果不想碰命令行可以去 Codex 官网找到 Windows 桌面版下载入口下载安装包后双击安装。桌面版自带一套完整的运行环境不需要单独安装 Node.js对新手非常友好。安装完成后桌面上会有 Codex 的快捷方式。第一次打开会让你登录登录流程和 CLI 类似。这里有个小细节桌面版和 CLI 可以共存互不干扰。你完全可以在桌面版里写写简单的需求在 CLI 里跑自动化脚本两者共享同一个配置文件~/.codex/config.toml所以模型设置不会冲突。3.3 方式三macOS 使用 HomebrewmacOS 用户除了 npm 方式外也可以用 Homebrew 安装。如果你已经装了 Homebrew只需要执行brew install codex或者按官方文档添加适合当前版本的工具源。Homebrew 的好处是它会把相关依赖一起处理好升级也方便后续直接brew upgrade codex就能更新。Linux 用户同理可以去官方仓库查看对应的安装包但我个人还是建议 Linux 服务器上用 npm 方式因为更灵活也更容易配合 CI 流程。3.4 安装完成后最关键的一步登录认证安装只是第一步真正让 Codex 跑起来的是登录认证。运行codex login终端会显示一个链接和一个授权码。浏览器打开链接把授权码填进去选择用 ChatGPT 账号授权即可。授权成功后回到终端就能看到登录成功的提示。如果你习惯用 API Key也可以直接用下面的方式登录codex login --api-key然后粘贴你的 API Key。这里要区分一下两种认证方式的差别ChatGPT 账号登录走的是订阅套餐额度API Key 走的是按 token 计费。对于新手我建议先用 ChatGPT 账号体验跑通流程后再考虑 API Key。无论用哪种方式都要记住不要把 API Key 提交到 Git 仓库里尤其是公开仓库否则别人拿到你的 Key 就能随意调用接口产生不必要的费用。4. 上手实操跑通一次完整的编码任务登录成功后Codex 就算正式能用了。很多新手到这一步就卡住了因为不知道第一句话该说什么。别急我带你跑一个最经典的“用 Python 写爬虫”任务把交互式和非交互式的用法都过一遍。4.1 交互式命令行第一次对话找一个空目录打开终端进入这个目录然后输入codex几秒钟后你会进入一个交互式界面类似终端里的聊天窗口。输入帮我在当前目录下写一个 Python 爬虫抓取某个公开博客的文章标题和发布时间保存为 csv 文件Codex 会先列出一个执行计划然后开始创建文件、安装必要的依赖库。每一步执行前它会请求你的确认。这里新手容易紧张以为是不是出问题了。其实不是这是 Codex 的安全控制机制在执行会改变系统的命令前需要经过你同意。看到提示后按回车确认Codex 就会继续干活。整个过程中你可以随时输入新的要求打断它比如“改用 requests 而不是 httpx”“结果里再加一个 url 字段”。这种边做边改的体验比传统的“把需求写完整再让工具执行”舒服很多。交互模式里还有几个实用快捷键CtrlC可以中断当前任务CtrlD退出 Codex输入exit也能退出。如果你不确定当前有哪些模型可用输入/model会列出账号支持的模型列表这个功能在排查模型报错时特别有用。4.2 非交互模式codex exec 批量执行如果每次都要进入交互模式那自动化就无从谈起了。Codex 提供了exec子命令可以在命令行直接指定任务执行完自动退出codex exec 给当前项目补充一个 README.md包含安装和运行说明这个模式下Codex 会在后台自动执行任务不会跟你反复确认适合你已经信任的目录或在 CI 脚本里使用。我平时最常用的几个参数是codex exec --sandbox workspace-write 修复 tests 目录下的失败用例 codex exec --skip-git-repo-check 检查当前目录里的 Python 文件风格--sandbox用来控制权限范围workspace-write表示只允许改动当前工作区--skip-git-repo-check用在非 Git 仓库目录避免 Codex 反复提醒你初始化版本控制。执行完以后在命令后面加上-o参数可以把输出保存到文件方便写定时任务时留日志。4.3 配置文件 config.toml 的日常调整Codex 的配置集中在~/.codex/config.toml。拿文本编辑器打开这个文件你会看到类似下面的内容model gpt-5.2-codex model_provider openai sandbox_mode workspace-write这里的model是主模型决定 Codex 的推理质量。OpenAI 官方会不定期更新模型名如果你默认配置里的模型在你账号下不可用就改成当前可用的模型。sandbox_mode有三个常见值read-only只允许读取文件workspace-write允许修改当前工作区danger-full-access允许任意操作。新手建议保持workspace-write既够用又不会把系统搞乱。4.4 VS Code 里用 Codex边写边改如果你平时主要写代码我更推荐安装 VS Code 的 Codex 扩展。安装后在侧边栏会多出一个 Codex 面板你可以直接在里面输入任务也可以选中报错代码后右键选择让 Codex 处理。它能看到当前打开的项目文件理解上下文能力比纯命令行更好一些。实际使用中我习惯把 VS Code 扩展和 CLI 搭配起来日常小改动用扩展批量脚本任务用 CLI。两边共用配置后你会发现同一个项目里两个入口看到的模型、权限完全一致不会出现“这边能用那边不能”的情况。5. 国内进阶玩法把 Codex 接到 DeepSeek装好、登录好你已经在用 Codex 了。但对不少国内用户来说还有一个很现实的问题ChatGPT 账号的订阅和网络环境未必那么顺手。这时候有一条国内开发者很喜欢的路——把 Codex 的后台模型替换成 DeepSeek。Codex 本身支持自定义模型提供商接 DeepSeek 以后操作界面和流程不变但底层跑的是 DeepSeek 的模型成本更低国内访问也更顺畅。5.1 为什么要“换模型”其实很简单Codex 的核心价值是那套能自己调工具、改代码的 agent 机制它相当于一个“手脚灵活的躯体”。模型相当于大脑大脑可以选择不同的供应商。DeepSeek 是国产开源模型里综合能力很强的选手写代码、做重构、解释报错都不含糊而且 API 价格对个人开发者非常友好。所以对于国内个人开发者尤其是处于学习阶段的新手把 Codex 接到 DeepSeek 是一个兼顾体验和成本的方案。你不用完全依赖 OpenAI 的订阅也不用担心海外支付渠道的问题只要有一个 DeepSeek 的 API Key就能在同样的 Codex 操作流程里继续干活。5.2 修改 config.toml 接入 DeepSeek打开~/.codex/config.toml在文件里加入一个自定义 provider然后把默认模型指向它。我实际跑通的配置如下model deepseek-chat model_provider deepseek [model_providers.deepseek] name DeepSeek base_url https://api.deepseek.com/v1 env_key DEEPSEEK_API_KEY接着设置环境变量。macOS/Linux 在终端里执行export DEEPSEEK_API_KEYsk-你的密钥Windows PowerShell 用户执行$env:DEEPSEEK_API_KEYsk-你的密钥设置完以后重新启动 Codex再执行codex进入交互模式它就会用 DeepSeek 模型来响应。你可以随便问一句“用 Python 写一个二分查找”看看返回质量是否符合预期。如果你想把 DeepSeek 作为无条件默认模型就把model_provider openai改为model_provider deepseek。如果只是临时想切换不用改文件在执行命令时加参数codex exec --model-provider deepseek 解释这段代码5.3 接入 DeepSeek 后要注意什么接入过程虽然简单但有几个坑我得提前告诉你DeepSeek 的接口地址一定要写对base_url结尾是/v1不要漏掉否则认证会失败。不同模型的工具调用能力有差异。Codex 这类智能体非常依赖模型能不能正确调用工具如果你的 DeepSeek 模型版本太旧可能会出现“模型说了要做但迟迟不动手”的情况。遇到这种问题先升级到 DeepSeek 最新版模型。成本不要只看单次价格。DeepSeek 便宜但智能体会反复调用多次容易比你预期的 token 消耗更多。个人体验下来日常任务影响不大但如果让 Codex 全自动跑一个大型重构还是要留意账户余额变化。我用 DeepSeek 跑了快两个月的日常开发最大的体会是“作为默认模型非常够用”。一些小脚本、注释、单元测试DeepSeek 的处理速度和准确度都不错。遇到特别复杂的架构设计、跨模块重构我再手动切回 OpenAI 模型两边互补既省钱又不损失质量。6. 新手最容易掉进去的坑报错定位与处理方法最后这部分我把自己和身边同事实际踩过的坑整理成一个排查手册。Codex 本身迭代很快网上教程的配置可能早就过时了但排查思路是通用的。遇到问题不要一上来就重装先按下面的顺序定位。6.1 遇到 “cc switch local ... codex endpoint /responses” 的处理这是最近不少人问过的一个报错。现象是执行codex命令时日志里出现类似cc switch local ... failed while handling codex endpoint /responses的提示然后任务被迫中断。第一次遇到我也被绕晕过。拆开看前半段是 Codex 在启动时切换本地运行状态失败后半段是它去调用/responses接口时没有拿到预期响应。换句话说这不一定是 Codex 安装坏了而是它向外发请求时没有走通或者本地运行环境被什么东西干扰了。我的排查顺序是这样的完全退出 Codex 进程重新启动一次排除偶发状态残留。检查系统防火墙或安全软件看是否拦截了终端程序和 Codex 相关进程。Windows 自带的防火墙偶尔会误拦Mac 上则要检查是否有权限弹窗没被处理。查看 hosts 文件有没有被其他工具改成奇怪的条目。如果之前用过什么网络优化工具它篡改 hosts 后可能会让 Codex 的域名指向错误地址。换一个网络环境再试。比如从公司网络切到手机热点或者从 Wi-Fi 切到有线网络。很多内部网络会做访问控制导致 Codex 的服务端连接异常。重新执行codex login刷新登录凭证。按这个顺序处理大部分情况都能解决。真正需要重装 Codex 的情况反而很少。6.2 模型报错The gpt-5.6-sol model is not supported这个报错在切换模型后特别常见。官方原话是The gpt-5.6-sol model is not supported when using Codex with a ChatGPT acc意思是当前 ChatGPT 账号不支持使用gpt-5.6-sol这个模型。它跟安装无关纯粹是账号权限和模型名不匹配的问题。解决办法分两种情况。如果你用的是 ChatGPT 账号登录就在config.toml里把model改成账号确实支持的模型。不确定的话直接在交互模式里输入/model它会列出当前账号可用的模型列表照着列表选一个填进去就行。如果你用的是 API Key优先确认 Key 对应的组织是否有权限访问指定的模型。有些 Key 是从老项目里继承下来的模型权限可能被限制在很小的范围。这时候去后台生成一个新的 Key或者改用一个默认支持模型的名字再试。还有一种情况是官方更新了模型名旧教程里的名字已经下线。遇到这种问题直接去 Codex 官方文档或 changelog 里查最新的模型列表比我这里写的任何具体名字都靠谱。6.3 桌面版打开就白屏、闪退桌面版虽然对新手友好但偶尔也会抽风。我遇到过的原因无非这几类系统版本太旧。Codex 桌面版对 Windows 和 macOS 的最低版本有要求太老的操作系统跑不起来。缺少系统运行库。Windows 下常见的是 VC 运行库缺失去微软官网装最新的 Microsoft Visual C Redistributable 通常能解决。配置文件损坏。如果你之前用过旧版 Codex~/.codex目录里可能残留了不兼容的配置。先把config.toml备份一份然后把整个.codex目录改名成.codex.bak再重新登录试试。杀毒软件误杀。Windows Defender 或其他安全软件可能会把 Codex 的主程序当成可疑文件隔离需要到隔离区里恢复并加入信任名单。桌面版闪退还有一种可能就是磁盘空间不足。Codex 在运行时会写日志和临时文件空间满了就会出现各种奇怪行为。清理一下磁盘缓存再启动往往就好了。6.4 登录不上、登录后一直没反应登录流程卡住也是问得比较多的问题。这里有一个通用套路如果你点开登录链接以后页面一直转圈先换一个浏览器试试或者用无痕模式重新打开链接。浏览器插件广告拦截、脚本管理很容易干扰授权页面的跳转无痕模式能避开大部分插件问题。如果授权页能打开但回到终端发现还是没反映可以检查一下系统时间。别笑这个问题我真实遇到过。系统时间跟实际时间偏差过大时HTTPS 握手会失败登录请求自然无法完成。校准系统时间后重新登录即可。如果登录后提示OpenAI account is not allowed之类的错误基本可以确定是账号本身的权限问题需要检查当前账号是否有 Codex 使用权限。免费账号与付费账号在可用模型和功能上是有差异的申请一个对应套餐或换成 API Key 登录问题一般就能解决。6.5 高频问题速查表现象常见原因处理动作codex命令找不到npm 全局目录不在 PATH手动添加 npm 全局目录到系统 PATH安装过程卡住或超时npm 源访问慢切换 npm 国内镜像源后重试执行任务时一步一确认沙箱权限设置为逐次确认在 config.toml 中调整 sandbox_mode模型报 not supported模型与账号权限不匹配进入交互模式用/model选择可用模型桌面版启动白屏配置文件损坏或系统库缺失备份配置后重置.codex目录更新运行库登录授权后终端没反应浏览器插件或系统时间问题切无痕模式、校准系统时间后重新登录最后再分享一个个人习惯不管新装哪个版本我都会先在临时目录里跑一个完整的“从零创建项目”流程。这样既不污染正经代码库又能快速确认工具链是否真的通畅。“能跑通”和“看起来很能跑”之间差的往往就是这个最小实验。Codex 版本更新很快配置写法可能过一两个月就有变化但只要你掌握了排查思路以后遇到任何新报错都不会慌。
