Codex 项目与团队定制

定制的目标不是让 Codex“更自由”，而是让项目事实、允许动作和完成标准在不同任务与入口中保持一致。

核对日期 2026-07-15 · 适用于当前 Codex CLI、IDE 与桌面 App 的共享配置模型

先用最小表面

需求	应该放在哪里
只对当前任务生效	当前提示词或任务上下文
仓库长期命令、目录和完成标准	`AGENTS.md`
模型、sandbox、approval、MCP 等项目默认设置	`.codex/config.toml`
对 sandbox 外命令前缀做实验性 allow / prompt / forbidden	`.codex/rules/*.rules`
重复的专业工作流和参考资料	Skill
并行探索、测试或专项审查	Subagents / custom agents
可安装、可分发的 skills、MCP servers、apps/connectors、hooks 和展示资产集合	Plugin
连接外部实时数据或执行动作	MCP server / app connector
工具调用前后的审计、提示和后置检查	Hook

不要把所有约束复制到每一层。规则重复后很快会冲突，也会增加上下文和排错成本。

用 AGENTS.md 保存项目事实

仓库根目录示例：

# AGENTS.md

## 项目结构
- apps/web：前端入口和页面
- packages/core：共享领域逻辑
- tests：集成测试

## 常用命令
- 安装：pnpm install --frozen-lockfile
- 开发：pnpm dev
- 检查：pnpm lint && pnpm typecheck
- 测试：pnpm test
- 构建：pnpm build

## 修改约束
- 修改前阅读同目录实现、测试和最近调用方。
- 不提交 .env、密钥、日志、覆盖率或临时截图。
- Bug 修复不顺手升级依赖或重构无关模块。
- 金额、权限和时间逻辑先增加回归测试。

## 完成标准
- 运行与改动直接相关的检查。
- 审查完整 diff，区分原有修改和本次修改。
- 最终列出改动、证据、未验证项和剩余风险。

子目录可以放更具体的 AGENTS.md；更接近目标文件的规则作用于对应子树。个人临时覆盖不要污染团队共享文件。

维护原则：

只写仓库里可以验证、团队愿意长期维护的事实。
命令要对应真实脚本，避免“运行测试”这种无法执行的描述。
不写真实密钥、内部账号或私人偏好。
项目变化后同步更新，否则错误规则会稳定地产生错误结果。

配置层与作用域

Codex 的有效配置从高到低依次为：

CLI flags 与 -c / --config 一次性覆盖。
受信任项目中的 .codex/config.toml，从项目根到当前目录逐层加载，离当前目录最近者优先。
--profile NAME 选择的 $CODEX_HOME/NAME.config.toml。
用户 ~/.codex/config.toml。
系统 /etc/codex/config.toml（存在时）。
内建默认值。

管理员 requirements.toml 是约束上限，例如禁止 approval_policy = "never"；它不是普通的第七层覆盖配置。项目未被信任时，项目 .codex 配置、Hooks 和 Rules 都会跳过。

一个保守示例：

toml

model = "gpt-5.6"
approval_policy = "on-request"
sandbox_mode = "workspace-write"

[shell_environment_policy]
inherit = "core"

这是旧版 sandbox 配置路径，适合仍以 sandbox_mode 为基线的环境。不要把它与下文的 Beta permission profiles 混在同一套有效配置里。

OpenAI 当前默认示例使用 gpt-5.6；该别名在 OpenAI 模型页中指向 gpt-5.6-sol。自定义 model_provider 或第三方网关应改用提供方实际支持的 ID。提交项目配置前，确认模型对团队账号可用，也不要把个人路径、代理、Token 或组织内部地址带给所有成员。

启动时校验未知配置键：

bash

codex --strict-config

权限设计：默认最小，按需放宽

把风险拆成四层：

文件： 读哪些目录、写哪些目录、是否碰受保护路径。
命令： 只读检查、构建测试、安装、删除、Git 写操作。
网络： 访问哪些域名、是否需要登录态或上传数据。
外部系统： GitHub、工单、云平台、数据库和发布权限。

推荐基线：

陌生仓库：read-only + untrusted。
熟悉仓库日常开发：workspace-write + on-request。
CI：外部容器隔离 + 精确工具和网络策略，不用危险参数代替隔离。
生产、发布和删除：保留独立人工审批，不只依赖模型判断。

approval_policy = "never" 只表示不弹出确认；权限不足时动作会失败。它不自动升级 sandbox，也不代表任务更安全。

workspace-write 默认关闭 spawned commands 的网络。确需命令联网时只开启这一项：

toml

[sandbox_workspace_write]
network_access = true

Web search 独立配置：普通本地任务默认是 cached，web_search = "live" 或 CLI --search 才是实时搜索；但 --yolo 或其他 full-access sandbox 设置会把默认值改为 live。命令网络、Web search、Browser/连接器权限必须分别检查。

Beta permission profiles：与旧 sandbox 二选一

Codex 0.138.0 及以上提供 permission profiles，把文件和网络边界组合成可选择的最小权限策略。该能力当前为 Beta，配置结构可能变化。必须二选一：

旧路径：sandbox_mode 与 [sandbox_workspace_write]。
新路径：default_permissions 与 [permissions.<name>]。

只要任一已加载配置、CLI --sandbox 或所选 profile 仍设置 sandbox_mode，Codex 就使用旧路径，default_permissions 不会按预期生效。迁移前先从用户、项目和系统层删除旧 sandbox 设置，再使用类似配置：

toml

default_permissions = "project-edit"

[permissions.project-edit.filesystem]
":minimal" = "read"

[permissions.project-edit.filesystem.":workspace_roots"]
"." = "write"
"**/*.env" = "deny"

[permissions.project-edit.network]
enabled = false

deny 可从较宽的 read/write 范围中排除敏感路径；它属于 permission profile 的 filesystem 规则，不是 Rules 的命令决策。配置后用 /permissions 确认实际选中的策略，并在无敏感数据的演示仓库验证读、写和网络边界。

Rules：控制可执行命令

Rules 当前仍是 Experimental，主要控制哪些命令前缀可以在 sandbox 外运行。文件放在活动配置层旁的 rules/ 目录，例如个人 ~/.codex/rules/default.rules 或受信任项目的 .codex/rules/default.rules。

python

prefix_rule(
    pattern = ["gh", "pr", "view"],
    decision = "prompt",
    justification = "查看远程 PR 前需要确认",
    match = ["gh pr view 123"],
    not_match = ["gh issue view 123"],
)

决策只有 allow、prompt、forbidden；多条匹配时取最严格结果。修改后重启 Codex，并在真正放行前测试：

bash

codex execpolicy check --pretty \
  --rules ~/.codex/rules/default.rules \
  -- gh pr view 123

设计步骤：

从真实审批记录找高频、稳定、可重复的命令。
使用足够具体的前缀，不允许过宽 shell 通配。
对删除、发布、凭据、远程写入和未知脚本保留 prompt 或 forbidden。
给规则加正反例并在更新后测试。

规则不能判断业务语义。即使 npm test 被允许，测试本身仍可能访问共享数据库；环境隔离和项目说明必须同时存在。

连接 MCP

添加远程 HTTP MCP：

bash

codex mcp add sentry --url https://mcp.sentry.dev/mcp
codex mcp login sentry
codex mcp list

只有服务要求 OAuth 时才运行 codex mcp login <name>；需要限定授权范围时先看 codex mcp login --help 的 --scopes。使用 bearer token 的服务应从环境变量读取凭据，不把 Token 写进命令、配置示例或截图。

添加本地 stdio MCP：

bash

codex mcp add my-server -- command-that-starts-the-server
codex mcp list

接入前检查：

服务发布者、包名和启动命令是否可信。
工具是只读查询还是可以创建、修改、删除外部数据。
Token 存储在哪里，是否最小权限、可轮换、可撤销。
项目级配置是否会要求所有成员安装相同工具。
日志、错误和最终回答是否可能泄露外部数据。

验证不要只看“connected”：让 MCP 执行一次无副作用查询，并检查返回范围、来源和账号边界。

Skills：复用成熟流程

适合做 Skill 的信号：

同一流程已经稳定重复至少三次。
步骤、输入、产物和完成标准清楚。
需要附带参考资料、脚本或模板。
使用者需要一致的质量门槛，而不是一段万能提示词。

不适合：一次性任务、仍在频繁变化的探索流程、只需一条 AGENTS.md 规则的约束。

Skill 内容应说明何时触发、需要什么前提、按什么顺序工作、如何验证以及遇到什么情况停止。仓库级 Skill 的最小结构是 .agents/skills/<name>/SKILL.md，并且 frontmatter 必须包含 name 与 description：

---
name: release-check
description: 核对发布前的构建、测试、产物和变更记录；只在准备发布或要求发布验收时使用。
---

1. 读取仓库发布说明和真实脚本。
2. 运行项目规定的最小发布检查。
3. 报告结果、失败和未验证项，不自动推送或发布。

Codex 会按 description 判断是否加载完整 Skill；描述要写清触发条件和边界。修改后通常会自动发现，未出现时重启客户端再检查。

Subagents：把独立工作移出主线程

当前 Codex 默认启用 multi-agent，桌面 App、CLI 和 IDE 都能显示子代理活动。适合把探索、测试、日志分析和不同审查维度拆成独立任务，再让主线程汇总。

text

使用三个 subagents 并行检查当前分支：
1. 安全与权限；
2. 行为回归与测试缺口；
3. 可维护性。
全部完成后由主线程去重，按严重程度列出带文件位置的发现。不要修改文件。

CLI 使用 /agent 或 /subagents 查看和切换线程。
子代理继承父任务当前 sandbox 和 permission mode；无交互环境中需要新审批的动作会失败。
每个线程都会使用模型、上下文和工具，Token 与资源消耗高于单代理。
读密集任务优先并行；写密集任务应按互不重叠的文件或模块分工，最终由一个主线程合并和验证。
需要稳定角色时，可在 ~/.codex/agents/ 或项目 .codex/agents/ 创建 custom agent TOML；项目文件只在受信任仓库加载。

最小 custom agent 文件必须包含 name、description 和 developer_instructions。例如 .codex/agents/reviewer.toml：

toml

name = "reviewer"
description = "只读审查当前改动中的行为回归、安全问题和测试缺口。"
developer_instructions = """
不要修改文件。按严重程度报告有证据的问题，并引用文件位置。
没有发现时明确说明剩余测试缺口。
"""

文件名只是约定，name 才是代理标识。custom agent 会作为 spawned session 的配置层继承父会话设置；官方明确提示该格式仍可能随作者体验成熟而演进。

Plugins：分发一组能力

Plugin 适合把 skills、MCP servers、apps/connectors、hooks 和展示资产打包分发。工具通过 MCP server 或 app/connector 暴露；当前官方结构没有可直接声明的一等 commands 或 tools manifest 字段。团队采用前检查：

manifest、来源和许可证。
安装后新增的 Skills、MCP tools、connectors、Hooks 和网络连接。
更新和回滚方式。
每次启动增加的上下文或 Token 成本。
工作区管理员是否允许安装。

只有一个简单流程时先用 Skill；需要一组可安装能力和生命周期管理时再做 Plugin。最小 Plugin 至少包含 manifest 和一个实际能力：

text

my-first-plugin/
├── .codex-plugin/
│   └── plugin.json
└── skills/
    └── hello/
        └── SKILL.md

.codex-plugin/plugin.json：

json

{
  "name": "my-first-plugin",
  "version": "1.0.0",
  "description": "Reusable team workflow",
  "skills": "./skills/"
}

先把 Plugin 加入受信任 marketplace，再按 codex plugin list 显示的准确标识安装：

bash

codex plugin marketplace add ./local-marketplace-root
codex plugin marketplace list
codex plugin list
codex plugin add my-first-plugin@MARKETPLACE_NAME

把 MARKETPLACE_NAME 替换为 codex plugin marketplace list 显示的实际名称。安装后启动新任务，确认 Skill 或 MCP tool 真正出现，再做最小无副作用验证。不要只以“安装成功”作为能力可用证据。

Hooks：审计与后置检查，不是写入阻断器

Hook 适合：

写入后运行格式化或静态检查。
在工具调用前记录或提示组织规则。
记录工具调用结果，供交付或合规检查。

当前 PreToolUse 不支持用 continue: false 或 stopReason 阻止工具；返回这些字段会让 Hook 标记失败，但工具调用继续。因此，密钥路径、受保护文件和危险命令的硬阻断必须交给旧 sandbox，或单独采用 permission profile 的 filesystem deny、管理员策略或 Rules，不能只靠 Hook，也不能把两套权限配置混用。

Hook 不适合替代业务测试，也不应悄悄修改大量文件。每个 Hook 都要有明确超时、错误输出、失败策略和跳过条件；后置 Hook 停止后续流程也不能撤销已经发生的写入。

启用来源不明的 Hook 前先审查脚本。危险的 --dangerously-bypass-hook-trust 只适合外部已经审查并隔离的自动化环境。

团队落地顺序

先补准确的 AGENTS.md 和真实验证命令。
使用保守的项目 config.toml，把个人设置留在用户层。
从审批记录提炼少量 Rules。
只连接必要的 MCP，并做最小权限验证。
重复流程成熟后再做 Skill。
多能力分发时再做 Plugin。
只有审计或后置检查需要自动化时才加 Hook；硬阻断仍交给 sandbox、permissions、管理员策略或 Rules。
每次变更都在 CLI、IDE 和 App 中各做一次冒烟检查。

定制故障隔离

出现异常时按层关闭：

新任务中用最小提示词复现。
检查 AGENTS.md 是否过时或作用域错误。
用 --strict-config 检查配置键。
暂停项目 MCP、Skill、Plugin 和 Hook，逐个恢复。
运行 codex doctor --summary。
比较 CLI、IDE 和 App 是否读取同一个项目与 CODEX_HOME。

一次只改变一层，才能知道根因。把所有定制同时删除会失去可复现证据，也可能误删用户原有配置。

Codex 项目与团队定制 ​

先用最小表面 ​

用 AGENTS.md 保存项目事实 ​

配置层与作用域 ​

权限设计：默认最小，按需放宽 ​

Beta permission profiles：与旧 sandbox 二选一 ​

Rules：控制可执行命令 ​

连接 MCP ​

Skills：复用成熟流程 ​

Subagents：把独立工作移出主线程 ​

Plugins：分发一组能力 ​

Hooks：审计与后置检查，不是写入阻断器 ​

团队落地顺序 ​

定制故障隔离 ​

官方资料 ​

Codex 项目与团队定制

先用最小表面

用 AGENTS.md 保存项目事实

配置层与作用域

权限设计：默认最小，按需放宽

Beta permission profiles：与旧 sandbox 二选一

Rules：控制可执行命令

连接 MCP

Skills：复用成熟流程

Subagents：把独立工作移出主线程

Plugins：分发一组能力

Hooks：审计与后置检查，不是写入阻断器

团队落地顺序

定制故障隔离

官方资料