10. 常见扩展路径¶

Codex 智能体的扩展需要沿运行时边界接入。新增能力通常不只涉及一个文件或一层逻辑，而会影响模型可见上下文、本地执行、权限、事件和恢复路径。扩展前应先确定能力类型：工具、技能、MCP、动态工具、模型提供方、入口客户端、上下文字段或事件。

通用改造顺序可以保持一致：先定义模型能看到什么，再接入本地执行或外部服务，再接入权限和沙箱，再定义事件与结果回填，最后确认压缩、恢复和分叉后的表现。这样扩展不会只在当前运行中可用，却在历史回放或恢复时丢失语义。

新增工具¶

新增工具需要同时提供模型可见规范和本地处理器。规范描述工具名称、参数和用途；处理器执行参数校验、权限检查、实际动作和结果回填。

会修改状态的工具还需要接入修改标记、审批、沙箱、差异和事件。工具失败结果也需要进入模型上下文，使模型能够调整后续方案。

完整工具扩展通常包含以下层面：

模型可见说明
参数结构
本地处理器
权限和沙箱
执行前后事件
结果回填格式
历史恢复兼容
测试覆盖

新增工具还需要定义历史语义。工具结果是否进入下一轮模型输入、是否需要截断、失败结果如何表达、恢复后如何恢复，都属于工具设计的一部分。

技能扩展以文档和依赖描述为核心。技能需要提供名称、摘要、完整工作说明、触发条件和依赖。摘要帮助模型判断适用场景，完整文档在触发后进入本轮上下文。

技能不应承担执行职责。命令执行、外部服务访问和文件修改仍通过工具完成。技能只描述任务方法、约束和依赖收集方式。

技能扩展还需要考虑触发粒度。过宽的 description 会导致模型在无关任务中加载技能，过窄的 description 会导致相关任务无法触发。依赖声明应最小化，避免在未使用技能时请求无关环境变量。

MCP 扩展应融入通用工具流程。外部服务端提供工具列表，Codex 管理连接、刷新、认证状态和可见性，模型通过规范请求工具，运行时调用外部工具并回填结果。

大量 MCP 工具需要考虑直接暴露与延迟暴露。直接工具出现在模型可见列表，延迟工具通过发现流程按需展开。该机制控制上下文体积和外部动作面。

MCP 扩展还需要处理认证失败、服务下线、工具结构变化和调用超时。这些状态应转成模型和客户端都能理解的错误，而不是表现为普通文本失败。

动态工具随会话动态提供，可能来自线程启动参数或持久化历史。扩展动态工具时需要覆盖传入、轮次上下文携带、模型可见性、本地执行和恢复/分叉恢复。

动态工具的定义必须可恢复。历史中出现过的动态工具调用在恢复后仍需要被解释和继续处理。

动态工具也需要版本兼容。工具结构变化后，旧历史中的调用参数可能不再匹配新定义。恢复逻辑需要明确使用历史定义、迁移参数或将旧调用标记为不可用。

模型提供方扩展不仅是发送 HTTP 请求。Codex 需要知道模型提供方的能力，包括工具调用、图片、结构化输出、推理内容、WebSocket、用量、错误重试和上下文窗口。

模型提供方返回的流式事件必须映射到 Codex 的统一响应条目、增量、工具调用、用量和完成状态。只有完成这一层映射，新模型提供方才能参与多轮模型与工具循环。

模型提供方扩展还需要定义错误分类。可重试错误、认证错误、上下文超限、模型拒绝、工具协议错误应进入不同恢复路径。错误分类不清会导致重试、降级和轮次 failure 行为不稳定。

新增界面、IDE 插件或脚本入口应优先复用 app-server 协议。入口层负责创建或恢复线程、提交轮次、消费通知、展示工具调用和差异、处理审批请求和中断。

入口层不应重新实现会话循环。绕过协议直接复制运行逻辑会导致工具、权限、长期记忆和事件行为不一致。

入口扩展还需要处理恢复和断线。客户端重新连接后应能通过 thread 历史和通知状态重建界面，而不是依赖本地内存中的临时 UI 状态。

新增模型可见信息需要确定注入层级。稳定规则适合作为初始上下文或设置差异；当前任务事实适合进入历史；工具执行结果应作为工具结果；长历史信息应进入压缩摘要；跨会话信息应进入长期记忆；特定任务说明应通过技能注入。

上下文扩展还需要考虑压缩、恢复/分叉、token 开销、模型能力过滤和敏感信息边界。临时拼接提示词可能造成后续轮次、压缩或恢复路径丢失信息。

上下文扩展应明确持久化策略。只影响当前采样的信息可以不进入长期记录；影响后续轮次、压缩或恢复的信息必须成为历史、上下文差异、持久化记录或长期记忆的一部分。

事件扩展需要同时考虑实时展示和历史恢复。某些事件只影响界面，某些事件会进入持久化记录并影响恢复/分叉、历史回放、token 用量或长期记忆后台处理。

新增事件应明确客户端展示语义、持久化需求、失败状态、顺序关系和兼容策略。事件是结构化运行记录，不是普通日志。

事件扩展还需要定义回放语义。历史回放时，客户端是否应该看到该事件、该事件是否参与条目状态重建、是否影响轮次最终状态，都需要在事件设计中确定。