缓存、工具与模型的关系

在 Agent 编程工具中接入 Modelink 时，模型能力、工具协议和缓存命中率不是彼此独立的三件事。Codex、Claude Code 这类工具会在每次请求中组织系统提示词、工具定义、历史消息、文件上下文和当前任务；这些内容如何排列、是否稳定、是否能被协议标记为可缓存，都会影响最终的缓存效果。

简单说：缓存命中率不只取决于模型是否支持缓存，也取决于工具用什么协议调用模型，以及工具是否把可复用内容稳定地放在请求前缀里。

信息

本文讨论的是 Agent 工具接入时的工程关系。具体缓存阈值、有效期、计费方式和返回字段，请以目标模型和 Modelink 控制台能力说明为准。

一张关系图

Agent 工具（Codex / Claude Code）
  -> 接入协议（OpenAI Chat / OpenAI Responses / Anthropic Messages）
  -> 请求结构（tools / system / messages / cache_control）
  -> 可缓存前缀是否稳定
  -> 缓存命中率、延迟和成本

工具不是只把用户问题转发给模型。它还会把可用工具、权限规则、项目上下文、历史对话和当前文件状态一起组织成一次 API 请求。请求结构越接近模型原厂训练和优化时使用的形态，模型越容易发挥稳定表现；请求中的长前缀越稳定，缓存也越容易命中。

协议支持会影响缓存命中率

缓存通常依赖稳定前缀。Agent 场景里，稳定前缀往往包括：

工具定义，例如读文件、写文件、运行命令、搜索代码、创建 diff。
系统提示词，例如角色、权限、安全边界、输出格式。
项目级说明，例如仓库规则、技术栈、目录结构、开发约束。
多轮任务中已经稳定的历史消息。

如果工具每次都用相同顺序和相同内容发送这些部分，模型服务就更容易复用缓存。如果工具在每次请求里重排工具定义、插入动态时间、改变系统提示词，或者把当前用户输入放在长上下文之前，缓存命中率就会下降。

协议本身也会影响工具能不能表达缓存边界：

工具 / 协议形态	常见缓存影响	接入建议
Codex + OpenAI Chat Completions	主要依赖自动 Prompt 缓存，要求稳定共享前缀足够长且完全一致	保持工具定义、系统提示词和固定上下文顺序稳定
Codex + OpenAI Responses	可观察字段常见于 `usage.input_tokens_details.cached_tokens`，具体行为取决于模型和 provider 实现	按工具支持选择 `responses`，并关注返回的 cached tokens
Claude Code + Anthropic Messages	更容易表达 `tools -> system -> messages` 层次；在支持时可用 `cache_control` 标记主动缓存断点	优先保持工具列表和系统消息稳定，必要时使用 Anthropic 兼容缓存能力
OpenAI 兼容工具调用 Anthropic 风格模型	可能丢失部分原厂协议特性，需要由网关或工具做协议映射	先验证工具调用、缓存字段和长上下文表现，再扩大使用
Anthropic 兼容工具调用 OpenAI 风格模型	同样可能出现协议语义映射，缓存行为不一定等同原厂协议	以实际请求日志和 usage 字段判断命中率

因此，“模型支持缓存”只是前提；“工具是否用合适的协议表达稳定上下文”才决定缓存能不能在真实 Agent 工作流中持续命中。

Codex 与自家模型

Codex 是 OpenAI 面向编程任务设计的 Agent 工具。它天然围绕 OpenAI 的模型、工具调用格式和 Responses / Chat 协议演进。使用 OpenAI 官方模型时，模型后训练、工具提示、工具调用格式、权限交互和错误恢复方式通常会一起优化。

这就像人用自己的手干活：手、眼睛和大脑长期一起训练，动作反馈是连贯的。模型知道工具返回大概长什么样，也更熟悉何时读文件、何时改文件、何时运行测试、何时收敛输出。

当 Codex 通过 OpenAI 兼容协议接入其他模型时，并不代表不能工作。Modelink 会尽量提供协议兼容和模型路由能力，但工具和模型之间多了一层适配关系：

工具发出的工具定义和调用格式，未必是目标模型后训练中最熟悉的格式。
模型对工具结果、错误消息和多轮修复节奏的理解，可能没有官方组合稳定。
如果协议从 Responses 映射到其他形态，缓存字段和上下文层次可能发生变化。
自动缓存依赖稳定前缀；如果工具版本升级改变请求结构，命中率也可能波动。

这更像给人装上假肢干活：假肢可以完成动作，甚至在某些场景里很强，但它需要适配、校准和练习。工具协议、模型能力和网关映射越匹配，使用体验越接近原生组合。

Claude Code 与自家模型

Claude Code 是 Anthropic 围绕 Claude 系模型设计的编程 Agent。它常用 Anthropic Messages 协议组织请求，并天然围绕 Claude 的工具使用方式、长上下文处理、系统提示结构和安全策略展开。

Claude 官方模型配合 Claude Code 时，也类似人使用自己的手：模型后训练通常会见过大量相似的工具轨迹，知道 Claude Code 的工具调用节奏、权限边界、文件编辑反馈和终端结果该如何理解。尤其在长上下文、多工具、主动缓存断点等场景中，原厂协议能表达更多细节。

当 Claude Code 通过 Modelink 接入第三方或非 Claude 模型时，关键问题同样不是“能不能请求成功”，而是：

目标模型是否熟悉 Anthropic 风格的工具调用和消息结构。
网关是否能准确映射工具定义、工具结果和停止原因。
目标模型是否支持 Anthropic 兼容的主动缓存语义。
tools -> system -> messages 的稳定层次是否被保留下来。

如果这些条件匹配，体验会更好；如果协议映射较重，模型可能仍能完成任务，但缓存命中率、工具调用稳定性和多轮修复效率都需要用真实任务验证。

为什么“官方模型 + 官方工具”通常更顺手

官方模型结合官方工具的优势，核心来自后训练和产品协同，而不只是品牌绑定。

模型后训练通常会针对自家工具做额外优化，包括：

学会特定工具调用格式和参数组织方式。
学会读取工具返回、错误信息和权限提示。
学会在多轮代码任务中规划、编辑、验证和回滚。
学会遵守工具内置的安全边界和交互节奏。
学会在特定协议下组织长上下文和缓存边界。

所以官方组合更像“身体原生协同”：工具设计者知道模型擅长什么，模型训练者也知道工具会给它什么输入。换成其他模型或其他工具时，本质上是在做跨系统协作。它可以有价值，但应当用工程指标评估，而不是假设协议兼容就等于体验等价。

使用 Modelink 接入时的判断方式

Modelink 的价值是让团队可以在同一套接入和治理体系下选择不同模型，而不是强迫所有工具只使用原厂模型。接入时建议把问题拆成三层验证：

验证层	要确认什么	观察指标
请求是否兼容	工具能否正常发起请求、调用工具、读取结果	成功率、错误码、工具调用是否闭环
模型是否适配	模型是否理解工具语义、能否稳定完成代码任务	任务完成率、编辑质量、测试通过率、多轮修复次数
缓存是否有效	稳定上下文是否被复用	`cached_tokens`、缓存读取 token、首 token 延迟、单位任务成本

如果只是普通问答，协议差异的影响可能不明显；如果是复杂 Agent 编程任务，协议、工具和模型训练分布会被放大。

提升命中率和稳定性的做法

优先使用目标工具明确支持的协议形态，例如 Codex 选择合适的 wire_api，Claude Code 使用 Anthropic 兼容接入点。
保持工具定义、系统提示词、项目规则和固定上下文的顺序稳定。
不要在可缓存前缀中插入时间戳、随机 ID、本次用户输入或实时数据。
对长任务记录 cached_tokens、输入输出 token、耗时和模型 ID，用数据判断收益。
工具或模型版本升级后，重新观察缓存命中率和任务完成率。
对关键生产任务，分别测试“官方模型 + 官方工具”和“Modelink 路由模型 + 目标工具”的表现，再决定默认配置。
如果需要主动缓存，优先选择能保留缓存断点语义的协议和模型。

常见误区

误区	正确认知
只要是 OpenAI 兼容就一定有同样缓存效果	OpenAI 兼容主要保证请求形态可调用，不保证缓存策略、字段和命中率完全一致
只要模型足够强，就能无损适配任何 Agent 工具	工具调用能力也依赖后训练分布、协议细节和错误恢复习惯
缓存命中率低一定是模型问题	工具重排上下文、动态内容混入前缀、协议映射变化都可能导致低命中
官方工具只能用官方模型	可以接入其他模型，但应明确它是跨系统适配，需要验证协议、工具和缓存表现
使用其他模型就一定不如官方模型	不一定。成本、速度、上下文长度、区域可用性和任务类型都可能让其他模型更合适