Codex / 入门
把项目导入 Codex
让 Codex 理解项目，关键不是一次性塞很多文本，而是提供仓库、规则、任务目标和验证方式。
导入项目的本质
把项目导入 Codex，不是一次性喂很多文本，而是让 Codex 在正确目录、正确权限和正确规则下读取真实仓库。
项目规则、命令、设计规范、测试要求应写进 AGENTS.md 或项目文档。任务中再补充具体目标、相关文件和验收标准。
首次读取建议
第一次让 Codex 读项目时，让它先输出理解，不要改文件。
请先不要改文件。
阅读项目根目录、package.json、路由和测试配置后输出：
- 技术栈
- 运行命令
- 主要目录
- 风险边界
- 后续任务建议导入时的边界
不要把密钥、cookie、生产数据直接交给 Codex。需要连接外部系统时，优先使用有权限边界和日志的 MCP 或受控命令。
完整使用要点
补充官方文档中容易被压缩遗漏的核心概念、操作顺序、权限边界和验证要求，方便中文学习者按页面完整学习。
导入项目的正确姿势
把项目交给 Codex 时，最重要的是让它在真实仓库和正确边界里工作。不要把大量文件粘贴到聊天里，也不要让它盲目扫描整个仓库。更好的方式是用项目根目录、AGENTS.md、README、package 或配置文件建立初始上下文。
- 首次读取：要求 Codex 先解释项目结构、运行方式、测试方式、主要目录和风险边界。
- 规则导入：把团队命令、设计约束、禁止事项、提交格式放进 AGENTS.md。
- 范围导入：任务里明确相关路径，例如 src/auth、routes/api、tests/auth。
- 敏感边界：不要导入密钥、cookie、客户数据或生产连接串；需要访问外部系统时使用受控工具。
导入后第一步最好是只读分析。等 Codex 能准确说出项目如何运行、要修改哪些文件、如何验证后，再允许它编辑。
学习检查清单
把本页内容落到真实任务中，用入口、上下文、权限、验证和团队规则五个维度检查是否真正掌握。
学习检查清单
读完本页后，不要只记住概念名。你应该能把“把项目导入 Codex”放回 Codex 的真实工程流程里：任务从哪里发起，系统会加载什么上下文，哪些动作需要审批，结果如何验证，失败时如何回退。
如果这是概念页面，要特别确认它如何影响真实任务：它改变上下文、权限、执行路径、验证方式，还是改变团队协作流程。
- 能用自己的话说明本页解决的具体问题，而不是只复述标题。
- 能写出一个最小示例任务，并标明目标、范围、禁止事项和验收标准。
- 能判断哪些信息应该放进当前提示，哪些应该沉淀到项目规则或配置里。
- 能说明哪些长期规则应该写进 AGENTS.md，哪些运行行为应该交给 config.toml、permission profile、skills 和 MCP。
- 能在任务完成后检查 diff、命令输出、测试结果、截图或 PR 说明，而不是只相信自然语言总结。
如果要把本页用于团队培训，可以让学员用 Codex 完成一个小任务：先只读解释，再提交计划，再执行最小改动，最后用真实验证命令和人工 diff 审查收尾。
Codex 实操注意事项
围绕本地环境、权限升级、远程入口、自动化失败和回滚补齐 Codex 使用中最容易被忽略的执行细节。
Codex 实操注意事项
这一页属于 Codex 的核心概念。学习时要把概念和真实执行联系起来：它会改变上下文、权限、任务拆分、验证路径，还是改变团队协作方式。
处理“把项目导入 Codex”相关任务时，建议始终先确认当前 Git 状态和工作目录。Codex 可以很快完成修改，但它不会自动知道哪些未提交改动来自用户、哪些文件不能碰、哪些命令会影响生产环境。
- 本地任务优先使用低风险分支或工作树，完成后用 git diff 审查。
- 涉及安装依赖、联网、数据库、部署、push、删除、reset 时，先要求 Codex 解释影响再批准。
- 远程或协作入口生成的结果，也要回到 PR、CI、构建日志和测试证据中确认。
- 自动化任务要提前定义失败输出和退出条件，避免 Codex 在错误方向上反复尝试。
把 Codex 当成能执行命令的工程队友，而不是只会写文本的助手。越靠近真实系统，越需要明确边界、证据和回滚。