在前面的 Claude Code 系列中我们从目录结构入手逐步拆解了Marketplace Plugin Skill Command Agent Hook MCP LSP Harness Runtime进入 Codex 后第一反应很容易是Codex AGENTS.md config.toml MCP这种理解并不能说错但已经不够完整。当前 Codex 的扩展体系至少包含AGENTS.md Skills Plugins MCP Servers Custom Agents Subagents Hooks Rules Profiles Permissions Sandbox Managed Requirements其中AGENTS.md → 提供持续生效的项目指导 Skill → 封装可复用的任务流程 Plugin → 分发 Skill、Connector 和相关资源 MCP → 接入外部工具与系统 Custom Agent → 定义专门的子任务执行角色 config.toml → 控制模型、工具、权限和运行环境 requirements.toml → 提供管理员不可被用户绕过的约束所以Codex 已经不只是一个读取项目 ↓ 调用模型 ↓ 执行 Shell的轻量 Coding Agent。它正在形成一套更加完整的 Harness 扩展架构Project Guidance Reusable Workflow External Tool Specialized Agent Runtime Policy Plugin Distribution本文暂时不深入讨论这些组件如何运行而是先建立 Codex 扩展体系的静态地图。重点回答Codex CLI、IDE、Desktop 与 Cloud 是什么关系 ~/.codex 中保存什么 项目中的 .codex 目录负责什么 AGENTS.md 与 config.toml 有什么区别 Skill 为什么放在 .agents/skills而不是 .codex/skills Custom Agent 如何配置 MCP 和 Hook 写在哪里 requirements.toml 与 config.toml 有什么不同 Plugin 在整个体系中处于什么位置 哪些目录属于公开接口哪些属于内部状态一、先理解 Codex 不是单一客户端分析 Codex 目录前首先要明确Codex 不是一个单独的命令行程序名称而是一组共享 Agent Harness 能力的产品形态。当前常见的使用入口包括Codex CLI Codex IDE Extension ChatGPT Desktop 中的 Codex Codex Web / Cloud App ServerOpenAI 对 Codex Harness 的定义是负责协调用户、模型和工具之间交互的 Agent LoopCodex CLI 会通过 Responses API 完成模型推理由 Harness 负责组织工具调用、审批、沙箱执行、上下文管理和后续循环。OpenAI 还通过 App Server 将 Codex Core 暴露为长生命周期服务供终端、IDE、本地 App 和其他客户端使用。可以把整体关系理解为┌──────────────────┐ │ Codex Web │ │ Cloud Runtime │ └──────────────────┘ ┌─────────────┐ │ Codex CLI │ └──────┬──────┘ │ ┌──────▼──────┐ │ IDE Plugin │ └──────┬──────┘ │ ┌──────▼────────────┐ │ ChatGPT Desktop │ └──────┬────────────┘ │ ▼ ┌───────────────────────────┐ │ Codex Harness / App Server│ │ │ │ Agent Loop │ │ Thread / Turn │ │ Tool Runtime │ │ Approval │ │ Sandbox │ │ Skill / Agent / MCP │ └──────────────┬────────────┘ ▼ Responses API不同客户端的界面不同但本地 Codex CLI、IDE Extension 和 ChatGPT Desktop 会共享一部分配置。例如OpenAI 官方文档明确说明Codex CLI IDE Extension ChatGPT Desktop可以共享config.toml中的 MCP 配置CLI 与 IDE Extension 也共享同一套配置层。所以分析 Codex 目录时不能只问CLI 把配置放在哪里而应问哪些配置属于 Codex 本地 Harness能够被多个客户端共同读取二、Codex 的整体目录地图先给出一个简化后的静态结构。1. 用户级目录$HOME/ ├── .codex/ │ ├── config.toml │ ├── AGENTS.md │ ├── AGENTS.override.md │ ├── profile.config.toml │ └── 其他运行状态与客户端数据 │ └── .agents/ └── skills/ ├── skill-a/ │ └── SKILL.md └── skill-b/ ├── SKILL.md ├── scripts/ ├── references/ └── assets/其中需要注意Codex 主配置目录 → ~/.codex/ 用户级 Skill 目录 → ~/.agents/skills/Skill 并不是统一放进~/.codex/skills/。当前官方 Skill 发现规范中用户级 Skill 的公开位置是$HOME/.agents/skills而不是$HOME/.codex/skillsCodex 还会读取管理员级/etc/codex/skills和内置 System Skills。2. 项目级目录project/ ├── .git/ │ ├── AGENTS.md │ ├── .codex/ │ ├── config.toml │ ├── hooks.json │ ├── hooks/ │ ├── rules/ │ └── 其他项目配置 │ ├── .agents/ │ └── skills/ │ ├── code-review/ │ │ ├── SKILL.md │ │ ├── scripts/ │ │ └── references/ │ └── release/ │ └── SKILL.md │ └── module-a/ ├── AGENTS.md ├── .codex/ │ └── config.toml └── .agents/ └── skills/Codex 支持从项目根目录向当前工作目录逐层发现AGENTS.md .codex/config.toml .agents/skills这意味着它不是只有项目级 用户级两层。在 Monorepo 中还可能出现仓库根层 业务域层 模块层 当前目录层Codex 默认通过向上寻找.git来识别项目根也可以通过project_root_markers修改根目录标识。3. 管理员级目录在受管机器或企业环境中还可能存在/etc/codex/ ├── config.toml ├── requirements.toml ├── skills/ └── 受管理的 Hook、规则或策略文件其中/etc/codex/config.toml → 系统级默认配置 /etc/codex/skills → 管理员级 Skill requirements.toml → 管理员强制约束系统级config.toml的优先级低于用户配置和项目配置但requirements.toml并不是普通的低优先级默认值而是用户不能突破的安全约束。三、~/.codexCodex 本地 Harness 的核心目录Codex 的主目录默认为~/.codex也可以通过CODEX_HOME修改。这个目录最重要的公开配置包括config.toml AGENTS.md AGENTS.override.md profile.config.toml需要区分公开配置接口 和 内部运行状态1.config.toml用户级主配置位于~/.codex/config.toml项目级配置位于project/.codex/config.toml官方文档明确规定CLI 和 IDE Extension 共享这些配置层。配置可以控制默认模型 Model Provider Reasoning 配置 Approval Policy Sandbox Permissions MCP Server Hooks Subagent Role Profiles Feature Flags 通知和遥测一个简化示例是model gpt-5.6 approval_policy on-request sandbox_mode workspace-write [mcp_servers.github] url https://example.com/mcp [agents.reviewer] description Review code for correctness and security. config_file ./agents/reviewer.toml这说明config.toml不只是偏好设置。它实际上接近 Codex 的Runtime Assembly Configuration也就是Codex 使用什么模型 Codex 能调用什么工具 工具何时需要审批 命令运行在哪个 Sandbox 有哪些 MCP Server 有哪些 Agent Role 有哪些 Hook2. 配置优先级Codex 当前的主要配置优先级是CLI 参数与 --config ↓ 项目 .codex/config.toml ↓ 选中的 Profile ↓ 用户 ~/.codex/config.toml ↓ 系统 /etc/codex/config.toml ↓ 内置默认值项目中的.codex/config.toml可以从项目根一直存在到当前目录更靠近当前工作目录的配置优先。但项目配置只有在项目被信任后才加载。项目被标记为不可信时Codex 会跳过项目.codex/层包括项目级配置、Hook 和 Rule。因此项目配置优先级高并不等于Clone 一个仓库后自动信任其配置Codex 仍然把项目配置置于 Trust Boundary 之后。3. Profile 文件Codex 支持独立 Profile~/.codex/profile-name.config.toml通过codex--profileprofile-name选择。Profile 适合表达日常开发 只读审查 高权限本地任务 低成本模型 高推理强度 特定 MCP 组合例如~/.codex/default.config.toml ~/.codex/review.config.toml ~/.codex/production.config.tomlProfile 不是项目配置而是用户主动选择的一组运行时差异配置。4. 哪些内容不应由项目配置覆盖虽然项目.codex/config.toml优先级较高但它不能覆盖所有用户和机器级设置。官方明确列出一组只能放在用户级或机器级的配置例如模型 Provider 定义 认证与 Host 元数据 通知设置 Profile 选择 Telemetry Routing 部分 OpenAI Base URL这些字段即使写入项目级.codex/config.toml也会被忽略。这背后的逻辑是项目可以决定如何工作 但不能决定用户向哪个服务认证 不能修改机器级遥测目的地 不能接管用户 Provider 配置四、AGENTS.md持续生效的项目指导层AGENTS.md与config.toml经常被放在一起讨论但它们解决的是完全不同的问题。config.toml → 配置 Harness 如何运行 AGENTS.md → 告诉 Agent 应该如何完成工作例如config.tomlmodel gpt-5.6 sandbox_mode workspace-write approval_policy on-requestAGENTS.md# Project conventions - Java code must target Java 21. - Run Maven tests after modifying backend code. - Do not introduce new dependencies without approval. - Controllers must not access repositories directly.前者是运行参数后者是任务指导。1. 全局指导用户可以创建~/.codex/AGENTS.md为所有项目提供默认工作约定。还可以创建~/.codex/AGENTS.override.md如果 Override 文件存在且非空Codex 会优先使用它而不是同级AGENTS.md。适合写入全局文件的内容包括代码风格偏好 默认测试习惯 常用包管理器 沟通方式 提交前检查规则 个人长期工作约定2. 项目和目录级指导Codex 启动时会从项目根向当前工作目录逐层寻找AGENTS.override.md AGENTS.md 配置的 fallback 文件名每个目录最多选择一个文件。最终按照项目根 ↓ 子目录 ↓ 当前目录的顺序拼接。越靠近当前目录的内容越晚进入组合 Prompt因此可以细化或覆盖上层指导。例如repo/ ├── AGENTS.md ├── backend/ │ ├── AGENTS.md │ └── payment/ │ └── AGENTS.override.md在payment/中运行 Codex 时指导链可能是repo/AGENTS.md ↓ backend/AGENTS.md ↓ payment/AGENTS.override.md3. AGENTS 指令链只在启动时构建官方文档说明Codex 会在启动时构建一次AGENTS.mdInstruction Chain在 TUI 中通常意味着每次启动 Session 时重新发现。因此修改AGENTS.md后当前已经启动的 Session不一定立即重新构建全部指导链。更稳妥的方式通常是重新启动 Session 或使用客户端提供的刷新机制后面的 AGENTS.md 专篇再进一步分析其热更新和运行时行为。4. 大小限制Codex 会跳过空文件并在累计内容达到project_doc_max_bytes后停止继续加入指导。当前默认上限是32 KiB这说明AGENTS.md不适合堆放完整 API 文档 大量业务知识 几十页开发规范 所有历史决策更合理的分工是AGENTS.md → 简短、稳定、持续生效的规则 Skill → 某类任务的完整执行流程 References → 需要时读取的详细资料 MCP → 动态查询外部知识和系统五、.agents/skills可复用工作流层Codex Skill 的公开目录结构不是.codex/skills而是.agents/skills这说明 Skill 被设计成一种更通用的 Agent 能力格式而不完全绑定于 Codex 私有目录。OpenAI 官方说明Codex Skills 基于 Open Agent Skills Standard。一个 Skill 是包含SKILL.md的目录还可以携带脚本、参考资料和资源。1. 用户级 Skill~/.agents/skills/ ├── gh-fix-ci/ │ ├── SKILL.md │ └── scripts/ ├── architecture-review/ │ ├── SKILL.md │ └── references/ └── release/ └── SKILL.md这些 Skill 对用户处理的所有项目都可见。2. 项目级 Skillproject/ └── .agents/ └── skills/ ├── database-migration/ │ ├── SKILL.md │ ├── scripts/ │ └── references/ └── deployment/ └── SKILL.md项目 Skill 适合提交到 Git作为团队共享工作流。3. 目录级 Skill在 Monorepo 中Codex 会从当前目录向仓库根扫描每一级.agents/skills例如repo/ ├── .agents/skills/ │ └── root-skill/ │ ├── services/ │ ├── .agents/skills/ │ │ └── service-skill/ │ │ │ └── payment/ │ └── .agents/skills/ │ └── payment-skill/在services/payment中启动 Codex 时这三层 Skill 都可能被发现。如果两个 Skill 使用相同的nameCodex 不会把它们合并两者都可能出现在 Skill Selector 中。这与AGENTS.md的覆盖逻辑不同AGENTS.md → 从根到当前目录拼接 Skill → 多个 Skill 作为独立能力同时发现4. 管理员与系统 SkillCodex 还会读取/etc/codex/skills作为管理员级 Skill。此外Codex 自身会提供 System Skills例如skill-creator plan所以 Codex Skill 来源至少包括Repository User Admin System Plugin5. Skill 的基本目录my-skill/ ├── SKILL.md ├── scripts/ ├── references/ ├── assets/ └── agents/ └── openai.yaml最小结构是my-skill/ └── SKILL.mdSKILL.md必须包含---name:my-skilldescription:Describe when and why Codex should use this workflow.---可选目录分别承担scripts/ → 确定性执行脚本 references/ → 详细知识和规范 assets/ → 图片、模板或其他资源 agents/openai.yaml → OpenAI 产品中的 UI、调用策略和工具依赖元数据OpenAI 官方文档说明Codex 在初始阶段只加载 Skill 的名称、描述和路径真正决定使用 Skill 后再读取完整SKILL.md。六、Custom Agent 与 Subagent 配置Claude Code 通常将 Plugin Agent 定义为独立 Markdown 文件。Codex 当前公开的 Custom Agent 配置更偏向config.toml 独立 Agent Config Layer核心入口是[agents]以及[agents.name]官方配置参考提供了以下字段agents.name.description agents.name.config_file agents.default_subagent_model agents.default_subagent_reasoning_effort agents.enabled1. 主配置中声明 Agent Role例如[agents.reviewer] description Review code for correctness, security, and maintainability. config_file ./agents/reviewer.toml [agents.explorer] description Explore large codebases and identify relevant files. config_file ./agents/explorer.toml其中description → 主 Agent 选择 Subagent 时看到的角色说明 config_file → 该 Agent 的独立 TOML 配置层2. 独立 Agent 配置.codex/ ├── config.toml └── agents/ ├── reviewer.toml └── explorer.toml例如# .codex/agents/reviewer.toml model gpt-5.6 model_reasoning_effort high sandbox_mode read-only developer_instructions Focus on correctness, security, concurrency, and maintainability. Do not modify files. 这类独立配置允许不同 Agent 使用不同模型 不同推理强度 不同 Sandbox 不同开发指令 不同工具或 MCP 配置3. Subagent 不是长期独立 PluginSubagent 解决的是当前任务内部 将独立子问题委托给专门执行者例如Main Agent ├── explorer ├── reviewer └── test-runner当前本地 Codex 客户端默认支持 Subagent 工作流。用户可以明确要求委托也可以由AGENTS.md或 Skill 指令要求 Codex 使用 Subagent主线程最终收集各 Subagent 的结果。因此需要区分Custom Agent → 可配置的专业执行角色 Subagent Invocation → 某次任务中创建的实际子线程 Plugin → 能力分发和安装单元七、MCP 与 Hook 为什么都写入配置层Codex 的 MCP 和 Hook 没有像 Claude Code Plugin 那样统一要求放在 Plugin 根目录。在本地 Codex 中它们主要属于config.toml 或 .codex/ 项目配置层1. MCP 配置Codex 将 MCP Server 配置保存在~/.codex/config.toml或者可信项目的.codex/config.tomlChatGPT Desktop、Codex CLI 和 IDE Extension 可以共享这套 MCP 配置。例如[mcp_servers.github] url https://example.com/mcp [mcp_servers.local-db] command python args [./tools/db_mcp.py]所以 MCP 属于Harness External Tool Configuration而不是 Skill 内容本身。Skill 可以声明它依赖某个 MCP但 Skill 不等于 MCP Server。2. Hook 配置Codex Hook 可以使用.codex/hooks.json也可以直接写入config.toml[[hooks.PreToolUse]] matcher ^Bash$ [[hooks.PreToolUse.hooks]] type command command ./.codex/hooks/check_bash.py timeout 30如果同一配置层同时包含hooks.json和内联[hooks]Codex 会同时加载并发出警告官方建议每层选择一种表示方式。这意味着 Hook 在 Codex 中属于Configuration Layer Capability并会跟随用户级、项目级或管理员级配置层参与加载。3. 不可信项目不会加载项目 MCP 和 Hook项目.codex/层只有在用户信任项目后才会生效。因此一个刚 Clone 的仓库不能自动通过.codex/config.toml .codex/hooks.json静默改变 Codex 的工具和生命周期行为。项目被设为不可信时Codex会跳过项目级配置、Hook 和 Rule但仍加载用户与系统级配置。八、requirements.toml企业不可覆盖的安全约束requirements.toml容易被误解成另一份 config.toml实际上它们职责完全不同。config.toml → 用户或项目希望怎样运行 Codex requirements.toml → 管理员允许 Codex怎样运行官方将requirements.toml定义为管理员强制配置专门约束用户无法覆盖的安全敏感设置。1. 普通配置用户可以在config.toml中写approval_policy never sandbox_mode danger-full-access表达自己的运行偏好。2. 管理员要求管理员可以通过requirements.toml限制禁止 approval_policy never 禁止 danger-full-access 限制可用 Permission Profile 强制默认权限 限制网络访问 禁用 Plugin 禁用远程 Plugin Catalog 禁用多 Agent 只允许 Managed Hook例如官方参考中包含features.plugins features.remote_plugin features.multi_agent allow_managed_hooks_only allowed_approval_policies default_permissions等管理项。最终关系是User config.toml Project config.toml Profile CLI 参数 ↓ 计算期望配置 ↓ requirements.toml ↓ 校验并限制最终有效配置因此requirements.toml不是普通优先级竞争者而是Policy Constraint Layer九、Plugin 在 Codex 目录体系中的位置在 Claude Code 中Plugin 很明显是一个本地目录包plugin.json skills/ agents/ commands/ hooks/ .mcp.jsonCodex 当前的 Plugin 概念更偏向跨产品分发单元。OpenAI 官方文档将两者区分为Skill → 可复用工作流的编写格式 Plugin → 向 ChatGPT 和 Codex 分发 Skill 与 Connector 的单元Plugin 可以包含一个或多个 Skills 注册的 MCP Server Connection 打包的 MCP 配置 展示资源它们通过 ChatGPT 与 Codex 共用的通用 Plugin Directory 分发。所以在第一篇中Plugin 暂时不适合被简单画成~/.codex/plugins/因为当前公开文档强调的是Plugin Builder Plugin Directory 安装、启用和共享 跨 ChatGPT 与 Codex 使用而不是公开承诺某一个稳定的本地 Plugin Cache 目录作为开发者接口。更准确的静态模型是Local Skill → .agents/skills 中直接发现 Plugin → 通过 Plugin Directory 安装和分发 Plugin Runtime → 向支持的 ChatGPT / Codex Surface 暴露 Skill 与 ConnectorPlugin 的 Manifest、安装快照、缓存和本地落盘位置应该放在后面的 Plugin 专篇中单独验证不能直接照搬 Claude Code 的~/.claude/plugins/cache结构。十、公开配置接口与内部状态的边界研究 Codex 目录时必须避免把~/.codex下看到的所有文件都当成稳定 API。可以分成三类。1. 官方公开的配置接口这些可以作为长期工程接口使用~/.codex/config.toml ~/.codex/AGENTS.md ~/.codex/AGENTS.override.md ~/.codex/profile.config.toml project/AGENTS.md project/AGENTS.override.md project/.codex/config.toml project/.codex/hooks.json project/.agents/skills/ ~/.agents/skills/ /etc/codex/config.toml /etc/codex/skills requirements.toml2. 半公开运行时接口例如App Server JSON-RPC Thread Turn Item skills/list skills/changed skills/config/writeOpenAI App Server 文档中已经公开了 Skill 列表、刷新、变更通知和启用状态写入等协议。这些接口更适合客户端和工具集成而不是用户直接修改内部状态文件。3. 内部状态和缓存~/.codex中可能还存在Session 状态 Thread 数据 认证信息 日志 缓存 Plugin 安装快照 App 数据 临时文件这些内容可能随版本变化。除非官方文档明确将某个文件定义为配置接口否则不应手动修改 在脚本中强依赖内部 Schema 将其提交进 Git 把它当作稳定 Plugin API更稳妥的原则是配置 → 使用官方 TOML、Markdown 和公开目录 管理操作 → 使用 Codex CLI、App 或 App Server API 内部状态 → 由 Codex 自己维护十一、Codex 扩展体系的分层模型经过前面的目录梳理可以将 Codex 的扩展体系分成七层。第一层Project GuidanceAGENTS.md AGENTS.override.md作用持续提供编码规范、测试要求和项目约定第二层Runtime Configurationconfig.toml Profile Config作用选择模型 设置 Approval 设置 Sandbox 配置 MCP、Hook 和 Agent第三层Reusable Workflow.agents/skills/skill/SKILL.md作用封装特定任务的方法、资源和脚本第四层Specialized Execution[agents] Agent Config Layer Subagent Runtime作用将任务委托给独立专业执行者第五层External CapabilityMCP Server Hook Script作用接入外部工具 拦截生命周期事件 执行确定性程序第六层DistributionPlugin Universal Plugin Directory Workspace Sharing作用跨用户、团队和产品分发 Skill 与 Connector第七层Governancerequirements.toml System Config Admin Skill Managed Hook Workspace Policy作用限制用户不可突破的运行边界完整关系是┌────────────────────────────────────┐ │ Governance │ │ requirements.toml / Admin Policy │ └─────────────────┬──────────────────┘ ↓ ┌────────────────────────────────────┐ │ Runtime Configuration │ │ config.toml / Profile / Project │ └─────────────────┬──────────────────┘ ↓ ┌────────────────────────────────────┐ │ Project Guidance │ │ AGENTS.md │ └─────────────────┬──────────────────┘ ↓ ┌────────────────────────────────────┐ │ Capability Discovery │ │ Skills / Agents / MCP / Hooks │ └─────────────────┬──────────────────┘ ↓ ┌────────────────────────────────────┐ │ Codex Harness │ │ Agent Loop / Approval / Sandbox │ └─────────────────┬──────────────────┘ ↓ ┌────────────────────────────────────┐ │ Tool Model Runtime │ │ Responses API / Shell / MCP │ └────────────────────────────────────┘十二、Codex 与 Claude Code 在目录设计上的初步差异这一篇暂时不做完整横向对比但从目录结构已经能看到几个明显区别。1. Codex 将长期指令和运行配置明确分离AGENTS.md → 工作指导 config.toml → Harness 配置2. Skill 使用通用.agents目录.agents/skills而不是完全绑定于.codex/skills这与 Open Agent Skills Standard 和跨产品复用方向一致。3. Agent 更偏配置层而不是 Markdown 组件目录Codex 的 Custom Agent 主要通过[agents] config_file组织可以给每个角色叠加独立 TOML 配置。4. MCP、Hook、Agent 汇聚到config.tomlCodex 的config.toml更像统一的 Harness Configuration Hub。5. Plugin 不只是本地 CLI 插件包Plugin 被定义成 ChatGPT 和 Codex 共享的分发单元重点是将 Skill、Connector 和展示资源交付到不同产品界面。6. 企业约束有独立的requirements.toml它不是普通高优先级配置而是用于限定用户可选配置的硬约束。十三、目前仍需要继续确认的问题通过官方文档已经可以建立主要静态地图但仍有一些问题需要在后续文章中结合源码和真实安装实验确认。1. Plugin 的本地安装结构需要确认Plugin Manifest 格式 安装状态保存位置 本地 Runtime Snapshot Cache 目录 版本目录 禁用状态 卸载后的清理方式2. Skill 新旧目录兼容部分 App Server 示例中仍可看到类似~/.codex/skills/...的路径而当前公开 Skill Authoring 文档主要推荐~/.agents/skills这可能涉及历史兼容目录 System Skill 内部位置 安装器目标目录 App Server 示例路径 新旧版本迁移后续 Skill 专篇需要通过当前版本实测区分推荐公开目录 兼容读取目录 内部内置 Skill 目录3. Plugin 与本地 Skill 的优先级需要确认同名 Skill 是否同时出现 Plugin Skill 如何命名 Workspace Plugin 与本地 Skill 是否冲突 显式调用时如何定位 自动匹配时是否保留来源4. Hook 的目录发现范围需要进一步确认用户 hooks.json 项目 hooks.json Inline hooks Plugin Hook Managed Hook Session Hook如何统一合并和排序。5. Custom Agent 的完整独立配置范围包括是否继承主 Agent MCP 是否继承 Skill Catalog 是否继承 AGENTS.md 是否继承 Approval 能否缩小或扩大 Sandbox 如何加载独立 Developer Instructions总结Codex 当前已经形成了一套多层扩展体系。从目录角度看最核心的结构是用户级 $HOME/ ├── .codex/ │ ├── config.toml │ ├── AGENTS.md │ ├── AGENTS.override.md │ └── profile.config.toml │ └── .agents/ └── skills/项目级结构则是project/ ├── AGENTS.md ├── .codex/ │ ├── config.toml │ ├── hooks.json │ └── rules/ └── .agents/ └── skills/其中AGENTS.md → 决定 Codex 应该遵循哪些工作约定 config.toml → 决定 Codex Harness 如何运行 .agents/skills → 提供可复用任务流程 [agents] → 声明 Custom Agent 和 Subagent Role MCP → 接入外部 Tool 和系统 Hooks → 接入 Harness 生命周期 requirements.toml → 限制用户不能突破的企业安全边界 Plugin → 跨 ChatGPT 和 Codex 分发 Skill 与 Connector从架构上可以把 Codex 的扩展体系概括为Instructions Configuration Workflow Agent Tool Distribution Governance完整链路是AGENTS.md ↓ 提供任务指导 config.toml ↓ 装配 Harness Runtime Skills / Agents / MCP / Hooks ↓ 扩展执行能力 Plugin ↓ 分发可复用能力 requirements.toml ↓ 约束最终安全边界 Codex Harness ↓ 执行 Agent Loop这与只依赖一个 Prompt 文件的早期 Coding Agent 已经有明显区别。Codex 当前更接近一个以config.toml为运行配置中心、以AGENTS.md为持续指导层、以 Skill 为工作流单元、以 Plugin 为跨产品分发单元、以 MCP 和 Subagent 为能力扩展、以requirements.toml为企业约束层的完整 Agent Harness。下一篇可以继续进入Harness Marketplace 剖析系列 - 之 CodexAGENTS.md 的发现、继承与覆盖重点分析全局 AGENTS.md 如何加载 AGENTS.override.md 如何生效 项目根如何识别 根目录到当前目录如何合并 多个目录的规则如何覆盖 32 KiB 限制如何影响设计 AGENTS.md 与 Skill、Prompt、config.toml 如何分工 Subagent 是否继承 AGENTS.md CLI、IDE、App 和 Cloud 的行为是否一致这样就能从 Codex 的完整静态地图继续深入最基础的一层Codex 在真正执行任务之前是如何先理解一个项目的规则和工作方式的 Harness Marketplace 剖析系列 - 之 Codex：目录与配置结构
在前面的 Claude Code 系列中我们从目录结构入手逐步拆解了Marketplace Plugin Skill Command Agent Hook MCP LSP Harness Runtime进入 Codex 后第一反应很容易是Codex AGENTS.md config.toml MCP这种理解并不能说错但已经不够完整。当前 Codex 的扩展体系至少包含AGENTS.md Skills Plugins MCP Servers Custom Agents Subagents Hooks Rules Profiles Permissions Sandbox Managed Requirements其中AGENTS.md → 提供持续生效的项目指导 Skill → 封装可复用的任务流程 Plugin → 分发 Skill、Connector 和相关资源 MCP → 接入外部工具与系统 Custom Agent → 定义专门的子任务执行角色 config.toml → 控制模型、工具、权限和运行环境 requirements.toml → 提供管理员不可被用户绕过的约束所以Codex 已经不只是一个读取项目 ↓ 调用模型 ↓ 执行 Shell的轻量 Coding Agent。它正在形成一套更加完整的 Harness 扩展架构Project Guidance Reusable Workflow External Tool Specialized Agent Runtime Policy Plugin Distribution本文暂时不深入讨论这些组件如何运行而是先建立 Codex 扩展体系的静态地图。重点回答Codex CLI、IDE、Desktop 与 Cloud 是什么关系 ~/.codex 中保存什么 项目中的 .codex 目录负责什么 AGENTS.md 与 config.toml 有什么区别 Skill 为什么放在 .agents/skills而不是 .codex/skills Custom Agent 如何配置 MCP 和 Hook 写在哪里 requirements.toml 与 config.toml 有什么不同 Plugin 在整个体系中处于什么位置 哪些目录属于公开接口哪些属于内部状态一、先理解 Codex 不是单一客户端分析 Codex 目录前首先要明确Codex 不是一个单独的命令行程序名称而是一组共享 Agent Harness 能力的产品形态。当前常见的使用入口包括Codex CLI Codex IDE Extension ChatGPT Desktop 中的 Codex Codex Web / Cloud App ServerOpenAI 对 Codex Harness 的定义是负责协调用户、模型和工具之间交互的 Agent LoopCodex CLI 会通过 Responses API 完成模型推理由 Harness 负责组织工具调用、审批、沙箱执行、上下文管理和后续循环。OpenAI 还通过 App Server 将 Codex Core 暴露为长生命周期服务供终端、IDE、本地 App 和其他客户端使用。可以把整体关系理解为┌──────────────────┐ │ Codex Web │ │ Cloud Runtime │ └──────────────────┘ ┌─────────────┐ │ Codex CLI │ └──────┬──────┘ │ ┌──────▼──────┐ │ IDE Plugin │ └──────┬──────┘ │ ┌──────▼────────────┐ │ ChatGPT Desktop │ └──────┬────────────┘ │ ▼ ┌───────────────────────────┐ │ Codex Harness / App Server│ │ │ │ Agent Loop │ │ Thread / Turn │ │ Tool Runtime │ │ Approval │ │ Sandbox │ │ Skill / Agent / MCP │ └──────────────┬────────────┘ ▼ Responses API不同客户端的界面不同但本地 Codex CLI、IDE Extension 和 ChatGPT Desktop 会共享一部分配置。例如OpenAI 官方文档明确说明Codex CLI IDE Extension ChatGPT Desktop可以共享config.toml中的 MCP 配置CLI 与 IDE Extension 也共享同一套配置层。所以分析 Codex 目录时不能只问CLI 把配置放在哪里而应问哪些配置属于 Codex 本地 Harness能够被多个客户端共同读取二、Codex 的整体目录地图先给出一个简化后的静态结构。1. 用户级目录$HOME/ ├── .codex/ │ ├── config.toml │ ├── AGENTS.md │ ├── AGENTS.override.md │ ├── profile.config.toml │ └── 其他运行状态与客户端数据 │ └── .agents/ └── skills/ ├── skill-a/ │ └── SKILL.md └── skill-b/ ├── SKILL.md ├── scripts/ ├── references/ └── assets/其中需要注意Codex 主配置目录 → ~/.codex/ 用户级 Skill 目录 → ~/.agents/skills/Skill 并不是统一放进~/.codex/skills/。当前官方 Skill 发现规范中用户级 Skill 的公开位置是$HOME/.agents/skills而不是$HOME/.codex/skillsCodex 还会读取管理员级/etc/codex/skills和内置 System Skills。2. 项目级目录project/ ├── .git/ │ ├── AGENTS.md │ ├── .codex/ │ ├── config.toml │ ├── hooks.json │ ├── hooks/ │ ├── rules/ │ └── 其他项目配置 │ ├── .agents/ │ └── skills/ │ ├── code-review/ │ │ ├── SKILL.md │ │ ├── scripts/ │ │ └── references/ │ └── release/ │ └── SKILL.md │ └── module-a/ ├── AGENTS.md ├── .codex/ │ └── config.toml └── .agents/ └── skills/Codex 支持从项目根目录向当前工作目录逐层发现AGENTS.md .codex/config.toml .agents/skills这意味着它不是只有项目级 用户级两层。在 Monorepo 中还可能出现仓库根层 业务域层 模块层 当前目录层Codex 默认通过向上寻找.git来识别项目根也可以通过project_root_markers修改根目录标识。3. 管理员级目录在受管机器或企业环境中还可能存在/etc/codex/ ├── config.toml ├── requirements.toml ├── skills/ └── 受管理的 Hook、规则或策略文件其中/etc/codex/config.toml → 系统级默认配置 /etc/codex/skills → 管理员级 Skill requirements.toml → 管理员强制约束系统级config.toml的优先级低于用户配置和项目配置但requirements.toml并不是普通的低优先级默认值而是用户不能突破的安全约束。三、~/.codexCodex 本地 Harness 的核心目录Codex 的主目录默认为~/.codex也可以通过CODEX_HOME修改。这个目录最重要的公开配置包括config.toml AGENTS.md AGENTS.override.md profile.config.toml需要区分公开配置接口 和 内部运行状态1.config.toml用户级主配置位于~/.codex/config.toml项目级配置位于project/.codex/config.toml官方文档明确规定CLI 和 IDE Extension 共享这些配置层。配置可以控制默认模型 Model Provider Reasoning 配置 Approval Policy Sandbox Permissions MCP Server Hooks Subagent Role Profiles Feature Flags 通知和遥测一个简化示例是model gpt-5.6 approval_policy on-request sandbox_mode workspace-write [mcp_servers.github] url https://example.com/mcp [agents.reviewer] description Review code for correctness and security. config_file ./agents/reviewer.toml这说明config.toml不只是偏好设置。它实际上接近 Codex 的Runtime Assembly Configuration也就是Codex 使用什么模型 Codex 能调用什么工具 工具何时需要审批 命令运行在哪个 Sandbox 有哪些 MCP Server 有哪些 Agent Role 有哪些 Hook2. 配置优先级Codex 当前的主要配置优先级是CLI 参数与 --config ↓ 项目 .codex/config.toml ↓ 选中的 Profile ↓ 用户 ~/.codex/config.toml ↓ 系统 /etc/codex/config.toml ↓ 内置默认值项目中的.codex/config.toml可以从项目根一直存在到当前目录更靠近当前工作目录的配置优先。但项目配置只有在项目被信任后才加载。项目被标记为不可信时Codex 会跳过项目.codex/层包括项目级配置、Hook 和 Rule。因此项目配置优先级高并不等于Clone 一个仓库后自动信任其配置Codex 仍然把项目配置置于 Trust Boundary 之后。3. Profile 文件Codex 支持独立 Profile~/.codex/profile-name.config.toml通过codex--profileprofile-name选择。Profile 适合表达日常开发 只读审查 高权限本地任务 低成本模型 高推理强度 特定 MCP 组合例如~/.codex/default.config.toml ~/.codex/review.config.toml ~/.codex/production.config.tomlProfile 不是项目配置而是用户主动选择的一组运行时差异配置。4. 哪些内容不应由项目配置覆盖虽然项目.codex/config.toml优先级较高但它不能覆盖所有用户和机器级设置。官方明确列出一组只能放在用户级或机器级的配置例如模型 Provider 定义 认证与 Host 元数据 通知设置 Profile 选择 Telemetry Routing 部分 OpenAI Base URL这些字段即使写入项目级.codex/config.toml也会被忽略。这背后的逻辑是项目可以决定如何工作 但不能决定用户向哪个服务认证 不能修改机器级遥测目的地 不能接管用户 Provider 配置四、AGENTS.md持续生效的项目指导层AGENTS.md与config.toml经常被放在一起讨论但它们解决的是完全不同的问题。config.toml → 配置 Harness 如何运行 AGENTS.md → 告诉 Agent 应该如何完成工作例如config.tomlmodel gpt-5.6 sandbox_mode workspace-write approval_policy on-requestAGENTS.md# Project conventions - Java code must target Java 21. - Run Maven tests after modifying backend code. - Do not introduce new dependencies without approval. - Controllers must not access repositories directly.前者是运行参数后者是任务指导。1. 全局指导用户可以创建~/.codex/AGENTS.md为所有项目提供默认工作约定。还可以创建~/.codex/AGENTS.override.md如果 Override 文件存在且非空Codex 会优先使用它而不是同级AGENTS.md。适合写入全局文件的内容包括代码风格偏好 默认测试习惯 常用包管理器 沟通方式 提交前检查规则 个人长期工作约定2. 项目和目录级指导Codex 启动时会从项目根向当前工作目录逐层寻找AGENTS.override.md AGENTS.md 配置的 fallback 文件名每个目录最多选择一个文件。最终按照项目根 ↓ 子目录 ↓ 当前目录的顺序拼接。越靠近当前目录的内容越晚进入组合 Prompt因此可以细化或覆盖上层指导。例如repo/ ├── AGENTS.md ├── backend/ │ ├── AGENTS.md │ └── payment/ │ └── AGENTS.override.md在payment/中运行 Codex 时指导链可能是repo/AGENTS.md ↓ backend/AGENTS.md ↓ payment/AGENTS.override.md3. AGENTS 指令链只在启动时构建官方文档说明Codex 会在启动时构建一次AGENTS.mdInstruction Chain在 TUI 中通常意味着每次启动 Session 时重新发现。因此修改AGENTS.md后当前已经启动的 Session不一定立即重新构建全部指导链。更稳妥的方式通常是重新启动 Session 或使用客户端提供的刷新机制后面的 AGENTS.md 专篇再进一步分析其热更新和运行时行为。4. 大小限制Codex 会跳过空文件并在累计内容达到project_doc_max_bytes后停止继续加入指导。当前默认上限是32 KiB这说明AGENTS.md不适合堆放完整 API 文档 大量业务知识 几十页开发规范 所有历史决策更合理的分工是AGENTS.md → 简短、稳定、持续生效的规则 Skill → 某类任务的完整执行流程 References → 需要时读取的详细资料 MCP → 动态查询外部知识和系统五、.agents/skills可复用工作流层Codex Skill 的公开目录结构不是.codex/skills而是.agents/skills这说明 Skill 被设计成一种更通用的 Agent 能力格式而不完全绑定于 Codex 私有目录。OpenAI 官方说明Codex Skills 基于 Open Agent Skills Standard。一个 Skill 是包含SKILL.md的目录还可以携带脚本、参考资料和资源。1. 用户级 Skill~/.agents/skills/ ├── gh-fix-ci/ │ ├── SKILL.md │ └── scripts/ ├── architecture-review/ │ ├── SKILL.md │ └── references/ └── release/ └── SKILL.md这些 Skill 对用户处理的所有项目都可见。2. 项目级 Skillproject/ └── .agents/ └── skills/ ├── database-migration/ │ ├── SKILL.md │ ├── scripts/ │ └── references/ └── deployment/ └── SKILL.md项目 Skill 适合提交到 Git作为团队共享工作流。3. 目录级 Skill在 Monorepo 中Codex 会从当前目录向仓库根扫描每一级.agents/skills例如repo/ ├── .agents/skills/ │ └── root-skill/ │ ├── services/ │ ├── .agents/skills/ │ │ └── service-skill/ │ │ │ └── payment/ │ └── .agents/skills/ │ └── payment-skill/在services/payment中启动 Codex 时这三层 Skill 都可能被发现。如果两个 Skill 使用相同的nameCodex 不会把它们合并两者都可能出现在 Skill Selector 中。这与AGENTS.md的覆盖逻辑不同AGENTS.md → 从根到当前目录拼接 Skill → 多个 Skill 作为独立能力同时发现4. 管理员与系统 SkillCodex 还会读取/etc/codex/skills作为管理员级 Skill。此外Codex 自身会提供 System Skills例如skill-creator plan所以 Codex Skill 来源至少包括Repository User Admin System Plugin5. Skill 的基本目录my-skill/ ├── SKILL.md ├── scripts/ ├── references/ ├── assets/ └── agents/ └── openai.yaml最小结构是my-skill/ └── SKILL.mdSKILL.md必须包含---name:my-skilldescription:Describe when and why Codex should use this workflow.---可选目录分别承担scripts/ → 确定性执行脚本 references/ → 详细知识和规范 assets/ → 图片、模板或其他资源 agents/openai.yaml → OpenAI 产品中的 UI、调用策略和工具依赖元数据OpenAI 官方文档说明Codex 在初始阶段只加载 Skill 的名称、描述和路径真正决定使用 Skill 后再读取完整SKILL.md。六、Custom Agent 与 Subagent 配置Claude Code 通常将 Plugin Agent 定义为独立 Markdown 文件。Codex 当前公开的 Custom Agent 配置更偏向config.toml 独立 Agent Config Layer核心入口是[agents]以及[agents.name]官方配置参考提供了以下字段agents.name.description agents.name.config_file agents.default_subagent_model agents.default_subagent_reasoning_effort agents.enabled1. 主配置中声明 Agent Role例如[agents.reviewer] description Review code for correctness, security, and maintainability. config_file ./agents/reviewer.toml [agents.explorer] description Explore large codebases and identify relevant files. config_file ./agents/explorer.toml其中description → 主 Agent 选择 Subagent 时看到的角色说明 config_file → 该 Agent 的独立 TOML 配置层2. 独立 Agent 配置.codex/ ├── config.toml └── agents/ ├── reviewer.toml └── explorer.toml例如# .codex/agents/reviewer.toml model gpt-5.6 model_reasoning_effort high sandbox_mode read-only developer_instructions Focus on correctness, security, concurrency, and maintainability. Do not modify files. 这类独立配置允许不同 Agent 使用不同模型 不同推理强度 不同 Sandbox 不同开发指令 不同工具或 MCP 配置3. Subagent 不是长期独立 PluginSubagent 解决的是当前任务内部 将独立子问题委托给专门执行者例如Main Agent ├── explorer ├── reviewer └── test-runner当前本地 Codex 客户端默认支持 Subagent 工作流。用户可以明确要求委托也可以由AGENTS.md或 Skill 指令要求 Codex 使用 Subagent主线程最终收集各 Subagent 的结果。因此需要区分Custom Agent → 可配置的专业执行角色 Subagent Invocation → 某次任务中创建的实际子线程 Plugin → 能力分发和安装单元七、MCP 与 Hook 为什么都写入配置层Codex 的 MCP 和 Hook 没有像 Claude Code Plugin 那样统一要求放在 Plugin 根目录。在本地 Codex 中它们主要属于config.toml 或 .codex/ 项目配置层1. MCP 配置Codex 将 MCP Server 配置保存在~/.codex/config.toml或者可信项目的.codex/config.tomlChatGPT Desktop、Codex CLI 和 IDE Extension 可以共享这套 MCP 配置。例如[mcp_servers.github] url https://example.com/mcp [mcp_servers.local-db] command python args [./tools/db_mcp.py]所以 MCP 属于Harness External Tool Configuration而不是 Skill 内容本身。Skill 可以声明它依赖某个 MCP但 Skill 不等于 MCP Server。2. Hook 配置Codex Hook 可以使用.codex/hooks.json也可以直接写入config.toml[[hooks.PreToolUse]] matcher ^Bash$ [[hooks.PreToolUse.hooks]] type command command ./.codex/hooks/check_bash.py timeout 30如果同一配置层同时包含hooks.json和内联[hooks]Codex 会同时加载并发出警告官方建议每层选择一种表示方式。这意味着 Hook 在 Codex 中属于Configuration Layer Capability并会跟随用户级、项目级或管理员级配置层参与加载。3. 不可信项目不会加载项目 MCP 和 Hook项目.codex/层只有在用户信任项目后才会生效。因此一个刚 Clone 的仓库不能自动通过.codex/config.toml .codex/hooks.json静默改变 Codex 的工具和生命周期行为。项目被设为不可信时Codex会跳过项目级配置、Hook 和 Rule但仍加载用户与系统级配置。八、requirements.toml企业不可覆盖的安全约束requirements.toml容易被误解成另一份 config.toml实际上它们职责完全不同。config.toml → 用户或项目希望怎样运行 Codex requirements.toml → 管理员允许 Codex怎样运行官方将requirements.toml定义为管理员强制配置专门约束用户无法覆盖的安全敏感设置。1. 普通配置用户可以在config.toml中写approval_policy never sandbox_mode danger-full-access表达自己的运行偏好。2. 管理员要求管理员可以通过requirements.toml限制禁止 approval_policy never 禁止 danger-full-access 限制可用 Permission Profile 强制默认权限 限制网络访问 禁用 Plugin 禁用远程 Plugin Catalog 禁用多 Agent 只允许 Managed Hook例如官方参考中包含features.plugins features.remote_plugin features.multi_agent allow_managed_hooks_only allowed_approval_policies default_permissions等管理项。最终关系是User config.toml Project config.toml Profile CLI 参数 ↓ 计算期望配置 ↓ requirements.toml ↓ 校验并限制最终有效配置因此requirements.toml不是普通优先级竞争者而是Policy Constraint Layer九、Plugin 在 Codex 目录体系中的位置在 Claude Code 中Plugin 很明显是一个本地目录包plugin.json skills/ agents/ commands/ hooks/ .mcp.jsonCodex 当前的 Plugin 概念更偏向跨产品分发单元。OpenAI 官方文档将两者区分为Skill → 可复用工作流的编写格式 Plugin → 向 ChatGPT 和 Codex 分发 Skill 与 Connector 的单元Plugin 可以包含一个或多个 Skills 注册的 MCP Server Connection 打包的 MCP 配置 展示资源它们通过 ChatGPT 与 Codex 共用的通用 Plugin Directory 分发。所以在第一篇中Plugin 暂时不适合被简单画成~/.codex/plugins/因为当前公开文档强调的是Plugin Builder Plugin Directory 安装、启用和共享 跨 ChatGPT 与 Codex 使用而不是公开承诺某一个稳定的本地 Plugin Cache 目录作为开发者接口。更准确的静态模型是Local Skill → .agents/skills 中直接发现 Plugin → 通过 Plugin Directory 安装和分发 Plugin Runtime → 向支持的 ChatGPT / Codex Surface 暴露 Skill 与 ConnectorPlugin 的 Manifest、安装快照、缓存和本地落盘位置应该放在后面的 Plugin 专篇中单独验证不能直接照搬 Claude Code 的~/.claude/plugins/cache结构。十、公开配置接口与内部状态的边界研究 Codex 目录时必须避免把~/.codex下看到的所有文件都当成稳定 API。可以分成三类。1. 官方公开的配置接口这些可以作为长期工程接口使用~/.codex/config.toml ~/.codex/AGENTS.md ~/.codex/AGENTS.override.md ~/.codex/profile.config.toml project/AGENTS.md project/AGENTS.override.md project/.codex/config.toml project/.codex/hooks.json project/.agents/skills/ ~/.agents/skills/ /etc/codex/config.toml /etc/codex/skills requirements.toml2. 半公开运行时接口例如App Server JSON-RPC Thread Turn Item skills/list skills/changed skills/config/writeOpenAI App Server 文档中已经公开了 Skill 列表、刷新、变更通知和启用状态写入等协议。这些接口更适合客户端和工具集成而不是用户直接修改内部状态文件。3. 内部状态和缓存~/.codex中可能还存在Session 状态 Thread 数据 认证信息 日志 缓存 Plugin 安装快照 App 数据 临时文件这些内容可能随版本变化。除非官方文档明确将某个文件定义为配置接口否则不应手动修改 在脚本中强依赖内部 Schema 将其提交进 Git 把它当作稳定 Plugin API更稳妥的原则是配置 → 使用官方 TOML、Markdown 和公开目录 管理操作 → 使用 Codex CLI、App 或 App Server API 内部状态 → 由 Codex 自己维护十一、Codex 扩展体系的分层模型经过前面的目录梳理可以将 Codex 的扩展体系分成七层。第一层Project GuidanceAGENTS.md AGENTS.override.md作用持续提供编码规范、测试要求和项目约定第二层Runtime Configurationconfig.toml Profile Config作用选择模型 设置 Approval 设置 Sandbox 配置 MCP、Hook 和 Agent第三层Reusable Workflow.agents/skills/skill/SKILL.md作用封装特定任务的方法、资源和脚本第四层Specialized Execution[agents] Agent Config Layer Subagent Runtime作用将任务委托给独立专业执行者第五层External CapabilityMCP Server Hook Script作用接入外部工具 拦截生命周期事件 执行确定性程序第六层DistributionPlugin Universal Plugin Directory Workspace Sharing作用跨用户、团队和产品分发 Skill 与 Connector第七层Governancerequirements.toml System Config Admin Skill Managed Hook Workspace Policy作用限制用户不可突破的运行边界完整关系是┌────────────────────────────────────┐ │ Governance │ │ requirements.toml / Admin Policy │ └─────────────────┬──────────────────┘ ↓ ┌────────────────────────────────────┐ │ Runtime Configuration │ │ config.toml / Profile / Project │ └─────────────────┬──────────────────┘ ↓ ┌────────────────────────────────────┐ │ Project Guidance │ │ AGENTS.md │ └─────────────────┬──────────────────┘ ↓ ┌────────────────────────────────────┐ │ Capability Discovery │ │ Skills / Agents / MCP / Hooks │ └─────────────────┬──────────────────┘ ↓ ┌────────────────────────────────────┐ │ Codex Harness │ │ Agent Loop / Approval / Sandbox │ └─────────────────┬──────────────────┘ ↓ ┌────────────────────────────────────┐ │ Tool Model Runtime │ │ Responses API / Shell / MCP │ └────────────────────────────────────┘十二、Codex 与 Claude Code 在目录设计上的初步差异这一篇暂时不做完整横向对比但从目录结构已经能看到几个明显区别。1. Codex 将长期指令和运行配置明确分离AGENTS.md → 工作指导 config.toml → Harness 配置2. Skill 使用通用.agents目录.agents/skills而不是完全绑定于.codex/skills这与 Open Agent Skills Standard 和跨产品复用方向一致。3. Agent 更偏配置层而不是 Markdown 组件目录Codex 的 Custom Agent 主要通过[agents] config_file组织可以给每个角色叠加独立 TOML 配置。4. MCP、Hook、Agent 汇聚到config.tomlCodex 的config.toml更像统一的 Harness Configuration Hub。5. Plugin 不只是本地 CLI 插件包Plugin 被定义成 ChatGPT 和 Codex 共享的分发单元重点是将 Skill、Connector 和展示资源交付到不同产品界面。6. 企业约束有独立的requirements.toml它不是普通高优先级配置而是用于限定用户可选配置的硬约束。十三、目前仍需要继续确认的问题通过官方文档已经可以建立主要静态地图但仍有一些问题需要在后续文章中结合源码和真实安装实验确认。1. Plugin 的本地安装结构需要确认Plugin Manifest 格式 安装状态保存位置 本地 Runtime Snapshot Cache 目录 版本目录 禁用状态 卸载后的清理方式2. Skill 新旧目录兼容部分 App Server 示例中仍可看到类似~/.codex/skills/...的路径而当前公开 Skill Authoring 文档主要推荐~/.agents/skills这可能涉及历史兼容目录 System Skill 内部位置 安装器目标目录 App Server 示例路径 新旧版本迁移后续 Skill 专篇需要通过当前版本实测区分推荐公开目录 兼容读取目录 内部内置 Skill 目录3. Plugin 与本地 Skill 的优先级需要确认同名 Skill 是否同时出现 Plugin Skill 如何命名 Workspace Plugin 与本地 Skill 是否冲突 显式调用时如何定位 自动匹配时是否保留来源4. Hook 的目录发现范围需要进一步确认用户 hooks.json 项目 hooks.json Inline hooks Plugin Hook Managed Hook Session Hook如何统一合并和排序。5. Custom Agent 的完整独立配置范围包括是否继承主 Agent MCP 是否继承 Skill Catalog 是否继承 AGENTS.md 是否继承 Approval 能否缩小或扩大 Sandbox 如何加载独立 Developer Instructions总结Codex 当前已经形成了一套多层扩展体系。从目录角度看最核心的结构是用户级 $HOME/ ├── .codex/ │ ├── config.toml │ ├── AGENTS.md │ ├── AGENTS.override.md │ └── profile.config.toml │ └── .agents/ └── skills/项目级结构则是project/ ├── AGENTS.md ├── .codex/ │ ├── config.toml │ ├── hooks.json │ └── rules/ └── .agents/ └── skills/其中AGENTS.md → 决定 Codex 应该遵循哪些工作约定 config.toml → 决定 Codex Harness 如何运行 .agents/skills → 提供可复用任务流程 [agents] → 声明 Custom Agent 和 Subagent Role MCP → 接入外部 Tool 和系统 Hooks → 接入 Harness 生命周期 requirements.toml → 限制用户不能突破的企业安全边界 Plugin → 跨 ChatGPT 和 Codex 分发 Skill 与 Connector从架构上可以把 Codex 的扩展体系概括为Instructions Configuration Workflow Agent Tool Distribution Governance完整链路是AGENTS.md ↓ 提供任务指导 config.toml ↓ 装配 Harness Runtime Skills / Agents / MCP / Hooks ↓ 扩展执行能力 Plugin ↓ 分发可复用能力 requirements.toml ↓ 约束最终安全边界 Codex Harness ↓ 执行 Agent Loop这与只依赖一个 Prompt 文件的早期 Coding Agent 已经有明显区别。Codex 当前更接近一个以config.toml为运行配置中心、以AGENTS.md为持续指导层、以 Skill 为工作流单元、以 Plugin 为跨产品分发单元、以 MCP 和 Subagent 为能力扩展、以requirements.toml为企业约束层的完整 Agent Harness。下一篇可以继续进入Harness Marketplace 剖析系列 - 之 CodexAGENTS.md 的发现、继承与覆盖重点分析全局 AGENTS.md 如何加载 AGENTS.override.md 如何生效 项目根如何识别 根目录到当前目录如何合并 多个目录的规则如何覆盖 32 KiB 限制如何影响设计 AGENTS.md 与 Skill、Prompt、config.toml 如何分工 Subagent 是否继承 AGENTS.md CLI、IDE、App 和 Cloud 的行为是否一致这样就能从 Codex 的完整静态地图继续深入最基础的一层Codex 在真正执行任务之前是如何先理解一个项目的规则和工作方式的