自学教程

Codex 配置与定制

Codex 教程

Codex 支持多层级、细粒度配置，可从全局、项目、会话三个维度调整智能体行为、沙箱权限、模型参数、工具扩展。企业管理员还能下发强制配置，统一管控团队Codex行为。本章讲解配置层级、核心配置文件、沙箱与审批策略、AGENTS.md、子代理、MCP扩展、环境变量与最佳实践。

一、配置优先级（核心规则）

Codex存在多层配置体系，优先级从高到低：

  1. requirements.toml：管理员强制配置（企业工作区），普通用户无法覆盖，优先级最高
  2. 项目目录配置：项目内 config.toml、AGENTS.md、规则文件
  3. 用户全局配置：~/.codex/config.toml（macOS/Linux）、%USERPROFILE%\.codex\config.toml（Windows）
  4. 会话临时设置：桌面App或CLI单次任务内临时参数，仅当前Thread生效

关键：高层级配置会覆盖低层级。例如管理员在requirements.toml锁定沙箱模式，用户本地config.toml的沙箱设置会直接失效。

二、核心配置文件说明

2.1 config.toml（用户自定义主配置）

config.toml是个人/项目自定义配置文件，用于定义模型、沙箱、审批策略、功能开关、子代理、记忆等参数。
基础示例

# 模型基础配置
model = "gpt-5-codex"
reasoning_effort = "high"

# 沙箱与安全策略
sandbox_mode = "workspace-write"
approval_policy = "on-request"

# 子代理开关
[agents]
multi_agent = true

# 全局记忆功能
[features]
memories = true

主要可配置项：

  • 模型名称、推理强度、输出详细度
  • 沙箱模式、审批策略、网络访问开关
  • 子代理启用、智能体迭代速度
  • 功能开关：记忆、操作历史、MCP扩展、自动评审

2.2 requirements.toml（企业管理员强制配置）

面向企业/团队管理员，托管下发至整个工作区，用户不可修改。可强制锁定：

  • 允许的沙箱模式，禁止高危danger-full-access
  • 审批策略，强制高危操作必须人工确认
  • 限制可用模型、禁用插件/技能包
  • 网络访问白名单，限制外部联网范围

适用场景：企业合规、安全管控、团队统一开发规范。

2.3 AGENTS.md（智能体项目指引文件）

AGENTS.md用于给Codex提供项目级持久化指引，不属于权限配置，是行为提示规范。
存放位置优先级：项目根目录AGENTS.md > 全局~/.codex/AGENTS.md。
适合写入内容：

  • 项目编码规范、命名规则、代码风格
  • 项目架构说明、模块依赖、技术栈
  • 禁止修改的文件、目录黑名单
  • 单元测试、提交、文档编写要求

示例片段：

# AGENTS.md
本项目采用Vue3 + TypeScript + TailwindCSS。
- 所有接口请求统一使用src/api下封装函数
- 禁止直接修改package.json的版本号
- 代码修改必须附带单元测试

2.4 Rules规则文件（Starlark语法）

使用Starlark编写命令黑白名单，控制Shell命令权限：定义哪些命令自动放行、哪些触发人工审批、哪些直接拦截。
适合限制高危命令，如rm、sudo、网络扫描等，作为沙箱之外的第二层安全约束。

三、沙箱模式与审批策略（安全配置）

沙箱是硬访问边界，控制文件读写、命令执行范围；审批策略是交互弹窗规则，二者配合使用。

沙箱三种模式

  1. read-only 只读模式：仅允许读取文件，所有修改、命令、网络请求均需要审批。适合代码阅读、架构分析、代码评审。
  2. workspace-write 默认模式：仅允许在当前项目工作目录读写文件、执行命令；工作目录外的文件访问、系统级操作需要人工审批。日常开发推荐。
  3. danger-full-access 完全访问：放开本地文件与系统命令权限，高风险，仅可信本地环境使用，企业环境一般禁用。

审批策略

  • on-request（默认按需询问）：跨工作区、高危操作弹出人工确认窗口，低风险操作自动放行。
  • untrusted不信任模式：绝大多数文件修改、命令执行都需要人工确认，适合陌生代码仓库。
  • never永不询问：不弹窗，完全自动执行，必须搭配严格沙箱使用。

Auto-review自动审核：内置子代理自动校验低风险操作，减少弹窗，高危操作依然会请求人工确认。

四、子代理与Agent相关配置

Codex支持主代理自动拆分任务，生成子代理协同工作，内置两类角色：

  • explorer探索者：读取大型代码库，分析项目架构、梳理依赖
  • worker执行者：编写代码、修复Bug、执行测试

在config.toml开启子代理：

[agents]
multi_agent = true
allow_recursive_subagents = false
speed = "balanced"
  • speed参数：fast快速迭代，适合简单任务；balanced平衡模式；thorough深度推理，适合大型重构。
  • allow_recursive_subagents：控制子代理是否继续生成更深一层子代理，关闭可降低资源消耗与风险。

五、MCP（Model Context Protocol）扩展配置

MCP模型上下文协议，是Codex外接外部工具、业务系统的标准化协议。支持两种连接方式：

  1. STDIO本地进程：本地MCP服务，通过子进程调用，适合本地工具。
  2. Streamable‑HTTP远程服务：远程MCP服务，对接团队内部业务平台。

在config.toml中配置MCP服务，加载自定义工具，扩展Codex能力，例如对接内部数据库、项目管理平台、CI接口。

六、环境变量配置

环境变量适合CLI、非交互模式、CI流水线场景，优先级低于项目配置文件。常用变量：

  • OPENAI_API_KEY：API密钥
  • OPENAI_BASE_URL：自定义API端点（对接兼容第三方模型）
  • CODEX_HOME：自定义Codex配置目录
  • CODEX_SANDBOX_MODE：临时指定沙箱模式

七、其他可定制能力

  1. Memories全局记忆
    开启后Codex跨会话记住你的编码偏好、项目约定，自动沉淀经验，减少重复描述需求。记忆文件存储在本地目录。
  2. Record & Replay 录制与重放
    录制Agent完整任务流程，用于调试配置、复现问题、教学演示。
  3. 任务生命周期Hooks钩子
    在任务启动、文件修改、任务完成等节点触发自定义脚本，适合自动化：自动格式化代码、运行lint、提交日志。
  4. 斜杠命令
    桌面App内置/plan、/goal、/share等命令，可结合项目配置自定义行为。

八、配置调试流程

  1. 新建或编辑对应层级的config.toml；项目级配置放置在项目根目录。
  2. 编写AGENTS.md，写入项目约束。
  3. 启动Codex，新建Thread会话（已有会话不会自动加载新配置，必须新建会话生效）。
  4. 测试任务，观察Agent行为、审批弹窗、权限限制是否符合预期。
  5. 调试完毕，可使用Record & Replay复现任务验证配置稳定性。

九、安全与最佳实践

  1. 日常开发默认使用 workspace-write + on-request，兼顾安全与效率。
  2. 避免随意启用danger-full-access，仅在完全可信本地环境短期使用。
  3. 团队项目必须维护AGENTS.md，统一编码规范，减少AI输出偏差。
  4. 企业环境由管理员通过requirements.toml统一强制安全策略，禁止开放高危权限。
  5. 修改配置后，必须新建Thread，已运行会话不会加载新配置。
  6. AI生成代码仍然需要人工审查，沙箱仅降低风险，不等于绝对安全。

十、小结

Codex的配置体系采用分层设计，兼顾个人自定义与企业管控。通过config.toml、AGENTS.md、Rules、MCP、子代理等能力，开发者可以深度定制Codex的模型行为、权限边界、工具扩展。合理配置沙箱与审批策略，在保障安全的前提下，充分发挥Codex在代码编写、重构、调试的自动化能力。

标签：

0 条笔记