如何使用本页
这是一页可检索的术语表，不要求从头背诵。遇到陌生词时，先看“一句话”，再看“在 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（代理循环）
一句话： “理解目标 → 采取行动 → 检查结果 → 再决定下一步”的工作节奏。 典型过程：- 读取相关文件和项目规则。
- 选择搜索、编辑、终端或其他工具。
- 观察工具返回的输出和错误。
- 修改假设，继续验证，或向用户请求决定。
Thread（线程、会话）
一句话： 一段连续的 Codex 对话及其任务状态。 在 Codex 中： Thread 通常包含用户消息、代理回复、工具调用、工具结果、审批记录和当前配置上下文。继续同一 Thread，代理更容易理解前文。 和 Agent 的区别： Agent 是执行者或运行角色；Thread 是一次协作过程。一个 Thread 可以由主 Agent 调用多个 Subagent。 安全边界： 不要默认 Thread 中的旧结论永远正确。任务切换、权限变化或上下文压缩后，应重新确认目标、路径、分支和当前状态。Context（上下文）
一句话： 模型在当前步骤可用的消息、文件片段、工具结果、规则和其他输入。 Context window（上下文窗口）： 模型一次能处理的上下文总量，有上限。对话过长或工具输出过多时，早期细节可能被压缩、截断或不再直接可见。 实用做法：- 只读取与任务有关的文件。
- 让命令输出保持短而有针对性。
- 把稳定规则写进
AGENTS.md，不要只埋在很早的对话里。 - 复杂调查可交给独立 Subagent，再把摘要带回主 Thread。
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 访问文件系统和网络的技术边界。 三种常见模式：workspace-write 不是“整台电脑可写”。工作区范围以当前会话实际显示为准；.git 等敏感目录通常有额外保护。网络访问也要单独配置，能写文件不等于能联网。
安全边界： danger-full-access 会显著扩大影响面。不要把它作为本机或生产机的全局默认；优先使用工作区边界、容器、虚拟机和最小权限。
Approval（审批）
一句话： 决定 Agent 在执行特定动作前是否暂停并请求人工确认的策略。 常见策略：
关键区别： 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 的两种常见形态：
在 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。退出码成功只表示进程认为运行完成，不代表代码正确或安全。 安全边界： 为测试、超时、权限拒绝、解析失败和模型不可用设计不同的处理路径；失败时停止后续发布，不要用“忽略错误”掩盖风险。六、易混概念对照
七、一个小例子：安全地修复一个测试失败
下面的例子展示这些概念如何协作。它不是固定命令清单，实际参数以本机版本为准。1. 定义 Thread 和 Workspace
在项目仓库中启动一个新 Thread，先确认路径和分支：2. 让 Agent 先观察
给出范围和验收标准：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、会话状态和官方文档为准。