Skip to content

Codex 术语表

这是一份解释型文档——回答「这个概念是什么、为什么这样设计、什么时候该用」。和 Codex 速查表 互补:速查表回答「命令怎么写」,本文回答「为什么要这么写」。

概念定义的唯一真相来源:本项目所有 Codex 文档中出现的概念,以本页的定义为准。其它页面只做「怎么用」的示范,不重复定义。

文档站点变更提示:Codex 官方文档已从 developers.openai.com/codex/* 迁移至 learn.chatgpt.com/docs,旧地址会 308 永久重定向到新地址。本页所有官方链接均使用新地址。

概念关系图

                        ┌─────────────────────────┐
                        │   requirements.toml     │  管理员托管策略(最高约束)
                        │   企业/团队统一下发       │
                        └────────────┬────────────┘
                                     │ 收窄可选范围

   ┌──────────────────────────────────────────────────────────────┐
   │                    config.toml  配置层                        │
   │   ~/.codex/config.toml(用户级) > .codex/config.toml(项目级) │
   │   Profile 配置档:$CODEX_HOME/<name>.config.toml               │
   └───────┬──────────────────────────┬───────────────────────────┘
           │                          │
           ▼                          ▼
   ┌───────────────┐          ┌──────────────────┐
   │  权限与沙箱     │          │  上下文与指令       │
   │  ─────────    │          │  ──────────      │
   │  approval_    │          │  AGENTS.md       │  ← 项目说明书
   │  policy       │          │  Rules           │  ← 结构化约束
   │  sandbox_mode │          │  Memories        │  ← 跨会话记忆
   │  trust_level  │          │  Compaction      │  ← 上下文压缩
   └───────┬───────┘          └────────┬─────────┘
           │                           │
           └───────────┬───────────────┘

           ┌───────────────────────┐
           │   Codex Agent 运行时   │
           │   会话 / Session       │
           └───────────┬───────────┘
                       │ 通过以下机制扩展能力
       ┌───────────────┼───────────────┬──────────────┐
       ▼               ▼               ▼              ▼
   ┌────────┐     ┌─────────┐    ┌─────────┐   ┌───────────┐
   │  MCP   │     │ Skills  │    │  Hooks  │   │ Subagents │
   │ 外部工具│     │ 可复用   │    │ 生命周期 │   │  子代理    │
   │        │     │ 流程     │    │ 拦截    │   │           │
   └───┬────┘     └────┬────┘    └─────────┘   └───────────┘
       │               │
       └───────┬───────┘

        ┌─────────────┐
        │   Plugins   │  把 MCP / Skills / Hooks 打包分发
        └─────────────┘

   运行形态(同一套配置,四种入口):
   CLI (codex) │ IDE 扩展 │ 桌面 App │ Web / Cloud

核心逻辑:最外层是约束(管理员托管 → 配置文件 → 权限沙箱),中间是上下文(AGENTS.md / Rules / Memories 决定 Codex 知道什么),最内层是能力扩展(MCP / Skills / Hooks / Subagents 决定 Codex 能做什么)。Plugins 不是新能力,只是前三者的打包分发格式。

理解这张图的实用价值:当 Codex 行为不符合预期时,按「约束 → 上下文 → 能力」的顺序自上而下排查,比随机改配置高效得多。


AGENTS.md

是什么

放在仓库里的 Markdown 文件,用自然语言告诉 Codex 这个项目的约定:用什么包管理器、改完代码要跑什么命令、哪些目录不要碰。可以类比新人入职时那份「团队约定文档」——只不过读者是 Agent。

为什么需要

不写 AGENTS.md,你就得在每次对话里重复交代「这个项目用 pnpm 不用 npm」。写了之后,这些约定变成每次任务自动加载的前置上下文。

工作机制(指令链)

Codex 启动时构建一条指令链(每次运行构建一次;在 TUI 中通常是每启动一个会话构建一次),发现顺序为:

  1. 全局作用域:在 Codex home 目录(默认 ~/.codex,可用 CODEX_HOME 改)读取 AGENTS.override.md,不存在则读 AGENTS.md。这一层只取第一个非空文件
  2. 项目作用域:从项目根(通常是 Git 根)向下走到当前工作目录。每经过一个目录,依次检查 AGENTS.override.mdAGENTS.mdproject_doc_fallback_filenames 里列出的备用文件名。每个目录最多取一个文件
  3. 合并顺序:从根往下拼接,用空行连接。离当前目录越近的文件出现在越后面,因此会覆盖前面的指导

Codex 会跳过空文件,并在合并后体积达到 project_doc_max_bytes(默认 32 KiB)时停止追加。

关键细节

细节说明
覆盖而非替换AGENTS.override.md 存在时,同目录的 AGENTS.md 被忽略
只向下不向上从项目根走到 cwd,走过头的目录不看
自定义文件名project_doc_fallback_filenames = ["TEAM_GUIDE.md", ".agents.md"]
提高上限project_doc_max_bytes = 65536
代码评审规则在最靠近被约束代码的 AGENTS.md 里加 ## Code Review Rules 小节
临时全局覆盖~/.codex/AGENTS.override.md,用完删掉即可恢复

与 Rules 的区别

维度AGENTS.mdRules
形态自然语言 Markdown结构化规则配置
用途传达项目约定和背景声明式约束与检查
覆盖粒度按目录层级继承覆盖按规则条目匹配

官方文档Custom instructions with AGENTS.md


Rules

是什么

比 AGENTS.md 更结构化的约束机制,用来声明「什么情况下必须/禁止做什么」。项目级 Rules 属于 .codex/ 项目层,因此同样受项目信任(trust level)的门控。

为什么需要

AGENTS.md 是自然语言,模型可能「理解偏了」。Rules 提供更明确的约束表达,也便于团队统一下发和审计。你可以用 /debug-config 查看当前生效的 rules。

官方文档Rules


沙箱(Sandbox)

是什么

限制 Codex 能读写哪些文件、能否访问网络的隔离层。它是机制层——决定「技术上能不能做」,与审批策略(决定「做之前要不要问你」)是两个独立的维度。

三种模式

sandbox_mode含义典型场景
read-only只读,不能改文件代码审查、架构分析
workspace-write可写工作区日常开发(常用默认)
danger-full-access无沙箱限制明确知道风险时才用

workspace-write 下可进一步微调:

配置键作用
sandbox_workspace_write.writable_roots追加可写根目录
sandbox_workspace_write.network_access是否允许网络访问
sandbox_workspace_write.exclude_slash_tmp/tmp 排除出可写范围
sandbox_workspace_write.exclude_tmpdir_env_var$TMPDIR 排除出可写范围

为什么沙箱和审批要分开

因为「安全」有两条独立的防线:沙箱是硬边界(越不过去),审批是人工闸门(越过去之前先问你)。只有审批没有沙箱,一次误点「同意」就可能造成破坏;只有沙箱没有审批,Codex 会在边界内自由行动而你毫不知情。两者组合才能既高效又可控。

官方文档Sandboxing


审批策略(Approval policy)与权限

是什么

决定 Codex 执行动作前是否需要你确认的策略。注意配置层和界面层用了两套命名,这是初学者最容易混淆的地方。

配置层:approval_policy

取值含义
untrusted只自动执行被认为安全的操作,其余都要问
on-request由模型按需请求审批
never从不询问
{ granular = { ... } }细粒度控制,可分别设置 sandbox_approvalrulesmcp_elicitationsrequest_permissionsskill_approval

旧取值 on-failure 已废弃。命令行上可用 --ask-for-approval <policy> 临时指定。

界面层:TUI 权限模式

在 TUI 里用 /permissions 切换,显示为三个档位:Auto(默认)、Read-onlyFull Access

为什么有两套名字

配置层描述的是「审批请求如何产生」,界面层描述的是「组合出的实用档位」——Read-only 和 Full Access 实际上同时调整了沙箱和审批两个维度。写文档或排查问题时必须说清自己在讲哪一层,否则沟通必然错位。

官方文档Permissions


项目信任(Trust level)与配置层级

是什么

Codex 是否信任某个项目目录的开关,配置在 projects.<path>.trust_level,取值 "trusted""untrusted"

为什么需要

因为项目里的 .codex/ 目录是别人可以往仓库里提交的内容。如果 clone 一个陌生仓库就自动加载它的配置、hooks 和 rules,等于把执行权交给了仓库作者。信任门控就是这道防线:未信任的项目会跳过所有项目级 .codex/(配置、hooks、rules 都不加载)。

配置优先级

官方 Config basics 的解析顺序(高优先在前):

  1. CLI flag 与 -c / --config 覆盖
  2. 项目 .codex/config.toml(从仓库根走到当前目录,近的覆盖远的)——仅信任项目会加载
  3. --profile 选中的 profile 文件($CODEX_HOME/<name>.config.toml
  4. 用户配置:~/.codex/config.toml
  5. 系统配置(若存在):Unix 上的 /etc/codex/config.toml
  6. 内置默认值

被信任的项目配置覆盖用户配置里的同名键。这是官方顺序。项目配置做不到的是另一条规则:下面这组机器本地键在项目层会被 忽略

openai_base_urlchatgpt_base_urlapps_mcp_product_skumodel_providermodel_providersnotifyprofileprofilesexperimental_realtime_ws_base_urlotel

这个设计的用意很直接:仓库不能悄悄把你的模型请求改道到别的服务端

官方文档Config Reference


Profile(配置档)

是什么

一组命名的配置集合,用于在不同场景间切换(例如工作项目 vs 个人实验)。

工作机制

Profile 文件与 config.toml 同级存放,命名为 $CODEX_HOME/<profile-name>.config.toml,用 --profile <profile-name> 选中。

CODEX_HOME 的区别

维度ProfileCODEX_HOME
切换的是同一个 home 里的一份配置整个 Codex home 目录
隔离程度只隔离配置配置、会话、日志全部隔离
典型用途工作/个人两套模型与权限CI 里用独立的自动化身份

官方文档Config ReferenceEnvironment Variables


MCP(Model Context Protocol)

是什么

让 Codex 连接外部工具和数据源的开放协议。可以理解成 AI 世界的「USB 接口」——协议统一之后,任何实现了 MCP 的服务都能被 Codex 直接使用,不需要 Codex 为每个服务单独适配。

为什么重要

没有 MCP,Agent 只能读写本地文件和跑命令。有了 MCP,同一个 Agent 可以查数据库、调内部 API、访问设计稿——而且这些能力的提供方和 Codex 是解耦的。

配置形态(重要纠错点)

mcp_servers以 id 为键的表(table),不是数组表:

toml
[mcp_servers.filesystem]
command = "npx"
args = ["-y", "@modelcontextprotocol/server-filesystem", "."]

常用键:

说明
command / args / cwd / envSTDIO 方式启动本地进程
url / http_headers / bearer_token_env_var流式 HTTP 方式连接远端
enabled / required是否启用、是否必需
enabled_tools / disabled_tools工具级白/黑名单
default_tools_approval_modeauto / prompt / approve
startup_timeout_sec启动超时,默认 10
tool_timeout_sec单次调用超时,默认 60

双向角色

Codex 既可以作为 MCP 客户端消费别人的服务,也可以作为 MCP 服务端被别的 Agent 调用(见 codex mcp 与 MCP Server 文档)。

官方文档MCPMCP Server


Skills

是什么

把一段可复用的工作流程封装成「技能」,让 Codex 在合适的时机自动调用。你可以用 /skills 查看当前可用技能。

与 MCP 的区别

维度SkillsMCP
本质打包的流程/知识接入的工具/数据
谁执行Codex 自己按流程做外部服务执行后返回结果
典型内容「发布流程分七步」「查询生产数据库」

简单判断:需要接一个外部系统用 MCP;需要固化一套做法用 Skills。

官方文档Skills


Hooks

是什么

在 Codex 生命周期的特定节点自动触发的命令,用于做强制检查或自动化动作。可以内联写在 config.toml 里。

支持的事件

PreToolUsePermissionRequestPostToolUsePreCompactPostCompactSessionStartSubagentStartSubagentStopUserPromptSubmitStop

当前限制:只支持 command 类型的 hook(prompt / agent 类型会被解析但跳过执行)。Windows 上可用 commandWindows(TOML 中写作 command_windows)指定平台差异命令。

与 AGENTS.md 的区别

AGENTS.md 是建议——模型可能不照做;Hooks 是强制——脚本一定会跑。要求「每次改完代码必须格式化」这类硬约束,写 Hooks 而不是写 AGENTS.md。

官方文档Hooks


Plugins

是什么

把 MCP 服务、Skills、Hooks 打包成一个可分发单元的格式。用 /plugins 管理。

为什么需要

团队里每个人手动配一遍 MCP + Skills + Hooks 不现实,也容易配错。Plugins 让「一套 Codex 工作环境」变成可以一次安装的东西。

生态角色:Plugins 是分发层,不引入新能力。配置上它可以覆盖所打包的 MCP 服务的启用状态与工具审批模式(plugins.<plugin>.mcp_servers.<server>.*)。

官方文档Plugins


Subagents(子代理)

是什么

主 Agent 派生出的独立 Agent,用于并行处理或隔离上下文。用 /agent 管理,在 [agents] 配置段声明。

关键行为只有你明确要求时才会派生子代理——不会自动发生。

相关配置

默认值说明
agents.max_depth1嵌套深度上限
agents.max_threads6并发线程上限
agents.job_max_runtime_seconds1800单任务运行时长上限
agents.<name>.config_file子代理使用的配置文件
agents.<name>.description描述,影响何时被选用

启用 features.multi_agent 后可用的工具:spawn_agentsend_inputresume_agentwait_agentclose_agent

什么时候该用

需要上下文隔离时(比如让一个子代理专门做对抗性审查,避免它被主线的思路带偏),或需要并行处理互不依赖的任务时。任务之间有强依赖的,串行做反而更快。

官方文档Subagents


Memories(记忆)

是什么

跨会话保留的信息,让 Codex 记住你的偏好和项目背景,不必每次重新交代。用 /memories 管理。

与 AGENTS.md 的区别

维度MemoriesAGENTS.md
来源Codex 自动提炼 + 你确认你手写
存放Codex 侧仓库里,可提交、可评审
适合个人习惯、渐进积累的经验团队约定,需要所有人一致

判断标准很简单:这条信息该让团队所有人共享吗?该,就写进 AGENTS.md 提交上去;只是你个人习惯,交给 Memories。

相关配置features.memories(默认关闭);细项在 memories.*,如 use_memoriesgenerate_memoriesmax_unused_daysmax_rollout_age_days 等。

官方文档Memories


会话(Session)与上下文压缩(Compaction)

是什么

一次连续对话及其累积的上下文。会话记录存放在 ~/.codex/sessions/

会话操作

操作命令
恢复会话(选择器)codex resume
恢复最近一次codex resume --last
恢复指定会话codex resume <SESSION_ID>
列出全部codex resume --all
从当前状态分叉/fork
归档 / 取消归档/archivecodex unarchive <SESSION>

会话 ID 可以从会话选择器、/status~/.codex/sessions/ 目录取得。

上下文压缩(Compaction)

上下文接近上限时,把早期对话压缩成摘要以腾出空间。手动触发用 /compact;自动触发阈值由 model_auto_compact_token_limit 控制。PreCompact / PostCompact 两个 hook 事件可以在压缩前后插入动作。

为什么要主动管理

压缩是有损的——摘要会丢细节。与其等它自动压缩,不如在任务切换时主动 /clear 或开新会话。一个会话只做一件事,比一个会话做十件事然后被迫压缩要可靠得多。

官方文档Slash commands


Web 搜索模式

是什么

Codex 获取外部网页信息的能力,有四档(重要纠错点:这是枚举字符串,不是布尔开关)。

web_search含义
disabled关闭
cached默认值,查询 OpenAI 维护的索引,不实时抓取
indexed仅当搜索索引放行时才允许外部网页访问
live实时抓取;在 --yolo / 全权限模式下默认变为此值

命令行上用--search(不带参数)开启实时搜索。搜索结果会以 web_search 条目出现在对话记录和 codex exec --json 输出里。

旧的开关式配置 features.web_searchfeatures.web_search_cachedfeatures.web_search_request 已废弃。

为什么默认是 cached 而不是 live

缓存索引更快、更省,而且对绝大多数「这个 API 怎么用」的问题足够。只有在查非常新的信息(比如刚发布的版本)时才需要 live

官方文档Config Reference


非交互模式(codex exec

是什么

不进 TUI、直接跑完一个任务就退出的运行方式,用于脚本和 CI。

bash
codex exec "run the test suite and fix any failures"
codex exec --json "summarize recent changes"
codex exec resume --last "now add tests for the new function"

为什么需要独立的子命令

因为 CI 里没有终端交互,也不该有人工审批等待。codex exec 明确表达「这是一次性的、无人值守的运行」,日志默认级别是 RUST_LOG=error,输出便于机器解析。

官方文档Non-interactive Mode


运行形态:CLI / IDE / App / Cloud

是什么

同一个 Codex Agent 的四种入口。它们共享同一套配置模型(config.toml、AGENTS.md、MCP、Skills),差异在交互方式和运行位置。

形态入口特点
CLIcodex终端 TUI,脚本化能力最强
IDE 扩展编辑器内与编辑器上下文结合
桌面 App独立应用图形界面、多线程会话管理
Web / Cloudcodex cloud在云端环境里跑,任务可并行多次尝试

云端相关命令

bash
codex cloud                              # 打开云端界面(Ctrl+O 可查看环境 ID)
codex cloud exec --env <ENV_ID> "..."    # 在指定云环境执行
codex cloud exec --env <ENV_ID> --attempts 3 "..."   # 同一任务尝试多次(1-4)

远程控制codex app-server --listen ws://127.0.0.1:4500 起服务,codex --remote ws://127.0.0.1:4500 连接。--remote 支持 ws://wss://unix://。跨网络使用时必须走 wss:// 并配置鉴权。

官方文档CLIIDE ExtensionApp Server


requirements.toml(托管策略)

是什么

管理员下发的策略文件,用于在组织范围内收窄可选项——它不是「又一份配置」,而是配置的上界。

能约束什么

作用
allowed_approval_policies允许的审批策略集合(如 untrustedon-requestnevergranular
allowed_sandbox_modes允许的沙箱模式集合
allowed_web_search_modes允许的搜索模式;disabled 总是允许,空列表等于只允许 disabled
allowed_permission_profiles允许的权限档位;需要 Codex 0.138.0+
default_permissions默认权限档,必须在允许列表内
allow_managed_hooks_only只执行托管 hooks,跳过用户/项目/会话/插件 hooks
features.*用与 config.toml 相同的键名锁定特性开关
mcp_servers 白名单需同时指定 id 与 identityidentity.commandidentity.url
marketplaces.*限制插件来源(git / host_pattern / local
enforce_residency数据驻留,当前仅支持 us

版本注意:0.137.0 及更早版本会忽略 allowed_permission_profiles 与托管的 default_permissions。要靠这两项做强制约束,必须先确保客户端版本 ≥ 0.138.0。

官方文档Config Reference


模型与推理强度

是什么

Codex 使用的模型,以及模型「想多久」的档位。

配置键取值说明
model字符串官方 Config basics 示例为 gpt-5.6;名称会变,以 Models 为准
model_reasoning_effortminimal / low / medium / high / xhigh仅 Responses API 支持
model_reasoning_summaryauto / concise / detailed / none推理摘要详细程度
model_verbositylow / medium / high输出详细程度

命令行上可用 --model <name> 临时切换,或 /model 在会话中切换。

怎么选推理强度

改一行配置、加个日志——low 够了。设计模块边界、排查复杂并发 bug——highxhigh 值得多等。默认 medium 适用于大多数日常任务。盲目全开 xhigh 只会让简单任务变慢,还更快耗尽额度。

官方文档Models


Chat / Work / Codex

是什么

同一 ChatGPT 应用里的三种工作方式,不是三个独立安装包。官方对照在 Use ChatGPT

名字是什么不是什么
Chat问答、短草稿、把设计谈清楚不是编程界面
ChatGPT Work把任务做到可审成品(PPT / 表 / 站点 / 定期更新)不是 Codex;没有 PR 侧栏
Codex编程 Agent:仓库、diff、测试、PR不是闲聊入口

2026-07-09 起独立 Codex 桌面应用并入 ChatGPT 桌面应用。Work 与 Codex 共用用量额度。

官方文档Use ChatGPT · ChatGPT Work


ChatGPT Work

是什么

官方原文:ChatGPT Work is a way to delegate real work to ChatGPT. 网页默认跑在云端;桌面可选 Work locally 摸本机文件和应用。

和 Codex 的区别

能力可以重叠(官方允许继续用 Codex 做非编程工作),界面不同:Work 藏起 Git / shell,面向日常知识工作。前端工程师用它写周报、出 Sites、盯 Slack,改仓库仍走 Codex。

官方文档Get started with Work · 本教程 ChatGPT Work


Sites

是什么

ChatGPT 创建、托管、分享网站和应用的工作流,公开测试。入口 chatgpt.com/sites

不是什么

不是 Claude Design。没有「从代码库抽品牌规范再交接实现」的官方产品。每个部署 URL 都是生产环境。

官方文档Sites · 本教程 Sites


Codex Cloud 与托管评审

是什么

在 OpenAI 托管的隔离环境里跑编程任务,可并行,可从 GitHub / Linear / Slack 派活。入口 chatgpt.com/codex

托管评审

Cloud 上的 code review / QA 对合格客户由 GPT-5.6 Sol 驱动,模型由 Cloud 自动选。Codex Security Review 是另一条研究预览(Enterprise / Business / Edu / Pro,不含 Plus)。本机 /review 仍是本地会话里的评审,不要和托管评审混名。

官方文档Codex cloud · What's new · 本教程 Cloud


Codex IDE 扩展

是什么

编辑器入口:打开的文件和选区进提示词;在源码旁边审 focused diff。配置模型和 CLI 相同。

官方文档IDE · 本教程 IDE


Codex Remote

是什么

手机(或另一台桌面)带一台已配对的 Mac / Windows 主机。干活的是主机。不是 Cloud。

官方文档Remote · 本教程 Remote


Codex Security

是什么

应用安全 Agent,三扇门:桌面插件、CLI/SDK(@openai/codex-security)、Cloud(研究预览)。只扫你有权评估的代码。

官方文档Security · 本教程 Security


Chrome 扩展

是什么

让 ChatGPT 控制你的 Chrome 配置,含已登录标签。不同于 @Browser(内置配置)和 Work 未登录的云端浏览器。

官方文档Chrome extension · 本教程 Chrome


Computer Use

是什么

桌面应用能力:ChatGPT 看见并操作 macOS / Windows 上的 GUI。Windows 会占前台。文件 / shell 仍走沙箱和审批。

官方文档Computer Use


Browser

是什么

要么是桌面内置浏览器(@Browser,单独配置),要么是 Work 的云端浏览器(未登录的公开站点)。CLI 和 IDE 扩展里没有。

官方文档Browser


ChatGPT Voice

是什么

桌面应用里 Chat / Work / Codex 的 GPT-Live 语音(配对后也可走 iOS Remote)。会话必须以语音模式开始。Voice 额度单独滚动;任务仍消耗 Codex 配额。

官方文档Voice


Computer History

是什么

macOS 桌面功能(默认关),把允许的应用 / 网站活动变成记忆和时间线。依赖 Memories。EEA / 瑞士 / 英国不可用。替代 Chronicle 预览。

官方文档Computer History


Codex SDK

是什么

启动和恢复本机 Codex 线程的库:TypeScript @openai/codex-sdk,Python openai-codex。结构化安全 findings 改用 @openai/codex-security

官方文档Codex SDK


GitHub Action

是什么

openai/codex-action@v1 在 GitHub Actions 里安装 CLI 并跑 codex exec。不想自己管 CLI 时用它。

官方文档GitHub Action


App Server

是什么

给富客户端(含 VS Code 扩展)用的 JSON-RPC 接口,也是 codex --remote 背后的进程。CI 用 SDK 或 codex exec,不要在公网自建监听。

官方文档App Server


Codex Micro

是什么

限量的 Work Louder 键盘:Agent Key 亮灯,触发桌面 ChatGPT 动作。硬件配件,不是 Codex 入口。

官方文档Codex Micro


Atlas(已下线)

是什么

曾经的独立 ChatGPT 浏览器。官方已把基于浏览器的代理能力迁进 ChatGPT 和 Codex,并给出停止日 2026-08-09

不是什么

不是现行产品,也不是需要单独成页的「桌面 superapp」。现行替代:桌面内置浏览器、Chrome 扩展、Work 的 Cloud Browser。

官方文档Evolving Atlas · 2026-07-09 公告


相关页面

为前端工程师打造 · 基于 VitePress 构建