1. Codex 是什么？

Codex App 是 OpenAI 在 2026 年 2 月推出的一款桌面级 AI 编程助手。

Codex 不是普通的聊天机器人，而是一个可以真正读取、编辑、测试你电脑上代码的 AI 智能体。

我们可以用中文或英文描述你想做的事， Codex 自己去打开文件、写代码、跑测试、告诉你改了什么，最后等你审核通过再提交。

Codex App 与普通 ChatGPT 的区别：

2. Codex App 能做什么？

• 代码生成：从零用自然语言描述，生成完整的功能、组件或整个项目骨架。

• Debug（调试）：把报错信息粘贴进去，或截图发给 Codex，它会定位问题并修复。

• 重构（Refactoring）：让它整理凌乱的代码、拆分大函数、统一命名规范。

• 写测试：让它为你的函数写单元测试，并自动运行验证通过。

• 代码解释：看不懂某段代码？让 Codex 逐行解释。

• 多 Agent 并行工作：同时让多个 AI 处理不同任务，互不干扰。

• 自动化定时任务设定定时任务：让 AI 每天自动跑特定工作流程。

• Computer Use（电脑操控）：让 AI 像人一样点击、打字，操控你电脑上的 GUI 应用。

3. 准备工作：账号与套餐

开始使用前你需要一个 ChatGPT 账号，Codex App 和你的 ChatGPT 账号绑定，没有独立订阅，前往 https://chat.openai.com 注册即可。

注意：也可以用 OpenAI API Key 登录，但部分功能（如 Cloud 模式）不可用，建议用 ChatGPT 账号登录。

用的不多的，Free 够体验使用了。

用量说明：

• 用量以 5 小时滚动窗口 为单位，到时自动重置
• 本地任务（Local）和云端任务（Cloud）共享同一个额度池
• 超限后可以等重置，或购买额外 Credits 继续用
• 复杂任务（多文件修改 + 测试）消耗的额度远多于简单任务

4. 下载与安装

系统支持

• macOS 版：芯片 Apple Silicon（M1、M2、M3 及以上）或 Intel，macOS（推荐 Sequoia 15.x 及以上）

• Windows 版：Windows 10/11 64 位
• Linux 用户：可使用 Codex CLI。

下载页面：https://developers.openai.com/codex/app

• macOS（Apple Silicon）：点击 "Download for macOS (Apple Silicon)"
• macOS（Intel）：点击 "Download for macOS (Intel)"
• Windows：点击 "Download for Windows"

macOS 安装步骤：

1. 下载完成后，双击 .dmg 文件
2. 将 Codex 图标拖入 Applications（应用程序）文件夹
3. 打开 Launchpad，找到 Codex，点击启动

如果 macOS 提示"无法验证开发者"：

1. 前往 系统设置 → 隐私与安全性
2. 找到关于 Codex 的提示，点击 "仍然打开"
3. 再次启动 Codex App 即可

Windows 安装步骤：

1. 运行下载的 .exe 安装程序
2. 按照安装向导点击 Next 完成安装
3. 从开始菜单或桌面快捷方式启动 Codex

5. 首次启动与界面认识

启动 Codex App 后，你会看到登录界面，有两个选项：

• 推荐选项：用 ChatGPT 账号登录点击 "Sign in with ChatGPT"，浏览器会打开 OpenAI 登录页，授权后自动回到 App。

• 备选选项：用 API Key 登录如果你有 OpenAI API Key，可以直接输入。

登录 ChatGPT 账号即可使用。

界面说明：

左下角是设置按钮：

常规设置都在这里，比如语言：

关键区域说明：

侧边栏（左侧）：

• 列出你所有的项目（Projects）
• 可以切换不同任务而不丢失上下文

主内容区（中间）：

• 显示当前项目的对话历史
• AI 的回复、代码修改计划都在这里

Diff 审查面板：

• AI 做完改动后，这里会显示改了什么 vs 原来是什么
• 类似于 Git 的 diff 视图，改动一目了然

内置终端

• 每个线程有自己的终端
• 可以直接在里面运行命令，无需切换到外部终端

输入框（底部）

• 输入你的指令 / 问题
• 支持 @ 文件名 来引用特定文件作为上下文
• 支持拖拽图片、截图进去

6. 核心概念：项目

项目对应你电脑上的一个文件夹。

• Codex App 里的每个项目 = 你选定的一个本地目录
• 同一个代码库可以有多个独立的任务线程
• 项目配置（比如 AGENTS.md）存在项目目录里

如何新建项目：

1. 点击侧边栏左上角的 "+" 号
2. 选择 "使用现有文件夹"，选择你的项目文件夹
3. Codex 会读取该目录的结构

三种执行模式：

Local（本地模式）

• AI 在你的机器上工作
• 直接访问你的文件系统
• 适合日常开发，实时看到变化
• 不需要 GitHub

Cloud（云端模式）

• 任务发送到 OpenAI 的服务器执行
• 你可以关掉电脑，等它做完
• 需要连接 GitHub 仓库
• 适合长时间复杂任务

Worktree（工作树模式）

• Codex 把当前分支克隆到一个隔离的 Git Worktree
• 两个线程可以在同一个仓库工作而不互相覆盖
• 相当于 AI 在自己的分支上工作，你的主分支不受影响
• 做完后 review 再合并

刚开始学习，可以先用 Local 模式，简单直接。等熟悉了再试 Cloud 和 Worktree。

7. 第一个任务：Hello World 实战

我们来做第一个真实任务，从头体验完整流程。

1、准备一个项目文件夹

在你的电脑上新建一个空文件夹，例如：

• macOS：~/Documents/my-first-codex-project
• Windows：C:\Users\你的用户名\Documents\my-first-codex-project

2、在 Codex App 中打开这个文件夹

• 打开 Codex App
• 点击侧边栏的 "+" → "使用现有文件夹"
• 选择刚才新建的文件夹

3、确认模式为 Local

在界面顶部，确保模式选择器显示为 "本地模式"（不是 Cloud 或 Worktree）。

4、发送你的第一条指令

在底部输入框输入以下内容，然后按回车或点击发送：

创建一个 Python 脚本 hello.py，要求：- 输出"Hello, Codex！"- 然后打印当前日期和时间- 写好注释，方便初学者看懂

完成后运行一次，确认输出正确。

5、观察 Codex 的工作过程

发送后，你会看到 Codex 开始运作：

• 分析阶段：Codex 读取你的指令，显示它的计划
• 执行阶段：AI 创建 hello.py 文件，在终端运行它
• 展示结果：在 Diff 面板显示新建的文件内容，在终端显示运行输出

整个过程大约 30 秒到几分钟，取决于任务复杂度。

鼠标移动到该文件名上或点击文件，查看改动。

6、查看改动

任务完成后，点击 Diff 面板，你会看到类似这样的内容：

绿色 + 表示新增的内容，我们也可以追加修改内容：

这样我们就完成了第一个 Codex 任务！

8. 写好提示词：四要素模型

Codex 不需要你写完美的提示词就能工作，但结构化的提示词能让结果更准确、更省额度。

官方推荐的四要素模型：

要素 1：目标（Objective）

做什么，用简洁的一句话说清楚。

• 差的写法：帮我搞一下登录

• 好的写法：为 Express.js 应用添加 JWT 用户登录接口，路由为 POST /api/login

要素 2：上下文（Context）

哪些文件、文档、错误信息是相关的，用 @文件名 引用具体文件。

相关文件：

相关文件：- @src/routes/auth.js（现有认证路由）- @models/User.js（用户模型）- @package.json（依赖列表）错误信息：TypeError: Cannot read property 'id' of undefined，出现在 auth.js 第 42 行

要素 3：限制条件（Constraints）

不能做什么，有什么约束：

限制：- 不要修改现有的 /api/register 接口- 使用项目现有的 bcrypt 版本，不要升级- 保持错误格式与其他接口一致：{ error: "..." }

要素 4：完成标准（Done When）

告诉 Codex 如何验证自己的工作，完成标准：

完成标准：- 运行 npm test 所有测试通过- 用 curl 测试正确凭证返回 200 和 token- 用错误凭证测试返回 401

把四要素组合起来：

【目标】为 Express.js 应用添加 JWT 用户登录接口，路由为 POST /api/login。【上下文】相关文件：@src/routes/auth.js、@models/User.js、@config/jwt.js依赖库：jsonwebtoken 和 bcryptjs 已安装（见 @package.json）【限制】- 不要修改 /api/register 接口- Token 有效期设为 7 天- 错误响应格式与项目保持一致：{ "error": "描述" }【完成标准】- 运行 npm test，登录相关测试全部通过- 手动测试：正确密码返回 200 + JWT token；错误密码返回 401

9. AGENTS.md：给 AI 的说明书

AGENTS.md 是放在项目根目录的一个 Markdown 文件，Codex 每次启动时都会自动读取它。

把它想象成给 AI 的说明手册：我们不需要每次都重复说"我们用 TypeScript"、"测试用 Jest"、"提交信息要用英文"……这些一次性写进 AGENTS.md，Codex 以后每次自动遵守。

我们可以在项目根目录创建一个名为 AGENTS.md 的文件（注意大写）。

可以参考以下模板：

# 项目说明这是一个用 React + Node.js 开发的待办事项 Web 应用。## 技术栈- 前端：React 18，TypeScript，Tailwind CSS- 后端：Node.js 20，Express 4，Prisma ORM- 数据库：PostgreSQL- 测试框架：Jest（后端）+ Vitest（前端）- 包管理：npm## 常用命令- 启动开发服务器：`npm run dev`- 运行后端测试：`npm run test:backend`- 运行前端测试：`npm run test:frontend`- 类型检查：`npm run typecheck`- 格式化代码：`npm run format`## 代码规范- 所有变量和函数名用英文，注释可以用中文- 组件文件名用 PascalCase（如 UserCard.tsx）- 工具函数用 camelCase- 不要使用 `any` 类型，必须明确指定 TypeScript 类型- 每个函数需要 JSDoc 注释## 目录结构- `src/` - 前端源码- `server/` - 后端源码- `prisma/` - 数据库 Schema- `tests/` - 测试文件## 工作规则1. 改动前先理解相关文件的现有逻辑2. 每次改动必须运行测试，确保全部通过再结束3. 不要修改 `prisma/migrations/` 目录里的文件4. API 新增接口必须同时写对应的单元测试5. 提交信息格式：`类型(范围): 描述`（如 `feat(auth): add JWT login`）## 安全注意事项- 不要在代码里硬写任何 API Key 或密码- 所有敏感配置通过 `.env` 文件管理- 不要修改 `.env.example` 里已有的键名

10. 审查 Diff：掌控每一行改动

Codex 做完任务后，你必须审查 Diff，这是保持代码质量的关键环节。

Diff 面板用颜色标注改动：

• 灰色：未改动的行

• 红色/- ：被删除的旧代码

• 绿色/+ ：新增的代码

审查流程：

• 逐文件查看：点击侧边栏每个被改动的文件

• 理解每处改动：不要盲目接受，不懂的改动可以问 Codex 解释

• 发现问题：直接在 Diff 面板上点击对应行，留下反馈意见

• 接受/拒绝：满意整体改动 → 点击 Accept All

• 只接受部分文件：逐文件选择 Accept / Reject

• 发现问题需要修改：在对话框继续追加指令

• 完全不对：点击 Discard All

使用 /review 命令：

在输入框输入 /review，Codex 会以代码审查者的视角检查自己的改动，主动指出潜在问题。

11. 内置终端：边写代码边测试

每个 Codex 都有独立的内置终端，你和 AI 可以共用这个终端。

终端的用途，手动测试你的代码

# 运行测试npm test# 启动开发服务器npm run dev# 查看日志tail -f logs/app.log

查看 AI 刚刚运行的命令AI 运行过的每个命令都会出现在终端历史里，透明可见。

修正 AI 的错误如果 AI 跑错了命令，你可以直接在终端手动修正，然后告诉 AI 结果。

12. Skills（技能）：让 AI 变得更专业

一个 Skill 就是一个可重复使用的工作流程包。

场景举例：你的项目每次新建 React 组件都需要：创建文件、写组件模板、加单元测试、更新 index.ts 导出、写 Storybook。这些步骤每次都一样，但每次都要跟 AI 解释一遍很烦。把这个流程做成一个 Skill，以后只需要说"帮我新建一个 Button 组件"，Codex 自动按照你定义的完整流程来执行。

Skills 的存放位置：

• 个人技能（只有你用）：~/.agents/skills/目录
• 团队技能（整个项目共用）：项目根目录下的 .agents/skills/ 目录

创建你的第一个 Skill：

以"新建 React 组件"为例：

第一步：创建目录

mkdir -p ~/.agents/skills/new-react-component

第二步：在该目录创建 SKILL.md 文件

---name: new-react-componentdescription: 当用户要求新建 React 组件时使用此技能。触发词：新建组件、create component、新增组件。不要在非 React 项目中使用。---# 新建 React 组件流程## 步骤1. 在 `src/components/` 目录下创建组件目录：`组件名/`2. 创建主组件文件：`组件名/index.tsx`   - 使用函数式组件   - 定义 Props 接口   - 导出具名导出和默认导出3. 创建测试文件：`组件名/组件名.test.tsx`   - 至少写 3 个测试：渲染测试、Props 测试、交互测试4. 创建 Storybook 文件：`组件名/组件名.stories.tsx`5. 在 `src/components/index.ts` 中添加导出## 命名规范- 组件名：PascalCase（如 UserCard、LoginForm）- 文件名与组件名一致- Props 接口：`组件名Props`（如 UserCardProps）## 模板组件文件参考：```typescriptimport React from 'react';interface ButtonProps {  label: string;  onClick: () => void;  variant?: 'primary' | 'secondary';}export const Button: React.FC = ({ label, onClick, variant = 'primary' }) => {  return (      {label}  );};export default Button;```## 完成标准运行 `npm test` 新组件测试全部通过后才算完成。

第三步：在 Codex 里使用这个 Skill方法 1（显式调用）：

使用 $new-react-component，帮我新建一个 SearchBar 组件， 需要支持防抖输入和清除按钮。

方法 2（隐式触发）：

帮我新建一个 SearchBar 组件，需要支持防抖输入和清除按钮。

13. Automations（自动化）：让 AI 帮你定时跑任务Automations 让你设定一个计划任务，Codex 按照你的计划时间自动执行，不需要你手动触发。

常见用途：

- 每天早上 9 点自动拉取 GitHub 上的新 PR，生成摘要- 每小时检查 CI 是否失败，失败了自动尝试修复- 每周一自动整理 TODO 注释，生成任务列表

可以通过聊天让 Codex 帮你创建，也可以自己创建：

 14. Git 与 Worktree：并行工作不出错

Codex App 内置了完整的 Git 操作界面，不需要切换到终端：

• 查看改动文件列表
• 分文件查看 Diff
• Stage 暂存区操作
• Commit（提交）并附上 AI 生成的提交信息
• Push 推送到远程
• 创建和管理 Pull Request

工作树（Worktree），什么情况用 Worktree：

• 你想让两个 AI 同时在同一个仓库做不同的任务
• 你担心 AI 的改动影响你的当前工作

Worktree 的工作原理： Codex 把你的当前分支克隆到一个隔离的 Worktree（本质上是一个独立的 Git 分支），AI 在那里工作，你的主分支完全不受影响，等 AI 做完，你 review 之后再合并。

如何使用 Worktree：

• 新建线程时，在模式选择器里选 "Worktree"

• 系统自动创建隔离环境

• 任务完成后，点击 "Merge" 或生成 PR

典型的 Git 工作流程：

1. 新建 Worktree 线程   ↓2. 给 AI 分配任务："实现用户头像上传功能"   ↓3. AI 在 Worktree 里开发（你可以同时干别的）   ↓4. AI 完成，通知你 review   ↓5. 查看 Diff，确认代码正确   ↓6. 点击 Create PR 或 Merge   ↓7. 推送到 GitHub，走正常 review 流程

Local 模式适用场景：

• 日常快速任务（几分钟内能完成的）

• 需要频繁跟 AI 来回对话的任务

• 不想连接 GitHub 的情况

• 直接操作你本地的文件、实时看到进度、任务在你的机器上跑。

Cloud 模式适用场景：

• 长达数小时的复杂任务

• 你需要关电脑或去做别的事

• 已经和 GitHub 连接

• 任务在 OpenAI 服务器上运行，可以关掉电脑、手机上查看进度，需要 GitHub 连接（AI 从 GitHub 拉代码，改完推回去）

• 比较适合批量处理、大型重构

16. Computer Use：让 AI 操控你的电脑

Computer Use 是一个让 Codex 像人一样操控图形界面（GUI） 的功能。AI 可以看到你的屏幕，然后移动鼠标、点击按钮、输入文字。

典型用途：

• 在没有 API 的 GUI 工具里操作（比如某个桌面软件）

• 测试你写的桌面应用的 UI

• 重现只在界面上出现的 Bug

• 操控浏览器做需要登录的任务（配合 Chrome 插件）

安装与开启：

第一步：安装 Computer Use 插件

• 打开 Codex 的 Settings（设置）

• 找到 Computer Use 选项

• 点击 Install 安装插件

第二步：授予权限（macOS）

• 弹出提示时允许 屏幕录制（Screen Recording） 权限

• 允许 辅助功能（Accessibility） 权限

第三步：使用

• 在提示词里加上 @Computer 或 @应用名：@Computer 帮我打开 Finder，找到 Downloads 文件夹里最新的 PDF，然后截图发给我。

17. MCP 服务器：连接外部工具

MCP（Model Context Protocol）是一个开放标准，让 Codex 连接到外部工具和服务，从而获取那些不在你代码仓库里的信息。

比如：你要让 Codex 根据 Jira 上的需求文档来写代码，而不是每次手动复制粘贴——就可以用 MCP 连接 Jira，让 Codex 直接读取。

常见 MCP 连接场景：

• Jira / Linear：让 AI 直接读取 Issue 里的需求

• Slack：读取频道里的讨论上下文

• GitHub：深度集成 PR、Issue

• 数据库：直接查询数据库 Schema

• 文档系统（Notion、Confluence）：读取设计文档

添加 MCP 服务器可以在 Codex App 设置里配置

• 打开 Settings → MCP Servers

• 点击 Add，填入 MCP 服务器地址

18. 移动端远程操控

Codex 支持通过 ChatGPT 手机 App 远程控制桌面端的 Codex。

应用场景：

• 出门在外，手机上检查 AI 进度

• 在手机上批准 AI 提交的改动

• 远程启动一个新任务

设置步骤：

• 手机上安装 ChatGPT App（iOS 或 Android）

• 用相同的 OpenAI 账号登录

• 在桌面 Codex App 里，找到 Codex Mobile 配对选项

• 扫描 QR 码配对

配对后，你可以在手机上看到所有线程的状态，发送新指令，批准或拒绝 AI 的改动。

移动端下载地址：https://chatgpt.com/zh-Hans-CN/codex/mobile/