Codex 团队落地实战：权限、规范、Bedrock 路径一站式决策

团队准备统一使用 Codex 时，安全负责人通常会先问三个问题：谁能开 full access、.env 文件能不能被读取、用量和审计日志在哪里看。这三个问题决定了 Codex 团队落地的第一步——不是先配 API key，而是先定权限边界。本篇给出 Codex 企业采用的决策框架：先配置 requirements.toml 和 permission profiles 约束成员权限，再统一 AGENTS.md 分层规范，再选择部署路径（ChatGPT workspace / API Key / Bedrock），最后接入 Analytics Dashboard 和 Compliance API。正文会澄清一个易混淆事实：AWS 2026-06-03 宣布 GPT-5.4 在 GovCloud 可用，但 Codex 的 Bedrock provider 当前不支持 GovCloud endpoints，两者不是一回事。

一、企业权限配置框架：别让 full access 散在每个人本地

企业管理员可以用云端 managed requirements 约束本地 Codex 的行为。requirements.toml 是 Codex 的策略配置文件，管理员可以按用户组分配不同策略，而不是让每个成员在各自环境里自己配。

1.1 requirements.toml 的关键字段

以下是团队落地时最常用的字段清单：

字段	作用	建议值
approval_policy	控制是否需要人工审批	"suggest" 或 "auto-edit"（不要用 "never" 作为团队默认）
approvals_reviewer	指定审批人	团队负责人或安全负责人
automatic_review_policy	自动 review 规则	按项目风险等级设置
permission profiles	新版本权限模型（0.138.0+）	推荐新部署使用
sandbox_mode	旧版本权限模型	仅用于老部署迁移
web_search_mode	是否允许网络搜索	限制性项目可禁用
managed_hooks	统一 hook 配置	lint-check、test-runner 等
MCP servers allowlist	限制可用 MCP 服务器	只允许 filesystem、github 等

Codex 0.138.0 之后推荐使用 permission profiles 和 allowed_permission_profiles，老部署才用 allowed_sandbox_modes。具体版本门槛以官方文档为准。

1.2 禁止的组合

以下组合不能作为团队默认配置：

danger-full-access + approval_policy = "never"

这是最高权限加免审批的组合，会让成员无需审批即可访问任何文件和执行任何操作。应该通过云端 managed requirements 禁止这个组合出现在成员的本地配置里。

1.3 配置示例

# requirements.toml
[managed]
approval_policy = "suggest"
allowed_permission_profiles = ["suggest", "auto-edit"]
default_permissions = "suggest"

[mcp]
allowed_servers = ["filesystem", "github"]

[hooks]
managed_hooks = ["lint-check", "test-runner"]

这个示例限制了成员只能使用 "suggest" 或 "auto-edit" 权限，默认是 "suggest"，MCP 服务器只允许 filesystem 和 github，hook 统一配置 lint-check 和 test-runner。

云端 managed requirements 可以按用户组分配。例如，核心开发组允许 "auto-edit"，实习生组只能用 "suggest"。这样权限边界就集中在企业管理员手里，而不是散在每个人本地。

二、最小权限与沙盒设计：具体规则、deny glob、敏感文件保护

安全负责人需要的不是”最小权限”的口号，而是具体规则：哪些文件能读、哪些能写、哪些完全禁止。

2.1 filesystem permission 三种值

Codex 的 filesystem permission 支持三种值：

• read：只读，不能修改
• write：读写，可以修改
• deny：禁止访问，优先级最高

优先级规则是：更具体的规则优先，deny 的优先级最高。例如，如果同时配置了 "**/*.env" = "deny" 和 ":workspace_roots" = "write"，.env 文件仍然被禁止访问，即使它在 workspace_roots 范围内。

2.2 工作区范围限制

:workspace_roots 用于限制 Codex 的工作区范围。配置示例：

[permissions.filesystem]
":workspace_roots" = "write"

这会让 Codex 只能在当前工作区根目录及子目录内操作，不能访问工作区以外的文件。

2.3 敏感文件保护

以下配置可以防止 Codex 读取敏感环境文件和密钥目录：

[permissions.filesystem]
":workspace_roots" = "write"
"**/*.env" = "deny"
"**/secrets/**" = "deny"
"**/*.log" = "read"

这段配置的含义：

• 工作区根目录及子目录：可读写
• 所有 .env 文件：禁止访问（无论在哪层目录）
• secrets/ 目录及其子文件：禁止访问
• 所有 .log 文件：只读

deny 规则会阻止 Codex 读取或修改这些敏感文件，即使它有 workspace_roots 的 write 权限。

2.4 network permission

Network permission 可以启用并按域名控制访问：

[permissions.network]
enabled = true
allow = ["github.com", "api.openai.com"]
deny = ["localhost", "127.0.0.1"]

这段配置允许 Codex 访问 github.com 和 api.openai.com，禁止访问 localhost 和 127.0.0.1。

Codex 对 local/private network 有额外的 guard，防止意外访问内网资源。团队可以根据项目需求配置 domain allow/deny 列表。

2.5 permission profiles vs sandbox mode

Permission profiles 是新版本（0.138.0+）推荐的权限模型，sandbox mode 是旧模型。两者的区别：

对比项	Permission profiles	Sandbox mode
适用版本	0.138.0+ 新部署	老部署迁移
粒度	更细粒度，支持多种 profile	较粗粒度
配置字段	allowed_permission_profiles + default_permissions	allowed_sandbox_modes
推荐	新部署优先使用	仅用于老部署

新部署建议使用 permission profiles，老部署可以逐步迁移。具体版本门槛以官方文档为准。

三、团队共享规范：统一 AGENTS.md，避免每人各写一套

团队要统一 prompt、上下文规则、review instruction，不能让每个人各写一套、维护成本爆炸。AGENTS.md 是 Codex 的自定义指令文件，支持分层架构和优先级规则。

3.1 instruction chain 顺序

Codex 启动时构建 instruction chain，顺序如下：

全局规则 ( ~/.config/codex/AGENTS.md )
    ↓ 优先级最低
项目规则 ( 项目根/AGENTS.md )
    ↓ 覆盖全局
模块规则 ( src/auth/AGENTS.md )
    ↓ 优先级最高
当前目录规则 ( AGENTS.override.md )

更靠近当前目录的指导排在后面、优先级更高。例如，如果全局规则要求”所有函数都要写单元测试”，但项目规则写”核心模块必须有单元测试，其他模块可选”，当前目录的 AGENTS.override.md 可以进一步覆盖为”本模块不需要单元测试”。

3.2 分层架构建议

不要把所有规则塞进一个大文件，应该分层编写：

• ~/.config/codex/AGENTS.md：全局规则（代码风格、测试要求、通用禁止项）
• 项目根/AGENTS.md：项目规则（架构、依赖、部署方式）
• src/auth/AGENTS.md：模块规则（认证模块特殊要求）

每层控制在 10-15 KiB 以内，这样既方便维护，也能避免截断问题。

3.3 32 KiB 上限处理

Codex 默认 project_doc_max_bytes 为 32 KiB。如果 AGENTS.md 文件过大，会被截断。

处理方法有两种：

1. 调整上限：修改 project_doc_max_bytes 配置值
2. 拆分到嵌套目录：把大文件拆成多个小文件，放在不同层级的目录里

推荐第二种方法，因为分层架构更便于团队维护和职责分工。

3.4 AGENTS.override.md 的作用

AGENTS.override.md 用于覆盖上级 AGENTS.md，优先级最高。适用场景：

• 特定子目录需要临时覆盖全局规则
• 实验性模块需要放宽某些限制
• 某个模块有与项目不同的特殊要求

使用时要明确记录覆盖原因，避免团队成员混淆。

3.5 团队维护建议

团队维护 AGENTS.md 时需要明确：

• Ownership：谁负责维护哪个层级（全局规则由技术负责人维护，项目规则由项目 owner 维护，模块规则由模块负责人维护）
• 维护预算：每个 sprint 分配多少时间 review 和更新
• Review cycle：多久 review 一次（建议每季度 review 全局规则，每月 review 项目规则）

这样 AGENTS.md 就能成为团队共享的活文档，而不是每个人各写一套。

四、部署形态决策：ChatGPT workspace、API Key、Bedrock 怎么选

组织要选择走哪条账单/合规/控制路径。三条路径的权益、限制、适用场景不同。

4.1 三条路径对照表

维度	ChatGPT Business/Enterprise	API Key	Amazon Bedrock
认证方式	ChatGPT sign-in	OPENAI_API_KEY	Bedrock API key 或 AWS IAM
账单归属	OpenAI workspace	OpenAI API 账户	AWS 账单
团队治理	Analytics Dashboard、managed requirements	无原生团队治理	AWS IAM、CloudTrail
功能完整性	最完整	最灵活	部分功能缺失（见 4.2）
合规/区域	OpenAI 区域	OpenAI 区域	AWS Regions、data residency
GovCloud 支持	无	无	模型可用 ≠ Codex provider 支持（见 4.3）
适用场景	中小团队、需要 workspace 管理	开发者灵活使用	AWS 体系、需要 AWS 账单/IAM

4.2 Bedrock 功能缺失清单

截至 2026-06-08 官方文档，以下功能在 Bedrock 路径不可用：

• Fast Mode：不支持
• Hosted web/file search：不支持
• Computer use：不支持
• Shell tool：不支持
• Image generation tool：不支持
• Remote MCP servers：不支持
• On-demand inference only：不支持 Provisioned Throughput

这些功能依赖 OpenAI-hosted cloud services / hosted tools / cloud-managed discovery，不在这条路径里。如果团队需要这些功能，优先选择 ChatGPT workspace 或 API Key。

4.3 GovCloud 风险澄清

这里需要区分两个事实：

1. AWS GPT-5.4 GovCloud (US-West) 可用（2026-06-03 AWS 公告）

   • 模型本身在 GovCloud 可用
   • 通过 Bedrock API 调用 GPT-5.4

2. Codex Bedrock provider 不支持 GovCloud endpoints（OpenAI Codex 官方文档）

   • Codex 的 amazon-bedrock provider 当前不支持 Bedrock Mantle endpoints in AWS GovCloud Regions
   • 不能在 GovCloud 环境下配置 Codex 走 Bedrock

不要写”Codex on Bedrock 已支持 GovCloud”。模型在 GovCloud 可用和 Codex provider endpoint 支持是两回事。

4.4 适用场景说明

根据团队需求选择路径：

ChatGPT Business/Enterprise：

• 中小团队（<50 人）
• 需要 workspace 管理、Analytics Dashboard
• 需要最完整的功能覆盖
• 不需要 AWS 账单或 IAM

API Key：

• 开发者灵活使用
• 不需要团队治理层
• 直接计费到 OpenAI API 账户
• 不需要合规审计

Amazon Bedrock：

• AWS 体系团队（已有 AWS 账户、IAM、billing）
• 需要 AWS 账单归集到 AWS commitments
• 需要 data residency 或特定 AWS Regions
• 接受部分功能缺失（见 4.2）

五、Bedrock 配置与限制：AWS-native auth、功能缺失、GovCloud 风险

选择 Bedrock 路径的团队需要知道具体配置方式、认证方法、不支持的功能和 GovCloud 风险。

5.1 配置 amazon-bedrock provider

在 Codex 配置文件中设置 provider：

{
  "provider": "amazon-bedrock",
  "aws_region": "us-east-1",
  "model_id": "openai.gpt-5.5"
}

这是官方示例。模型 ID 和 Region 以官方文档为准。

5.2 AWS-native auth

Bedrock 路径使用 AWS-native 认证，不用 OPENAI_API_KEY：

• Bedrock API key：短期 key 最长 12 小时，继承 IAM principal permissions
• AWS IAM credentials：通过 IAM role 或 IAM user 配置

推荐生产环境使用短期 key 或 IAM role，长期 key 只用于探索测试。

5.3 支持的 commercial AWS Regions

官方文档支持的 commercial AWS Regions 包括：

• us-east-1
• us-west-2
• eu-west-1
• ap-northeast-1

具体 Region 列表以 AWS Bedrock OpenAI models 文档为准。

5.4 Bedrock API key 治理

Bedrock API key 的关键规则：

• Short-term key：最长 12 小时（或 session duration），继承 IAM principal permissions，推荐生产使用
• Long-term key：只用于 exploration，不推荐生产使用
• CloudTrail 记录：API calls 记录到 AWS CloudTrail（API key 本身不记录在日志里）
• IAM actions 控制：可以通过 IAM actions 控制谁可以生成和使用 API keys

5.5 功能缺失清单（重申）

截至 2026-06-08 官方文档，以下功能在 Bedrock 路径不可用：

• Fast Mode
• Hosted web/file search
• Computer use
• Shell tool
• Image generation tool
• Remote MCP servers
• On-demand inference only（不支持 Provisioned Throughput）

如果团队依赖这些功能，需要改用 ChatGPT workspace 或 API Key 路径。

5.6 GovCloud 风险（重申）

这里再次强调：

• AWS GPT-5.4 GovCloud (US-West) 可用（2026-06-03 AWS 公告）：模型本身在 GovCloud 可用
• Codex Bedrock provider 不支持 GovCloud endpoints（OpenAI Codex 官方文档）：Codex 的 Bedrock Mantle path 当前不支持 AWS GovCloud Regions

不要混淆这两个事实。需要 GovCloud 的团队，目前不能配置 Codex 走 Bedrock。

六、治理与审计：团队用量、合规日志在哪看

管理员要追踪团队 adoption、usage、code review 效果，接入 audit logs 和 SIEM。

6.1 三条治理路径对照表

路径	功能	滞后时间	适用场景
Analytics Dashboard	adoption、usage、code review feedback	Usage data lag up to 12 hours	团队推广效果追踪
Analytics API	Daily/weekly buckets、workspace/per-user usage、per-client breakdown、Code Review 指标	实时到数小时	成本治理、深度分析
Compliance API	导出 Codex 活动和 audit metadata	取决于 SIEM/eDiscovery 配置	合规审计、接入 SIEM

6.2 使用场景说明

6.2.1 推广效果追踪

使用 Analytics Dashboard 查看团队 adoption 和 usage：

• 查看成员激活率
• 查看 code review feedback 质量
• 查看各客户端使用分布

Dashboard 数据可能最多滞后 12 小时，适合做周报和月报，不适合实时监控。

6.2.2 成本治理

使用 Analytics API 做深度分析：

• 按 workspace/user/model 拆分用量
• Daily/weekly buckets 对比趋势
• Per-client breakdown（Codex App/CLI/IDE/Cloud）
• Code Review 指标统计

适合对接到内部成本治理系统，与成本优化策略联动。

6.2.3 合规审计

使用 Compliance API 导出 audit logs：

• 导出 Codex 活动记录
• 导出 audit metadata
• 接入 SIEM/eDiscovery 系统
• 配合合规审计要求

适合需要合规审计的组织，如金融、政务、医疗等。

6.3 治理路径选择建议

• Analytics Dashboard：适合技术负责人、项目经理追踪团队推广效果
• Analytics API：适合平台工程团队做成本治理和深度分析
• Compliance API：适合安全/合规团队接入 SIEM 和 eDiscovery

三条路径可以根据组织需求组合使用。

七、团队推广路径：从个人试用到组织治理

团队不知道从哪里开始、怎么分阶段推进、如何选择第一批试点任务。

7.1 三阶段推进框架

阶段一：个人可控（定权限边界）

目标：先确保每个成员的权限边界可控，不让敏感文件散在各人本地。

核心动作：

• 禁止 danger-full-access + approval_policy = "never" 作为团队默认
• 配置 deny glob 保护 .env、secrets/
• 设置 :workspace_roots 限制工作区范围

检验标准：无成员能无审批访问敏感文件。

阶段二：小团队试点（统一规范 + 低风险任务）

目标：在小团队内统一 AGENTS.md 和 skills，先跑低风险任务，验证流程可行。

核心动作：

• 编写全局 AGENTS.md（代码风格、测试要求）
• 编写项目级 AGENTS.md（架构、依赖、部署）
• 选择低风险任务：文档生成、lint 修复、test 补充
• 避免：直接自动化生产部署、直接处理支付逻辑

检验标准：团队 AGENTS.md 被 80% 成员使用，无重大安全事件。

阶段三：组织治理（managed requirements + Analytics/Compliance API）

目标：把权限和规范上升为组织级治理，接入观测和审计。

核心动作：

• 配置云端 managed requirements 按用户组分配
• 接入 Analytics Dashboard/API 追踪 adoption 和用量
• 接入 Compliance API 对接 SIEM
• 定期 review permission profiles 和 MCP allowlist

检验标准：治理仪表板上线，audit logs 可追溯。

7.2 试点任务建议

低风险任务优先

适合第一批试点：

• 文档生成：README、API 文档、注释补充
• Lint 修复：eslint、prettier、自动格式化
• Test 补充：单元测试、集成测试骨架
• 重构建议：代码结构优化建议（需人工审核）

避免直接自动化

不适合第一批试点：

• 生产部署
• 支付逻辑
• 权限变更
• 数据删除

这些任务风险高，应该等权限治理和审计机制成熟后再逐步放开。

7.3 与系列文章的关系

本篇是团队落地决策页，后续可以深入具体模块：

• AGENTS.md 详细写法：如何编写分层规则、如何避免截断、如何维护
• 个人排障与沙盒：权限问题、沙盒配置、常见错误
• Cloud/GitHub 集成：远程开发、GitHub review、Cloud task
• 成本与额度优化：token 级降本技巧、预算控制
• 自动化与长任务治理：定时触发、heartbeat、跨天任务

总结与下一步

如果你是技术负责人，正在推进 Codex 团队落地：

1. 先读权限配置（本文一、二节）→ 禁止危险权限组合
2. 再统一规范（本文三节）→ 编写 AGENTS.md 分层规则
3. 选部署路径（本文四、五节）→ ChatGPT workspace / API Key / Bedrock 决策
4. 接入治理（本文六节）→ Analytics Dashboard/API、Compliance API

后续可以深入具体模块：

• AGENTS.md 详细写法：如何编写分层规则、如何避免截断、如何维护
• 个人排障与沙盒：权限问题、沙盒配置、常见错误
• Cloud/GitHub 集成：远程开发、GitHub review、Cloud task
• 成本与额度优化：token 级降本技巧、预算控制
• 自动化与长任务治理：定时触发、heartbeat、跨天任务

相关基础：

• 团队 Git 协作基础：Git flow、branch 策略、code review 流程
• CI secrets 和权限安全：GitHub Actions secrets、权限边界、安全实践