最近聊 AI 编程 Agent，最常见的顾虑不是“它能不能写代码”，而是“我完全看不懂它在干什么”。你给 Codex 派一个任务，它安静地读文件、改文件、执行命令、安装依赖，最后输出一句“已完成”。如果只能看到结果、看不到过程，那它对你来说就是一个黑盒。
我的判断是：Codex 恰恰是当前最容易摆脱“黑盒感”的编程 Agent。它把 Agent 循环暴露得很完整——计划、工具调用、输出、审阅，每一步都有对应的查看入口、控制入口和外部接入方式。问题只在于，大多数教程只教“怎么给 Codex 下命令”，没教“怎么观察和干预它每一步的动作”。
这篇文章不讨论“Codex 会不会取代程序员”之类的宏大问题，只讲三件事：如何让 Codex 的每一步看得见、改得动、接得上。读完你可以做到：用 Plan 模式先看方案再动手；用 debug 日志定位它为什么读某个文件；用 config.toml、AGENTS.md、自定义命令把它的行为锁在项目规则里；再用 MCP 和 CI 把它接入现有工具链。
1. 这篇文章真正要解决的问题
先还原一个真实场景。你在团队里引入 Codex，让它在某个分支上“把登录接口加上验证码校验”。半小时后它完成任务，提交里改了十几个文件：路由、数据库模型、前端页面、测试用例。你逐一 review，却回答不了评审人最常问的三个问题：
- 它为什么改了
auth_service.py里的依赖注入方式？ - 它为什么把测试用例里的 mock 数据从 5 组缩减到 2 组？
- 它是从哪里知道项目里存在
captcha_client这个内部组件的？
这类问题如果答不上来，Codex 的能力再强，在工程流程里也是不可用的。因为代码评审的本质不是“结果对不对”，而是“过程能不能被理解和追责”。
所谓“黑盒”，其实包含三个层面：
| 黑盒层面 | 表现 | 工程后果 |
|---|---|---|
| 决策不可见 | 不知道它读了哪些文件、为什么做某个修改 | 评审无法进行 |
| 行为不可改 | 它总是不遵守项目规范，你只能一次次在提示词里“求”它 | 效率低、结果不稳定 |
| 系统不可接 | 它只会在终端里自说自话，接不进公司平台和 CI | 无法规模化落地 |
这篇文章的框架就是针对这三点展开的：让每一步看得见，让行为改得动，让工具链接得上。你可以把这三条当作评估任何 AI 编程 Agent 是否适合工程使用的标尺。
需要先说明一点：这里说的 Codex，是 OpenAI 当前主推的编程 Agent，也就是终端版的 Codex CLI、ChatGPT 里的 Codex 功能，以及同源的 Codex 云端 Agent，不是 2021 年那个 GPT-3 时代的代码模型。由于 Codex 迭代很快，本文以通用能力和实践思路为主，具体命令参数以你环境中codex --help的输出和官方文档为准。
2. Codex 不是玄学：先理解 Agent 循环
想摆脱黑盒感，第一步是把 Codex 的运行机制讲清楚。它和传统的“AI 补全代码”有本质区别。
传统的 IDE 代码补全，或者是 Copilot 这类助手，是典型的“单次预测”模型：你写一个函数开头，模型根据上下文补出接下来的几行。它的输出是一次性的，你看到了，接受或拒绝，过程结束。
Codex 不是这样。它运行的是一个Agent 循环：观察环境 → 决定下一步动作 → 执行动作 → 观察新结果 → 再决定下一步。这个循环不断重复，直到任务完成。每一步里，Codex 可以做的事包括：
- 读取项目里的文件，理解现有代码结构
- 修改文件、创建文件、删除文件
- 执行 shell 命令，比如跑测试、装依赖、调构建工具
- 根据命令的报错输出调整自己的下一步动作
- 在完成一个阶段后，继续推进下一个子任务
把这段话翻译成工程语言：Codex 不是一个“代码生成器”，而是一个“会自己推进任务的执行器”。它更像一个拿到需求后自己动手编码、自己跑测试、自己修 bug 的初级工程师，你给它的是目标，它自己规划路径。
关键问题来了：既然它每一步都有明确的“观察-决策-执行-再观察”结构，为什么普通用户还是觉得它是黑盒？
原因有三个，它们都和技术实现有关。
第一，交互层做了压缩。Codex 在界面上经常只显示“正在修改文件”“正在运行测试”这类摘要，真正的工具调用参数、上下文内容、模型中间推理过程都被折叠了。折叠本身为了可读性，但它让用户失去了检查中间态的机会。
第二，提示词隐式包含了很多项目信息。Codex 会自动读取工作区里的文件、git 状态、项目配置，你并没有显式告诉它“去看 package.json”，它却已经看到了。你不知道它看了什么，自然就觉得它“莫名其妙知道很多”。
第三，模型的决策过程本身是概率性的。同一任务跑两次，路径可能完全不同，这让它看起来难以预测。但这是模型的固有特性，不代表过程不可观测——我们真正需要做的，是给这个过程加上“仪表盘”。
从工程角度看，Codex 的 Agent 循环可以拆成下面这张表，它也是我们后续做控制的基础：
| Agent 循环环节 | 你可以观察的入口 | 你可以干预的入口 |
|---|---|---|
| 目标理解 | 初始交互输出、Plan 方案 | 提示词、AGENTS.md |
| 工具调用 | TUI 中的工具列表、debug 日志 | 审批策略、沙箱权限 |
| 文件改动 | git diff、文件变更列表 | 自定义命令、项目规则 |
| 执行结果 | 命令输出、测试结果 | 终止会话、回滚快照 |
| 最终交付 | 最终 diff、提交信息 | 人工评审、CI 验证 |
看到没有？Codex 并不是没有中间态，而是大部分中间态默认被隐藏了。接下来的三章，就是教你怎么把这些中间态一个个打开。
3. 看得见：把每一步都摊开在桌面上
3.1 不要只盯着最终结果，先学会读 TUI
启动 Codex 后，你看到的交互界面就是最直接的观测层。它通常会展示当前模型、审批模式、沙箱状态，以及每一次工具调用的摘要。很多用户忽略这些信息，直接盯着最后的 diff，等于放弃了第一层审计能力。
建议形成固定习惯：Codex 每执行一个工具调用，先看一眼它调用的是什么工具、参数是什么、作用在哪个路径下。如果它在读一个你没想到的文件，马上打断，追问“为什么要看这个文件”。这一步能拦截掉大量跑偏的修改。
3.2 Plan 模式：先看方案，再允许动手
Codex 最容易闯祸的时机，是它还没完全理解需求就开始改文件。Plan 模式解决的就是这个问题：先让 Codex 只做调研和方案设计，不触碰任何文件，你确认方案后再进入执行阶段。
不同版本的 Codex 进入 Plan 模式的方式不太一样，有的用--plan参数，有的在 TUI 里切换模式，还有的在交互中直接说“先给我一个计划，不要改文件”。统一的做法是：在让 Codex 动手之前，强制它输出计划、涉及文件列表和风险点。
这里真正容易踩坑的地方是：你以为自己用了 Plan 模式，但 Codex 仍然在计划阶段进行了少量写操作。为了验证，执行完 Plan 后用git status看工作区是否干净。如果文件有变动，说明当前版本的 Plan 模式没有严格隔离写操作，需要手动撤回。
3.3 打开 debug 日志：看到模型没有说的细节
TUI 里的摘要信息还是太“干净”了。如果你需要看清 Codex 真正读入了什么内容、发送了什么请求、为什么做出某个决策，就需要打开详细日志。
# 查看当前版本和可用参数 codex --version # 交互式会话，适合逐步观察每次工具调用 codex # 用 plan 模式先输出方案 codex --plan "给项目增加一个 /healthz 接口" # 非交互式一步执行，适合明确的小任务 codex exec "为 src/utils.py 补充单元测试并运行 pytest" # 打开 debug 级别的详细日志 codex --debug "排查前端构建失败" # 部分版本也支持环境变量方式开启调试 CODEX_DEBUG=1 codex exec "修复登录接口的 500 错误"--debug模式会输出大量请求和响应细节，信息噪音很大，不适合日常使用，但在两种场景下很有价值：一是 Agent 行为诡异、需要确认它到底读了什么上下文；二是接入自建平台时需要定位调用失败的位置。日常开发，建议用普通 TUI 加git diff就够了。
3.4 用 git diff 形成最终审计段
不管你在 TUI 里看到了多少工具调用，最终交付到仓库里的，是代码变更本身。所以，git 是 Codex 工程化里最重要的审计工具，没有之一。
Codex 在改文件时，不会像人一样一次只改一个小块，它可能同时改多个文件。建议养成以下固定流程：
# 查看所有文件级变更 git status # 查看具体改动内容 git diff # 只看删除的行数，警惕它对现有代码的大规模“重构” git diff --stat # 检查它是否误改了无关文件 git diff --name-only如果你发现 Codex 的改动范围明显超出任务范围，比如让它加接口，它却重构了配置模块，立即中断后续操作。这不是“多做了点事”，而是任务边界失控的信号。加一个审批动作，让 Codex 停下来。
3.5 利用快照快进快退
Codex 会为会话中的关键变更建立历史快照。当它执行了一系列操作，而你想回到某个中间状态时，不需要反向手改 diff，直接从历史快照恢复即可。不同版本恢复快照的入口不同，有的在界面下方有操作提示，有的通过快捷键触发，具体以当前版本说明为准。
这里要特别提醒：不要把快照当成唯一保险。快照通常只覆盖会话内 Codex 自己产生的变更，如果你或其他人同时改了文件，快照恢复可能冲突。最可靠的安全网仍然是：任务开始前提交或 stash 当前工作区，任务过程中让 Codex 只在自己清点过的文件范围内工作。
4. 改得动：不用“求”模型，直接改配置
“看得见”解决的是审计问题，“改得动”解决的是控制问题。很多人的误区是：想让 Codex 遵守规范，只能在每次提示词里反复强调。实际上，Codex 提供了三层配置入口，优先级从全局到项目递减。
4.1 第一层：安全边界配置
全局配置文件通常位于~/.codex/config.toml，项目级配置文件位于项目根目录的.codex/config.toml。项目级配置会覆盖全局配置。
# 文件路径：项目根目录/.codex/config.toml # 模型选择。具体模型名以你账户可用模型为准 model = "gpt-5-codex" # 审批策略 # never ：自动执行所有操作，适合可信场景 # on-request ：关键操作（如写文件、执行命令）需要你确认 # untrusted ：默认谨慎，几乎每一步都可能停下来询问 approval_policy = "on-request" # 沙箱模式 # read-only ：只读，不会真正写文件 # workspace-write ：允许修改当前工作区文件 # dangerously-full-access ：完全访问系统，慎用 sandbox_mode = "workspace-write"这里的核心设计思想是最小权限。刚接触 Codex 时，approval_policy = "on-request"加sandbox_mode = "workspace-write"是一个合理的起点：它能改项目代码，但每次写文件、执行命令前都会向你确认。等熟悉了它的行为模式，再逐级放大权限，而不要一开始就用“完全自动、完全访问”。
4.2 第二层：AGENTS.md 项目规则
安全边界只能管住“能不能做”，管不了“该怎么做”。项目规范要靠 AGENTS.md 文件：放在仓库根目录，Codex 每次开工前都会读取它，把它当作项目的最高行为准则。
# 文件路径：项目根目录/AGENTS.md ## 技术栈 - 后端：Python 3.11 + FastAPI - 前端：React 18 + Vite ## 常用命令 - 安装依赖：pip install -r requirements.txt - 运行测试：pytest tests/ - 类型检查：mypy src/ ## 代码约定 - 每个接口都返回统一 JSON 结构 { "code": 0, "data": ..., "msg": "..." } - 新增函数必须有 docstring - 所有时间字段使用 UTC，前端再转本地时区 ## 边界约束 - 禁止修改 tests/conftest.py - 禁止在源码和配置文件中写入任何密钥 - 禁止直接修改数据库迁移文件，只能新增迁移 - 修改公共模块前，先在计划里说明影响范围AGENTS.md 写得好不好，直接决定 Codex 的交付质量。注意两个实践细节：一是 AGENTS.md 本身要纳入版本管理，它是项目文档的一部分，它和代码一样需要 review；二是内容要具体，写“代码风格要优雅”毫无意义，写“私有方法需要在类注释中说明用途”才算可执行约束。
4.3 第三层：自定义命令
如果有一类任务你反复让 Codex 做，比如“审查 git diff”“生成发布说明”“补充测试”，可以把它封装成自定义命令。这样每次只需输入一个短命令，Codex 就会按你预设的提示词执行。
# 文件路径：项目根目录/.codex/config.toml [custom_commands.review] description = "检查当前改动是否有遗漏和风险" prompt = """ 请审查当前 git diff。 重点检查： 1. 是否有硬编码密钥或敏感信息 2. 是否有超出任务范围的无关改动 3. 是否缺少异常处理和日志 4. 是否存在破坏既有 API 兼容性的修改 最后输出问题清单，按严重程度排序。 """ [custom_commands.gen-migration] description = "为新需求生成数据库迁移文件" prompt = """ 根据下面的需求描述生成迁移文件： 技术栈为 Alembic，迁移文件命名使用需求编号前缀。 生成后不要执行迁移，先运行 alembic check 验证。 """自定义命令的价值在于行为标准化。同一个命令在团队任何人的电脑上执行，Codex 面临的约束都是同一份，这比每个人自己去写提示词要可靠得多。配置好后，在会话里直接输入命令名即可触发。
4.4 三层控制的优先级理解
从“改得动”的角度，三条规则的理解难度不大：
- 安全边界决定权限，是底线；
- AGENTS.md 决定规则，是项目级约束；
- 自定义命令决定标准动作，是流程复用。
如果一个行为同时被多层约束冲突，比如 AGENTS.md 说“不允许改迁移文件”，但你的提示词说“帮我更新迁移文件”，多数情况下 AGENTS.md 会优先，因为模型在上下文里最早读到、且被定义成“项目约束”。但不要把期望完全压在机制上，冲突场景最终要靠你 review 兜底。
5. 接得上：把 Codex 接进现有工具链
“看得见、改得动”解决的是单机场景，而工程落地还需要“接得上”：让 Codex 能访问内部系统、能在 CI 里跑、能被你自研平台调度。这一节讲三条最常用的接入路径。
5.1 通过 MCP 接入外部工具和数据
MCP（Model Context Protocol）可以类比成 AI 工具的 USB-C 接口：以前每个工具都要单独写集成代码，现在只要双方支持 MCP，就可以即插即用。Codex 支持配置 MCP Server，让模型在运行过程中调用你指定的外部工具。
# 文件路径：.codex/config.toml，追加内容 [mcp_servers] [mcp_servers.gitlab] command = "npx" args = ["-y", "@your-org/gitlab-mcp-server"] [mcp_servers.internal-docs] command = "python" args = ["/opt/mcp/internal-docs-server.py"]接入 MCP 的典型场景包括：查询内部知识库、读取工单系统、调用内网发布的 API 文档、操作测试环境。它让 Codex 从“只知道自己项目里的代码”扩展成“知道你公司内部的系统和数据”。
这里最常见的问题是：MCP Server 启动失败，但 Codex 界面没有明显报错。排查时先单独运行一遍 server 命令，确认进程能正常启动、端口和协议没问题，再检查 config.toml 的格式。另外，MCP 权限很高，只连你信任的 Server，并且尽量让 Server 侧只开放必要的子命令。
5.2 在 CI 里使用 codex exec
把 Codex 跑在 PR 流程里，可以让它在代码合并前自动做一件事：审查变更、生成说明、补充测试。CI 场景通常是非交互的，需要用codex exec加上--full-auto模式，让它不需要人工确认也能跑完流程。
下面的 GitHub Actions 示例演示了怎么在 PR 触发时让 Codex 按项目规则输出审查意见：
# 文件路径：.github/workflows/codex-review.yml name: codex-review on: pull_request: types: [opened, synchronize] jobs: codex-task: runs-on: ubuntu-latest steps: - uses: actions/checkout@v4 - uses: actions/setup-node@v4 with: node-version: 20 - name: 安装 Codex CLI run: npm install -g @openai/codex - name: Codex 审查本次变更 env: OPENAI_API_KEY: ${{ secrets.OPENAI_API_KEY }} run: | codex exec --full-auto \ "根据 AGENTS.md 审查本次 git diff， 找出安全问题、越界改动和遗漏的测试， 输出为 review-report.md"CI 里运行 Codex 有几条铁律：密钥只从 Secret 注入，不要写进任何文件；默认保持沙箱限制，绝不在 CI 里使用绕过沙箱的全权限参数；输出产物要先落盘，后续步骤再决定是否上传或通知。
5.3 程序化调用：把 Codex CLI 变成你平台的子进程
如果你的平台希望以可控的方式调用 Codex，最稳妥的不是直接调用模型 API，而是封装 Codex CLI 为子进程。这样你可以复用 CLI 自身的安全机制、日志和配置。
import subprocess def run_codex_task(task: str, cwd: str) -> str: result = subprocess.run( [ "codex", "exec", task, "--json", # 部分版本支持 JSON 输出，具体以版本为准 ], capture_output=True, text=True, cwd=cwd, timeout=600, check=False, ) if result.returncode != 0: print("stderr:", result.stderr) return result.stdout程序化调用的关键点是：超时、重试和输出解析都要做在应用层。Codex 任务的执行时间波动很大，不要假设一次调用 30 秒内肯定返回；也不要一次性丢给它一个超大任务，把一个目标拆成多个小任务，逐步推进，比一次性长任务更容易控制和审计。
6. 完整示例：一个可审计的 Codex 实战
前面讲的是“招式”，这一节把它串成一个完整流程。场景如下：一个基于 FastAPI 的项目，需求是“增加一个/healthz健康检查接口，并在 README 里补充说明”。
6.1 前置状态清理
开始前，确保工作区干净：
git status git stash push -u # 如果有未提交内容，先保存这一步非常重要。Codex 在执行过程中会创建自己的 git commit，干净的工作区能让你在审查时一眼看到它所有动作。
6.2 编写项目规则
在项目根目录创建 AGENTS.md，内容包含技术栈、路由风格、测试要求。为了让示例足够具体，最小版可以写成下面这样：
# AGENTS.md ## 技术栈 - Python 3.11 + FastAPI - 测试用 pytest ## 命令 - 运行服务：uvicorn app.main:app --reload - 运行测试：pytest tests/ ## 约定 - 接口路径使用 kebab-case - 新接口必须写对应的 pytest 测试 - 不修改现有接口的返回结构6.3 先跑 Plan，不急着执行
codex --plan "增加 /healthz 健康检查接口，并在 README 中补充启动信息"Plan 输出里应该包含：要新建或修改的文件列表、接口的设计思路、是否会影响现有测试。如果 Plan 里出现你不认可的设计，比如它打算改app/main.py的路由注册方式而你并不希望你建议把改动范围限制得更小，再调整提示词重新出方案。
我们始终要记住一个原则：Codex 的 Plan 是模型自己生成的方案，不等于最终方案，你有权改；真正能压制它的，是通过 AGENTS.md 和提示词给出清晰的约束，而不是执行到一半才算账。
6.4 执行并观察工具调用
方案确认后，开始执行。在 TUI 里，关注每次工具调用的目标和输出：
codex "按已确认的方案实现 /healthz 接口"理想情况下，你会看到它做了这几件事：读取app/main.py、查看现有路由结构、修改文件、运行测试。如果它开始修改config.py或者你明确说“不要改”的文件，立即中断。
6.5 审查 diff 并验证
执行完成后，不要直接接受提交。按下面的顺序做最终验证：
# 1. 文件级变更是否合规 git diff --name-only # 2. 代码内容是否满足项目规范 git diff # 3. 独立运行测试确认 pytest tests/确认无误后，你可以让 Codex 生成提交信息，或者自己手动提交。如果你发现改动有问题但不想手动清理，可以使用会话快照回滚，或者直接git checkout -- .放弃工作区改动，重新从 Plan 阶段开始。宁可重跑一遍，也不要带着看不明白的改动提交。
7. 常见问题与排查思路
实践过程中，下面几个问题出现频率最高，整理成表方便查阅：
| 问题现象 | 可能原因 | 排查方式 | 解决方案 |
|---|---|---|---|
| Codex 启动后提示认证失败 | API Key 失效或没有正确登录 | 查看启动日志，检查~/.codex下的认证信息 | 重新执行登录流程，或更新OPENAI_API_KEY环境变量 |
| 它每次都试图修改无关文件 | AGENTS.md 缺失，或任务描述太模糊 | 确认仓库是否有 AGENTS.md，检查 Plan 里的文件清单 | 补齐 AGENTS.md，在任务中明确禁止文件列表 |
| 写入操作被沙箱拒绝 | sandbox_mode设置过严 | 看运行时沙箱拒绝提示 | 按需提升为workspace-write，不要直接使用完全访问模式 |
| MCP Server 没有生效 | 配置格式错误，或 Server 启动失败 | 单独运行command验证，检查启动日志 | 修正配置，确认端口与协议一致 |
| 模型名无效报错 | model配置了不可用的模型名 | 运行codex --help查看默认模型 | 删除自定义模型或换成官方可用模型名 |
| Plan 模式仍然改了文件 | 当前版本 Plan 隔离不严格 | 运行git status确认差异 | 回滚并改用手动确认模式再执行 |
codex exec在 CI 里卡住 | 审批策略等待人工授权 | 查看 CI 日志中的提示 | 在可信环境使用--full-auto，并保持沙箱限制 |
| 想回滚但快照不可用 | 会话结束、工作区被外部修改 | 检查 git 状态、reflog | 以 git 为主备份机制，任务前先提交或 stash |
排查问题有一个统一思路：先从日志看，再从权限看，最后才怀疑模型能力。绝大多数 Codex 行为异常，原因不是模型“笨”，而是上下文不对、权限不对或者配置不对。按照“日志 → 配置 → 提示词 → 模型”的顺序排查，通常能快速定位。
8. 最佳实践与工程建议
到这里，你已经知道如何让 Codex 透明化、可控化、可集成了。下面几条是团队落地时最值得写入规范的建议。
第一，任务开始前务必清理工作区。Codex 的 diff 越干净，审查者越容易建立信任。如果工作区本身有大量未提交改动，Agent 很容易把新旧改动混在一起，最终谁也分不清哪行是谁改的。
第二，将计划和实际改动分开审查。把“计划评审”和“代码评审”当成两个独立环节。计划评审解决方向问题，代码评审解决质量问题。只做后者不做前者，等于每次都让一个执行者带着不确定的方向跑完整个任务再返工。
第三，AGENTS.md 要纳入代码评审流程。它不是给 Codex 一个人的说明文件，而是整个团队对自动化开发的契约。它需要和产品文档、架构文档一样被维护，变更也要有理由、有记录。
第四，安全边界先紧后松。新接入 Codex 的团队，统一使用on-request加workspace-write；运行至少两周、确认事故率可接受后，再逐步放开到never模式。永远不要把“完全访问权限”作为默认配置，更不要在 CI 里通过绕过参数跑它。
第五，用 git 做兜底，不用快照做兜底。会话快照是便利功能，不是可靠备份。任何重要任务开始前，先确认当前状态可以被 git 恢复。记住这一点，遇到意外时你将节省大量时间。
第六，给每个 Codex 任务设边界。在提示词里尽量写清楚“修改哪些路径”“不要碰哪些文件”“完成后输出什么”。边界越清晰，它的不确定性就越小，你的审查负担就越低。
9. 写在最后：把 Agent 当成需要管理的工程师
回到开头的问题：Codex 是不是黑盒？答案取决于你怎么使用它。如果你只给它一句话，然后等结果，它确实是黑盒；但如果你把 Plan 打开、把日志打开、把 git diff 当作它的工作底稿，再通过配置文件给它划边界，它就是一个过程透明的自动化协作者。
真正值得思考的是工作方式的变化。以前写代码，是我们的手直接接触代码；现在用 Codex，我们接触的是“给 Agent 的指令、规则和审批动作”。这意味着，我们的大部分精力应该花在定义项目约束、审查 Agent 的中间产出、优化 AGENTS.md 上，而不是盯着一行代码怎么实现。
实践建议很直接：第一次用 Codex，不要从--full-auto开始，先跑一个不重要的任务，全程用 Plan 模式加手动确认，然后再把完整 diff 从头到尾读一遍。等它在你划定的边界内连续多次稳定交付，再逐步放开权限。这个过程本身就是把 AI 编程 Agent 从“工具”变成“团队资产”的过程。
如果你已经跑通了单机流程，下一步值得深入的方向是：MCP 生态的工程化治理、CI 场景下 Agent 审批的自动分级、以及如何为多个 Agent 并行任务建立统一的日志和审计标准。这些都是从“能用 Codex”走向“用好 Codex”的必经路径。
