/* MD / 富文本中的 .toc（含博客园搬家等嵌套结构）；.toc-box 在侧栏，不受影响 */
#content_views .toc,
/* 编辑器常在目录前后插入空 p（:empty 仍占 20px），一并去掉避免顶空隙 */
#content_views.markdown_views > p:empty:has(+ .toc),
#content_views.markdown_views > .toc + p:empty,
/* 富文本旧版目录标记 */
#content_views.htmledit_views #main-toc,
#content_views.htmledit_views #hr-toc,
#content_views.htmledit_views p[id*=\”-toc\”] {
display: none !important;
}
/* 目录去掉后，紧跟的首个标题不再多出一块上边距 */
#content_views.markdown_views > .toc + h1,
#content_views.markdown_views > .toc + h2,
#content_views.markdown_views > .toc + h3,
#content_views.markdown_views > .toc + h4,
#content_views.markdown_views > .toc + p:empty + h1,
#content_views.markdown_views > .toc + p:empty + h2,
#content_views.markdown_views > .toc + p:empty + h3,
#content_views.markdown_views > .toc + p:empty + h4 {
margin-top: 0 !important;
}
最近好几个朋友都在问 Codex 怎么下载、怎么登录，尤其是 Windows 和 macOS 上的桌面版，装完一堆报错。正好我前后在 Windows 和 macOS 两台机器上从零装过 Codex，也帮同事处理过 Linux 上的一些问题，把完整的下载、安装、登录流程和踩坑记录整理成这篇东西。不管你是用 npm 装 CLI，还是下载桌面版，或者想在国产 Linux 发行版上跑，这篇都能直接照着做。先说结论：Codex 的安装本身不难，难的是三件事——环境依赖、登录认证、路径配置。这篇文章的核心价值就是把这三件事讲透，顺便把你大概率会撞上的几个报错提前排掉。
1. Codex 不是套壳工具：先搞懂它到底怎么工作
1.1 从 ChatGPT 的模型名到独立编程代理
Codex 这个名字很多人不陌生，ChatGPT 早期版本里专门负责写代码的那个模型就叫 Codex。当时它被嵌在聊天窗口里，你只能通过对话框让它生成代码片段，本质上还是一个“对话式补全”工具。2025 年 OpenAI 把它拆出来，做成了一个独立的编程代理（agent），彻底改变了用法。
怎么理解“编程代理”和“补全插件”的区别？用 GitHub Copilot 举例，你写代码时它会根据上下文自动补下一段，核心是你还在主导开发，它负责加速打字。而 Codex 的玩法反过来了：你给它一个自然语言任务，比如“帮我修复这个仓库里所有未处理的 Promise 异常”，它会自己打开项目文件、分析代码、修改多处需要改的地方，然后跑测试验证结果。中间每一步你都可以介入、叫停、调整方向。这就像你从“请了一个会打字的助理”换成了“请了一个能独当一面的实习生”——需要盯着，但很多体力活真能甩给它。
对比下来我个人的体会是：日常写 CRUD 或者算法题，Copilot 类工具够用；但如果是重构老项目、批量改 bug、跨文件追踪调用链，Codex 这种 agent 形态明显效率更高。它不再是一个“提示词放大器”，而是一个能自主执行任务的工作流工具。
1.2 CLI 和桌面版到底是什么关系
Codex 现在主要有两个形态：命令行工具（CLI）和桌面版（Desktop）。
CLI 是通过 npm 安装的 @openai/codex 包，装完在终端里敲 codex 就能交互。这是 Codex 的“底座”，也是功能最完整、更新最快的形态。桌面版则是官方推出的图形界面应用，把 CLI 的能力包了一层 GUI，方便不习惯用命令行的用户。
这里藏着 90% 报错的根源： 桌面版并不是一个完全独立的 App，它在底层还是要调用 CLI 的二进制文件 。所以你装完桌面版，会发现设置里有一个“Codex CLI Path”或者“codex_cli_path”选项。如果系统里没有 CLI，或者桌面版找不到它，就会报那个经典的错误：
unable to locate the codex cli binary. set codex cli path or ensure the elec…
看清楚这个报错的逻辑链条，你就知道解决方案不是上网乱搜“神秘补丁”，而是二选一：要么先把 CLI 装好，要么手动在桌面版设置里指定 CLI 路径。理解了这一点，后面第 5 章的排查思路就顺理成章了。
2. 装之前必须处理的三平台环境差异
2.1 Windows：PowerShell 执行策略与 npm 全局路径
Windows 上装 Codex 的坑，大部分不在 Codex 本身，而在 Node.js 环境。
第一个坎是 Node.js 版本。Codex 官方要求 Node.js 18 及以上，我建议直接装 20 LTS，目前最稳。去 nodejs.org 下载安装包一路 Next 就行，装完在 PowerShell 里验证：
node -v
npm -v
第二个坎是 PowerShell 执行策略。npm 全局安装的 CLI 会生成一个 .ps1 脚本，而 Windows 默认禁止运行 PowerShell 脚本，你敲 codex 会直接被拦下来，报红字错误。解决办法是以管理员身份打开 PowerShell，给当前用户放开脚本执行权限：
Set-ExecutionPolicy RemoteSigned -Scope CurrentUser
RemoteSigned 表示本地脚本可以运行，从网上下载的脚本需要签名，这是个人开发机比较合适的策略，不要用 Unrestricted 。
第三个坎是 npm 全局路径。Windows 上 npm 全局包的安装目录是 %APPDATA%\\npm ，如果安装时没自动加入 PATH，你装完 Codex 敲 codex 会提示“不是内部或外部命令”。手动把下面的路径加到系统环境变量 PATH 里：
%APPDATA%\\npm
添加到 PATH 后记得重开终端，环境变量才会生效。还有个小建议：如果你平时主力用 WSL 开发，不如直接在 WSL 里面装 Codex，走 Linux 的流程，能少踩很多 Windows 特有的坑。WSL 里跑 Codex 也是官方推荐的方式之一，命令访问和文件系统的兼容性好不少。
