如果你和我一样在 Windows 命令行里装完 Codex 后发现codex --version能正常输出版本号、真正跑任务时却各种报错那这篇就是给你准备的。我最近把 Codex 从第一次安装到日常使用的完整流程重新走了一遍原以为几分钟就能搞定结果在终端类型、登录认证、模型配置这几个环节反复踩坑。这篇快速入门的第二篇专门讲命令行安装与使用适合已经知道 Codex 是干什么、正准备动手装的人也适合装了一半卡住的人拿来对照排查。1. 先从命令行认识 Codex它能替你干到什么程度1.1 它和聊天式 AI 的根本区别很多人第一次打开 Codex 会困惑这不就是一个终端里的 ChatGPT 吗还真不是。Codex 是 OpenAI 出的 agent 型编程工具它拿到你的自然语言任务之后会真的去读你项目里的文件、搜索代码、做修改然后执行命令、查看运行结果再根据结果决定下一步做什么。打个比方普通聊天 AI 是你问它答Codex 更像是坐在你工位旁边的一个实习生你说帮我把这个模块的错误处理补上它会先打开项目看结构、定位相关文件、动手改代码、跑测试然后把结果汇报给你。这个动手闭环是它和聊天式工具最本质的区别。也正因为如此Codex 适合用来处理那些说起来简单、做起来繁琐的重复性任务批量重命名、补测试用例、重构旧接口、写迁移脚本、解释陌生项目结构。它不适合完全放手做架构决策至少现阶段还不建议。1.2 为什么入门阶段先死磕命令行Codex 现在已经提供了桌面版应用界面更友好看起来似乎更适合新手。但我建议入门阶段优先把命令行版本用熟原因有三点。第一CLI 跨平台行为一致。我在 Windows 和 Linux 上分别用过CLI 的核心命令几乎没有差别桌面版在某些系统上反而存在安装路径、权限之类的问题。第二CLI 更容易脚本化。你可以把常用任务写成一个 npm script 或者批处理一键执行桌面版做这类自动化就麻烦得多。第三远程服务器上只有命令行。如果你要在一台云主机或者开发机上跑任务桌面版是没有用的Install CLI 是唯一选择。这篇的定位是快速入门第二篇命令行安装与使用所以我默认你已经知道 Codex 是什么了。接下来的内容全是我自己实操过的流程和踩过的坑尽量给完整步骤。2. 安装前的环境检查清单Node 版本、终端类型与常见假象2.1 Node.js 版本与 npm 源最常见的隐形坑Codex CLI 是基于 Node.js 分发的安装前必须先确认 Node 环境。官方要求 Node.js 18 及以上但我实测下来18.x老版本偶尔会在某些依赖上出问题建议直接装 20 LTS 或者 22 LTS省心很多。在命令行里先看一下版本node --version npm --version如果提示找不到命令说明 Node 还没装或者没加到 PATH。Windows 用户可以直接去 Node 官网下载 LTS 安装包一路下一步即可。macOS 用户建议用 nvm 管理多版本这个后面排查问题更方便。npm 源这个问题在部分网络环境下非常致命。很多人执行npm install -g openai/codex之后进度条卡在那里一动不动等十几分钟最后报错安装未完成。绝大多数情况下不是 Codex 本身的问题而是默认 npm 源在这网络环境下不稳定。解决办法是把 npm 源切到国内镜像npm config set registry https://registry.npmmirror.com设置完之后再次安装速度会有质的提升。这个操作只影响 npm 包下载不影响 Codex 运行。2.2 Windows 终端差异能输出版本号不代表能正常跑有一个非常典型的现象搜索相关词条里出现过在 Windows 命令行里装了 Codex CLIcodex --version也能看到版本号但换到 Windows Terminal 里运行就直接报错或者闪退。我一开始也遇到过当时差点以为是安装包坏了。后来逐个排查发现问题根本不在 Codex而在 Windows 的终端环境差异。Windows 下至少有四种常见环境CMD、Windows PowerShell、PowerShell 7、Git Bash。Codex CLI 本质是一个 Node.js 脚本理论上在这些环境里都能跑但表现差异很大。最常见的几个坑PATH 没刷新安装完 Codex 之后如果你是在已有的命令行窗口里执行codex很可能提示找不到命令。这不是安装失败而是 PATH 环境变量没刷新。关掉当前窗口重新开一个终端再试。执行策略限制Windows PowerShell 默认的执行策略可能阻止某些脚本运行。可以检查一下执行策略设置必要时调整为RemoteSignedGet-ExecutionPolicy Set-ExecutionPolicy -Scope CurrentUser RemoteSigned终端编码问题Windows 老版本终端默认编码不是 UTF-8Codex 的输出会显示成乱码。Windows Terminal 里可以在设置中把默认编码切到 UTF-8能解决大部分显示问题。所以我的建议是Windows 用户直接统一用Windows Terminal PowerShell 7这个组合。Windows Terminal 从微软商店装PowerShell 7 从 GitHub 或商店装两个都是免费的装完之后使用体验和 macOS 的终端差距很小。2.3 安装未完成与打不开的初步判断另外很多人在 Windows 上遇到安装未完成或者codex 打不开的问题。先说结论如果codex --version有输出Codex 本体就装好了打不开大概率是运行环境或配置问题如果版本号都出不来才是安装本身出了问题。安装中断导致的半成品状态处理办法是清理掉缓存和残留文件然后重装npm cache clean --force npm uninstall -g openai/codex npm install -g openai/codex清理时注意全局 node_modules 目录是否还有残留。Windows 下一般在%APPDATA%\npm\node_modules\openai\codex确认删干净再重装。这些步骤做完90% 的安装问题都能解决。3. npm 安装与桌面版路线两条路我都跑了一遍3.1 npm 全局安装与验证环境确认没问题之后安装其实就一条命令npm install -g openai/codex安装过程会拉取不少依赖所以前面才强调先把 npm 源切好。装完之后执行codex --version能看到版本号就说明核心安装成功。如果你需要升级到最新版和装的时候一样也是先卸载再装或者直接用 npm 的 alias 方式覆盖升级npm install -g openai/codexlatest卸载的话就一条命令npm uninstall -g openai/codex注意装完之后如果codex命令找不到除了刷新 PATH也可以手动看一下全局 bin 目录是否在 PATH 里。Windows 下 npm 全局 bin 通常是%APPDATA%\npm把它加进系统 PATH 即可。3.2 桌面版与 CLI 的取舍我在安装过程中也试过 Windows 桌面版。桌面版的优点是对新手友好提供图形界面安装时会把 Node 环境一并处理掉省去很多前置配置。而且现在 Codex 桌面版是集成在 ChatGPT 桌面应用里的使用上更像一个 AI 编程助手适合不想折腾命令行的用户。但如果你打算长期用、要跑自动化、要在服务器上用CLI 依然是绕不开的。而且桌面版和 CLI 共用同一套认证和配置文件项目级配置两边都能读到所以不存在选了某个就锁死的问题。我的建议是新手可以先用桌面版跑通第一个任务找回信心之后再切到 CLI体验更自由。3.3 首次运行与沙箱概念安装完成后第一次运行codex会进入登录引导。登录相关问题我放在下一节详细说这里先解释一个新手最容易懵的概念沙箱模式。Codex 默认在一个受限环境里执行操作目的是防止它乱改你系统里的文件。它有如下几种权限级别read-only只能读文件不能做任何修改适合让它先做项目分析。workspace-write可以修改当前工作目录内的文件但不能碰工作目录之外的东西这是日常使用的默认推荐级别。danger-full-access完全放开Codex 可以执行任何命令、修改任何文件只在你有把握时才建议使用。首次运行时如果你不确定它要做什么先让它用只读模式分析代码确认它理解的上下文是对的再放开写入权限。这个习惯能帮你避免它胡改文件。4. 登录认证与模型配置卡住大多数人的地方4.1 codex login 的完整流程与 token 位置Codex CLI 安装完必须先登录才能使用。登录方式很简单codex login它会生成一个验证码并打开浏览器你只需要在页面上确认授权即可。如果你是在远程服务器或者没有图形界面的环境登录可以用设备码模式codex login --device-code它会给你一个 URL 和代码在任意一台电脑的浏览器打开网址、输入代码就能完成授权。登录成功之后凭证会保存在家目录的.codex文件夹里文件名是auth.json。Windows 下位置是C:\Users\你的用户名\.codex\auth.jsonmacOS/Linux 下是~/.codex/auth.json。我遇到过的 codex auth token is unavailable 报错基本上就是由两种情况触发的一种是auth.json文件被删除、损坏或权限不对另一种是你改了配置文件里的 provider导致 Codex 不知道该用哪套令牌。处理办法也很直接删掉旧的auth.json或者备份一份到别处重新执行codex login。排查的时候先确认文件存在且内容非空再确认 config.toml 里没有错误地指向一个需要额外env_key的 provider。如果文件都在试着删除重登基本都能恢复。4.2 第三方模型接入以 DeepSeek 为例的 OpenAI 兼容配置很多人在热搜里搜codex 接入 deepseek说明大家已经不满足于只用一个模型了。Codex 的配置机制支持接入任何 OpenAI 兼容的模型服务DeepSeek 就是很典型的一个。配置文件位置也是在.codex目录下主配置文件叫config.toml。用户级配置路径为~/.codex/config.toml如果你只想针对某个项目配置可以放在项目根目录的.codex/config.toml。下面是我实际跑通过的 DeepSeek 接入配置model deepseek-chat model_provider deepseek [model_providers.deepseek] name DeepSeek base_url https://api.deepseek.com env_key DEEPSEEK_API_KEY把这段内容写到~/.codex/config.toml之后还需要配置环境变量DEEPSEEK_API_KEY。在终端里临时设置export DEEPSEEK_API_KEY你的keyWindows PowerShell 对应的写法是$env:DEEPSEEK_API_KEY 你的key也可以把 key 写进环境变量永久保留但我建议不要硬编码在配置文件里。配置里的env_key字段指定了 Codex 从哪个环境变量读取 API key这样既安全又灵活。改完配置后重启 Codex 进程再执行任务就会走 DeepSeek 的接口了。这里要特别提醒一个点不同的模型服务支持的模型名不一样接口兼容性也有细微差别。如果配置完发现报错说模型不存在或者参数不支持先去服务商的文档确认模型名和 OpenAI 兼容接口地址这个排查思路在所有第三方接入里都通用。4.3 模型不支持的报错与中文输入设置热搜里有一个很具体的报错the gpt-5.6-sol model is not supported when using codex with a...。这类问题的本质是模型名和当前 provider 不匹配或者你配置的模型名并没有在你当前账号/服务商的可选范围内。处理思路就是检查 config.toml 里的model字段把它改成当前 provider 实际支持的模型名改完重启验证。关于中文设置这也是很多人问的。Codex 本身没有中文界面这种设置项但你可以通过项目约定文件让它用中文回复你、用中文写注释。Codex 会读取项目根目录下的AGENTS.md文件作为操作约定这个文件类似给 Codex 的工作手册。我在项目里通常这样写# 项目约定 - 所有回复请使用中文 - 代码注释使用中文但保留英文术语 - 不要修改 src/legacy 目录下的任何文件 - 提交信息使用英文遵循 Conventional Commits 规范把这份AGENTS.md放到项目根目录Codex 每次在这个项目里工作时都会自动读取并遵循里面的约定。如果你想让它全局都这样可以把AGENTS.md放到家目录的.codex文件夹下作为全局约定。用这种方式解决中文回复问题比在每次对话里重复强调要靠谱得多。5. 日常高频使用路径交互会话、exec 模式与沙箱策略5.1 交互模式从提问到执行安装登录配置完成之后日常使用最直接的方式是交互模式。在项目目录里直接运行codex它会以当前目录作为工作目录启动一个交互会话。你可以像跟同事沟通一样描述你要做的事情。我第一次跑通时让它做一个真实的项目分析指令是帮我看看这个项目整体的模块划分以及 controllers 目录下有没有明显重复代码。 Codex 先是以只读方式定位相关文件然后给我列出模块结构和重复代码位置最后还给出了重构建议。整个过程不需要我手动打开任何文件。交互模式下还有一些内置命令输入/就能看到/status查看当前会话的上下文和文件读取情况/cost查看这次会话的 token 消耗/quit结束会话这里有一个习惯上的建议别在交互会话里混着聊不相关的事情。Codex 是 agent 架构它的上下文窗口会被待处理的代码占满你如果一会儿让它改代码、一会儿问它天气它很容易丢失关键上下文。最好是每个会话聚焦一个任务任务做完就/quit有新的任务再开新会话。5.2 exec 模式一条命令跑完整个任务如果说交互模式是边聊边做exec 模式就是一句话派活。它的基本用法是codex exec 要完成的任务描述比如codex exec 把 README.md 里所有过时的安装命令替换成最新版本exec 模式适合在自动化脚本、CI 流程里使用。我常用的几个关键参数--full-auto让 Codex 不需要每一步都确认跑完整个任务。适合你有把握的场景但不要在未受版本控制的项目里贸然使用。-C 目录指定要操作的项目目录不需要先 cd 进去。--model 模型名临时指定模型优先级高于 config.toml 里的配置。--sandbox 级别指定沙箱级别比如临时用只读模式做代码分析。--skip-git-repo-check默认 Codex 希望你在 git 仓库里运行跳过这个检查可以在非 git 目录里用。举一个组合使用的例子我想让 Codex 在/data/project目录下用 DeepSeek 模型全自动补齐缺失的 JSDoc 注释codex exec -C /data/project --model deepseek-chat --full-auto 给 src 目录下所有缺失的 JSDoc 注释补齐5.3 让 Codex 记住项目约定AGENTS.md 的更多用法前面提到了用AGENTS.md让 Codex 说中文但这只是它能力的一小部分。实际上你可以把它理解为一个项目通行规范的文件里面可以写任何你希望 Codex 在动代码之前知道的信息。我见过比较实用的写法还有# 代码规范 - TypeScript 优先不要新写任何 JavaScript 文件 - 组件命名使用 PascalCase - 所有 API 请求必须走统一的 request 工具函数 # 禁止事项 - 不要格式化整个文件只修改你负责的部分 - 不要改动 test/fixtures 里的任何 fixture 数据 # 测试 - 修改代码后必须运行对应的单测 - 单测运行命令npm run test -- --run需要注意的是AGENTS.md只是给 Codex 的强建议不是一把锁。它仍然可能在某些边缘情况下做出超出约定的行为。所以越是重要的项目越要配合沙箱模式来约束它的实际动作。6. 实测中反复出现的报错与排查思路6.1 cc switch local proxy failed while handling codex endpoint切换配置留下的历史问题这个报错在热搜里出现的频率很高我的评价是它和 Codex 本身关系不大纯粹是配置管理工具改坏了你的配置。用 CC Switch 这类第三方便捷切换工具管理多个模型供应商时它会把 Codex 的config.toml里的base_url改写成它自己管理的本地服务地址。正常状态下这个本地服务会自动启动请求会被转发到你实际使用的模型供应商。但如果这个本地服务没有正常运行或者服务地址残留成了上一次的值Codex 就会报出 local proxy failed while handling codex endpoint。排查思路很明确如果之前用过 CC Switch 之类的工具先打开.codex/config.toml看一眼当前model_providers里的base_url指向的是什么地址。如果你确定要回到官方默认服务把model_provider和base_url改回官方默认值即可。如果本地服务本身是你需要保留的那就去确认那个服务是否启动了端口是否和配置一致。改完配置重启 Codex 进程让它重新加载配置文件。我这里强调一下这个报错是配置层面的地址错误和你机器上的网络通道没有任何关系。不用去做任何额外操作把配置理顺就能解决。6.2 网络相关连接中断、正在重新连接使用 Codex 过程中我偶尔会看到界面提示正在重新连接或者 connection interrupted。出现这类提示常见原因有三个长时间没有操作会话超时服务端响应慢或限流任务本身太大单次请求处理时间过长导致连接被中断处理建议按优先级排列先检查是不是任务太复杂拆成小步骤再执行然后排查服务端是否限流可以间隔几分钟再试最后确认你自己机器的网络稳定性避免在弱网环境下跑大任务。如果同一个大任务反复中断我的经验是换一个思路先让 Codex 只读分析出方案并输出到文件你检查方案确认无误之后再分步执行修改。这样既减少单次连接时长也降低了误改风险。别硬扛着反复重试同一个大任务浪费时间还可能把上下文搞乱。6.3 Windows 下运行 codex 的其他玄学问题汇总最后把我在 Windows 上遇到过的其他情况一次性列出来做成一个对照表方便你排查现象常见原因处理思路codex提示找不到命令PATH 未刷新或全局 bin 不在 PATH 中重开终端检查%APPDATA%\npm是否在 PATHWindows Terminal 里输出乱码终端编码不是 UTF-8Windows Terminal 设置里切换默认编码为 UTF-8能查看版本但启动闪退PowerShell 执行策略限制设置执行策略为 RemoteSigned重开终端输入中文变成问号/乱码Windows Terminal 字体不支持中文切换终端字体到 Cascadia Mono 或 Nerd Font安装过程卡住npm 源不稳定切换 npmmirror 镜像源后重装有一个容易被忽略的细节Windows Terminal 默认字体如果不对中文输入和显示会是另一种乱码不是编码问题而是字体缺字。早期我在这里浪费了不少时间。现在我的固定组合是 Windows Terminal Cascadia Mono中文显示和英文对齐都正常即使有 emoji 显示成方框也不用太在意不影响操作。另外一个玄学来自 Codex 桌面版和 CLI 共存的场景。如果你两个都装了有时候 CLI 行为异常会让人误以为是 CLI 的问题其实是桌面版在后台占用了同一个配置文件句柄或者改写了配置。遇到诡异行为时先把桌面版退出再试 CLI大概率就恢复正常了。收尾的一点实际操作体会我用了这段时间 Codex 之后最大的感受是它确实能干活但你需要给它一个清晰的边界。我的习惯是新任务一律先进沙箱让它分析确认它的理解和我的意图一致之后再放开写入权限而不是一上来就--full-auto。这个习惯帮我避免过很多次不必要的文件乱改尤其是接手陌生代码库的时候。另外AGENTS.md一定不要偷懒不写。我见过太多人抱怨 Codex不听话结果项目里一份约定文件都没有Codex 只能靠猜。你花十分钟把规范写清楚后面省下的是无数小时的对齐成本。最后建议把常用的 Codex 参数整理成项目里的 npm scripts 或批处理脚本比如npm run codex:review执行只读检查、npm run codex:fix -- 任务描述执行修复。让日常操作从敲一串命令变成记住一个 script 名字频率高了之后你会回来感谢这个习惯的。