Codex 使用说明

一份面向日常项目协作的实用指南。

Codex 是 OpenAI 的编程助手，可以理解代码、修改文件、运行命令、做代码审查、调试问题，并把结果落到真实项目里。它可以在桌面 App、网页/云端、CLI 终端、IDE 插件等环境中使用。

1. 什么时候用 Codex

适合用 Codex 的任务：

• 阅读陌生项目：解释目录结构、关键模块、运行方式。
• 修改代码：实现功能、修 bug、调整 UI、补测试。
• 调试报错：根据日志定位原因并尝试修复。
• 代码审查：检查当前改动、PR、分支或某些文件。
• 批量整理：重构、迁移 API、更新文档、清理重复逻辑。
• 生成交付物：报告、表格、幻灯片、可视化结果、网页原型等。

不建议直接交给 Codex 的任务：

• 目标极其模糊，比如“优化一下项目”，但没有说明优化什么。
• 需要访问敏感系统、生产数据库、密钥、付款、删除数据等高风险操作。
• 你还没有备份或没有版本管理的项目。

2. 基本使用流程

1. 打开项目
   在 Codex 桌面 App、CLI 或 IDE 插件里打开你的项目目录。

2. 先让它了解上下文
   可以先让 Codex 阅读项目并说明技术栈、目录结构、启动方式和关键模块。

3. 明确任务
   说明目标、范围、限制、验证方式和期望输出。

4. 让它执行并验证
   Codex 可以读文件、改文件、运行本地命令和测试。

5. 审查结果并迭代
   查看总结、文件改动和测试结果，不满意时继续追问。

3. Codex 菜单和界面速查

不同版本的 Codex App 菜单名称可能略有调整，但常见入口可以按下面这几类理解。

入口/菜单	主要作用	适合怎么用
新建任务 / New chat	开启一个新的 Codex 任务或对话。	适合开始一个独立目标，比如“修复登录 bug”或“阅读这个项目”。
快速对话 / Quick chat	快速问一个问题，不一定要展开成长任务。	适合问概念、查某个文件含义、确认思路。
项目 / 工作区	选择当前任务能看到的文件、目录和上下文。	开始正式改代码前，先确认打开的是正确项目目录。
任务列表 / 侧边栏	切换、查看、继续不同任务。	多个需求并行时，用任务列表区分上下文。
输出文件 / Outputs	查看 Codex 生成的文档、表格、图片、网页、报告等交付物。	让 Codex 输出可交付文件时，优先放到 outputs 目录。
终端 / 命令输出	查看 Codex 运行测试、构建、启动服务时的结果。	可以让 Codex 总结关键结果，不必自己逐行看日志。
权限 / Approvals	批准访问网络、安装依赖、修改受限文件或执行敏感操作。	看到权限请求时，先看清楚它要做什么、为什么需要。
浏览器 / Browser	让 Codex 打开网页、测试网页应用、查阅在线资料。	适合做页面验收、网页自动测试、查最新官方资料。
Computer use / 使用电脑	让 Codex 控制桌面应用，点击、输入、检查界面。	适合跨应用操作，但涉及账号、付款、隐私时要谨慎。
设置 / Settings	管理模型、权限、记忆、插件、技能、连接器等偏好。	当 Codex 行为不符合预期时，先检查这里。
插件 / Plugins	给 Codex 增加一整套外部能力、工具或工作流。	适合连接 GitHub、Slack、Linear、专用业务系统等。
技能 / Skills	保存可复用的专业工作方法和材料。	适合重复任务，比如“每周生成经营分析报告”。
自动化 / Automations	定时提醒、监控、周期性检查或长任务跟进。	适合日报、周报、定期扫描、到点提醒。
代码审查 / Review	以审查视角检查代码改动。	让 Codex 先找风险和缺测试，再决定是否修改。

4. 常用指令模板

解释项目

帮我快速理解这个项目：技术栈、目录结构、启动方式、核心业务流程、最值得注意的风险点。

修 bug

请根据这个报错定位问题并修复。修复时尽量保持改动最小，最后运行相关测试。
报错如下：
...

实现功能

请实现 [功能描述]。
要求：
- 遵循现有代码风格
- 不引入新依赖，除非确实必要并先说明原因
- 补充或更新测试
- 完成后总结改动和验证结果

代码审查

请 review 当前未提交改动，重点看 bug、回归风险、边界情况和缺失测试，不要直接修改代码。

前端页面

请实现这个页面/组件。
要求：
- 保持现有设计系统
- 移动端和桌面端都要适配
- 文案不要溢出或重叠
- 启动本地预览并检查页面是否正常

数据/文件处理

请读取这些文件，整理出一份清晰的分析结果。不要改动原始文件，输出可复查的结果文件。

菜单问题

请说明当前界面里这些菜单分别是做什么的，并告诉我完成这个任务应该点哪个入口。

技能问题

请判断这个任务是否适合做成 Skill。如果适合，请帮我设计 Skill 名称、触发场景、步骤和需要的参考资料。

5. Skills（技能）怎么理解

Skill 可以理解为“Codex 可重复调用的一套工作方法”。普通提示词只在当前任务里生效；Skill 更适合保存成长期可复用的能力。

概念	作用	例子
普通提示词	一次性告诉 Codex 怎么做。	“这次请用中文回答。”
AGENTS.md	给某个项目的长期规则。	“这个仓库改 TS 后必须运行 npm test。”
Skill	给某类重复任务的专门流程、资料和脚本。	“每次做财务模型审查都按这套清单检查。”
Plugin	可安装的一整包能力，可能包含技能、工具、MCP、命令、UI 等。	“安全扫描插件”“React Native 插件”。
MCP / Connector	连接外部工具或私有数据源。	GitHub、Slack、Notion、内部数据库。

6. 当前常见 Skill 类型

• 文档技能：生成报告、PRD、会议纪要、学习笔记、说明书。
• 数据技能：清洗表格、分析 CSV、生成图表、做财务模型。
• 图片技能：生成或编辑位图、产品图、插画、纹理、页面视觉素材。
• 代码技能：创建项目、迁移接口、写测试、审查安全风险。
• 插件/技能创建技能：帮你创建新的 Codex Skill 或 Plugin。
• 官方文档技能：查 OpenAI / Codex 最新官方说明，避免靠旧记忆回答。

在本次环境中，可用的系统技能包括：imagegen、openai-docs、plugin-creator、skill-creator、skill-installer。实际可用技能会随你的安装、账号、工作区策略和任务环境变化。

7. 怎么让 Codex 使用 Skill

• 直接点名：例如“用 imagegen 帮我生成一张产品主图”。
• 用 $SkillName：例如“$openai-docs 查一下 Codex 当前说明”。
• 描述任务场景：如果任务明显匹配某个技能，Codex 会自动选择。
• 要求沉淀成技能：当一个流程会重复出现时，可以让 Codex 把它整理成 Skill。

8. 什么时候该创建自己的 Skill

• 同类任务每周或每月都会重复。
• 任务有固定步骤、固定检查清单、固定输出格式。
• 需要带上专门术语、品牌规范、模板、样例或参考文件。
• 你希望 Codex 以后不用每次重新解释背景。

示例：

请帮我把这个重复流程做成一个 Codex Skill：
目标：每周生成运营周报
输入：销售表、客服反馈、产品更新记录
输出：一份中文周报和一页重点图表
要求：固定包含增长、风险、下周行动三部分。

9. 如何让 Codex 更稳定

给它这些信息，成功率会明显提高：

• 目标：你到底想要什么结果。
• 范围：哪些文件、模块、页面、接口在范围内。
• 限制：不能改什么、不能引入什么、要兼容什么。
• 验证：需要运行哪些测试、构建、检查命令。
• 风格：沿用现有代码风格，还是按某个新规范来。
• 输出：希望最后得到总结、diff、测试结果，还是交付文件。

10. 权限和安全

Codex 通常在受控环境里工作。常见权限模式包括：

• read-only：只能查看，不能直接改文件。
• workspace-write：可以读文件、修改工作区内文件、运行常规本地命令。
• danger-full-access：几乎不受限制，风险最高，只在明确需要时使用。

建议默认使用 workspace-write。需要访问网络、安装依赖、改工作区外文件、执行高风险命令时，再单独批准。

11. AGENTS.md：给 Codex 长期规则

如果你希望 Codex 每次进项目都遵守固定规则，可以在项目根目录放一个 AGENTS.md。例如：

# AGENTS.md

## 项目规则

- 修改 JavaScript/TypeScript 后运行 npm test。
- 不要引入新生产依赖，除非先说明原因。
- 保持现有代码风格。
- 修改用户可见行为时，更新相关文档。

也可以在全局目录放个人偏好，在项目里放项目规则。Codex 会在开始工作前读取这些说明。

12. 推荐工作习惯

• 开始前先提交或保存当前改动，方便回退。
• 一次给一个清晰任务，不要把十几个目标混在一起。
• 大改动先让 Codex 出计划，再让它分阶段执行。
• 对关键业务、支付、权限、安全相关代码，一定要求测试和 review。
• 不满意就继续追问，Codex 适合迭代式合作。

13. 一句话上手

请先阅读这个项目，告诉我如何启动、主要模块在哪里、有哪些菜单/工具可以用，以及你建议我如何让你安全地帮我修改它。