The reviewed guide body for this track is currently maintained in Chinese.
预计阅读时间: 15 分钟
会用 Codex 的关键，不只是安装成功，而是让它进入一个稳定、可审查、可重复的工作区。工作区模型由五件事组成：仓库状态、项目规则、权限模式、外部上下文和验证命令。
这一篇按“从单人本地使用到可复用项目配置”的顺序展开。
第一步：确认你在哪个仓库工作
每次交给 Codex 任务前，先确认三件事：
pwd
git status --short --branch
ls
这不是仪式感，而是避免三类事故：
- 在错误目录里改文件。
- 覆盖别人或自己未提交的工作。
- 在没有 Git 保护的临时目录里做不可追踪的大修改。
如果工作区已经有未提交改动，Codex 应该先识别哪些是本轮任务相关、哪些是已有改动。除非你明确要求，它不应该重置、回滚或清理用户已有变更。
第二步：建立 AGENTS.md
AGENTS.md 是 Codex 进入仓库时自动读取的项目说明。它应该短、准、可执行。一个起步版本可以是：
# AGENTS.md
## Project
- This is a Next.js static export site.
- Public routes must keep the ICP footer.
- Prefer existing components and data structures.
## Commands
- Run `npm run lint` after TypeScript or component edits.
- Run `npm run build` before deployment.
## Editing rules
- Use focused patches.
- Do not revert user changes unless explicitly asked.
- Sync product decisions into `openspec/` or `docs/` when they affect planning.
好规则有三个特点：
- 能被执行，而不是价值观口号。
- 能被验证，比如“运行哪个命令”。
- 能减少重复沟通，比如“备案号不可移除”。
第三步：理解权限和 sandbox
Codex 的权限通常由 sandbox 和 approval policy 两层控制：
| 层 | 控制什么 | 典型问题 |
|---|---|---|
| sandbox | 技术上能读写哪里、能不能访问网络 | 能否写工作区外文件，能否联网安装依赖 |
| approval policy | 什么动作需要先问你 | 修改服务器、用网络、执行高风险命令是否要确认 |
日常开发推荐从工作区写入开始。只有在明确需要时才放开网络或服务器权限。生产操作要更严格：先备份、再测试配置、再 reload 或切换版本，最后做外部验证。
第四步：配置 Codex 的个人默认值
不同界面会共享部分 Codex 配置。个人默认值适合放在 ~/.codex/config.toml，项目默认值适合放在仓库的 .codex/config.toml。常见配置包括：
sandbox_mode = "workspace-write"
approval_policy = "on-request"
[sandbox_workspace_write]
network_access = false
不要把所有任务都默认设成最大权限。更好的做法是按任务需要临时提升，或者为安全边界清楚的场景建立 profile。
第五步：把外部上下文接入 MCP
当上下文不在仓库里时，不要长期依赖复制粘贴。MCP 更适合接入：
- GitHub issue、PR、review 线程。
- Notion、Google Drive、设计稿或内部文档。
- 监控、日志、工单和知识库。
- 官方文档检索。
接入 MCP 前先问一个问题：这个工具是否能明显减少反复复制信息的成本？如果只是偶尔用一次，直接贴上下文更轻。
第六步：定义项目的完成标准
Codex 最怕“差不多就行”。你应该在项目里明确 done criteria：
## Done means
- The requested behavior is implemented.
- `npm run lint` passes.
- `npm run build` passes before deployment.
- Public pages keep the ICP footer.
- Deployment changes are verified with live `curl` checks.
完成标准越明确，Codex 越能自己闭环。否则它只能停在“我改好了，你看看”。
第七步：准备回滚和审查路径
Codex 写代码很快，审查路径更要稳：
- 保持 Git 状态可见。
- 让每次变更都能用
git diff看清楚。 - 复杂任务拆成小提交。
- 部署用 release 目录或可回滚版本。
- 对生产配置先
nginx -t或等价检查，再切换。
如果你把 Codex 接到服务器，建议每次部署保留：
release stamp
build command
rsync or upload path
symlink switch result
live endpoint checks
这样出问题时能知道是哪一版、怎么回去。
一个最小可用工作区模板
repo/
AGENTS.md
package.json
src/
docs/
openspec/
ops/
AGENTS.md 说明工作方式，docs/ 和 openspec/ 记录产品与设计决策，ops/ 保存部署资产。Codex 每次工作时都可以从这些稳定入口恢复上下文。
参考资料
- OpenAI Codex Manual: https://developers.openai.com/codex/codex-manual.md
- Custom instructions with AGENTS.md: https://learn.chatgpt.com/docs/agent-configuration/agents-md
- Config basics: https://learn.chatgpt.com/docs/config-file/config-basic
- Agent approvals and security: https://learn.chatgpt.com/docs/agent-approvals-security