Codex 桌面端新手使用教程
一、概述
1.1 Codex 桌面端是什么
Codex 桌面端是装在本机上的 AI 编程助手。用户指定一个文件夹并用自然语言描述需求，Codex 可在该文件夹内创建文件、修改代码、执行命令。
与 ChatGPT 网页聊天的区别：Codex 桌面端会直接修改本机文件，用户可在 App 内查看变更（Diff），并在文件夹中验收结果。
1.2 主要能力
| 能力 | 说明 |
|---|---|
| 本地写代码 | 在指定文件夹内创建、修改文件 |
| 多任务并行 | 同时开启多条对话，分别执行不同任务 |
| 变更审查 | 在 App 内查看 AI 修改了哪些代码行 |
| 自动化 | Automations 按计划在后台执行任务 |
| 技能扩展 | Skills 为 Agent 增加专项能力 |
本教程默认使用 Local 本地模式，即 AI 直接在本机项目文件夹中工作。
二、使用前准备
2.1 登录方式
正常是需要使用 ChatGPT 账号登录。Plus、Pro、Business、Enterprise、Edu 等订阅通常包含 Codex 使用额度。
那么没有账号的小伙伴，也可使用 OpenAI API Key去登录，可参考 Codex配置使用教程
2.2 项目文件夹
在桌面新建空文件夹，例如：
C:\Users\你的用户名\Desktop\我的第一个项目命名宜简短，可用中文或英文，避免特殊符号。不要选择整个桌面、文档目录或 C 盘根目录作为项目，以免 AI 误改范围过大。
2.3 Git（可选）
建议安装 Git，便于在 AI 改乱文件时回退。Windows 下载：https://git-scm.com/download/win
三、安装与登录
3.1 安装步骤
- 打开 https://openai.com/codex
- 下载对应系统的安装包（Intel Mac 需选 Intel 版本）
- 双击安装，按向导完成
- 启动 App，点击 Sign In，使用 ChatGPT 账号登录
登录成功后应能看到主界面，左下角显示账号信息。
3.2 常见安装问题
| 现象 | 处理办法 |
|---|---|
| 卡在 Logo 画面 | Windows：设置 → 应用 → Codex → 修复或重置后重启 |
| 登录后闪退 | 从官网下载最新版覆盖安装 |
| 登录后 App 无响应 | 检查网络、防火墙，可暂时关闭 VPN 重试 |
| 提示无权限 | 确认订阅有效，或尝试 API Key 登录 |
| Mac 无法打开 | 系统设置 → 隐私与安全性 → 允许打开 |
四、创建第一个项目
4.1 绑定文件夹
- 打开 Codex
- 点击 Select a project（选择项目）
- 选中已创建的项目文件夹
- 点击选择文件夹
此后 AI 创建、修改的文件均在该文件夹内。
4.2 确认 Local 模式
在界面顶部或侧边栏确认已选中 Local。Local 表示 AI 直接修改所选文件夹中的文件。若显示 Cloud，请先切换为 Local 再发送消息。
4.3 连通测试
在底部输入框发送：
你好，请看看这个文件夹里有什么文件，用中文介绍一下你能帮我做什么。若 Codex 用中文回复并说明文件夹状态及可提供的帮助，说明项目绑定成功。
五、界面概览
5.1 主要区域
界面分为四部分：左侧边栏（项目、对话、Skills、Automations）、中间对话区、右侧审查面板（Diff）、底部输入框。另可通过顶部按钮打开集成终端。
| 区域 | 作用 |
|---|---|
| 项目切换 | 打开、切换不同文件夹 |
| Local 模式 | 确认本地模式已开启 |
| 对话列表 | 管理历史对话，建议一个任务一条对话 |
| 对话内容 | 查看 AI 回复与执行步骤 |
| 变更预览 | 审查 AI 修改了哪些文件的哪些行 |
| 输入框 | 输入需求并发送 |
日常使用建议：一个任务开一条新对话；AI 改完后先查看 Diff；最后打开文件或浏览器验收结果。
5.2 整体布局
- 顶部：工具栏（终端、Diff、侧边栏、弹出窗口等）
- 左侧：项目、对话线程、Skills、Automations
- 中间：对话内容、执行步骤、审批提示
- 右侧：审查面板、任务侧栏或内置浏览器预览
- 底部：输入区（Composer）、模型选择、运行模式
- 集成终端：顶部图标或 Ctrl+J（Mac：Cmd+J）
六、界面选项与按钮说明
以下按区域说明常见按钮与选项。界面可能随版本更新，名称以 App 内英文显示为主。Windows 快捷键记为 Ctrl，Mac 记为 Cmd。
6.1 左侧边栏
项目（Projects）
| 操作 | 位置 | 作用 |
|---|---|---|
| Add new project | 项目列表上方或 Ctrl+O | 绑定新的本机文件夹 |
| 点击项目名称 | 项目列表 | 切换到该项目 |
| Remove | 悬停项目名 → 三点菜单 | 从侧边栏移除（不删除本机文件夹） |
建议每个代码库或小工具对应一个项目，不要将整个桌面设为项目。
对话线程（Threads）
每个 Thread 是一次独立任务对话，拥有独立上下文。项目指文件夹，线程指在该文件夹内的一次对话。
| 操作 | 快捷键 | 作用 |
|---|---|---|
| New thread | Ctrl+N / Cmd+N | 新建对话 |
| Search threads | Ctrl+G / Cmd+G | 搜索历史对话 |
| Previous / Next thread | Ctrl+Shift+[ ] / Cmd+Shift+[ ] | 切换对话 |
| Find in thread | Ctrl+F / Cmd+F | 在当前对话内查找 |
| Filter | Threads 旁筛选图标 | 调整排序或筛选方式 |
| Pin | 对话菜单 | 固定常用对话 |
| Archive | 对话菜单 | 归档，可在 Settings 中恢复 |
Skills（技能）
| 入口 | 作用 |
|---|---|
| 侧边栏 Skills | 浏览、启用、管理技能包 |
| 输入 $技能名 | 在对话中调用指定 Skill |
| 输入 / | 已启用 Skill 会出现在斜杠命令列表 |
示例：$imagegen调用图片生成；$hatch-pet创建桌面宠物（见 Appearance 设置）。
Automations（自动化）
| 入口 | 作用 |
|---|---|
| 侧边栏 Automations | 创建、管理定时任务 |
| 编辑器内 @ | 引用项目或 Skill（部分版本） |
| 类型 | 适用场景 |
|---|---|
| 项目 / 独立自动化 | 定时启动新任务，如每周总结变更 |
| 线程自动化 | 在同一条对话内定时唤醒 AI，延续上下文 |
自动化运行时电脑通常需保持开机。
Chats（纯聊天）
不绑定代码项目文件夹的对话，适合调研、规划等。工作目录默认为~/.codex/threads。
任务侧栏
长任务执行时可能显示 Plan（计划）、Sources（来源）、Artifacts（产物预览）、Summary（摘要），便于中途调整方向。
6.2 顶部工具栏
| 按钮 / 功能 | 快捷键 | 作用 |
|---|---|---|
| Toggle sidebar | Ctrl+B / Cmd+B | 显示或隐藏左侧边栏 |
| Toggle diff panel | Ctrl+Alt+B / Cmd+Option+B | 显示或隐藏审查面板 |
| Toggle terminal | Ctrl+J / Cmd+J | 打开或关闭集成终端 |
| Pop-out | 窗口菜单或按钮 | 将对话弹出为独立窗口 |
| 自定义快捷按钮 | 窗口顶部（若已配置） | 一键执行常用操作 |
终端说明：作用范围限定在当前项目或 worktree；Ctrl+L 清空终端（Ctrl+K 为命令菜单）；Codex 可读取终端输出。
6.3 底部输入区（Composer）
基本操作
| 操作 | 作用 |
|---|---|
| Enter | 发送消息（可在设置中改为 Ctrl+Enter 换行） |
| Shift + 拖拽图片 | 将图片加入上下文 |
| 拖拽图片 | 附加图片参考 |
| 上方向键 | 恢复上一条输入 |
模型选择
输入框附近下拉菜单可选择 AI 模型。对话中输入/model可运行时切换。
运行模式
| 模式 | 说明 | 适用场景 |
|---|---|---|
| Local | 直接修改当前项目文件夹 | 新手默认 |
| Worktree | 在 Git worktree 中隔离修改 | 已是 Git 项目且怕改乱主分支时 |
| Cloud | 在 OpenAI 云端环境运行 | 需预先配置云端环境 |
语音输入
按住 Ctrl+M 可语音输入，转写后可编辑再发送。
斜杠命令（输入 /）
| 命令 | 作用 |
|---|---|
| /plan | 计划模式，先规划再执行 |
| /review | 代码审查模式 |
| /status | 查看线程 ID、上下文用量、速率限制 |
| /goal | 设定持久目标 |
| /init | 生成 AGENTS.md 脚手架 |
| /mcp | 查看 MCP 连接状态 |
| /feedback | 提交反馈 |
输入$可显式调用 Skill。
审批提示
AI 执行敏感操作（运行命令、访问网络等）时需用户确认：
| 选项 | 含义 |
|---|---|
| Approve once | 仅批准本次 |
| Approve for session | 本次对话内同类操作不再询问 |
| Deny | 拒绝执行 |
不确定时建议选择批准一次，并看清命令内容后再确认。
6.4 审查面板（Review / Diff）
显示范围
| 范围 | 说明 |
|---|---|
| 未提交改动（默认） | 当前工作区相对 Git 的变更 |
| All branch changes | 相对主分支的全部分支改动 |
| Last turn changes | 仅 AI 上一轮的改动 |
若项目非 Git 仓库，面板会提示先初始化 Git。绿色表示新增行，红色表示删除行。
面板操作
| 操作 | 作用 |
|---|---|
| Stage | 将改动加入暂存区 |
| Unstage | 取消暂存 |
| Revert | 丢弃改动 |
| Stage all | 暂存全部改动 |
| Revert all | 丢弃全部未提交改动（慎用） |
| 按文件 / 按块 | 单独 stage 或 revert |
| 行内评论 | 在 diff 行上留言，让 Codex 按评论修改 |
Git 与 PR
项目为 Git 仓库且已配置远程时，可在 App 内 Commit、Push、创建 PR，并处理 PR 评论。
6.5 集成终端
通过顶部图标或 Ctrl+J 打开。用于git status、npm test、启动开发服务器等。Codex 也会在此执行命令，并可读取输出。
6.6 内置浏览器
可在 App 内预览 localhost 或本地 HTML。支持 Browser comments（页面标注反馈）与 Browser use（自动操作页面，需在 Settings → Browser 配置）。不支持登录态、Cookie 及浏览器插件。
6.7 命令菜单
Ctrl+Shift+P 或 Ctrl+K（Mac：Cmd+Shift+P 或 Cmd+K）打开命令面板，可搜索执行设置、重载 Skills、切换主题等操作。
6.8 设置面板（Settings）
打开方式：菜单 → Settings，或 Ctrl+,（Mac：Cmd+,）。
| 分类 | 主要选项 |
|---|---|
| General | 文件打开方式、命令输出量、多行输入、运行时防止休眠 |
| Profile | 用量统计、头像昵称、邀请 |
| Keyboard Shortcuts | 查看、自定义、重置快捷键 |
| Notifications | 任务完成与审批通知 |
| Agent configuration | 审批策略、沙箱权限、高级配置 |
| Appearance | 主题、字体、Pets |
| Git | 分支命名、提交与 PR 模板、force push 策略 |
| Integrations & MCP | 连接外部工具（MCP 服务器） |
| Browser | 内置浏览器、允许 / 禁止的网站列表 |
| Computer Use | 桌面应用操控权限 |
| Personalization | 回复风格、自定义指令（AGENTS.md） |
| Memories | 跨对话记忆偏好与规范 |
| Archived threads | 查看、恢复已归档对话 |
6.9 常用快捷键
| 操作 | Windows | macOS |
|---|---|---|
| 命令菜单 | Ctrl+Shift+P 或 Ctrl+K | Cmd+Shift+P 或 Cmd+K |
| 设置 | Ctrl+, | Cmd+, |
| 快捷键帮助 | Ctrl+/ | Cmd+/ |
| 打开项目 | Ctrl+O | Cmd+O |
| 新建对话 | Ctrl+N | Cmd+N |
| 搜索对话 | Ctrl+G | Cmd+G |
| 对话内查找 | Ctrl+F | Cmd+F |
| 切换侧边栏 | Ctrl+B | Cmd+B |
| 切换 Diff | Ctrl+Alt+B | Cmd+Option+B |
| 切换终端 | Ctrl+J | Cmd+J |
| 清空终端 | Ctrl+L | Ctrl+L |
| 语音输入 | Ctrl+M（按住） | Ctrl+M（按住） |
6.10 界面相关常见问题
| 问题 | 答案 |
|---|---|
| 项目和对话有何区别？ | 项目指文件夹，对话指在该文件夹内的一次任务 |
| Local 和 Worktree 如何选？ | 新手用 Local；怕改乱主代码且已是 Git 项目时用 Worktree |
| 如何只看 AI 刚改的内容？ | 审查面板选 Last turn changes |
| AI 要跑命令该批准吗？ | 先看命令内容；不懂则批准一次 |
| 找不到历史对话？ | Ctrl+G 搜索，或调整 Threads 筛选，或在 Settings 查看归档 |
七、实战：制作待办清单网页
7.1 第一步：创建网页
向 Codex 发送：
请在这个文件夹里创建一个待办清单网页，要求如下： 1. 只要一个 index.html 文件，使用 HTML、CSS、JavaScript 2. 功能：添加待办、删除待办、标记完成或取消完成 3. 数据保存在 localStorage，刷新后不丢失 4. 界面为中文，风格简洁 5. 完成后说明如何在 Windows 浏览器中打开验收：文件夹中出现index.html；双击用浏览器打开；测试添加、完成、刷新后数据是否保留。
7.2 第二步：美化界面
在同一条对话中发送：
请优化 index.html 的视觉效果： 居中布局、浅色背景、蓝色强调色、卡片式待办项、完成项显示删除线。 只改样式，不要破坏现有功能。验收：刷新浏览器，外观改善且功能正常。
7.3 第三步：增加功能
在同一条对话中发送：
在现有待办清单上增加： 1. 未完成 / 已完成数量统计 2. 清除已完成按钮 3. 输入框支持 Enter 添加 4. 空输入不添加 改完后说明如何测试。验收：统计、清除已完成、Enter 添加均正常。
7.4 第四步（可选）：README
请创建 README.md（中文），含项目简介、功能列表、打开方法、改进建议。 不要修改 index.html。八、审查 AI 的修改
Diff 用绿色标新增、红色标删除。不必读懂全部代码，但应确认：修改的文件是否正确、有无大段误删、实际效果是否符合预期。
| 检查项 | 做法 |
|---|---|
| 改了几个文件 | 是否只改了预期的文件 |
| 有无误删 | 红色删除行是否异常 |
| 效果是否正确 | 在浏览器或文件中亲自测试 |
不满意时可在同一条对话中继续说明，例如：
请撤销上一步对样式的修改，恢复到我让你优化外观之前的状态。「清除已完成」按钮点击没反应，请修复，不要改其他功能。九、如何向 Codex 描述需求
描述越具体，结果越好。
| 类型 | 示例 |
|---|---|
| 不宜 | 帮我做个网站 |
| 不宜 | 做一个像微信一样的 App |
| 建议 | 在 index.html 增加深色模式按钮，指定配色，不引入外部 CSS 框架 |
可套用结构：在某文件或文件夹中，做某功能，要求某效果，不要改动某部分。
原则：一次只做一件事；说明不要改什么；结尾写明如何验收。
十、进阶功能
- 多对话并行：新建多条对话，分别处理代码、文档、检查等任务
- 审查与回滚：通过 Diff 逐文件查看；不满意可在对话中要求撤销
- Automations：侧边栏或设置中配置定时任务
- Skills：启用后可在 prompt 中要求按某 Skill 规范执行
- 多项目：可绑定多个文件夹，在 App 内切换
十一、常见问题
| 问题 | 答案 |
|---|---|
| 不懂代码能用吗？ | 可以，用户负责描述需求与验收 |
| 必须用英语吗？ | 对话可用中文，界面为英文 |
| 改乱了怎么办？ | 查看变更预览，对话中要求撤销，或用 Git 回退 |
| 会修改其他文件夹吗？ | 仅修改所选项目文件夹内的文件 |
| 免费版 ChatGPT 能用吗？ | 通常需 Plus 及以上，以官网政策为准 |
| Windows 无法打开 html？ | 右键 → 打开方式 → Chrome 或 Edge |
| 运行命令安全吗？ | Local 模式可能在项目文件夹内执行命令，请使用专用文件夹并备份 |
十二、项目备份
大改前建议 Git 备份。可让 Codex 执行：
请在这个文件夹里初始化 git 仓库，添加所有文件并提交，说明写「待办清单初版」。也可手动执行git init、git add .、git commit -m "待办清单初版"。改乱可用git checkout .回退。
十三、常用 Prompt 参考
从零创建：
在【文件夹】里创建【工具名】，单文件 HTML，中文界面， 功能：【列举 3～5 条】，localStorage 保存，说明如何打开。只改外观：
只优化【文件名】的 CSS，指定风格，不修改 JavaScript 逻辑。修 bug：
【描述现象】请定位原因并修复，说明验证步骤。加功能：
在现有项目基础上增加【功能】，不破坏已有逻辑，说明如何测试。只问不改：
用中文解释【文件名】的结构，分页面、样式、逻辑三部分，不要改文件。写文档：
为项目写 README.md（中文），不要修改代码文件。