ORANGE BOOK · CODEX

第五章 安装 Codex

5.1 选择哪种形态

第二章讲过 Codex 有四种形态。这一章我们重点装两种：

  • 桌面版：普通用户首选，95% 的人装这个就够
  • CLI 版：进阶 / 程序员选这个，灵活又轻量

Web 版不需要安装（直接打开 chatgpt.com 就有）。GitHub Action 是配置不是安装（第十九章详讲）。

建议： 两个都装。它们用同一个账号，数据互通，但适合不同场景。

5.2 安装桌面版（macOS）

第 1 步：下载安装包

打开浏览器，访问：

https://chatgpt.com/codex/download

或者从 ChatGPT 网页里找到 Codex 入口，会有"下载桌面版"按钮。下载下来的是一个 Codex.dmg 文件。

第 2 步：拖进 Applications

双击打开 Codex.dmg，会弹出一个安装窗口。把 Codex 图标拖到右边的 Applications 文件夹图标上。

第 3 步：首次启动

打开 Launchpad，找到 Codex 图标，点击启动。

第一次启动会弹出 macOS 的安全提示："App 来自互联网，确定要打开吗？"——点"打开"。

第 4 步：登录账号

App 启动后会自动打开一个登录页面（在你的默认浏览器里）。

  • 点 "Sign in with ChatGPT"
  • 在浏览器里完成登录（用你的 ChatGPT Plus 账号）
  • 浏览器会提示"是否允许 Codex 访问？"，点"允许"
  • 浏览器会自动跳转回 Codex App

如果登录成功，你会看到 Codex 的主界面：左侧是项目列表，中间是对话区，右侧是 Task Sidebar。

第 5 步：授权权限

macOS 会弹出几个权限请求，全部允许：

  • 文件与文件夹访问（必需）
  • 辅助功能（如果你要用 Computer Use）
  • 屏幕录制（如果你要用 Computer Use）

如果你之前误点了"不允许"，可以去：系统设置 → 隐私与安全性 → 文件与文件夹里手动开启。

第 6 步：选择工作目录

主界面顶部会有一个"Open Folder"按钮，选你之前建好的 ~/codex-workspace/。

恭喜，Codex 桌面版安装完成。

5.3 安装桌面版（Windows）

Windows 版的步骤和 macOS 类似，但有几处差异：

第 1 步：下载

访问 https://chatgpt.com/codex/download，下载 Codex-Setup.exe。

第 2 步：安装

双击 .exe 文件，按引导一步步走：

  • 同意许可协议
  • 选择安装路径（默认就行）
  • 选择"为所有用户安装"还是"仅当前用户"
  • 等待安装完成

第 3 步：首次启动

从开始菜单或桌面快捷方式启动 Codex。Windows 可能会弹出 Defender 警告——点"更多信息" → "仍要运行"。

第 4 步：登录与授权

跟 macOS 完全一样。登录后，给 Codex 文件访问权限即可。

Windows 用户的额外注意

  • WSL 用户： 如果你想让 Codex 操作 WSL 里的文件，需要在 Codex 配置里指定 WSL 路径
  • 杀毒软件： 360、火绒等可能误报，加白名单即可
  • PowerShell vs CMD： Codex 默认用 PowerShell 执行命令，确保 PowerShell 版本 ≥ 7

5.4 安装 CLI 版

前置检查

打开终端（macOS：Terminal.app / Windows：PowerShell / Linux：bash），确认 Node.js 版本：

node --version

应该输出 v22.x.x 或更高。如果版本不够，回到 第四章 · 准备工作 装新版 Node。

一行命令安装

npm install -g @openai/codex

参数解释：

  • npm install：用 npm 包管理器装包
  • -g：装到全局，这样在哪儿都能用 codex 命令
  • @openai/codex：Codex 的官方 npm 包名

如果速度慢，加镜像：

npm install -g @openai/codex --registry=https://registry.npmmirror.com

如果报权限错误（Permission denied），可能需要 sudo：

sudo npm install -g @openai/codex

但更优雅的方式是配置 npm 用用户目录：

mkdir ~/.npm-global
npm config set prefix '~/.npm-global'
echo 'export PATH=~/.npm-global/bin:$PATH' >> ~/.zshrc  # 或 .bashrc
source ~/.zshrc

之后再 npm install -g @openai/codex 就不需要 sudo 了。

macOS 用户的另一个选择：Homebrew

brew install codex

Homebrew 会自动处理依赖和权限。

验证安装

codex --version

应该输出版本号，比如 0.42.0。如果提示 command not found，说明 PATH 没配置好，回去看上一步。

第一次启动

codex

第一次跑会自动打开浏览器，让你登录 ChatGPT 账号。流程跟桌面版一样：

  1. 浏览器跳到 OpenAI 登录页
  2. 用 Plus 账号登录
  3. 授权 Codex CLI
  4. 浏览器跳回，提示登录成功
  5. 终端里 Codex 进入交互模式

登录信息会保存在 ~/.codex/auth.json，下次启动不用再登录（除非过期）。

5.5 安装后的"健康检查"

不管你装的是桌面版还是 CLI 版，都跑下面这套"健康检查"，确保所有功能正常。

检查 1：基本对话

桌面版：在对话框输入 "Hi"，能正常回复。

CLI 版：

codex
> Hi

能正常回复。

检查 2：模型选择

CLI 输入 /model，应该能看到模型列表（包括 GPT-5.4、GPT-5.3-Codex 等）。

桌面版在设置里能看到模型选项。

检查 3：文件操作

让 Codex 创建一个测试文件：

在当前目录创建一个 hello.txt，内容是"Hello from Codex"。

它会请求授权，你批准。然后查看：

ls hello.txt
cat hello.txt   # 桌面版用 Finder 打开看

应该能看到文件。

检查 4：命令执行

让 Codex 跑一个简单命令：

帮我看看当前目录下有几个文件，按文件类型分类统计。

它会运行 ls 之类的命令，并请求授权。看到分类统计就成功。

检查 5：图片输入（CLI）

codex -i some_image.png "图里有什么"

能正确描述图片就成功。

检查 6：网络与延迟

简单聊几句，感受响应速度。如果每次回复都要等 30 秒以上，说明网络有问题，回 第四章 · 准备工作 排查代理。

5.6 一些初次启动会遇到的小坑

坑 1：登录跳不回 App

现象：浏览器登录成功了，但 Codex App 里还是"等待登录..."。

解决：

  • macOS：检查浏览器是不是 Safari，有时候 Safari 不会触发跳转。换 Chrome 试试。
  • Windows：浏览器跳转协议没注册，重启 App 一般能解决。
  • 实在不行：手动复制浏览器地址栏里的 token，粘贴回 App 输入框。

坑 2：Codex CLI 启动报错 "Cannot find module"

现象：codex 命令存在，但运行时报模块缺失。

解决：重新安装一遍：

npm uninstall -g @openai/codex
npm install -g @openai/codex

坑 3：网络 502 / 超时

现象：发指令后等很久，最后报错"网络错误"或"502"。

解决：

  • 检查代理是否开启
  • 检查 HTTPS_PROXY 环境变量
  • 切换代理节点（推荐 OpenAI 友好的节点：日本、台湾、新加坡）
  • 检查 OpenAI 是否在维护：status.openai.com

坑 4：拖文件进对话框没反应

现象：拖一个 PDF 进 Codex 对话框，没反应。

解决：按住 Shift 再拖。这是 macOS 的权限模型导致的，不是 bug。

坑 5：磁盘权限警告

现象：Codex 跑某个命令时报"权限不足"。

解决：

  • macOS：系统设置 → 隐私与安全性 → 完全磁盘访问，添加 Codex
  • Windows：右键 Codex → 属性 → 兼容性 → 以管理员身份运行（仅在必要时）

5.7 升级 Codex

Codex 更新很频繁（每两周一个版本是常态）。升级方法：

桌面版升级

App 启动时会自动检查更新，弹出提示后点"立即更新"。

也可以手动：菜单栏 → Codex → Check for Updates。

CLI 版升级

npm update -g @openai/codex

或者完全重装：

npm uninstall -g @openai/codex
npm install -g @openai/codex

升级后跑 codex --version 确认版本变了。

怎么知道有没有重要更新

关注：

5.8 卸载

如果哪天你不想用了：

桌面版（macOS）： 把 Codex.app 拖到废纸篓，再删掉 ~/Library/Application Support/Codex 和 ~/.codex/。

桌面版（Windows）： 控制面板 → 程序卸载 → Codex。

CLI 版：

npm uninstall -g @openai/codex
rm -rf ~/.codex

5.9 本章小结

  • 桌面版安装：下载 dmg/exe → 拖进 Applications → 启动登录 → 授权权限
  • CLI 版安装：npm install -g @openai/codex → codex → 浏览器登录
  • 装完跑 6 项健康检查
  • 常见坑：登录跳转、模块缺失、网络 502、Shift 拖文件
  • 定期升级，关注 Changelog

环境就绪，下一章我们正式开聊：第六章 · 第一次对话。