开篇 · 这是什么

一句话 Codex 桌面端 = 装在电脑上的 ChatGPT：能打开本地文件夹、改代码、跑命令、预览产物；下拉里选 Codex 做开发，选 ChatGPT Work 做文档/汇报，选 Chat 做随问随答。

安装macOS / Win

登录ChatGPT 或 API Key

开项目本地文件夹

选 Codex开发模式

发任务改代码 / 测

审改沙箱审批

形态	适合	官方入口
桌面端（本教程）	本地项目、长任务、文件预览、Appshots / Computer Use	chatgpt.com/download
Codex CLI	终端、CI、脚本化	本站 20 天教程 · 官方
IDE 扩展	编辑器内联协作	Codex IDE
Web ChatGPT	纯网页对话 / Work	chatgpt.com

资料：Quickstart · Download · llms.txt 文档地图

01

安装与登录

1

下载安装

作用：装上 ChatGPT 桌面端（内置 Codex）。官方下载页同时提供 macOS / Windows。

系统	怎么装
macOS	打开 chatgpt.com/download，点 macOS；或直接下 ChatGPT.dmg： persistent.oaistatic.com/.../ChatGPT.dmg
Windows	同上下载页，或 Microsoft Store： Store 安装包；命令行：`winget install --id 9PLM9XGG6VKS -s msstore`

已有旧版 Codex.app：更新到 ChatGPT 后仍可在下拉里打开 Codex。应用目录里可能仍能看到兼容路径 /Applications/Codex.app。

✅ 验收：能打开桌面端，看到登录页或主界面。

2

ChatGPT 账号（推荐）：未登录页点 Continue to sign in，浏览器完成授权后回到 App。用量走你的 ChatGPT 套餐与工作区权限。
API Key：点 Sign in another way，粘贴 Platform API Key。按 API 计价；部分依赖 ChatGPT 工作区 / 云能力的功能会受限。

注意凭证会缓存在本机（常见 ~/.codex/auth.json 或系统钥匙串）。别提交到 Git、别贴到聊天里。退出登录：点头像 / Profile → Log out。

资料：Authentication · Feature availability

02

三种工作模式

怎么选打开桌面端后，用 ChatGPT 下拉切换模式。官方建议：随问用 Chat，交付物用 Work，写代码用 Codex。

Chat · Quick Chat

普通对话

提问、头脑风暴、改语气、总结。不绑本地项目。快捷键 Cmd/Ctrl+Alt+N。

ChatGPT Work

交付物 / 研究

决策备忘录、报表、幻灯片、表格、Sites。适合「要一份能审的结果」，不一定动代码库。

Codex

软件开发

带代码库上下文：读改文件、跑测试、看 Review 面板、Worktree 并行。本教程主线。

选这个	当你想…	例子
Chat	聊通一件事	解释概念、草稿消息、对比方案
Work	产出可交付物	做 PPT、合并表格、写一页决策 memo
Codex	动代码 / 工程	修 bug、加功能、跑测、审 PR

资料：Use ChatGPT · Desktop Quickstart

03

第一个 Codex 任务（跟做）

1

打开本地文件夹当工作区

作用：Local project 把某个目录变成 Codex 的工作目录，Agent 才能读改你的代码。

按 Cmd+O（Windows：Ctrl+O）或点 Add new project
选一个 Git 仓库根目录（或你要改的包目录）
下拉切到 Codex
确认沙箱策略：建议先用会询问审批的模式（如 Ask for approval），不要一上来 Full Access

✅ 验收：侧栏出现该项目，新任务能看到项目路径。

2

发第一条开发指令

作用：说清目标 + 验收标准，比空喊「优化一下」稳得多。官方 Quickstart 示例风格如下。

# 可直接粘贴到 Codex 输入框（按你的仓库改措辞）
Inspect this app, identify one high-impact usability improvement,
implement it, update the relevant tests, and verify the result
on mobile and desktop.

更小的起步示例：

Read the README and package scripts. Summarize how to run tests locally.
Then run the unit tests and paste the failing cases (if any) with a fix plan.
Do not change files until I approve the plan.

✅ 验收：侧栏能看到计划 / 文件变更 / 终端输出；有审批弹窗时你能点允许或拒绝。

3

审结果并迭代

打开 Review 面板看 diff（Git 仓库会按 staged / unstaged / 与主分支对比展示）
想只看「这一轮 Codex 改了什么」：切到 Last turn
用跟进句收口：「只改登录页」「回退刚才对 CSS 的修改」「补一条失败用例」
任务跑偏：取消当前 run，在输入框按 ↑ 可找回上一条 prompt

资料：Code review · Troubleshooting

04

项目与任务组织

概念	大白话	建议
ChatGPT Project	云端项目：文件、指令跨任务复用	长期主题、多产出共用同一批资料
Local Project	本机文件夹 / 代码库	一个可工作的仓库根；monorepo 可拆多个 local project
Task	一次有结果的任务线程	一个清晰 outcome 开一个 task；好命名便于搜索
Quick Chat	不绑项目的闲聊	聊清楚后再 Add to task
Worktree	Git worktree 隔离改动	并行任务、怕弄脏当前 checkout 时用

组织习惯：Pin 常用项目/任务 → 用描述性标题 → 结束就 Archive → Cmd/Ctrl+G 搜历史（可匹配内容或分支名）→ Cmd/Ctrl+F 只搜当前任务内。

Worktree 默认只带 Git 已跟踪文件；依赖若靠被 ignore 的本地文件，需配 local environment 或 .worktreeinclude，否则「代码在、跑不起来」。

资料：Projects, chats, and tasks · Worktrees

05

沙箱与审批（必读）

两层防护 Sandbox = Agent 技术上能碰到哪（写哪里、有无网）； Approval = 什么时候必须停下来问你。默认网络通常关闭，工作区外写入需审批。

模式直觉	行为	何时用
Ask for approval	越界/联网/敏感操作先问	日常默认，推荐
Auto（工作区可写）	工作区内读写与命令更自动	信任仓库、想少打断
Read-only	只聊/只计划，不改文件	先摸清再动手
Full access	几乎不限目录	高风险；可能误删，慎用

官方警告 Full access 下 Agent 不受项目目录限制，可能造成数据损失。优先保留沙箱边界，用 Rules 做精准例外，而不是全局放开。

项目级说明可写在仓库的 AGENTS.md，给 Codex 固定上下文与习惯（构建命令、目录约定、禁止事项）。

资料：Agent approvals & security · AGENTS.md

06

桌面端能力包

能力	干什么	怎么开
Appshots macOS	把当前最前窗口截图 + 可读文本塞进任务	双击左右 Command，或自定义热键；需屏幕录制 / 辅助功能权限
内置 Browser	在 App 内浏览网页、受控访问站点	Settings → Browser；站点默认需询问后才用
Computer Use	看 GUI、点按桌面应用（Work / Codex）	Plugins → Computer Use 安装/启用；macOS 需 Screen Recording + Accessibility
文件预览 / 批注	预览文档、幻灯、表格、PDF，点选区域让它改	任务产出后在侧栏打开预览，用 annotation 定点修改
Skills & Plugins	可复用流程 / 连接 GitHub、Drive 等	浏览安装；ChatGPT 用 `@`，Codex 侧技能可用 `$` 提及
Scheduled	定时重复任务	深链 `codex://automations` 或侧栏 Scheduled；注意别堆太多 worktree
Deep link	用 `codex://` 打开新任务、设置、插件	例：`codex://threads/new?prompt=...`（参数需 URL 编码）

Computer Use 会动到工作区以外的系统/App 状态：任务范围要小，每次审批都看一眼。 Windows 上它占用前台鼠标键盘；需要边跑边干活时，官方建议用远程控制、或放在虚拟机里跑。

资料：Appshots · Browser · Computer Use · Skills & Plugins · Work with files

07

设置与快捷键

打开设置：Cmd+, / Ctrl+,，或深链 codex://settings。

分类	常用项
General	多行是否要 Cmd+Enter；Prevent sleep while running；跟进消息是「转向当前 run」还是「等下一轮」
Appearance	主题、强调色、UI/代码字体
Notifications	回合完成通知
Personalization	性格 Friendly / Pragmatic / None；自定义指令会写回个人 `AGENTS.md`
Browser / Computer Use	站点黑白名单、系统权限、常允许 App
Archived tasks	找回已归档任务
Keep near work	任务弹出独立窗口 + Always on top，贴在编辑器旁边

⌘

高频快捷键

动作	macOS	Windows
命令面板	Cmd+Shift+P 或 Cmd+K	Ctrl+Shift+P / K
打开文件夹	Cmd+O	Ctrl+O
新任务	Cmd+N	Ctrl+N
搜任务	Cmd+G	Ctrl+G
任务内查找	Cmd+F	Ctrl+F
切换侧栏	Cmd+B	Ctrl+B
切换终端	Ctrl+`	Ctrl+`
快捷键一览	Cmd+Shift+/	Ctrl+Shift+/

资料：Settings · Commands

08

Windows 专章

默认跑 Windows-native Agent（PowerShell）+ Windows sandbox；也可在 Settings 切到 WSL2 后重启 App 才生效。
WSL1 自 Codex 0.115 起不再支持（沙箱改用 bubblewrap）。
项目尽量放在 Windows 盘，WSL 通过 /mnt/<drive>/... 访问；直接开 \\wsl$\ 路径时 Git 检测可能不稳。
建议预装：Git、Node LTS、Python、.NET SDK、GitHub CLI（可用 winget）。
需要提权命令：用「以管理员身份运行」启动桌面端，Agent 继承权限。
遇 npm.ps1 cannot be loaded...：Set-ExecutionPolicy -ExecutionPolicy RemoteSigned（改策略前先看微软文档）。
Windows App 与 WSL 里 CLI 默认不共享 ~/.codex；要共享可设 export CODEX_HOME=/mnt/c/Users/<you>/.codex。

资料：ChatGPT desktop app for Windows

09

踩坑、验收与延伸

常见坑（官方 FAQ） Review 面板出现「不是 Codex 改的文件」→ 那是 Git 工作区整体 diff；切 Last turn 只看本轮。
侧栏任务变少 → 检查 Tasks 过滤器是否不是 Chronological，以及 Archived tasks。
CLI 有功能、桌面端没有 → 两边 Codex 版本可能不同；桌面端可用兼容路径查版本： /Applications/Codex.app/Contents/Resources/codex --version
macOS 弹 Apple Music 权限 → 访问家目录相关路径时的系统提示，按需批准。

✓

跟做验收清单

□ 已从 chatgpt.com/download 装好并登录
□ 能区分 Chat / Work / Codex 三种模式
□ 已用 Cmd/Ctrl+O 打开本地仓库
□ 在 Codex 下完成一次「读代码 → 改文件 → Review」闭环
□ 知道审批弹窗该怎么处理，未盲目开 Full Access
□ （可选）试过 Appshots 或 Browser / Computer Use 之一

全部勾完，你就已经会用 Codex 桌面端主路径了。下一步可接 CLI / IDE，或写仓库级 AGENTS.md 固化团队规范。

📖

官方文档索引

主题	链接
文档总入口	developers.openai.com/codex
快速开始	Quickstart · Desktop
下载	chatgpt.com/download
Markdown 文档地图	llms.txt（每页有 `.md` 孪生页）
命令 / 深链	Commands
设置	Settings
故障排查	Troubleshooting

Codex 桌面端使用教程