Codex 安装与使用教程：桌面 App 下载、命令行、IDE 怎么选

Codex 是 OpenAI 的编程助手。给它一个项目和一段任务描述，它会读代码、改文件、跑命令、看报错，再把结果交给你检查。

它有好几个入口：桌面 App、终端里的命令行（CLI）、编辑器里的插件，以及网页和云端。OpenAI 现在把桌面端叫 ChatGPT 应用，Codex 是应用里的一个入口，新手我推荐直接从桌面 App 开始，图形界面，不用碰命令行。

这篇先给出桌面 App 的下载地址和第一个任务，再讲命令行怎么装和登录，最后讲几个新手最需要懂的设置：沙箱、审批、AGENTS.md。后面的权限和配置部分按命令行的叫法写，桌面 App 里是同一套概念。

先确认三件事

1. 账号。 有两种方式用 Codex：

• ChatGPT 账号登录（推荐）：用你的 ChatGPT 订阅额度。Free、Go、Plus、Pro、Business、Edu、Enterprise 套餐目前都包含 Codex，只是额度不同。Codex 干活有用量窗口和周限额，用满了要等；而 ChatGPT 网页版的问答额度，在我用下来非常宽松，可以一直问。所以我的分工是：调研、查资料、想方案放在网页版（或 App 里的"聊天"）里，定了方案再交给 Codex 执行，下面"使用技巧"一节有具体做法。
• API Key 登录：按 API 用量付费。部分依赖 ChatGPT 工作区或云服务的功能会受限。Codex 云端任务必须用 ChatGPT 账号登录。

订阅 ChatGPT 的方法，本站有一篇用 Apple 礼品卡的教程：Apple 礼品卡订阅 ChatGPT。

2. 地区。 ChatGPT 和 Codex 在部分地区不可用，先确认你所在的地区能正常使用。

3. 一个能存放代码的文件夹。 Codex 是围绕"项目目录"工作的。首次尝试，建议用一个有 Git 记录的小项目，或者先新建一个空文件夹练手。

入口：桌面 App、命令行、IDE、网页怎么选

命令行和 IDE 插件共用同一份登录信息，在一个地方登录过，另一个不用再登。

第一步：下载桌面 App（推荐）

官方现在把桌面端叫 ChatGPT 应用：第一次发消息时，在输入框的下拉菜单里选 ChatGPT 或 Codex。写代码选 Codex，查资料、写文档、做表格选 ChatGPT。所以不用单独找一个"Codex 安装包"，下载 ChatGPT 应用就行。

下面是官方文档给出的下载地址，点击就会开始下载：

几点说明：

• Intel 芯片的 Mac：官方文档没有提供桌面 App 安装包，可以用下面的命令行或 IDE 插件。

• Windows 也可以用命令装： winget install --id 9PLM9XGG6VKS -s msstore。

• Linux 安装： 下载后用包管理器安装，装好后在应用菜单里打开 ChatGPT，或者运行 chatgpt。支持的系统是 Ubuntu 24.04 LTS 和 26.04 LTS、Debian 13、Fedora 43 和 44、当前的 Arch Linux。

  sudo apt install ./chatgpt_amd64.deb     # Ubuntu / Debian，ARM64 换成 chatgpt_arm64.deb
  sudo dnf install ./chatgpt.x86_64.rpm    # Fedora，ARM64 换成 chatgpt.aarch64.rpm
  sudo bash install-arch.sh                # Arch
  

• 已经装了命令行？ 运行 codex app 也能启动桌面 App，没装的话会打开安装程序。

• 这些是官方文档里的地址，版本更新后文件内容会换成最新版。点了没反应的话，回到官方 App 页面重新拿链接。

Windows 用户注意： 官方建议先装好常用开发工具，比如 Git、Node.js、Python（文档给了 winget 命令）。要用 GitHub 的功能，装 GitHub CLI 后运行 gh auth login。App 里的任务可以在 PowerShell 里运行（这时用 Windows 沙箱），也可以在设置里切到 WSL2，改完要重启 App。

第二步：登录并开始第一个任务

1. 登录。 装好后打开应用，用 ChatGPT 账号登录。官方说也可以用 API Key，但部分功能会受限。
2. 选一个文件夹。 新建聊天、创建项目，或者打开一个文件夹。应用能读取和修改你选的文件夹里的文件，所以选具体的项目目录，别选整个用户主目录。
3. 切到工作。 新建对话时，在顶部切到工作（有的版本是在输入框的 ChatGPT 下拉菜单里选 Codex）。
4. 描述任务。 写下目标，需要的话加上文件或背景。写法见后面的"怎么提问"。
5. 留意权限提示。 它要执行命令或改文件时，会按权限设置来问你，设置方法见后面的"权限：沙箱和审批"。Windows 版文档写明：要在输入框下方选 Ask for approval，沙箱保护才会生效；完全访问模式不受项目目录限制，可能造成数据丢失。

使用技巧：聊天做调研，工作来执行

在桌面 App 里新建对话时，顶部（红框处）可以在聊天和工作之间切换。

• 聊天：就是你熟悉的 ChatGPT，问问题、搜资料、做调研都用它。网页版 ChatGPT 的问答额度在我用下来很宽松，可以一直问。
• 工作（ChatGPT Work，也就是用 Codex 干活的那一边）：能读你选的文件夹、改文件、替你执行任务。
• 输入框左下角是权限选项，截图里是红色的"完全访问"。它不受项目目录限制，可能造成数据丢失，新手建议改成需要你批准的模式（英文界面叫 Ask for approval）。

我自己的用法是：调研和搜集信息，用聊天或者网页版，我觉得它在这件事上比"工作"好用一些；方案定了，再切到"工作"让它动手。 一个例子：

1. 在聊天里问："对比给静态网站加站内搜索的三种做法，列出各自的优缺点，推荐一种。"
2. 把结论整理成几句话，切到"工作"，用后面"怎么提问"里的四句话交代任务：做什么、看哪里、别碰什么、做到什么算完。

想用终端？安装命令行（CLI）

官方现在最先推荐的是安装脚本。

macOS、Linux：

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

Windows（PowerShell）：

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

其他方式：

npm install -g @openai/codex       # npm，需要先有 Node.js 和 npm
brew install --cask codex          # Homebrew，注意是 --cask

手动下载： 去 GitHub Releases 下载对应系统的压缩包，解压后把里面的文件改名为 codex，放到 PATH 里。命令行的包有 macOS（Apple 芯片和 Intel）和 Linux（x86_64 和 arm64）两类。

早些时候的教程里常见 brew install codex，现在要写成 brew install --cask codex。

验证：

codex --version

能打印出版本号（像 codex-cli 0.144.4）就装好了。想检查安装、配置和登录是否正常，运行 codex doctor。

命令行登录与 auth.json

进入项目目录，直接运行 codex：

cd your-project
codex

首次运行，选 Sign in with ChatGPT，在浏览器里授权。登录成功后回到终端就能开始提问。

几个登录相关的命令：

codex login                 # 浏览器登录（默认）
codex login status          # 看现在是否已登录
codex logout                # 退出登录

用 API Key 登录，把 key 从环境变量里传给它，不要把 key 直接写在命令里：

printenv OPENAI_API_KEY | codex login --with-api-key

auth.json 是什么

Codex 会把登录信息缓存下来，位置是 ~/.codex/auth.json，或者你系统的凭据库（比如 macOS 钥匙串）。配置项 cli_auth_credentials_store 决定存在哪：

把 auth.json 当密码对待。 它里面是访问令牌，不要上传到 GitHub，不要贴到论坛或工单里，也不要发给别人。

在远程服务器上登录

服务器没有浏览器时，官方给了三种办法：

1. 设备码登录（测试版，优先用）： codex login --device-auth，在自己电脑上打开它给的链接，输入一次性验证码。需要先在 ChatGPT 的安全设置或工作区权限里打开设备码登录。
2. 复制登录缓存： 在有浏览器的机器上登录，再把 ~/.codex/auth.json 复制到服务器同一路径。
3. 转发回调端口： ssh -L 1455:localhost:1455 user@remote，然后在远程机器上运行 codex login。

自动化场景，官方建议用 API Key。

怎么提问

先让它读项目，别急着改：

这个项目是做什么的？目录结构是怎样的？

入口文件在哪？帮我理清主要流程。

让它做事：四句话

熟悉之后再让它做事，我习惯把任务说成四句话：

1. 做什么：一句话说清要得到什么结果。
2. 看哪里：告诉它去哪些文件或目录找，别让它满项目乱翻。
3. 别碰什么：哪些文件、格式、依赖不能动。
4. 做到什么算完：用什么检查结果（测试通过、页面上能看到变化），以及要它汇报什么。

笼统的说法：

文章列表有点问题，帮我修一下

说成四句话：

文章列表页里出现了状态是 draft 的文章，应该只显示 published 的。
只看 lib/posts.ts 和 app/(zh)/posts 下的文件。
不要改 data/posts.generated.json，它是脚本生成的文件。
改完运行 npm run build 和 npm test，都通过后告诉我改了哪几行。

OpenAI 官方的最佳实践里推荐的也是类似的四项：目标、背景、限制、完成标准。任务复杂或者说不清楚的时候，官方建议先用 Plan 模式让它列方案，你看过再动手。

权限：沙箱和审批

这是新手最该花五分钟看懂的部分。Codex 有两个互相独立的开关：

沙箱模式（它技术上能做什么）：

审批策略（什么时候停下来问你）：

官方的默认建议：

• 在有 Git 记录的目录里，推荐 Auto，就是 workspace-write 加 on-request。
• 在没有 Git 记录的目录里，推荐 read-only。
• 根据设置，Codex 可能在你确认信任这个目录之前，先以 read-only 启动。

在会话里输入 /permissions 就能切换，比如想只聊天、只看方案，就切到 read-only。启动时也可以用参数指定：

codex --sandbox read-only --ask-for-approval on-request

写进配置文件也行（见后面的 config.toml）。想让沙箱里能联网：

[sandbox_workspace_write]
network_access = true

最危险的开关： --dangerously-bypass-approvals-and-sandbox（别名 --yolo）会同时关掉审批和沙箱。官方只建议在已经被外部隔离好的环境里用。新手不要碰。

Windows 上有原生沙箱和 WSL 两种用法，见官方的Windows 沙箱和WSL说明。

AGENTS.md：让它记住项目规则

和人一样，Codex 每次开新对话都不记得你的项目。把规则写进 AGENTS.md，它每次启动都会读。

在项目里输入 /init，它会生成一份 AGENTS.md 初稿，再手动改。

Codex 在两个范围找这个文件：

• 全局： ~/.codex/AGENTS.md（有 AGENTS.override.md 时优先用它）
• 项目： 从项目根目录（通常是 Git 根目录）一路往下走到你当前所在的目录，每个目录最多取一个文件

合并规则：从根往下依次拼接，离你当前目录越近的越靠后，覆盖前面的。合并后的总大小默认上限是 32 KiB，到了上限就不再加入更多文件。内容多的话，要么在配置里调大 project_doc_max_bytes，要么把说明拆到各子目录。

官方的例子：

# ~/.codex/AGENTS.md（全局）
- Prefer `pnpm` when installing dependencies.

# AGENTS.md（项目根目录）
- Run `npm run lint` before opening a pull request.

# services/payments/AGENTS.override.md（子目录）
- Use `make test-payments` instead of `npm test`.

想确认它到底读到了什么，运行：

codex --ask-for-approval never "Summarize the current instructions."

写 AGENTS.md 时：具体比笼统有效。"改完运行 npm test"比"注意代码质量"管用。

配置文件 config.toml

配置是 TOML 格式，常见位置：

优先级从高到低：命令行参数 → 项目配置 → profile 文件 → 用户配置 → 系统配置 → 内置默认值。

一个够用的最小例子：

# ~/.codex/config.toml
approval_policy = "on-request"
sandbox_mode = "workspace-write"
web_search = "cached"

其中 web_search 的取值有 "cached"（默认）、"indexed"、"live"、"disabled"。想在一次运行里开实时搜索，可以加 --search。

用哪个模型，在会话里输入 /model 选，比在配置里写死更不容易过时。

在编辑器里用：IDE 插件

VS Code、Cursor、Windsurf： 在扩展市场搜索并安装 OpenAI 的 Codex 扩展（扩展 ID 是 openai.chatgpt）。装好后，点编辑器侧边栏里的 Codex 图标，用 ChatGPT 账号登录。

"Codex 的 IDE 怎么打开？" 如果看不到图标，打开命令面板（macOS 是 Cmd+Shift+P，Windows 和 Linux 是 Ctrl+Shift+P），运行 Codex: Open Codex Sidebar。

JetBrains： 打开 AI Chat，选择 Codex 作为 agent。Xcode： 开一个新的聊天，选择 Codex。具体步骤见官方的IDE 页面。

网页和云端

在 chatgpt.com/codex 提交任务，让它在云端跑，不占用你的电脑。云端必须用 ChatGPT 账号登录。

在桌面 App 里新建任务时，选 Work in → Cloud，再选 Select environment → Create environment，Codex 会检查你的仓库，帮你准备并测试环境。在终端里用 codex cloud 可以浏览云端任务，再把改动应用到本地。

常用命令速查

终端里的子命令：

会话里的斜杠命令：

接上外部工具（MCP）

MCP 让 Codex 连接外部服务，比如查文档。用命令加一个：

codex mcp add context7 -- npx -y @upstash/context7-mcp

这条会写进 ~/.codex/config.toml，等价于：

[mcp_servers.context7]
command = "npx"
args = ["-y", "@upstash/context7-mcp"]

加完用 codex mcp list 查看，在会话里输入 /mcp 看连接状态。只接你信得过的服务。

改坏了怎么撤销

"Codex 怎么撤销记录"是搜索里的常见问题。我在官方文档里没有找到 Codex 内置的回滚命令，所以最可靠的办法是 Git：

1. 动手之前先提交一次。 这样不管它改成什么样，都有一个能回去的点。
2. 看它改了什么： git status 看改了哪些文件，git diff 看具体内容；也可以在 Codex 里用 /review。
3. 想退回某个文件： git restore <文件>。注意，这条会直接丢弃该文件还没提交的改动，丢掉就找不回来。拿不准时先 git stash，把改动收起来，需要时还能取回。

它适合做什么，不适合做什么

适合：看懂陌生项目、修小 bug、补测试、改文档、做重构、读报错日志、评审代码。

第一次别交给它：

• 涉及支付、权限、账号的代码，必须自己逐行看
• 批量删除文件或数据
• 直接改线上环境
• 没有备份、没提交过的重要项目

一定要注意的安全问题

• 密钥不要贴给它，也不要写进项目。 放在 .env 里，并确认 .gitignore 排除了 .env。
• ~/.codex/auth.json 当密码保管。
• 不要在重要数据所在的机器上开 --yolo。
• 看清它要执行的命令和要联网访问的网址，再同意。

更新

• 安装脚本装的：重新运行同一条安装命令，或者 codex update。
• npm 装的：npm install -g @openai/codex@latest。
• Homebrew 装的：brew upgrade --cask codex。

一页速记

1. 有 ChatGPT 账号（含 Codex 的套餐），且所在地区可用。
2. 下载 ChatGPT 桌面 App（macOS Apple 芯片、Windows、Linux），登录，在输入框里选 Codex，打开项目文件夹。
3. 喜欢终端的话装命令行：curl -fsSL https://chatgpt.com/codex/install.sh | sh，进入项目目录运行 codex，选 Sign in with ChatGPT。
4. 先问项目是做什么的，再用"四句话"让它做一件小事。
5. 动手前先 Git 提交；默认在 workspace-write + on-request 下工作；用 /permissions 调整。
6. /init 生成 AGENTS.md，以后每次启动都省得重复说明。

和 Claude Code 怎么对应

对应的教程见Claude Code 安装与使用教程。

官方链接

• Codex 总览
• 桌面 App（macOS）
• 桌面 App（Windows）
• 桌面 App（Linux）
• Codex CLI
• 权限
• 最佳实践
• 登录方式
• 审批与沙箱
• AGENTS.md
• 配置文件
• IDE 插件
• openai/codex 源码仓库（Apache-2.0 协议）