AIGCBot
EN领取验证清单
Codex 原理与日常使用

AI 编程助手 / 工程工作流 / LESSON 01

Codex 安装、配置与工作区模型

把仓库、AGENTS.md、权限、sandbox、配置和登录状态整理成一套可复用的 Codex 工作区模型。

阅读时间
15 分钟
学习路径
Codex 原理与日常使用
内容来源
Codex 专题教程

预计阅读时间: 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 每次工作时都可以从这些稳定入口恢复上下文。

参考资料