装完 Codex CLI,第一句指令发出去就卡住:要么 command not found,要么提示还没认证。你以为工具装坏了,卸载重装三遍,问题还是原样。
CSDN 作者把这套终端 AI 代理从环境检查到配置排错完整走了一遍。他强调 Codex CLI 的核心能力是读写文件、执行命令、根据报错反复调修,跟单纯的代码补全不是一回事;工具装好不等于能用,认证、配置和权限任何一处没对,都跑不起来。(原文有删节)
先认清要装的是哪一个 Codex
「Codex」这个词被用得挺乱。早几年指的是补全代码的 Codex 模型,早就不作为单独产品维护;现在说的是 OpenAI 开源的 Codex CLI,一个跑在终端里的编码代理,macOS、Linux、Windows 都能装。两个东西名字一样,用法完全不同,不少安装问题就出在拿旧教程去装。版本号也不用背,这类工具两三周就发一版,把安装和更新方式搞清楚就行。
装之前先过四道检查
操作系统和终端先确认。macOS 和 Linux 最稳,Windows 上建议放进 WSL 里跑,伪终端和换行符的麻烦会少很多。走 npm 路线要确认 Node 版本够新。账号和 API Key 要准备好,它本身不包含本地模型,智能全靠云端接口。最后确认用户目录下的 .codex 目录可读写,很多「配置改了没生效」最后都查到了权限和路径上。

三条安装路线,按系统挑一条
macOS 有 Homebrew 就用 brew install codex,装完 codex –version 出版本号就算进 PATH。Linux 和 Windows 走 npm install -g @openai/codex,报 command not found 多半是 npm 的全局 bin 目录不在 PATH,用 npm prefix -g 看到路径再补进去。源码构建留给要改源码、追最新提交的人,普通使用没必要。

装完先认证,再跑一条最小任务
认证有两条路,codex login 走设备登录,适合 ChatGPT 订阅账号;codex login –api-key 直接把密钥写进本地配置,适合按量计费和脚本场景。认证完在 ~/.codex/config.toml 里对一遍模型和接口地址,不同版本字段名会变,别照抄老示例。权限策略从保守的只读或仅工作区可写开始,熟悉它的行为边界再放宽。
先别拿真实仓库开刀。建一个干净的小目录,放两三个小文件,跑一条最小任务:「列出当前目录下的文件,并告诉我每个文件的行数」。这一步同时验证认证有没有效、模型响应正不正常、终端界面显示对不对。这一步都过不了,别急着怀疑任务难度,回头查配置和网络。

报错别急着重装,按顺序看证据
作者给的顺序是,先看命令退出码和终端最后的错误信息,再看 ~/.codex 下的日志找堆栈,用最小任务复现排除任务描述的问题,确认版本和 Node 版本,确认目录权限和配置路径,最后再查认证、配额和网络。多数时候问题出在账号过期、路径权限这些外部条件上,重装十次也没用。
一分钟速查

常见问题
问:command not found 怎么处理?
答:多半是 PATH 没配好。npm 装完用 npm prefix -g 找到 bin 目录补进 PATH,再重开终端。
问:登录了还提示未认证?
答:查 ~/.codex 目录的权限和密钥所在的环境变量,配置路径不对也会这样。
问:任务跑一半中断了怎么办?
答:先看日志,能续跑就续跑,不能就把任务拆小,别整批重跑。
问:改了配置不生效?
答:确认它实际读的是哪个配置文件,改完再用一条最小任务验证一次。
来源与编译
本文转载自CSDN(weixin_28840143) 《2026最新版Codex CLI安装实战:从环境检查到配置排错全指南》,原文链接:https://blog.csdn.net/weixin_28840143/article/details/170676574。版权归原作者所有,如需删除请联系我们。