> ## Documentation Index
> Fetch the complete documentation index at: https://aicoding.cscitech.top/llms.txt
> Use this file to discover all available pages before exploring further.

# Codex术语表

> 按概念分组解释 Codex 的 Agent、上下文、工具、权限、扩展与自动化术语，并给出对照、示例和安全边界。

## 如何使用本页

这是一页可检索的术语表，不要求从头背诵。遇到陌生词时，先看“一句话”，再看“在 Codex 中”与“安全边界”。

Codex 的命令、模型和界面会随版本变化。具体选项以本机的 `codex --help`、子命令的 `--help`、`/status` 和官方文档为准。

本文将术语分为六组：

* 运行模型：Agent、Thread、Context、Token 和代理循环。
* 执行边界：Tool、Sandbox、Approval、Workspace 与 Profile。
* 项目规则：`AGENTS.md`、配置和 Memory。
* 扩展与协作：MCP、Skill、Subagent、Plugin 和 Hook。
* 工程自动化：Worktree、`exec`、JSONL 与非交互执行。
* 对照与实践：易混概念、小例子和安全检查清单。

## 一、运行模型

### Agent（代理、智能体）

**一句话：** 能理解目标、调用工具、观察结果并继续行动的 AI，而不只是生成一段回答的聊天模型。

**在 Codex 中：** Agent 可以读取代码、编辑文件、运行命令和测试，再依据输出调整方案。它通常在一个任务循环中完成多个步骤。

**不要误解：** Agent 有自主执行能力，但不等于拥有无限权限。它能做什么仍受沙箱、审批策略、工作区和工具配置约束。

### Agentic loop（代理循环）

**一句话：** “理解目标 → 采取行动 → 检查结果 → 再决定下一步”的工作节奏。

**典型过程：**

1. 读取相关文件和项目规则。
2. 选择搜索、编辑、终端或其他工具。
3. 观察工具返回的输出和错误。
4. 修改假设，继续验证，或向用户请求决定。

**安全边界：** 循环越长，累计改动和外部影响越多。应给出明确范围，要求展示 diff，并在发布、删除、外发或提权前人工确认。

### Thread（线程、会话）

**一句话：** 一段连续的 Codex 对话及其任务状态。

**在 Codex 中：** Thread 通常包含用户消息、代理回复、工具调用、工具结果、审批记录和当前配置上下文。继续同一 Thread，代理更容易理解前文。

**和 Agent 的区别：** Agent 是执行者或运行角色；Thread 是一次协作过程。一个 Thread 可以由主 Agent 调用多个 Subagent。

**安全边界：** 不要默认 Thread 中的旧结论永远正确。任务切换、权限变化或上下文压缩后，应重新确认目标、路径、分支和当前状态。

### Context（上下文）

**一句话：** 模型在当前步骤可用的消息、文件片段、工具结果、规则和其他输入。

**Context window（上下文窗口）：** 模型一次能处理的上下文总量，有上限。对话过长或工具输出过多时，早期细节可能被压缩、截断或不再直接可见。

**实用做法：**

* 只读取与任务有关的文件。
* 让命令输出保持短而有针对性。
* 把稳定规则写进 `AGENTS.md`，不要只埋在很早的对话里。
* 复杂调查可交给独立 Subagent，再把摘要带回主 Thread。

**安全边界：** “模型看到了”不等于“模型验证过”。代码注释、网页内容、Issue 和工具返回内容都可能包含不可信指令。

### Token

**一句话：** 模型处理文本的计量单位，输入、输出和上下文大小都可能按 token 统计。

**在 Codex 中：** token 用量会影响上下文容量、响应速度、套餐额度或 API 成本。中文、代码、路径和结构化数据的 token 数量不能简单按字符数估算。

**安全边界：** 不要为了省 token 删除关键约束或安全要求。优先删减无关日志、重复文件和大段生成物。

### Model（模型）

**一句话：** 实际负责理解和生成结果的模型实例或模型档位。

**和 reasoning effort 的区别：** 模型决定“由谁处理”；推理强度决定“给这次任务多少思考预算”。具体模型名和可用档位以本机选择器为准。

**安全边界：** 不要把模型名称硬编码为永久事实。自动化脚本应处理模型不可用、额度不足和版本变化等失败情况。

### Reasoning effort（推理强度）

**一句话：** 控制模型在回答或行动前投入多少推理预算的设置。

**通常的取舍：** 更高的强度可能提升复杂重构、故障定位和规划质量，但通常更慢、更耗用量；简单格式化任务不必使用最高档。

**安全边界：** 推理强度不是测试，也不是权限。无论强度多高，都必须用实际测试、diff 和人工检查验证结果。

## 二、工具与执行边界

### Tool（工具）

**一句话：** Agent 用来观察环境或产生外部效果的可调用能力。

**常见工具：** 文件读取与编辑、文本搜索、终端命令、版本控制、浏览器、MCP 工具以及任务管理工具。

**观察型与执行型：** 读取文件、搜索文本通常主要是观察；写文件、安装依赖、发网络请求、删除数据和推送提交会改变状态或影响外部系统。

**安全边界：** 每次工具调用都应检查目标路径、参数、输入来源和预期影响。工具名称可信不代表参数安全；`rm`、脚本、包管理器和网络请求尤其需要逐项确认。

### Tool call（工具调用）

**一句话：** Agent 向某个工具提交结构化参数并等待结果的一次动作。

**在 Codex 中：** 工具结果会回到当前 Context，成为下一轮判断的依据。失败的工具调用不一定代表任务失败，可能需要修正路径、参数或权限。

**安全边界：** 不要只看代理的自然语言总结。需要知道实际执行了什么时，查看调用参数、命令输出和最终 diff。

### Sandbox（沙箱）

**一句话：** 限制 Agent 访问文件系统和网络的技术边界。

**三种常见模式：**

| 模式                   | 文件访问     | 网络    | 适用场景       |
| -------------------- | -------- | ----- | ---------- |
| `read-only`          | 不能直接写入   | 不允许   | 阅读、审查、规划   |
| `workspace-write`    | 允许工作区内写入 | 默认不允许 | 日常开发       |
| `danger-full-access` | 可能访问整台机器 | 允许    | 隔离容器或一次性环境 |

`workspace-write` 不是“整台电脑可写”。工作区范围以当前会话实际显示为准；`.git` 等敏感目录通常有额外保护。网络访问也要单独配置，能写文件不等于能联网。

**安全边界：** `danger-full-access` 会显著扩大影响面。不要把它作为本机或生产机的全局默认；优先使用工作区边界、容器、虚拟机和最小权限。

### Approval（审批）

**一句话：** 决定 Agent 在执行特定动作前是否暂停并请求人工确认的策略。

**常见策略：**

| 策略           | 含义                    |
| ------------ | --------------------- |
| `untrusted`  | 对不在可信范围内的命令更谨慎，通常需要确认 |
| `on-request` | 在边界内自动执行，越界时请求确认      |
| `never`      | 不主动请求审批，适合严格隔离的自动化环境  |

**关键区别：** Sandbox 管“技术上能不能访问”；Approval 管“执行前要不要问”。两者是独立维度，不能互相替代。

**安全边界：** `never` 不会自动扩大文件或网络权限；但若同时使用完全访问，风险会叠加。审批窗口出现时，检查命令、路径、网络目标和数据流向，而不是机械点击允许。

### Workspace（工作区）

**一句话：** Codex 当前被允许重点读写的项目目录集合。

**在 Codex 中：** 通常是启动会话时所在的仓库或项目目录，可能还包括系统临时目录。`/status` 可用于核对当前沙箱、审批和工作区范围。

**和当前目录的区别：** 当前目录是进程的工作路径；Workspace 是权限边界概念，可能包含多个明确允许的目录，也可能比当前目录更受限。

**安全边界：** 运行前确认路径不是生产目录、共享目录或含有真实客户数据的目录。无 Git 的目录缺少天然的 diff 和回滚保护，应更谨慎。

### Permission profile（权限配置档）

**一句话：** 将文件系统和网络访问规则打包成可命名、可复用权限边界的配置机制。

**和旧式 sandbox 配置的区别：** `sandbox_mode` / `approval_policy` 是传统的两个设置维度；permission profiles 是更细粒度的权限描述机制，具体状态和语法以版本文档为准，部分能力可能处于 Beta。

**安全边界：** 不要同时混用互相冲突的权限配置。自定义规则应先在临时目录验证；对 `.env`、密钥目录和生产域名采用明确拒绝或白名单。

### Profile（配置预设）

**一句话：** 给一组 Codex 配置起名字，启动时按名称加载。

**可包含：** 默认模型、推理强度、沙箱、审批、MCP 等常用设置，具体字段取决于版本和配置格式。

**易混对照：** “配置 profile”是配置组合；“permission profile”专门描述权限边界；“用户账号”或“登录 Profile”又是身份概念，三者不要混称。

**安全边界：** 每次切换 profile 后检查实际生效值。不要因名称叫 `safe`、`local` 或 `ci` 就假设它真的安全。

## 三、项目规则与持久状态

### `AGENTS.md`

**一句话：** 写给 Agent 的持久项目指导文件，类似项目入职手册。

**适合写：** 构建和测试命令、目录约定、代码风格、提交要求、生成文件规则和验收步骤。

**作用范围：** 可以有全局指导，也可以在仓库根目录或更深的子目录提供项目指导。离当前工作目录更近的规则通常更相关，冲突时应明确处理。

**和聊天指令的区别：** 聊天消息主要影响当前 Thread；`AGENTS.md` 旨在跨 Thread 持久复用。它是指导，不是权限系统，不能替代 Sandbox 或 Approval。

**安全边界：** 只把可信、可审查的规则放进文件。不要在其中保存密钥，也不要把“永远自动执行任意命令”当作团队规范。修改后检查 diff，避免陌生仓库中的同名文件改变你的预期。

### Config（配置）

**一句话：** 控制 Codex 默认行为的设置集合，常见载体是 `config.toml`。

**通常配置：** 默认模型、推理强度、沙箱、审批、MCP server、profile 和功能开关。

**临时与持久：** 命令行参数或会话命令通常只影响一次运行；写入用户级或项目级配置会影响后续运行。两者叠加时，以当前版本的优先级规则为准。

**安全边界：** 配置文件可能影响所有项目。把高权限设置写成全局默认尤其危险；密钥只通过环境变量或受支持的凭据机制提供，不要提交到 Git。

### Memory（记忆）

**一句话：** 将过去会话中可能有用的偏好、项目惯例或经验带到后续工作的功能。

**在 Codex 中：** Memory 通常默认关闭，是否可用、保存位置和逐会话控制取决于版本、平台和地区。它更像辅助回忆，不是严格规则引擎。

**和 `AGENTS.md` 的区别：** `AGENTS.md` 是明确、可审查、可随仓库管理的规则；Memory 是自动生成或本地保存的经验摘要，可能遗漏、过时或不适用。

**安全边界：** 不要把密码、令牌、客户资料或必须执行的合规要求交给 Memory 保存。重要约束写进经过审查的 `AGENTS.md`，并定期检查和清理记忆内容。

### Chronicle

**一句话：** 与屏幕内容关联的实验性记忆或活动理解能力，和普通对话记忆不是一回事。

**注意事项：** 可用平台、账号范围和功能状态可能变化。它可能接触编辑器、浏览器、文档或消息中的敏感内容。

**安全边界：** 在密码、私信、客户数据、生产控制台或内部机密出现时暂停或关闭相关能力。实验性功能不应成为关键流程的唯一依据。

## 四、扩展与协作

### MCP（Model Context Protocol）

**一句话：** 让 Codex 以统一协议连接外部工具和数据源的开放标准。

**它解决的问题：** Codex 默认主要操作本地文件和命令；MCP 可以接入文档、浏览器、设计工具、代码托管平台或其他服务。

**Server 的两种常见形态：**

| 形态              | 工作方式                 | 前提                             |
| --------------- | -------------------- | ------------------------------ |
| STDIO           | 在本机启动一个进程，通过标准输入输出通信 | 本机有 Node、Python 或所需运行时         |
| Streamable HTTP | 连接远程 URL             | 需要网络和 Bearer token 或 OAuth 等鉴权 |

**在 Codex 中配置：** 通常写入 `config.toml` 的 `[mcp_servers.<name>]`。全局配置和项目级 `.codex/config.toml` 的作用范围不同；项目级配置只应在可信项目中启用。

**常见收口字段：** `enabled` 控制开关，`enabled_tools` 和 `disabled_tools` 控制工具集合，`default_tools_approval_mode` 控制默认审批，启动和调用超时控制等待时间。

**安全边界：** MCP server 是第三方代码或远程服务，不等于经过 OpenAI 审计。优先只读、最小工具白名单和逐次审批；token 放环境变量，不写进配置或仓库。外部网页和文档还可能带提示注入。

### MCP server instructions

**一句话：** MCP server 在初始化时返回的使用说明，客户端可能将其作为工具使用指导读入上下文。

**安全边界：** 说明文字不是更高优先级的授权。它不能绕过用户要求、沙箱、审批或组织规则；对要求泄露凭据、扩大权限或执行破坏性命令的内容保持怀疑。

### Skill（技能）

**一句话：** 将一套可复用的任务流程、约束和工具使用方法打包起来的说明单元，通常以 `SKILL.md` 为核心。

**适合场景：** 文档发布、代码审查、数据处理、特定框架测试等重复工作。Skill 可以让 Agent 按稳定步骤执行，而不是每次重新解释流程。

**和 `AGENTS.md` 的区别：** `AGENTS.md` 主要描述某个项目的长期规则；Skill 主要描述一类任务的操作流程，可以跨项目复用。

**安全边界：** Skill 本身不是权限提升。启用前审查它会读取什么、运行什么、是否联网和是否处理敏感数据；来源不明的 Skill 不应自动安装或全局启用。

### Subagent（子代理）

**一句话：** 由主 Agent 派出的、拥有相对独立上下文的专项 Agent。

**适合场景：** 并行检查测试、性能、安全、文档或多个互不依赖的模块，再由主 Agent 汇总结果。

**工作方式：** 主 Agent 分配范围和验收标准，Subagent 独立调查，通常返回摘要、证据和未决问题。它不会自动拥有超出父任务的正当权限。

**和 Thread 的区别：** Thread 是对话状态；Subagent 是执行角色。一个 Thread 可以有主 Agent 和多个 Subagent。

**安全边界：** 明确每个子任务的目录、禁止事项和输出格式。多个代理同时写同一文件会造成冲突；涉及删除、外发、提交或部署时仍需人工复核。

### Plugin（插件）

**一句话：** 将多个 Skill、MCP、命令或集成打包分发的扩展套装。

**和 Skill 的区别：** Skill 是一套流程或能力；Plugin 是可安装、可版本化、可整体管理的能力集合。

**安全边界：** 安装插件等同于引入一组新代码和配置。先确认来源、版本、权限、网络行为和卸载方式，不要因为“官方样例”就跳过审查。

### Hook（钩子）

**一句话：** 在特定生命周期事件发生时自动执行的脚本或动作。

**和 Skill 的区别：** Skill 通常需要被点名或匹配后执行；Hook 是在配置的事件发生时自动触发，例如工具调用前后或会话事件。

**安全边界：** Hook 可能在你没有再次输入指令时运行。限制脚本来源、环境变量、网络访问和写入路径，变更后用无害事件测试触发条件。

## 五、工程化执行

### Worktree（Git 工作树）

**一句话：** 同一个 Git 仓库中彼此分离的工作目录，可用于并行分支开发。

**在 Codex 中：** Worktree 可以让主任务和子任务分别在独立目录或分支中修改，减少互相覆盖，并便于分别查看 diff、测试和合并。

**和 Workspace 的区别：** Worktree 是 Git 的目录与分支机制；Workspace 是 Codex 的访问边界。一个 Worktree 可以成为一个 Workspace，但两者不是同义词。

**安全边界：** 创建前确认分支、目录和基准提交。合并前分别运行测试并检查冲突；不要把包含未提交用户改动的目录当作可随意重建的临时工作树。

### `exec`

**一句话：** 通过命令行执行 Codex 任务的非交互方式，常写作 `codex exec`。

**适合场景：** CI、批处理、定时任务和一次性分析。它通常接收任务说明并输出结果，不依赖持续的人工对话。

**和交互模式的区别：** 交互模式方便逐步澄清和审批；`exec` 更适合固定输入、固定输出和可重复验证。非交互不代表无权限，也不代表结果已验证。

**安全边界：** 为自动化设置明确的工作目录、超时、输出格式和失败码。生产环境不要默认使用完全访问；避免把凭据、完整环境变量或不可信内容直接拼接进命令。

### `codex exec` 的自动化输入

**一句话：** 把任务作为命令参数或标准输入交给 `codex exec`，让脚本驱动一次 Codex 运行。

**建议：** 任务中明确只读或可写范围、验收命令、禁止提交推送，以及失败时的退出行为。输出应保存到临时位置，再由脚本或人工审查。

**安全边界：** 不要把用户可控字符串未经转义地拼进 shell 命令。脚本要区分 Codex 的文本输出和真正的成功状态，不能只因返回了一段“完成”就继续部署。

### JSONL（JSON Lines）

**一句话：** 每行一个独立 JSON 对象的文本格式，适合流式记录和机器处理。

**在 Codex 中：** 某些非交互或事件输出可以用 JSONL 表示，使脚本逐行读取事件、工具调用、状态和结果，而不必等待一个巨大 JSON 文档结束。

**和普通 JSON 的区别：** 普通 JSON 通常是一个完整值；JSONL 是多行、每行独立可解析的 JSON 值。不要把整份 JSONL 当成单个 JSON 数组直接解析。

**安全边界：** 解析时处理空行、未知事件、截断行和错误对象；不要把字段中的文本当作可执行命令。日志可能包含路径、代码和敏感值，应按敏感日志处理。

### Exit code（退出码）

**一句话：** 命令进程结束时向调用方报告成功或失败状态的数值。

**在自动化中：** CI 应同时检查退出码、JSONL 事件和产物 diff。退出码成功只表示进程认为运行完成，不代表代码正确或安全。

**安全边界：** 为测试、超时、权限拒绝、解析失败和模型不可用设计不同的处理路径；失败时停止后续发布，不要用“忽略错误”掩盖风险。

## 六、易混概念对照

| 容易混淆                           | 准确区分                                    |
| ------------------------------ | --------------------------------------- |
| Agent / Thread                 | Agent 是执行者；Thread 是一次对话和状态              |
| Context / Memory               | Context 是当前可见输入；Memory 是跨会话的辅助保存        |
| Tool / MCP                     | Tool 是一次可调用能力；MCP 是连接外部工具的协议            |
| Sandbox / Approval             | Sandbox 管访问边界；Approval 管是否暂停询问          |
| Workspace / Worktree           | Workspace 是权限范围；Worktree 是 Git 工作目录     |
| `AGENTS.md` / Memory           | 前者是明确项目规则；后者是可能生成的经验回忆                  |
| Skill / Plugin                 | Skill 是一套流程；Plugin 是多个扩展的可安装套装          |
| Skill / Hook                   | Skill 按需调用或匹配；Hook 按事件自动触发              |
| Subagent / Parallel tool calls | Subagent 是独立协作角色；并行调用只是同时发起工具动作         |
| Profile / Permission profile   | Profile 是配置组合；Permission profile 专注权限边界 |
| `exec` / 交互模式                  | `exec` 面向脚本自动化；交互模式便于澄清和逐步审批            |
| JSON / JSONL                   | JSON 是一个完整值；JSONL 是每行一个 JSON 值          |
| Model / Reasoning effort       | Model 是处理者；Reasoning effort 是思考预算       |
| 网络访问 / MCP                     | 网络访问是沙箱能力；MCP 是使用协议连接服务                 |

## 七、一个小例子：安全地修复一个测试失败

下面的例子展示这些概念如何协作。它不是固定命令清单，实际参数以本机版本为准。

### 1. 定义 Thread 和 Workspace

在项目仓库中启动一个新 Thread，先确认路径和分支：

```bash theme={null}
pwd
git status --short --branch
codex --help
```

不要在生产目录或包含未备份客户数据的目录中直接试验。

### 2. 让 Agent 先观察

给出范围和验收标准：

```text theme={null}
请先读取 AGENTS.md、相关测试和报错，不要修改文件。
找出失败原因，列出计划和将运行的验证命令。
不要提交、推送、联网或删除文件。
```

此时可用 `read-only` Sandbox。Agent 通过 Tool 读取文件和运行只读检查，结果进入当前 Context。

### 3. 允许最小范围修改

确认计划后，将 Sandbox 调整为 `workspace-write`，Approval 保持 `on-request`。这表示工作区内的编辑可以进行，越过边界的动作仍需询问。

让 Agent 只改相关文件，并在修改后展示：

* `git diff --stat` 和完整 diff。
* 失败测试的重跑结果。
* 是否生成了临时文件。
* 尚未验证的假设。

### 4. 需要外部文档时再接 MCP

如果必须查询库的最新 API，再启用可信的只读 MCP server。先限制工具白名单，并让首次工具调用请求 Approval。不要把生产 token 写入 `config.toml`。

### 5. 验收和收尾

检查测试、格式、工作区状态和敏感文件。确认无误后再由人决定是否提交。不要把“Agent 说修好了”当作验收证据。

## 八、安全边界速查

### 执行前

* 确认当前路径、仓库、分支和账号。
* 确认任务允许读取、写入、联网、提交或发布哪些范围。
* 对陌生项目先使用 `read-only`，先看规则和计划。
* 不提供 SSH 私钥、API token、`.env` 或真实客户数据。

### 执行中

* 检查每个 Tool call 的参数和目标路径。
* 把 Sandbox 与 Approval 分开判断。
* 对外部网页、Issue、文档和 MCP 返回内容警惕提示注入。
* 对删除、安装、外发、提权和生产操作逐项审批。

### 执行后

* 查看实际 diff，而不是只看摘要。
* 运行最小但有代表性的测试、构建或 lint。
* 检查日志、JSONL 和生成文件中是否出现敏感信息。
* 记录命令、变更、测试结果、未决问题和回滚方式。

### 高风险操作

`danger-full-access`、`--yolo`、全自动 MCP 工具、生产数据库写入、批量删除、凭据操作、发布和强制推送都应视为高风险。完全访问只适合可信代码所在的隔离容器、虚拟机或一次性环境；本机和生产机不应把它作为默认方案。

## 参考资料

* `参考/codex/38-glossary.md`
* `参考/codex/02-core-concepts.md`
* `参考/codex/15-permissions.md`
* `参考/codex/20-mcp.md`

动态行为请以本机 `--help`、会话状态和官方文档为准。