代理循环

每一轮，Codex 都跑同一个循环。理解它，是你能做的最高杠杆的一件事：

读 → 推理 → 提议 → 批准 → 应用 → 验证 循环

1. READ       —— 加载相关文件、git 状态、之前几轮
2. REASON     —— 决定下一步（跑命令？改文件？问用户？）
3. PROPOSE    —— 抛出动作；若高风险，暂停等批准
4. APPLY      —— 执行已批准的动作
5. VERIFY     —— 重读、跑测试、检查结果
       ↺ 重复，直到目标达成或它求助

为什么重要： 聊天机器人吐文字。代理行动、观察结果、纠正方向。循环是 Codex 体现价值的地方 —— 也是 harness（AGENTS.md、配置、审批策略）塑造有效上下文和迭代质量的地方。

线程（Threads）

线程是 Codex 里对话和上下文的单位。每个线程带自己的消息历史和积累的状态。实际影响：

• 一个线程一个任务 —— 别把不相关的活堆进一个线程；上下文会腐烂。
• 恢复 —— Codex 能恢复之前的线程，接上它积累的上下文。
• 并行 —— 桌面 App 和 worktree 让多个线程同时跑而不串味（见标签页 5）。

黄金法则

Codex 是个戴着紧箍咒的能干搭档，不是许愿池。 你的活是给方向、画好它能动手的圈、跑偏时拉一把。

这一句就能预测你能否拿到好结果。Codex 不是魔法 —— 它是个需要驾驭的强执行者。给它目标（不是逐步配方），约束它能碰什么（沙盒 + 审批），它在错误假设时纠正它。

上下文窗口

每轮能装进模型工作记忆的东西

Codex 每轮的有效工作记忆是有限的。随着线程增长，早先的轮次、工具输出和文件读取会累积。两个实际后果：

• 主动 compact —— /compact 总结线程以回收空间；在质量下降之前做，而不是之后。
• “1M 上下文”不等于 1M 可用 —— 系统提示、工具定义、检索到的文件占了一大块；你任务的有效预算比标题数字小得多。

审批模式与沙盒

Codex 暴露两个独立旋钮，不是一个。这是新手最常见的混淆：

三种沙盒模式：

三种审批策略： untrusted（问得多）、on-request（日常默认）、never（仅无头/CI）。

💡 日常开发黄金组合： workspace-write + on-request。代理在你项目里自由改，出圈前暂停。

⚠️ --yolo = danger-full-access + never。它为一次性容器而存在。绝不在你真机上跑 —— 有文档记录的删用户文件案例。

模型与推理强度

两个旋钮决定”Codex 多使劲想”：

• 模型（/model 或配置里 model = "..."）—— 按能力 vs 成本选。别为琐碎编辑默认最强；别在硬重构上抠门。
• 推理强度（/effort 或强度旋钮）—— low/medium/high/xhigh。这比换模型影响更大，且调整更便宜。30 秒的重命名要 low；模块重构要 high。

把旋钮对准任务，不是对准你的心情。任务→模型+强度对照表见标签页 6 的模型选择部分。

斜杠命令

斜杠命令控制Codex 本身（切模型、清上下文、看状态），不是模型。只有 / 是消息第一个字符时才生效。打 / 看你当前入口能用什么。

日常 CLI 命令，按你在干啥分组：

⚠️ CLI 暴露 40+ 斜杠命令；桌面 App 约 6 个，IDE 约 8 个。别指望 CLI 那张全表在 GUI 界面里也有。

计划模式与提示词

先规划，再执行。 对任何不简单的事，描述目标让 Codex 出计划；review 计划，再让它执行。给目标和约束，不是逐步配方 —— 代理循环排序比你强。

提示词原则：

• 给上下文，不是更多字。 指向文件、说目标、列约束。啰嗦没用；具体才有用。
• 说不要做什么 —— 负向指令（“别碰 legacy/”、“用 pnpm 不用 npm”）比正向更锐利。
• 一条消息一个任务 —— 代理循环奖励专注；多任务提示会稀释它。

常见工作流

四个日常流：

AGENTS.md

AGENTS.md 是 Codex 的每项目指令文件 —— 每轮开始时、动手前读一遍。它是 Codex 版的 Claude Code 的 CLAUDE.md（同一概念，不同名字和发现规则）。

为什么需要它： 每轮都从白纸开始。没有 AGENTS.md，你每次都要重新解释”用 pnpm、别碰 legacy/、测试这么跑”。

发现链（3 层，就近优先）：

1. 全局 —— ~/.codex/AGENTS.md（或 AGENTS.override.md，后者胜）。你的跨项目默认。
2. 项目根 —— Git 根的 AGENTS.md。团队共享规则。
3. 子目录 —— 从根走到你当前目录，每个目录都可贡献一个 AGENTS.md。离你工作目录最近的冲突时胜。

~/.codex/AGENTS.md          ← 全局默认（你的偏好）
project-root/AGENTS.md      ← 团队规则（冲突时覆盖全局）
project-root/src/AGENTS.md  ← 子目录规则（最近胜）

💡 冲突”就近优先”解决 —— 项目规则覆盖个人偏好，子目录规则覆盖项目规则。这正是你想要的团队协作行为。

写好 AGENTS.md

最高杠杆用法： 当成反馈回路。Codex 对你代码库做了错误假设时，别只在聊天里纠正（那是一次性的）—— 让它把修正写进 AGENTS.md。几周后这文件就填满了它已被逮过的坑，新会话不再重复那些错误。

config.toml 基础

config.toml 是行为旋钮文件 —— 代理照着执行的机器设置，区别于 AGENTS.md（自然语言指导）。就像车：AGENTS.md 是车主手册，config.toml 是中控台旋钮。

两个位置：

⚠️ 信任门： 项目级 .codex/config.toml 对不信任的项目被忽略。这防止恶意 clone 的仓库偷偷给自己放权。如果你的项目配置”不生效”，检查首次打开时是否信任了它。

最小配置：

# ~/.codex/config.toml
model = "gpt-5.5"
approval_policy = "on-request"
sandbox_mode = "workspace-write"

config.toml 进阶

不改文件、按次运行覆盖：

codex -c model="gpt-5.5" -c approval_policy="never"

用 profile 在预设配置间切换：

codex --profile ci        # 加载 [profiles.ci] 块

在 workspace-write 里开网络（默认关 —— 常见坑）：

[sandbox_workspace_write]
network_access = true

配置参考

高频键：

ℹ️ 完整参考：developers.openai.com/codex/config-reference。

权限与审批策略

经上面两个旋钮配置。日常开发中，初始设置后你很少碰它 —— workspace-write + on-request 覆盖大部分活。只对受信任的、容器化的自动化放开到 never；把仓库交给 Codex 只做分析时锁到 read-only。

沙盒与审批

沙盒把文件系统写隔离到工作区，并管住网络出口。关键行为：

• workspace-write 里 .git 是只读保护 —— Codex 不会弄坏仓库元数据。
• 即使允许写，网络也默认关 —— 显式开启。
• danger-full-access 移除所有边界 —— 仅容器/虚拟机。

⚠️ Windows 警告（已核实，必须带）： 有多份报告称 Windows 上 Full Access 模式删除了用户文件（报告丢失 240–700 GB）。绝不在 Windows 上开 Full Access；用 WSL2 并留在 workspace-write。

生命周期钩子（Hooks）

管理员可经 requirements.toml 锁定 hooks：

allow_managed_hooks_only = true

这会忽略用户/项目/会话 hook 配置，同时仍允许 managed hooks。它只在 requirements.toml 里有效 —— 写进 config.toml 没用。用于企业治理（见标签页 6）。

MCP —— 外部工具

MCP（模型上下文协议） 让 Codex 调用外部工具 —— 拉实时文档、查数据库、驱动浏览器。Codex 恰好支持两种传输：

两种方式加服务器：

# CLI（最快）—— context7 = 免费开发文档服务器
codex mcp add context7 -- npx -y @upstash/context7-mcp

或手写进 config.toml：

[mcp_servers.context7]
command = "npx"
args = ["-y", "@upstash/context7-mcp"]

模型如何决定调用外部工具

💡 所有 MCP 配置都在 config.toml —— 没有 --scope。范围由你改哪个文件决定（~/.codex/ = 全局，<repo>/.codex/ = 项目，需信任）。CLI 和 IDE 共用这一份配置。

子代理（Subagents）

子代理是带自己线程、模型、指令和权限的专项代理。Codex 并行跑几个，每个只回摘要给主线 —— 把吵闹的中间产物挡在你的主上下文外。

主代理派活；子代理回摘要，不回原始输出

子代理解决两个问题：

• 上下文污染 —— 一个大任务的日志淹没主线；子代理把脏乱隔离。
• 上下文腐烂 —— 长线程退化；拆分让每个上下文短而专注。

⚠️ 反直觉： Codex 不会自动派生子代理。只有你明确开口它才派。别期待并行，除非你要求 —— 这是为了防止成本失控。

定义自定义 agent 为 TOML 文件放 ~/.codex/agents/ 或 <repo>/.codex/agents/：

# ~/.codex/agents/reviewer.toml
name = "reviewer"
model = "gpt-5.5"
instructions = "Review diffs for correctness bugs and security issues."

Agent Skills

Skill 是打包成目录（带 SKILL.md + 可选脚本/资源）的可复用工作流。写一次；Codex 按需调用。

一个 skill：带 SKILL.md 加可选脚本和参考的目录

最小 SKILL.md：

---
name: summarize-diff
description: Summarize uncommitted changes and flag risks. Use when the user asks for a change summary.
---

Summarize the diff, group changes by file, and call out anything risky
(uncommitted secrets, large deletions, test coverage gaps).

⚠️ 常见坑（来自过时教程）： frontmatter 需要 name + description —— 没有 trigger 字段。触发靠对 description 的语义匹配，不是关键词。而且目录在 .agents/skills 下，不是 ~/.codex/skills。以官方文档为准，别信老博客。

渐进式加载： 启动时 Codex 只加载每个 skill 的名称、描述和路径。完整 SKILL.md 只在 skill 被用时加载 —— 保持上下文精简。

插件（Plugins）

插件是能力的一键安装包 —— skills + agents + hooks + MCP 服务器 —— 打包成一次装一整套，而不是逐个手配。当社区或团队已组装好一套连贯工具箱时用插件；当你只需要一样东西时用单个 skill/MCP。

规则与钩子（Rules & Hooks）

规则和钩子加执行卡点和扳机：

• 规则 —— 按上下文条件加载的指令（如框架专属规则）。
• 钩子 —— 在生命周期事件（pre-tool-use、post-turn 等）触发的 shell 命令，用于确定性自动化（保存时格式化、拦命令、通知）。

钩子可在 config.toml 或按 agent 定义；企业可锁到仅 managed（见上面的 allow_managed_hooks_only 说明）。

Command → Agent → Skill 模型

Codex 的编排镜像 Claude Code 的三层模型：

选哪种扩展

为什么 Harness 重要

输出质量 = f(有效上下文, 模型能力, 迭代轮数)

harness —— AGENTS.md、配置、审批策略、skills、hooks —— 塑造有效上下文和迭代质量。仅靠提示词复制不了它：提示词是建议性的，但 harness 强制工具限制、按路径懒加载规则、调度并行子代理、跨会话持久状态。

提示词够不到的层 —— harness 替你做的事

非交互模式（codex exec）

codex exec 不开 TUI 跑 Codex —— 给提示词，它干活、打印结果、退出。为”没人盯着”的场景而生：脚本、定时任务、CI 流水线。

codex exec "总结这个仓库的结构，列出 5 个该警惕的地方"

关键设计 —— 进度走 stderr、结果走 stdout。 这刀切开，让你能把干净结果管道给下一个程序，同时屏幕上还能看进度：

# 机器可读事件流
codex exec --json "找不稳定的测试" | jq ...

# 只把最终消息存进文件
codex exec -o result.txt "为最近 10 个提交写 release notes"

⚠️ 非交互模式默认只读沙盒。要让它改文件，显式抬沙盒（-s workspace-write）和审批（完全无人值守用 -a never）。

执行策略（Execution Policy）

codex exec 可由执行策略治理 —— 基于规则的、对它无人值守时能干什么的控制。定义规则约束哪些命令可跑、哪些路径可写等。安全用于 CI 必备。

Git 与 GitHub 集成

Codex 在两条线上集成 Git/GitHub：

云端审查需要付费套餐 + 仓库授权给 Codex cloud；本地 /review 不需要那些。

经 AGENTS.md 的 Review guidelines 定制审查规则 —— 如”每条路由都要鉴权中间件”、“日志里不许有 PII”。Codex 按你的标准标违规，不是泛泛的标准。

GitHub Actions / CI

openai/codex-action 在 GitHub 托管 runner 上跑 Codex，由仓库事件（开 PR、CI 挂了）触发。它是 CI/CD 线 —— 区别于桌面 App 的本地 Automations。

最小 workflow：

# .github/workflows/codex-review.yml
on: [pull_request]
jobs:
  review:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: openai/codex-action@v1
        with:
          prompt-file: .codex/prompts/review.md
          sandbox: workspace-write

💡 两条自动化线，别混： GitHub Action（云 runner、仓库事件、团队协作）vs 桌面 App Automation（你的机器、cron 计划、私人任务）。把线对到活在哪。

Worktree —— 并行隔离

worktree 给每个 Codex 线程一份隔离的仓库文件副本（共享 .git 元数据）。这让多个任务并行跑而不互相覆盖。

git worktree add ../feature-x -b feature-x
cd ../feature-x && codex    # 在 feature-x 上隔离干活

• 同一分支不能同时在两处 worktree 检出。
• worktree + Handoff（桌面 App）在前景/背景间搬活 —— 如把长重构甩进背景 worktree 跑，你前景继续写。
• 定期清理陈旧 worktree —— 每个都持有一份完整文件副本。

自动化任务（Automations）

桌面 App 的 Automations 在你的机器上跑定时后台任务 —— “每天早上，总结昨天的提交”。区别于 CI（GitHub runner）—— 这些只在你机器开着时跑。配 worktree 让每个定时任务隔离。

电脑操控（Computer Use）

Computer Use 给 Codex “长手” —— 它能看屏幕、点 UI、驱动浏览器。范围：GUI 自动化、浏览器测试、操作桌面 App。风险高 —— 它能对任何可见的东西行动；把它限制在 workspace-write 或容器，头几次跑密切盯着。

集成（Slack / Linear / SDK）

除 CLI 外，Codex 可从 Slack 和 Linear 召唤，经 SDK 嵌进你自己的产品。用这些把 Codex 变成已有工作流里的一个节点，而不是单独的目的地 —— 如 Slack 消息触发 Codex 任务，结果贴回频道。

记忆系统

Codex 的记忆是两套系统，不是一套：

⚠️ 两个常见错：（1）以为记忆是实时的 —— 它在会话闲下来后才写，所以立刻测它必失败；（2）以为记忆能替代 AGENTS.md —— 不能。“必须每次生效”的规则进 AGENTS.md；别赌记忆。

Chronicle 是实验性的、Codex 专属的、由屏幕内容喂养的记忆（仅 Pro + macOS，不含 EU/UK/瑞士）。启用前 review 它的隐私影响。

安全与风险边界

“Codex 该不该碰这个”的决策框架：

⚠️ 不可商量： 绝不在真机 --yolo；绝不在 Windows 开 Full Access；把不信任的 clone 仓库的 .codex/ 当不信任对待（Codex 默认这么做 —— 别覆盖它）。

企业与治理

跨公司运营 Codex（vs 一个人）需要治理：

• 托管设置 —— IT 部署的组织配置，用户松不了。
• requirements.toml —— allow_managed_hooks_only = true 把 hooks 锁到仅 managed。
• 信任策略 —— 控制哪些项目的 .codex/ 层加载。
• 白名单 —— 把 MCP 服务器、工具和模型限制到批准的集合。

定价与第三方模型

计费要么是 ChatGPT 订阅（Pro/Plus/Team/Enterprise —— 含使用量）要么是 API 额度（按 token 付）。在 OpenAI 站点核实当前定价 —— 数字会变；带”截至”日期引用。

第三方模型： 经 config.toml 里的 model_provider 把 Codex 路由到其他供应商（如 DeepSeek、本地模型）。用于控成本、数据驻留或离线。

Windows 要点与故障排查

Windows： 在 WSL2 里跑（原生不被支持）。Full Access 丢文件的报告是 Windows 专属 —— 留在 workspace-write。

常见失败：

从 Claude Code 迁移

你的 Claude Code 心智模型能搬 ~90%。概念映射：

代理循环、“先读再动手”、“给目标不给步骤”的习惯原样搬过来。

命令与配置速查表

# 安装 / 认证
curl -fsSL https://chatgpt.com/codex/install.sh | sh
codex login                      # ChatGPT OAuth
printenv OPENAI_API_KEY | codex login --with-api-key
codex doctor                     # 自检

# 日常 CLI
codex                            # 交互
codex exec "..."                 # 非交互
codex -s workspace-write -a on-request

# 斜杠命令（会话内）
/init  /model  /effort  /status  /clear  /compact  /diff  /review  /mcp  /skills  /agents  /memories

# config.toml 要点
model = "gpt-5.5"
approval_policy = "on-request"
sandbox_mode = "workspace-write"
[sandbox_workspace_write]
network_access = true

最佳实践与常见问题

正确的废话之外，真正能落地的：

• AGENTS.md 当反馈回路 —— Codex 每个错误假设都变成它一行。
• 把强度对准任务，不是把模型对准任务 —— /effort 更便宜影响更大。
• 一个线程一个任务 —— 上下文腐烂是真的；别堆活。
• 质量下降前 compact，不是之后。
• --yolo 容器化 —— 绝不在真机。

常见问题（简）：

• Codex 跨会话记东西吗？ 只有 AGENTS.md（可靠）和 Memories（尽力而为）里的。
• 能用非 OpenAI 模型吗？ 能，经配置里的 model_provider。
• 让它改文件安全吗？ 在 workspace-write + on-request 下安全 —— 出圈前暂停。
• CLI vs 桌面 App？ CLI 是超集；先学它。

术语表