Codex — OpenAI 的编程智能体

它是什么

Codex 是 OpenAI 的编程智能体。它可以在终端（Codex CLI）、代码编辑器扩展和 ChatGPT 应用中工作。用 codex cloud 还可以把工作交给云端环境，再把结果应用到自己的电脑上。

项目规则写在 AGENTS.md 里，这是一种许多编程智能体都会读取的开放格式。Codex 能做什么，由你用 /permissions 来选择。

你需要什么

• 账户：用 ChatGPT 登录（Plus、Pro、Business、Edu 或 Enterprise 套餐）。也可以用 API 密钥登录，但需要额外设置。
• 电脑：macOS 或 Linux（安装脚本），或 Windows（PowerShell 安装脚本）。也可以用 npm 和 Homebrew 安装。
• 一个用来工作的项目文件夹 — 最好是 Git 仓库，这样每处改动都能查看和撤销。

安装

在 macOS 和 Linux 上运行第一行；在 Windows 上运行 PowerShell 那一行。如果是用脚本安装的，再运行一次同样的命令即可更新。

macOS · Linux

curl -fsSL https://chatgpt.com/codex/install.sh | sh 复制

Windows PowerShell

powershell -ExecutionPolicy ByPass -c "irm https://chatgpt.com/codex/install.ps1 | iex" 复制

npm

npm install -g @openai/codex 复制

Homebrew

brew install --cask codex 复制

检查安装

打开一个新的终端窗口。codex --version 应显示版本号。如果看到“command not found”，请重新打开终端并检查 PATH。

第一次运行 — 五个步骤

1. 进入项目文件夹，运行 codex，然后选择“Sign in with ChatGPT”。
2. 问它“给我介绍一下这个项目”，让它阅读项目。
3. 运行 /init 创建 AGENTS.md，然后写上你的测试命令和要遵守的规则。
4. 用 /permissions 选择 Codex 不用问就能做的事。
5. 布置任务时写明文件、行为和检查方法。阅读 diff，自己运行测试，然后提交。

在 SONUB 上深入学习

• Codex：OpenAI 的编程智能体
• 智能体和子智能体：AI 是怎样一步步工作的
• 目标和 Ralph Loop：让智能体一直做到真正完成
• 智能体技能 — Codex 使用同样的 SKILL.md 文件夹

官方文档

• OpenAI — Codex
• Codex CLI — GitHub
• AGENTS.md

已于 2026-10-18 对照官方文档核实。这些工具变化很快 — 如果命令不起作用，请查看官方文档。

写好 AGENTS.md

Codex 开始工作时会读取 AGENTS.md。它先读取你的全局文件（~/.codex/AGENTS.md），然后从项目顶层（通常是 Git 仓库的顶层）一路走到当前文件夹，每个文件夹找一个文件，按顺序拼接起来。越靠近当前文件夹的文件排在越后面，所以以它为准。

• ~/.codex/AGENTS.md — 适用于所有项目的个人指令
• 项目顶层的 AGENTS.md — 团队共享的指令（提交它）
• 子文件夹里的 AGENTS.md — 只在该文件夹里工作时追加的指令
• AGENTS.override.md — 如果它在同一个文件夹里，会代替 AGENTS.md 被读取（用于临时试一下改动）。
• 默认总共只读取 32 KiB（project_doc_max_bytes）。要使用其他名称的文件，把它们列在 project_doc_fallback_filenames 里。

# AGENTS.md

## Setup
- Install: pnpm install
- Test: pnpm test
- Lint: pnpm lint

## Code style
- TypeScript strict mode, single quotes.
- Keep functions small. Add a test for every bug fix.

## Don't
- Don't edit generated files in dist/.
- Don't commit .env files.

~/.codex/AGENTS.md          ← you, every project (read first)
my-project/AGENTS.md        ← team rules (commit it)
my-project/web/AGENTS.md    ← only for web/ (read last, so it wins)

/init 会阅读项目并写出第一版 AGENTS.md。AGENTS.md 每次运行只读取一次，所以编辑后要重启 Codex。

和 Claude Code 一起使用 — 指令集中在 AGENTS.md 一处

如果一个项目在 Codex 之外还用 Claude Code、Cursor、Gemini 等其他 AI，每个工具各自的指令文件很快就会变得不一致。AGENTS.md 是许多编程智能体都会读取的开放格式，所以把规则在 AGENTS.md 里写一次，所有 AI 就会按同一份指令工作。

和 Claude Code 一起使用时，最好的方法是项目里不放 CLAUDE.md，只用 AGENTS.md。没有 CLAUDE.md 时，Claude Code 会读取 AGENTS.md，也仍会读取你的全局 ~/.claude/CLAUDE.md。原因和步骤在 Claude Code 进阶里有详细说明。

1. 共享规则只写在 AGENTS.md 里。
2. 项目里不放 CLAUDE.md。只要有一个文件夹使用 CLAUDE.md，就在每个文件夹都放 CLAUDE.md，每个只写一行：@AGENTS.md。
3. 要修改规则，只改 AGENTS.md。两个 AI 都会遵守修改后的规则。

~/.claude/CLAUDE.md   ← personal rules for Claude Code (still loaded)
~/.codex/AGENTS.md    ← personal rules for Codex

my-project/
└── AGENTS.md         ← the rules — Codex and Claude Code both read this
                        (no CLAUDE.md in the project)

• 只用 AGENTS.md 的方法 — 详见 Claude Code 进阶

审批和沙箱 — 交出多少权限

Codex 用两种方式保证安全。沙箱决定它在技术上能做什么（写文件、网络），审批策略决定它什么时候问你。两者要一起选择。

• read-only — 只读取，什么都不改。用来浏览你不熟悉的项目。
• workspace-write — 只在工作文件夹内编辑和运行命令。在 Git 仓库里默认是“Auto”，即把它和 on-request 搭配使用。网络默认关闭，.git、.codex 和 .agents 无法写入。
• danger-full-access — 没有沙箱，什么都能做。只在隔离的容器里使用。
• 审批策略（-a）：on-request 在需要走出沙箱时询问，never 不询问（只在沙箱内工作）。
• /permissions 在对话中切换模式，/status 显示当前设置。

codex --sandbox read-only                      # look only, change nothing
codex --sandbox workspace-write                # edit inside this folder ("Auto" in a Git repo)
codex -a never --sandbox workspace-write       # never ask, but stay inside the sandbox

approval_policy = "on-request"
sandbox_mode = "workspace-write"

[sandbox_workspace_write]
network_access = false

旧文章里的 --full-auto 已经不存在了。要达到同样效果，请用 --sandbox workspace-write。--yolo（--dangerously-bypass-approvals-and-sandbox）会同时关闭沙箱和审批，所以只在隔离的地方使用。

聊天界面里的命令

在 Codex 聊天界面输入 /，就会出现命令列表。先学会每天都用的那些。

• /model — 选择模型和思考的深度（推理努力程度）。
• /diff — 查看这次会话中改动的文件。/review — 让它审查改动的代码。
• /compact — 总结对话来腾出空间。/new — 开始新的对话。
• /resume — 选一个更早的对话继续。在终端里用 codex resume 或 codex resume --last。
• /status — 查看模型、权限、工作文件夹等当前设置。/mcp — 查看已连接的 MCP 服务器。
• @ — 查找文件并附加到请求里。$ — 调用技能。! — 立即运行 shell 命令（!git status）。
• -i picture.png — 附带截图启动（对话中直接粘贴）。--search — 开启实时网页搜索。
• /init — 创建 AGENTS.md。/plan — 让它先做计划。

从 Claude Code 过来的？/import 会导入 Claude Code 的设置和最近的对话。

好好交代工作 — 在哪里、做什么、怎么检查

好的请求有三个部分：在哪里（文件和文件夹）、做什么（你想要的行为）、怎么检查（测试、命令、画面）。这三点越清楚，Codex 就越少走弯路，也越会自己检查结果。

• 模糊的请求：“修一下购物车”
• 清楚的请求：“在 @src/cart.ts 里，数量为 0 时总价会变成 NaN。改成数量为 0 时删除该商品，在 tests/cart.test.ts 里加一个测试，并确认 pnpm test 通过。”

• 大任务先说“先只给我看计划”，调整计划后再让它继续。
• 如果它改的比你要求的多，就让它停下，用 git restore 回退，然后指明文件重新请求。
• 把完整的错误输出粘贴进去 — 原文比总结更准确。
• 完成后，用 /diff 阅读改动，自己运行测试，然后提交。

进阶练习 — 在你自己的项目里试试

1. 用 /init 创建 AGENTS.md，完善测试命令和三条规则。
2. 如果你也用 Claude Code，确认项目里没有 CLAUDE.md，让两个 AI 读取同一个 AGENTS.md。
3. 用 codex --sandbox read-only 让它浏览项目，再用 workspace-write 交给它一个小修改。
4. 用 /diff 和 /review 审查改动。
5. 用 /status 查看当前设置，用 codex resume --last 继续对话。

五项都做完了？进入 [高级] 标签。

官方文档

• Codex — AGENTS.md
• Codex — Approvals & security
• AGENTS.md

已于 2026-10-18 对照官方文档核实。这些工具变化很快 — 如果命令不起作用，请查看官方文档。

config.toml 和配置档 — 让它适合你的工作方式

Codex 的设置保存在 ~/.codex/config.toml 里。以前每次都要加的选项，写在这里就成了默认值。因工作而异的设置放进配置档文件。

• model · model_reasoning_effort — 使用的模型和思考的深度
• approval_policy · sandbox_mode — 审批策略和沙箱（进阶里讲过的值）
• 配置档是一个 ~/.codex/<名称>.config.toml 文件。用 codex -p <名称> 选择，它的值会叠加在基础设置之上（旧的 [profiles.x] 表已不再读取）。
• -c key=value 只在这次运行中更改某项设置（比如 -c sandbox_workspace_write.network_access=true）。

model_reasoning_effort = "high"
approval_policy = "on-request"
sandbox_mode = "workspace-write"
web_search = "cached"

# a profile: codex -p review
model_reasoning_effort = "xhigh"
sandbox_mode = "read-only"

codex -p review
codex -c sandbox_workspace_write.network_access=true

项目里的 .codex/config.toml 只保存该项目的设置 — 只有在你标记为受信任的项目里才会被读取。

codex exec — 不用聊天界面的自动化

codex exec "…" 不打开聊天界面完成一次工作后退出。进度输出到 stderr，最终回答输出到 stdout，所以很适合放进脚本、cron 和 CI。

• 默认是 read-only。加上 --sandbox workspace-write 才能让它编辑文件。
• --json 以 JSON 行（JSONL）发送进度，-o <文件> 把最终回答保存到文件，--output-schema <文件> 得到符合 JSON Schema 的回答。
• 不带提示运行时，标准输入就成为提示；带着提示再用管道传入输入时，输入会附加在后面。
• 在 Git 仓库之外需要 --skip-git-repo-check。codex exec resume --last 继续上一次运行。

# Ask once, print the answer (read-only by default)
codex exec "Summarize what changed in the last 5 commits"

# Allow edits inside this folder
codex exec --sandbox workspace-write "Fix the failing test in tests/cart.test.ts"

# Pipe input in
cat error.log | codex exec "Find the cause"

# For scripts: JSON events, the final answer in a file, a JSON Schema answer
codex exec --json "List the TODOs in src/" > events.jsonl
codex exec -o notes.md "Write release notes for this week"
codex exec --output-schema schema.json "Rate the test coverage of each file"

# Continue the last run
codex exec resume --last "Now add tests for it"

在 CI 里，只把 CODEX_API_KEY 传给运行 Codex 的那一步，这样其他步骤的脚本就看不到密钥。

MCP — 连接外部工具

MCP（Model Context Protocol）是让 AI 工具使用外部服务（问题跟踪、数据库、浏览器、文档工具）的开放标准。给 Codex 添加一个 MCP 服务器，它就能使用该服务器的工具 — Claude Code 用的服务器也可以直接使用。

• codex mcp add <名称> -- <命令> — 添加在你电脑上运行的服务器（stdio）。
• codex mcp add <名称> --url <url> — 添加远程服务器（streamable HTTP）。
• 添加的服务器保存在 config.toml 的 [mcp_servers.<名称>] 表里。对话中，/mcp 会显示它们的状态。

# A server that runs on your computer (stdio)
codex mcp add playwright -- npx @playwright/mcp@latest

# A remote server (streamable HTTP)
codex mcp add notion --url https://mcp.notion.com/mcp

codex mcp list

[mcp_servers.playwright]
command = "npx"
args = ["@playwright/mcp@latest"]
tool_timeout_sec = 60

只添加你信任的 MCP 服务器。获取外部文字的服务器，可能会把藏在文字里的指令带进来（提示注入）。

智能体技能 — 教它你重复做的工作

技能就是一个装有 SKILL.md 的文件夹 — 和 Claude Code 是同样的开放格式。平时 Codex 只知道每个技能的名称和说明；当工作符合说明时，它才会读取正文并照着做。以前的自定义提示（~/.codex/prompts）现在应该改成技能。

• .agents/skills/<名称>/SKILL.md 用于这个仓库，~/.agents/skills/ 用于你的所有项目。
• 用 $<技能名称> 直接调用，或用 /skills 从列表中选择。当说明符合时，它也会自己使用。
• 写好 name 和 description，把脚本和参考文档放在 scripts/ 和 references/ 里。
• 向内置的 $skill-creator 提出请求，它会帮你做一个新技能。

---
name: release-notes
description: Write release notes from the git log. Use when the user asks for release notes or a changelog.
---

1. Find the last tag: `git describe --tags --abbrev=0`
2. Read the commits since then: `git log <tag>..HEAD --oneline`
3. Group them under Added / Fixed / Changed, in plain sentences.

• 了解智能体技能 — 制作、安装、SONUB 技能

钩子 — 在设定的时机必定运行的命令

钩子是 Codex 在设定的时机必定运行的命令。AGENTS.md 里的请求可能会被忘记，但钩子每次都会运行。可以用钩子运行格式化工具、挡住危险命令，以及在工作完成时收到通知。

• 放在 ~/.codex/hooks.json（你自己）或仓库里的 .codex/hooks.json（项目）。
• 把它们挂到这些时机上：PreToolUse 和 PostToolUse（使用工具前后）、UserPromptSubmit（你发送请求时）、Stop（它回答完毕时）和 SessionStart（会话开始时）。
• matcher 选择工具，如果命令以退出码 2 结束，该操作会被阻止。
• 如果只需要通知，在 config.toml 的 notify 里放一个程序 — 每轮结束时它都会带着一个 JSON 参数运行。

新的钩子要在 /hooks 里标记为受信任后才会运行。别人写的钩子，要先读懂它的命令再信任。

高级练习

1. 在 ~/.codex/config.toml 里写上默认的审批和沙箱，做一个只读的审查配置档（review.config.toml），并用 codex -p review 使用它。
2. 写一个脚本，用 codex exec -o 把这周的提交总结到一个文件里。
3. 添加一个 MCP 服务器，用 /mcp 检查。
4. 把一件常做的工作做成 .agents/skills/ 里的技能，并用 $name 调用。
5. 用 PostToolUse 钩子，让每次编辑文件时都运行格式化工具，并在 /hooks 里把它标记为受信任。

五项都做完了？进入 [大师] 标签。

官方文档

• Codex — Config reference
• Codex — Non-interactive mode
• Codex — MCP
• Codex — Skills
• Codex — Hooks

已于 2026-10-18 对照官方文档核实。这些工具变化很快 — 如果命令不起作用，请查看官方文档。

子智能体 — 把部分工作交出去

请 Codex 启动子智能体，它就会把调查、构建和审查拆开同时进行。每个子智能体都有自己的对话，所以主对话保持干净。

• 内置的 default、worker 和 explorer 一开始就有，/subagents 可以在子智能体之间切换。
• 在 .codex/agents/（项目）或 ~/.codex/agents/（你自己）里用 TOML 文件做你自己的子智能体 — name、description、developer_instructions。
• 子智能体会继承父级的沙箱和审批设置。
• 在请求里分好角色，比如“用 reviewer 审查当前的 diff，同时让 worker 写测试”。

name = "reviewer"
description = "Reviews diffs for bugs and missing tests. Read-only."
developer_instructions = """
Run git diff. List bugs with file and line, then missing tests.
Never edit files.
"""
model_reasoning_effort = "high"

Codex cloud — 把工作交给云端

codex cloud 在 OpenAI 的云端环境里运行工作。它不占用你的电脑，所以你可以一次交出多项工作，只把你选中的完成结果应用到自己的文件上。

• 先在 ChatGPT 的 Codex 设置里创建一个环境（仓库、设置脚本、密钥、互联网访问）。
• codex cloud 显示任务列表并启动新任务。也可以用 codex cloud exec --env <环境 ID> "…" 直接交出一项任务。
• codex apply <任务 ID> 把云端做的改动应用到你的仓库（git apply）。
• 让它把同一项工作尝试多次（--attempts），再挑出最好的结果。

codex cloud                                   # see and start cloud tasks
codex cloud exec --env <ENV_ID> "Add input checks to the signup form"
codex cloud list
codex apply <TASK_ID>                         # apply the result to your files

GitHub — 在 PR 里使用 @codex review

把 GitHub 仓库连接到 Codex 后，只要在 PR 评论里写 @codex review 就能得到审查。用 GitHub Action（openai/codex-action），还可以在每个 PR 上自动运行。

• @codex review — 审查该 PR，只报告严重的问题（P0、P1）。你可以在 Codex 设置里开启对每个 PR 的自动审查。
• 其他任何 @codex … 评论都会以该内容启动一个云端任务。
• openai/codex-action@v1 接收 prompt 和 sandbox，运行 Codex，并以 final-message 给出最终回答 — 在下一步把它发成评论。
• 把密钥作为仓库 secret（OPENAI_API_KEY）传入；只读取的审查，sandbox 保持 read-only。

name: Codex review
on:
  pull_request:
jobs:
  review:
    runs-on: ubuntu-latest
    permissions:
      contents: read
    steps:
      - uses: actions/checkout@v4
      - uses: openai/codex-action@v1
        id: codex
        with:
          openai-api-key: ${{ secrets.OPENAI_API_KEY }}
          prompt: "Review this pull request. List bugs and missing tests."
          sandbox: read-only
      # the answer is in steps.codex.outputs.final-message

在 AGENTS.md 里加一个 ## Code Review Rules 小节，Codex 的 PR 审查就会遵守这些规则。

多个 AI 一起使用 — 互相审查

让另一个 AI 审查一个 AI 写的代码，单独一个会漏掉的问题就会显现出来。如果通过 AGENTS.md 共享同一份指令，在一个项目里切换 Codex 和 Claude Code 就很容易。

分配角色也是一种方法。一个 AI 计划和构建，另一个审查和测试，最后由人阅读最终的 diff 并决定是否合并。

• codex review --uncommitted — Codex 审查未提交的改动。--base <分支> 审查整个分支。
• git diff | claude -p "…" — Claude Code 审查 Codex 做的改动。
• 在另一个 AI 的会话里，可以用 codex exec 把一项工作交给 Codex（比如写测试或做图片）。
• 两个 AI 意见不一致时，让双方都给出证据（文件、行、测试结果），由人来检查并选择。

# Claude Code wrote the change — Codex reviews it
codex review --uncommitted

# Codex wrote the change — Claude Code reviews it
git diff | claude -p "Review this diff. List bugs and missing tests."

# From inside another AI's session, hand one job to Codex
codex exec --sandbox workspace-write "Write unit tests for src/price.ts"

• 只用 AGENTS.md 的方法 — 详见 Claude Code 进阶

管理团队设置 — 大家用同一套设置

当很多人和很多 AI 在一个仓库里工作时，设置会很快堆积起来。要决定哪些共享、哪些个人，哪些是请求、哪些是强制。

• 共享（提交）：AGENTS.md、.codex/config.toml、.codex/hooks.json、.codex/agents/、.agents/skills/
• 个人（不提交）：~/.codex/config.toml、配置档文件、~/.codex/AGENTS.md
• AGENTS.md 保持简短。只有同样的错误反复出现时才加规则，错误的规则就删掉。
• 必须遵守的事，用沙箱、审批和钩子来强制，而不是靠指令。
• CI 密钥只传给运行 Codex 的那一步，审查用 read-only 运行。

大师检查清单

• 共享规则写在 AGENTS.md — Claude Code 等其他 AI 按同一份指令工作
• 你根据工作选择沙箱和审批，默认值写在 config.toml 和配置档里
• 重复的工作交给技能，必须遵守的规则交给钩子，外部工具通过 MCP 连接
• 重复的工作用 codex exec 和 GitHub Action 自动化
• 大任务分给子智能体和 codex cloud，只应用选中的结果
• AI 互相审查彼此的工作，由人检查最终的 diff 和测试

工具变化很快。如果命令不起作用，先查看 codex --help 和官方文档。旧文章里的选项（--full-auto、[profiles.x]）可能已经变了。

官方文档

• Codex — Subagents
• Codex — Cloud
• Codex — GitHub
• Codex — GitHub Action

已于 2026-10-18 对照官方文档核实。这些工具变化很快 — 如果命令不起作用，请查看官方文档。