Last updated: 2026-06-30

Last verified: 2026-06-30 against OpenAI Codex official docs and the current local Codex manual cache. Product surfaces, install commands, plan coverage, and account behavior can change; re-check the official docs before treating this as a permanent setup reference.

Official references checked:

  • Codex Quickstart: https://developers.openai.com/codex/quickstart
  • Codex app: https://developers.openai.com/codex/app
  • Codex IDE extension: https://developers.openai.com/codex/ide
  • Codex CLI: https://developers.openai.com/codex/cli
  • Codex Windows: https://developers.openai.com/codex/windows
  • Codex web / cloud: https://developers.openai.com/codex/cloud

OnlyPat 建站指南 is an independent site. This article is a personal setup guide, not official OpenAI documentation.

先说结论

安装 Codex 之前，先不要纠结“到底哪一种才是正统用法”。

Codex 现在更像一组入口：你可以在桌面 App 里用，可以在 IDE 侧边栏里用，可以在终端里用，也可以把任务交给云端跑。真正的问题不是“装哪个”，而是你在哪个环境里最容易把一个任务做完。

我的建议很简单：

  • 你是 Windows 用户，想稳定做本地项目：先装 Codex app。
  • 你每天写代码都在 VS Code、Cursor、Windsurf 或 JetBrains：装 IDE 扩展。
  • 你习惯终端、脚本、SSH、WSL 或命令行工作流：装 Codex CLI。
  • 你想让任务在后台跑、改 GitHub 仓库、最后开 PR：用 Codex web / cloud。
  • 你在 Windows 上做 Linux 项目：优先考虑 WSL2 + CLI 或 WSL 里的 IDE 远程窗口。

不要一上来全装。先选一个最贴近你日常工作的入口，跑通第一次真实任务，再决定要不要补第二个入口。

先用这张表选入口

你现在的工作方式 推荐入口 为什么
Windows 或 macOS 上有多个本地项目 Codex app 项目切换、并行线程、diff、Git 和插件入口更集中
主要在编辑器里写代码 IDE 扩展 能直接利用打开文件、选区和编辑器上下文
经常用终端处理项目 CLI 适合在当前目录里直接让 Codex 读文件、改文件、跑命令
Windows 上跑 Linux 工具链 WSL2 + CLI / IDE WSL Linux 环境和仓库都在 WSL 里，路径和依赖更一致
想让长任务后台跑 Codex web / cloud 云端环境执行，适合异步任务和 PR 流程
想把 Codex 接进自己的程序 SDK / 非交互模式 这是自动化和产品集成路线，不建议作为新手第一站

如果你只是想马上开始，我会选：Codex app 或 IDE 扩展。

如果你已经会用终端，而且知道项目在哪个目录，我会选：CLI。

如果你想在手机、浏览器或 GitHub 流程里发任务，我会选：Web / Cloud。

方法一：Codex app，适合大多数本地项目

Codex app 是最适合“我想认真用起来”的入口。

它的价值不是安装命令最短，而是把项目、线程、diff、Git、插件和本地执行集中在一个地方。你可以选择一个项目目录，让 Codex 在本机读取文件、修改文件、运行命令，然后在同一个界面里看结果。

适合这些人：

  • 你在 Windows 或 macOS 上维护多个项目；
  • 你希望 Codex 能并行处理几个任务；
  • 你想看清楚每次改了什么；
  • 你不想把所有操作都塞进终端；
  • 你想后续使用插件、浏览器、自动化、技能等能力。

基本步骤：

  1. 打开官方 Codex app 页面。
  2. 下载 Windows 或 macOS 版本。
  3. 安装后登录 ChatGPT 账号或 OpenAI API key。
  4. 选择一个项目文件夹。
  5. 确认当前任务跑在 Local，本地项目由你自己的机器执行。
  6. 发第一个小任务，例如“读一下这个项目结构，告诉我 README 和 AGENTS.md 里最重要的规则”。

Windows 上还有一个额外判断：你是要原生 Windows 环境，还是 WSL2。

如果你的项目就在 D:\Code\... 这种 Windows 路径下，先用原生 Windows。官方 Windows 文档说明 Codex 可以使用 Windows sandbox，并且有 elevated 和 unelevated 两种模式。正常情况下优先让它跑在更强的 sandbox 里。

如果你的项目依赖 Linux 工具链，或者仓库本来就在 WSL 里，就不要强行用 Windows 路径。把仓库放在 WSL 的 Linux home 目录里，例如 ~/code/my-app，再从 WSL 环境里打开项目。

方法二：IDE 扩展，适合边写边问

如果你每天大部分时间都在编辑器里，IDE 扩展会更顺手。

官方文档里，Codex IDE extension 支持 VS Code 以及一些 VS Code fork，比如 Cursor 和 Windsurf；也提供 JetBrains IDE 路线。安装后，它会出现在编辑器侧边栏，你可以在写代码时直接把当前文件、选区、打开的上下文交给 Codex。

适合这些人：

  • 你正在读一个函数，想让 Codex 解释它；
  • 你选中一段代码，让 Codex 帮你改；
  • 你想让 Codex 根据当前打开文件补测试；
  • 你希望在 IDE 里直接跟进云端任务；
  • 你不想频繁切到另一个 App。

基本步骤：

  1. 从官方 IDE extension 页面进入对应编辑器的安装入口。
  2. 在 VS Code、Cursor、Windsurf 或 JetBrains 里安装扩展。
  3. 重启编辑器或打开 Codex 侧边栏。
  4. 登录 ChatGPT 账号或 API key。
  5. 打开一个项目目录，先让 Codex 解释项目结构。
  6. 第一次任务尽量小，例如“只改这个组件的空状态文案，并运行构建”。

IDE 扩展最容易用错的地方，是你以为它自动知道所有项目背景。其实它最懂的是当前编辑器上下文：打开文件、选区、当前工作区。跨目录或跨仓库的规则，还是要靠 AGENTS.md、README 和明确提示词。

方法三：CLI，适合终端党和可复现工作流

CLI 是最直接、最工程化的入口。

官方 Quickstart 给了几种安装方式。macOS / Linux 可以用 standalone installer：

curl -fsSL https://chatgpt.com/codex/install.sh | sh

Windows PowerShell 可以用：

powershell -ExecutionPolicy ByPass -c "irm https://chatgpt.com/codex/install.ps1 | iex"

也可以用 npm 或 Homebrew：

npm install -g @openai/codex
brew install --cask codex

安装后进入项目目录运行：

codex

第一次运行会提示登录。登录后，你就可以在当前目录里让 Codex 读文件、修改文件、运行命令。

CLI 适合这些场景：

  • 你已经习惯 git status、npm test、rg、pytest 这种工作方式；
  • 你希望任务可以被脚本化；
  • 你经常在服务器、WSL 或远程环境里工作；
  • 你想把 Codex cloud 任务从终端里发出去；
  • 你希望每次都从一个明确目录开始。

CLI 的关键不是“装上就完事”，而是确认三个点：

codex --version
pwd
git status --short

你要知道自己正在用哪个 Codex、在哪个目录、当前 Git 状态是否干净。否则 Codex 可能会在你没意识到的目录里工作。

方法四：Windows 原生还是 WSL2

Windows 用户最容易卡在这里。

官方 Windows 文档给了三种实际运行方式：

  • 原生 Windows + elevated sandbox；
  • 原生 Windows + unelevated sandbox；
  • WSL2 里的 Linux 环境。

我的判断方式是：

如果你的项目是普通前端、Node、Python、Java、.NET 或 Windows 路径里的本地项目，先用原生 Windows。它更贴近你现有文件系统，打开项目也更直接。

如果你的项目强依赖 Linux 环境，比如 shell 脚本、Linux-only 依赖、容器工具链、路径大小写、软链接行为，优先用 WSL2。

WSL2 路线大致是：

wsl --install
wsl

进入 WSL 后：

mkdir -p ~/code
cd ~/code
git clone <your-repo>
cd <your-repo>
curl -fsSL https://chatgpt.com/codex/install.sh | sh
codex

不要把 Linux 项目长期放在 /mnt/c/... 里硬跑。官方文档也建议把仓库放在 Linux home 目录下，例如 ~/code/my-app，这样 I/O、权限、软链接和工具链会更稳定。

方法五：Codex web / cloud，适合后台任务

Web / Cloud 路线不一定要“安装”到本机，但要配置环境。

官方 Codex web 文档的核心思路是：进入 chatgpt.com/codex，连接 GitHub，让 Codex 在云端环境里处理仓库任务。云端任务会在容器里 checkout 你的仓库，执行 setup script，然后让 agent 修改代码、运行检查，最后给你 diff 或 PR。

适合这些场景：

  • 任务比较长，你不想一直开着本地线程；
  • 你想并行跑几个方案；
  • 你希望 Codex 直接围绕 GitHub 仓库工作；
  • 你想从浏览器或另一个设备发任务；
  • 你希望最后用 PR 方式审查变化。

不适合这些场景：

  • 你还没把代码推到 GitHub；
  • 你的项目依赖大量本机私有状态；
  • 任务需要操作你本地桌面软件；
  • 你没有配置 cloud environment；
  • 你需要立刻在本地看 UI 或跑只有本机才有的数据。

第一次配置 cloud，不要急着发大任务。先用一个只读任务测试环境：

请读取这个仓库，告诉我项目结构、主要构建命令、测试命令，以及你认为第一个安全的小任务是什么。不要改文件。

这样能先确认仓库、环境和 setup 是否能跑通。

方法六：SDK 和非交互模式，先别急

Codex 还有 SDK、非交互模式、GitHub Action 等更自动化的入口。

这些不是新手第一步，而是你已经知道自己要把 Codex 接到哪个流程里之后，再考虑的路线。比如：

  • 在内部工具里启动 Codex 线程；
  • 用脚本批量跑诊断任务；
  • 在 CI 或定时流程里触发检查；
  • 把 Codex 作为某个工程自动化系统的一环。

如果你只是想开始使用 Codex，先不要从 SDK 开始。先用 App、IDE 或 CLI 跑通人工可控的闭环，再把重复流程自动化。

第一次装完后，怎么确认真的能用

不要只看“安装成功”。

你应该做一个最小可验证任务：

请先只读当前项目，不要修改文件。
告诉我：
1. 这个项目是什么；
2. 主要源码目录在哪里；
3. 构建或测试命令是什么；
4. 如果我要做第一个小改动，最安全的入口是什么。

如果 Codex 能正确读出项目结构，说明它至少能访问工作区。

接着再做一个小改动：

请给 README 增加一行本地运行说明。只改 README。改完后运行最小可行检查，并告诉我 diff 摘要。

这个任务能验证它是否能写文件、跑命令、汇报变化。

账号、API key 和安全边界

Codex 可以用 ChatGPT 账号登录，也可以在一些入口里用 OpenAI API key。具体可用功能会随产品和账号策略变化，所以我不建议在文章里记死“某个套餐一定如何”。

你需要记住的是：

  • 不要把 API key 写进仓库；
  • 不要把 .env、token、密码提交到 Git；
  • 第一次任务尽量不要让 Codex 接触真实生产数据；
  • 让 Codex 改代码前，先看 git status；
  • 做完任务后，看 diff，而不是只看总结；
  • 涉及付款、账号权限、DNS、生产数据库、客户数据时，不要让它自动决策。

Codex 很强，但它应该在你设定的工作区、权限和验收标准里工作。

我自己的推荐安装顺序

如果我是从零开始，我会这样安排：

第一步，装 Codex app。
先用它打开一个本地项目，体验完整的读代码、改文件、跑命令、看 diff 流程。

第二步，装 IDE 扩展。
当你开始在编辑器里频繁让 Codex 解释函数、改组件、补测试时，它会更顺手。

第三步，装 CLI。
当你已经知道哪些任务可以命令行化，CLI 会让你更快、更稳定、更容易复现。

第四步，配置 cloud。
当你有 GitHub 仓库和比较明确的后台任务时，再让云端帮你跑长任务或开 PR。

第五步，考虑 SDK 或自动化。
只有当你已经形成重复流程，才把 Codex 接进脚本、内部工具或 CI。

常见卡点

装了扩展但找不到 Codex

先看侧边栏是否折叠，或者 Codex 图标是否被隐藏。VS Code fork 可能需要调整 activity bar 或把 Codex 拖到右侧侧边栏。重启编辑器也值得试一次。

Windows 上 sandbox 报错

先分清你是在原生 Windows 还是 WSL2。原生 Windows 有 sandbox 设置；WSL2 走 Linux 环境。企业电脑、权限策略、UAC、网络限制都可能影响 sandbox。不要一上来就关掉所有保护，先看错误信息。

WSL2 里很慢

检查仓库是不是放在 /mnt/c/...。如果是，把仓库移动到 ~/code/...，再从 WSL 内部运行 Codex 或打开 VS Code WSL 窗口。

CLI 能打开，但项目不对

大概率是当前目录错了。先运行：

pwd
git status --short --branch

确认你在目标仓库里，再启动 codex。

云端任务跑不起来

先检查 GitHub 是否连接、仓库是否可访问、environment 是否配置、setup script 是否能跑。第一次 cloud 任务建议只读，不要直接让它大改项目。

最后给一个选择建议

如果你只记住一句话：

本地项目用 App 或 IDE，终端流程用 CLI，后台长任务用 Cloud，Windows Linux 项目用 WSL2。

你不需要一次把所有入口都配置完。Codex 的真正价值不是“装了很多种”，而是你能在一个真实项目里稳定完成：读上下文、改最小范围、跑验证、看 diff、沉淀规则。

先让一个入口顺手，再扩展到第二个入口。