Codex CLI 实战：AGENTS.md、配置分层与权限管控

Codex CLI 是用于检查、编辑、执行命令和自动化重复工作的本地终端客户端，可以在仓库上进行操作。它的核心关键词是 Codex CLI；搜索意图很实际：仅安装它是不够的，开发者想知道 AGENTS.md 里要写什么、config.toml 在哪里、如何使用 profiles，以及如何避免无人能解释的全局权限。

我推荐的配置分为三层：仓库行为说明、个人偏好配置，以及针对每种任务风险级别的 profiles。不要把所有规则都塞进一个 prompt，也不要把全部权限写在全局的 config.toml 里。

我的立场：workspace 下的舒适写 preset 是本地开发的良好起点；danger-full-access 和开放网络不是高效能的 profile。它们是临时例外，必须有原因、有任务、有审查。

Codex CLI 到底配置了什么

Codex CLI 可以交互式工作、用 codex exec 运行脚本或 CI，且使用与 IDE 扩展相同的配置基础。CLI 有可见命令：启动指令（/init）、查询状态（/status）、选择权限（/permissions）和审查变更（/review）。价值不在于终端本身：而是可以把这个循环转换成可复现的配置。

要把两个常被混淆的问题分开：agent 对项目了解到什么程度，以及它能做什么。AGENTS.md 说明命令、约束和验收标准；sandbox、网络和 approval policy 控制实际能力。一句禁止发布的指令不会阻止拥有发布权限的 token。

指令指导任务；profile 和 sandbox 界定 agent 能做什么；审批决定何时停下来。

避免意外的层级结构

选项不是存在一个文件里。Codex 按以下顺序应用配置：先是 CLI flags 和 --config 值，然后从根目录到当前子目录的 .codex/config.toml，再是选中的 profile，之后是 ~/.codex/config.toml，最后是默认值。项目文件只在信任该项目时才加载；这样可以避免克隆一个仓库就激活配置、hooks 或规则，而无需你的决定。

利用这个优先级避免雪球效应。在 ~/.codex/config.toml 里放置不依赖仓库的个人默认值。在 .codex/config.toml 里只放团队可以审查的项目调整。在 profile 里放置风险差异：例如，只读审查与有网络控制的本地编辑。

AGENTS.md 是操作契约，不是重复的 README

Codex 在每次执行开始时构建一条指令链：先读全局指南，然后从 Git 根目录遍历到当前目录。在每个层级，AGENTS.override.md 优先于 AGENTS.md；离代码更近的文件出现在最后，因此可以细化通用规则。不要把它变成百科全书：默认的组合限制是 32 KiB，埋在深处的一条关键指令就不再是指令。

根目录的 AGENTS.md 应该回答操作性问题：如何安装、什么命令用来验证、哪些路径是敏感的、什么变更需要迁移或审查、以及什么绝对不能包含在日志或 commits 中。services/payments/ 下的 override 可以添加该区域的命令和限制，而不会污染 monorepo 的其余部分。

不要存放密钥、凭据、完整的 incident playbooks 或客户数据。文件是作为上下文发送给 agent 的：这是一份工作契约，不是保险箱。

每周一剂

每周我会在 5 分钟的邮件中为你总结开发者工具、AI、Agent、MCP、安全和工作流。在西班牙语中，没有噪音。

示例最小配置：带有可验证 guardrails 的仓库

这个示例故意很短。它不试图描述产品；而是声明少数几条能改变任务结果的规则。真实的 approval 和网络策略存在于配置中，而非 Markdown 里。

值得检查的内容

# 仓库工作契约

## 编辑之前
- 阅读 docs/architecture.md 并执行 npm ci。
- 未经批准不要修改 .github/workflows、infra/ 或迁移文件。

## 验证
- 对 src/ 的更改执行 npm run lint 和 npm test。
- 在结果中解释你无法执行的测试。

## 数据
- 永远不要打印环境变量，也不要将生产数据复制到 fixtures。

要检查加载了什么，从根目录启动一个新会话，让 Codex 枚举当前激活的指令；从子目录重复检查。如果解释与你的层级不一致，在更近的文件或忘记的 override 中修正，然后再自动化任何事情。

Profiles：权限必须跟随任务

Profile 不是人的身份；而是某种工作的策略。创建一个阅读用的 profile 来探索或审查，创建一个 workspace 编辑 profile 用于本地更改，创建一个隔离 profile 用于需要网络的孤立任务。避免创建全能 profile 因懒惰而成为默认。

Profile 位于用户配置旁边，用 --profile 选择。这样 config.toml 可以保存公共基础，而每个 profile 只需改变最少的部分：sandbox、审批策略，以及在不可避免时才改变的网络策略。不要试图把提供商凭据或遥测移到仓库的 .codex/config.toml：文档将这些密钥保留在用户级别。

有效的规则是：CI 不继承你笔记本的 profile，仓库也无法降低你机器的策略。为 runner 单独定义账户、密钥和权限，只在已经有验证和回滚契约时才执行非交互模式。

一个合理的起始 config.toml

以下 profile 允许在 workspace 内编辑，并把扩大能力的决策保留在审批之下。这不是通用配置：它是一个起点，你应该在一个没有敏感数据的仓库里测试它。

~/.codex/local-edit.config.toml

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

[sandbox_workspace_write]
network_access = false

用 codex --profile local-edit 启动，在第一个任务前查询 /status。如果你需要文档或依赖，不要把整个会话变成开放网络：创建一个受限的研究 profile，或为该具体操作请求批准。

Sandbox、审批和网络是三个不同的控制

Sandbox 定义技术边界——例如读取、workspace 写入或更广泛的访问；approval policy 定义 Codex 何时停下来请求授权。使用 Auto 模式（workspace-write 和 on-request）时，它可以在工作目录内编辑和执行，但必须请求批准才能超出该限制或使用网络。

网络值得单独决定。使用 workspace-write 时，它是关闭的，除非你激活它。如果你激活它而没有代理，传出流量是直接的，不受域名列表限制。要限制目标，激活 features.network_proxy 并声明 allowlist 规则；代理本身不会自动授予网络。* 代表广泛的公共网络，而非安全列表。

MCP tools 和集成不会自动被命令代理过滤。检查它们各自的作用域、效果注释和审批策略。模型可以链式调用工具：分析每个孤立的权限不如看完整的数据流有用。

目前还不该自动化的东西

不要用 approval_policy = "never" 执行发布、删除、迁移数据、轮换密钥、改变基础设施或在测试环境外写入的操作。非交互模式适用于其 diff、测试、目标和回滚都已定义的可重复操作；不适用于在还没有控制时消除摩擦。

也不要混淆绿色测试与授权。测试可以证明本地行为，但仍可能不知道用户是否有权发送邮件、部署变更或读取其他租户的资源。这些屏障存在于后端、token 和环境中，而非对话中。

团队采用清单

• 添加一个不超过两屏的根 AGENTS.md，包含 setup、验证、敏感路径和数据处理。
• 只在规则确实本地化的地方创建 override，并测试 Codex 从该文件夹加载了哪些文件。
• 定义阅读、编辑和网络受限 profiles；从阅读或无网络编辑开始。
• 对环境变更、网络、受保护路径和有副作用的工具保持 on-request。
• 将 CI runner 配置与开发者的个人配置分开。
• 审查 diff、命令和测试，并记录为什么允许一个权限例外。
• 在扩大自主权之前，测量阻塞、重试、被拒绝的审查和节省的时间。

FAQ

它是什么？

它是 Codex 的终端客户端，用于检查仓库、编辑文件、执行命令和从项目目录自动化重复工作流。

config.toml 在哪里？

个人配置在 ~/.codex/config.toml；仓库可以添加 .codex/config.toml，Codex 只对可信项目加载它，且不能替换机器级别的敏感密钥。

AGENTS.md 和 config.toml 有什么区别？

AGENTS.md 提供指令和上下文；config.toml 控制 profiles、sandbox、审批、网络和 MCP 服务器等客户端选项。指令文件不会授予或撤销技术权限。

我应该使用 approval_policy never 吗？

只在操作、环境、回滚和数据限制都已定义狭窄且已验证的自动化中。对于探索性工作或敏感变更，保留人工审批。

网络 allowlist 在声明域名后自动激活吗？

不是。你必须启用网络和网络代理；网络关闭时代理不起作用，网络开启但没有代理时流量仍然是直接的。

我可以在笔记本和 CI 中使用相同的 profile 吗？

这不是好主意。CI 需要特定的身份、密钥、权限和回滚；不应该继承交互式个人配置。

如何在仓库中安全配置 Codex CLI

1. 创建检查点。在向 agent 请求更改之前，确认仓库是干净的或记录当前状态。
2. 编写根契约。添加 AGENTS.md，包含团队可以检查的 setup、验证命令、敏感路径和数据规则。
3. 测试层级。从根目录和子目录请求 Codex 枚举激活的指令，修正意外的 override。
4. 选择基础 profile。从阅读或 workspace-write 加 approval_policy on-request 和网络关闭开始。
5. 分离例外。为网络创建研究 profile 或临时审批；不要因单一任务而降低基础 profile。
6. 用限制配置网络。如果需要网络，激活 network_proxy 且只允许任务所需的具体主机。
7. 执行可逆任务。在中等风险的仓库使用文档、测试或小更改，并审查命令、diff 和证据。
8. 扩大之前先测量。在多个任务中记录权限阻塞、失败测试、重试和审查发现。
9. 最后自动化。只有在输入、允许的操作、审批、验证和回滚都在 prompt 之外定义时，才在 CI 中使用 codex exec。

健康的限制

并行化研究和有边界的任务。不要并行化技术判断或最终集成。

参考来源

OpenAI Docs: Codex CLI

OpenAI Docs: Config basics

OpenAI Docs: AGENTS.md

OpenAI Docs: Config reference

OpenAI Docs: Agent approvals & security

你可能还感兴趣

Codex 与互联网：sandbox 和安全

AGENTS.md 和 CLAUDE.md：agent 的上下文

Agent hooks

Agent 指标

如何协调多个代码 Agent

每周接收一次开发者 AI 工具阅读

每周我会在 5 分钟的邮件中为你总结开发者 AI 工具、Agent、MCP、安全和工作流。在西班牙语中，没有噪音。