一、核心定位与入口
Codex 是直接在你的代码仓库里干活的 AI 工程师，可理解、编辑、调试、重构、写单测、写文档。
入口：
Web：chatgpt.com/codex（绑定 GitHub）
IDE：VS Code 扩展「OpenAI Codex」

VS Code OpenAI Codex 扩展
CLI：npm i -g @openai/codex / brew install --cask codex

二、Prompt 写法（决定 80% 效果）
1）范围锁死（最重要）
用 @文件名 或直接写路径，不要让它全仓库乱找。
示例：
plaintext
只看 @src/pages/login.tsx 和 @src/hooks/useAuth.ts
修复登录态时序 bug，不要改其他文件
2）状态说清：只读 / 修改 / 先计划
只读分析：先不要改代码，只输出问题分析和修复思路
改前先计划：可以修改，但动手前先给我变更计划（文件+步骤）
直接动手（小改动）：直接修改并解释变更点
3）验收标准明确
必须包含：改什么、涉及文件、如何验证完成。
示例：
plaintext
给 utils/date.ts 补全 ISO 日期格式化函数
要求：兼容 UTC、写 Jest 单测、注释英文、函数纯
完成标准：npm test 全部通过
4）结构像 GitHub Issue
写清：背景、当前行为、期望行为、相关文件、参考代码片段。

三、必用的内置命令（CLI/IDE）
/plan：先生成执行计划，确认后再执行（大重构必备）
/init：自动生成 AGENTS.md 模板OpenAI
/fork：分叉对话，并行试不同方案，保留上下文
/model：切换模型（如 gpt-5.4、o3）
/clear：清空本轮上下文（不丢会话）
/resume：恢复历史会话

四、AGENTS.md：把规则固化，少写重复 Prompt
放在仓库根目录，Codex 会自动加载，优先级高于临时 PromptOpenAI。
核心内容（控制在 100–300 行）
仓库结构、关键目录
启动 / 构建 / 测试 / 格式化命令
代码规范（命名、注释、函数长度、类型）
禁止项（如禁止 default 参数、禁止 any）
完成标准与验证方式OpenAI
示例片段
plaintext
## 代码规范
- 所有函数必须显式类型标注（TS）
- 注释只用英文
- 函数≤80行，组件≤300行，否则拆分
- 禁止 any、禁止 default 参数

## 工作流
- 改后必须 npm run lint && npm test
- 禁止自动 commit/push
嵌套目录可放子 AGENTS.md，子目录优先级更高。

五、IDE 高效用法（VS Code）
安装扩展后登录，底部选模型。
选中代码 → 右键「Ask Codex」→ 直接重构 / 解释 / 转 TS / 加单测。
用 @ 在聊天框直接引用文件，自动带上下文。
开启「Auto-Apply」（谨慎），小改动自动写入；大改动先看 Diff。

六、CLI 常用命令（脚本 / 自动化）
bash
运行
codex                    # 启动交互 TUI
codex "任务描述"         # 直接执行任务
codex exec "写文档"      # 非交互（适合 CI）
codex -m o3 "重构"       # 指定模型
codex --sandbox read-only # 只读模式（安全）
codex resume --last      # 恢复上次会话

七、高级技巧：Skills + MCP
1）Skills：可复用工作流
把高频任务（如安全审查、性能优化）封装成 Skill，一键调用。
plaintext
Use $security-review to check current diff for XSS/SQLi/权限漏洞
2）MCP：连接外部工具
通过 Model Context Protocol 接入：
实时文档（避免过时训练数据）
Jira/GitHub Issues
设计稿、API 文档、内部系统

八、避坑指南（新手最常踩）
不要一次丢太大任务：控制在几百行 / 1 小时工作量，否则容易乱改。
必看 Diff 再确认：Codex 可能幻觉、漏依赖、改错逻辑。
环境要对：确保依赖安装、环境变量正确、可联网（影响成功率）。
不要全自动化：--full-auto 风险高，仅用于信任的小仓库。
规则别写太泛：AGENTS.md 要可验证，别写 “写高质量代码” 这种空话。

九、最佳实践总结
小步快跑：拆分任务、先计划、再执行、每步验证。
规则固化：用 AGENTS.md 沉淀规范，减少重复 Prompt。
范围精准：用 @文件 锁定上下文，避免全仓库搜索。
人机协作：Codex 写代码、你审逻辑、共同调试。