OpenCode 2.3.2 实测:GPT-6.2 不缓存 instructions,system prompt 改放开头的 developer 消息

发布于 2026年11月22日 作者 Remy

结论先说: 从 GPT-6.2 开始,Responses API 会把请求顶层的 instructions 放到 input 后面,落在缓存断点之外。哪怕每次内容一字不差,这部分也按未缓存的价格算。[4][5] OpenCode 的 system prompt 一直放在 instructions 里,所以用 GPT-6.2 时每一步都要把一万多 token 的 system prompt 重新付一遍全价。2.3.2(北京时间 11 月 18 日 09:35 发布)把它挪成了 input 里的第一条 developer 消息,从第二步起就能命中缓存。GitHub Copilot 的 gpt-6.2-sol 上,每步未缓存输入从 14,163 token 降到 3。[1][3]

你现在的情况该做什么
在 OpenCode 里用 GPT-6.2(API key、ChatGPT 登录、Copilot、Zen、Azure、OpenRouter)升到 2.3.2:opencode upgrade,或 npm i -g @opencode/cli@latest,或 curl -fsSL https://opencode.ai/v2/install | bash。不用改配置。
自建路由,配置里还是 V1 的 provider 块加 "npm": "@ai-sdk/openai-compatible"这条路走 AI SDK,不在这次修复范围内。改成 V2 的 providers 块,package 写 @opencode/ai/providers/openai-compatible/responses。[10]
中间隔着 LiteLLM 这类网关,网关再转成 Responses 请求网关自己也要修。LiteLLM 已在 v1.108.13、v1.110.2 等版本修复,用 Claude Code 经 LiteLLM 调 GPT-6.2 的也在受影响之列。[8]
自己写代码调 Responses API固定的 system prompt 放进 input 开头的 developer 消息。instructions 只留给本轮临时的指示,比如「最后一轮请总结」。
用 GPT-6.1 及更早的模型两种写法都能缓存,升级不影响结果。[2]

OpenCode v2.3.2 changelog 页面

前缀缓存只认一模一样的开头

模型处理一段输入时,会为每个 token 算出一组中间结果(KV cache)。下一次请求如果开头完全相同,服务端就可以直接复用这些结果,只算后面新增的部分。复用的那部分按缓存价计费,GPT-6.2 Sol 和 Astra 的缓存读取价是普通输入的 0.05 倍,写入是 1.25 倍(30 分钟有效)或 2.5 倍(12 小时)。[4] 所以一个 agent 每一步发出的请求,开头越长越稳定,账单越便宜。

「开头相同」是按渲染后的 token 序列逐个比的,不是比语义。中间改一个字符,从那里往后全部作废。OpenAI 的做法是在请求里找几个「查找边界」,从最长的往短里试,看哪个前缀已经在缓存里。GPT-5.6 之后的隐式模式下,这些边界包括:最新一条符合条件的消息末尾,往前最多 20 条消息的末尾,以及开头那一串连续 developer 消息的结尾。[4] 最后一条很关键:只要 system prompt 是开头的 developer 消息,哪怕后面的对话全变了,这一段也能单独命中。

instructions 在 GPT-6.2 上的位置恰好相反。文档的说法是,GPT-6.2 起的模型把它追加在 input 之后,这样你在每一轮改它也不会破坏前面的缓存。代价是它永远在断点之外,每次都按未缓存价算,也不能在里面加显式断点。[4][5] 这个设计本身说得通:instructions 本来就该放「只对这一次请求有效」的话。问题在于大多数客户端一直把整段 system prompt 塞在这里,GPT-6.1 及以前它和 developer 消息缓存效果一样,没人觉得需要区分。

同一份 system prompt,在 GPT-6.2 上的位置不同,计费就不同OpenCode 2.3.1请求里:instructions 字段tools对话历史(逐步追加)新输入system prompt缓存可复用的前缀GPT-6.2 把 instructions 接在 input 之后,落在缓存断点外面:每步按未缓存价重算每步未缓存OpenCode 2.3.2请求里:input[0] developer 消息toolssystem prompt对话历史(逐步追加)新输入缓存可复用的前缀system prompt 在开头,和 tools、历史一起成为可复用前缀:第 2 步起读缓存工具定义和开头的 developer 消息都排在对话之前,两者的先后由服务端渲染决定,图中只作示意。字符数来自本地 mock 抓到的 OpenCode 请求(tools 约 15.0k,system prompt 11.3k 字符)。

这个变化不报错,请求照常成功,只是账单变厚。LiteLLM 的复盘写得很直白:11 月 17 日 OpenAI 更新了文档,他们的告警一个都没响,直到 18 日有客户来问缓存为什么没命中。[8] 还有一处容易误导人:OpenAI 的缓存诊断(prompt_cache_options.comparison_response_id)在 instructions 的请求上报告 cache_hit,而 usage 里的 cached_tokens 和 cache_write_tokens 都是 0。[2][9] 查账以 usage 为准。

2.3.1 和 2.3.2 发出去的请求差在哪

把 OpenCode 指向本地 mock 服务,模型选 openai/gpt-6.2-sol,两轮对话、每轮调一次工具,抓到的请求如下。

OpenCode 2.3.1 和 2.3.2 的 system prompt 位置

2.3.1 的请求里,instructions 是 11,325 个字符的 system prompt,input[0] 就是用户消息。2.3.2 的请求没有 instructions,input[0] 是一条 developer 消息,内容是同样的 11,325 个字符,哈希也一样。12 个工具声明(14,976 字符)两个版本完全相同,仍然放在顶层 tools。每一步的请求都是上一步原样加上新内容,把 tools、system prompt、input 依次拼起来比,上一步的全文都是下一步的开头,两个版本都是这样。

也就是说,2.3.2 只动了一件事:system prompt 换了位置,文本一个字节都没变。在 GPT-6.1 上这两种请求的缓存效果相同。在 GPT-6.2 上,前者每步都要为这 11k 字符付全价。

同样的对比在 xai/grok-4.7 和一个自定义路由(V2 providers 块,package 用 @opencode/ai/providers/openai-compatible/responses)上也做了,结果一致:2.3.1 用 instructions,2.3.2 用开头的 developer 消息。这对应两个 PR 的分工。#64542 先改了 OpenAI 自家的 Responses 路由,#64544 把改动下沉到所有 Responses 路由共用的 OpenResponses.lowerConversation,Copilot、xAI、OpenRouter、Vercel AI Gateway 和自定义的 OpenAI 兼容服务都跟着变。[2][3]

真实账单 mock 测不出来,只能看 PR 里作者的实测。ChatGPT 登录、gpt-6.2-sol、一个会话里三句短提示,每步未缓存输入从 16,969、16,992、14,457 变成 16,969、352、121。[2] 用 API key 直接发请求,instructions 写法四步的缓存命中都是 0,换成 developer 消息后从第二步开始命中 9,632、9,660、9,691 token。[2]

有两种配置不会因为升级而受益。一种是 V1 的 provider 块配 "npm": "@ai-sdk/openai-compatible",这条路走 /chat/completions,system prompt 是 messages[0],本来就不涉及 instructions。另一种是 V1 块里写了 package 但同时留着 npm:V2 只从 npm 取运行时,package 被忽略。#64783 里的用户就是这样,升到 2.3.2 后每轮仍有 1 万到 2 万 token 未缓存,改成 V2 写法后降到 6k 左右。[10]

{
  "providers": {
    "myrouter": {
      "package": "@opencode/ai/providers/openai-compatible/responses",
      "settings": { "baseURL": "https://router.example.com/v1", "apiKey": "{env:ROUTER_KEY}" },
      "models": { "gpt-sol": { "limit": { "context": 1050000, "output": 128000 }, "body": { "store": false } } }
    }
  }
}

压缩之后,前缀还剩多少

缓存最怕的就是压缩。OpenAI 文档也直说,摘要、压缩或截断都会改变前缀,让缓存复用归零。[4] 能做的是让压缩只动历史,不动前面的 system prompt 和工具。

OpenCode 2.3.2 压缩前后的请求结构

把 2.3.2 的上下文窗口设成 20,000,让 mock 报告的 token 数逐步变大,自动压缩就会触发。compaction.type 设成 native 时,OpenCode 不另开请求,而是在正常的 /responses 请求末尾追加一个 compaction_trigger,前面的内容原样保留,这一步仍是上一步的延续。压缩之后的下一次请求变成 [developer, 第一条 user, user, compaction]:system prompt、工具和第一条用户消息都在,从 input[2] 开始才不同。TUI 里手动输入 /compact 走的也是这条路。

设成 summary 时,写摘要的请求同样是完整前缀加一条「You MUST summarize the conversation above…」的用户消息,能吃到前面的缓存。压缩后剩下 [developer, user "<conversation-checkpoint>…"],system prompt 和工具不变。2.3.1 两种模式的形状相同,只是 system prompt 还在 instructions 里。

release notes 说 /responses/compact 现在也读同一份缓存前缀。[1] #64544 的数据是:带 instructions 的压缩请求在 gpt-6.2-sol 上读到 0 个缓存 token,换成 developer 消息后读到 3,190 个里的 2,962 个。[3] 本地几次压缩都没走到这个端点,这一点没能亲眼看到。

其他几家怎么排前缀

同样的 mock 也接了 Codex CLI 0.171.0、Claude Code 2.1.330、Gemini CLI 0.70.0 和 Qwen Code 0.28.3。它们的 system prompt 都不在 instructions 里,但排法各不相同。

五家 harness 的请求前缀:放了什么、断点在哪(本地 mock 实测)OpenCode 2.3.2Responses · gpt-6.2-soltools 15.0ksystem 11.3k历史Codex CLI 0.171.0Responses · gpt-6.2-soladditional_tools 26.1k4 条 developer 32.8kenv历史Claude Code 2.1.330Messages · claude-opus-5-5tools 31.1ksystem 3 块 7.2k★历史system 消息 9.4k历史★Gemini CLI 0.70.0generateContentsystemInstruction 30.7ktools 16.0k历史—Qwen Code 0.28.3Chat Completionssystem 消息 22.4ktools 19.8k历史—★显式 cache_control 断点服务端隐式查找边界(文档规则)—请求里没有缓存标记,靠服务端隐式缓存数字是请求 JSON 里的字符数(k = 千)。Qwen Code 走 OpenAI 兼容接口,后端怎么缓存取决于服务商。
协议system prompt 放在哪工具声明放在哪缓存标记压缩后前缀
OpenCode 2.3.2Responsesinput[0] developer(11,325 字符)顶层 tools(12 个)无,靠隐式边界system 和工具不变,历史重写
Codex 0.171.0Responsesinput[1..4] 四条 developerinput[0] 的 additional_tools无内容相同,条目 id 全部换新
Claude Code 2.1.330Messages顶层 system 三块顶层 tools(12 个)system[1]、system[2]、最后一条消息system[0] 计费头变了,其余不变
Gemini CLI 0.70.0generateContent顶层 systemInstruction(30,747 字符)顶层 tools无,不用 cachedContent没有测
Qwen Code 0.28.3Chat Completionsmessages[0] system(22,432 字符)顶层 tools(10 个)无没有测

Codex 从来不发 instructions,顶层也没有 tools。它开了 incremental_tools,工具声明放进 input[0] 的一个 additional_tools 条目里,分 functions、clock、collaboration 三组,共 26,071 字符。后面是四条 developer 消息(第一条 26,194 字符),再是一条装环境信息的 user 消息,最后才是用户的话。这正好就是 #64542 说的「工具在开头的 additional_tools 里时,system prompt 紧跟其后」的排法。[2] 每一步和 codex exec resume 都是原样追加。0.170.0 给 GCP、0.171.0 给 Bedrock 默认打开了增量工具声明,0.171.0 还让压缩保留当前生效的附加上下文。[11][12]

Codex 0.171.0 的 additional_tools 布局

把 model_auto_compact_token_limit 设成 9,000 触发自动压缩后,Codex 重建了初始上下文:工具和 developer 消息的文本一字不差,但每个条目的 id(at_…、msg_…)都是新生成的。忽略 id 比,前 7 个条目完全一样。条目 id 会不会进入模型看到的 token 序列,本地判断不了。如果不进,压缩后的前缀就能接着用。另外,OpenAI 文档写明 additional_tools 条目不接受 prompt_cache_breakpoint,想给工具加显式断点只能加在它后面的 developer 消息上。[4]

Claude Code 走 Anthropic Messages。Anthropic 的缓存前缀顺序固定为 tools、system、messages,最多 4 个断点,断点往前回看 20 个块。[6] Claude Code 的 system 有三块:第一块 74 字符的 x-anthropic-billing-header: cc_version=2.1.330.581; cc_entrypoint=sdk-cli;,第二块 62 字符的身份声明,第三块 7,077 字符的正文。cache_control 打在第二、第三块和最后一条消息上,工具本身不打。环境信息不在 system 里,而是在第一条用户消息后面插了一条 role 为 system 的消息(9.4k 字符),请求头里带着 mid-conversation-tool-changes 之类的 beta 标记。工作目录、平台这类随环境变化的内容因此碰不到前面的 system prompt。

Claude Code 2.1.330 的缓存断点

手动 /compact 时,写摘要的请求在最后一条用户消息上追加「CRITICAL: Respond with TEXT ONLY…」,前缀完整保留。压缩后工具和 system 正文都没变,唯一变的是第一块计费头里的数字,从 .581 变成 .232,两次独立会话都是这两个值。自动压缩的情况相同:2.1.328 修了自动压缩沿用旧 system prompt 的问题,现在它和 /compact 一样重建 system prompt。[13] 这块计费头排在 system 的最前面,它是否算进缓存比较的前缀,只有用真实账号才能看出来。

Claude Code 2.1.330 自动压缩

测自动压缩时还撞见一条提示。让 mock 每步都报 150,000 输入 token、把 CLAUDE_AUTOCOMPACT_PCT_OVERRIDE 设成 10 之后,Claude Code 连续压缩几次就停下来,报「Autocompact is thrashing: the context refilled to the limit within 3 turns of the previous compact, 3 times in a row」。真实场景里遇到这句,多半是某个文件或工具输出太大。

Gemini CLI 把 30,747 字符的 systemInstruction 和 16,002 字符的工具声明放在顶层,每一步、包括 --resume latest 之后都不变,contents 原样追加,不用显式的 cachedContent,靠 Gemini 2.5 起默认开启的隐式缓存。Google 的文档建议把大段公共内容放在开头,它正是这样做的。[7] 另外每一轮开始前,它会先用 gemini-3.5-flash-lite 跑两次路由判断,system prompt 只有 2,346 字符,没有工具,是另一份独立的前缀。

Qwen Code 走 Chat Completions,system prompt 是 messages[0](22,432 字符),10 个工具在顶层,没有任何 cache_control,能不能缓存完全看后端。主循环在 --continue 之后也是原样追加。不过每轮结束后,它会跑一个「managed memory extraction」子 agent,system prompt 换成 14,683 字符的另一份,工具只有 5 个。这一步每次都从头算,不吃主循环的缓存。0.28.3 新增的 inject 模式会把新消息投到正在跑的那一轮,在下一批工具调用结束时读到,也是追加而不是改写。[14]

Gemini CLI 和 Qwen Code 的请求前缀

Goose 1.60.1 改了压缩提示词,去掉了 Claude 模型会拒绝的 <analysis> 草稿段,[15] 本期没有实测。

写 agent 时可以照做的几点

五家放在一起看,思路其实一样:不变的东西放最前面,会变的东西往后放,压缩只重写历史。OpenCode 2.3.2 和 Codex 用开头的 developer 消息,Claude Code 用 system 块加显式断点,Gemini 用顶层字段。大家都在保护同一段前缀,只是各自的 API 给的工具不同。

自己写 agent 的话,下面三点可以直接拿去用。第一,GPT-6.2 上别再把长 system prompt 放 instructions,这是一条「不报错的回归」,只能靠看 usage.cached_tokens 发现。第二,日期、工作目录、git 状态这类每次都可能变的信息,不要拼进 system prompt。Claude Code 把它放进第一条用户消息之后的 system 消息,Codex 放进一条单独的 user 消息,都是为了让前面那段保持原样。第三,标题生成、路由判断、记忆提取这类旁路调用各自有一份前缀,次数多了也是一笔账,值得单独看。

上一期写的是 OpenCode 2.3 把子 agent、超时命令和压缩改到后台。压缩到底省不省钱,可以拿 Claude Haiku 5.5 当 subagent 和压缩引擎的那套账 自己算。团队层面怎么用路由和治理管住 coding agent 的花费,见 企业 coding-agent 路由与治理。Claude Code 核心循环的整体结构见 Agent Harness 模式。

测了什么,没测什么

实测过的(Linux x64,所有 CLI 都指向本机 mock 服务,没有用任何真实账号):

本期安装的各 CLI 版本

  • OpenCode 2.3.1 和 2.3.2:openai/gpt-6.2-sol、xai/grok-4.7、自定义 Responses 路由三条路的 system prompt 位置和逐步前缀,V1 provider 块和 OpenRouter 走 Chat Completions 的情况,native 和 summary 两种自动压缩,TUI 里手动 /compact。
  • Codex CLI 0.171.0:自定义 provider(wire_api = "responses"),exec、exec resume 和一次自动压缩。
  • Claude Code 2.1.330:两轮对话、手动 /compact、自动压缩。
  • Gemini CLI 0.70.0 和 Qwen Code 0.28.3:一轮加一次续接会话。

没测的:

  • 任何真实计费和缓存命中。mock 只能看请求长什么样,本文里的 token 和命中数字全部来自 PR、issue 和官方文档。
  • /responses/compact 端点,以及 Copilot、Zen、Azure 的真实路由。OpenCode 内置的 OpenRouter provider 在本地走的是 Chat Completions,它平时是否用 Responses 没能确认。
  • Codex 在 GCP 和 Bedrock 上的增量工具声明,Codex 条目 id 是否影响缓存。
  • Claude Code 的计费头是否计入缓存前缀。
  • Gemini CLI 和 Qwen Code 的压缩,Qwen 的 inject 模式。
  • Goose 1.60.2、Aider 0.86.0、Kimi CLI 1.52.0、Cursor CLI、Amp 本期都没有跑。

参考来源

  1. OpenCode v2.3.2 changelog:https://opencode.ai/changelog/v2.3.2,GitHub release:https://github.com/anomalyco/opencode/releases/tag/v2.3.2 ↩
  2. OpenCode PR #64542,send the OpenAI system prompt as a developer message:https://github.com/anomalyco/opencode/pull/64542 ↩
  3. OpenCode PR #64544,send the system prompt as a developer message on every Responses route:https://github.com/anomalyco/opencode/pull/64544 ↩
  4. OpenAI 文档,Prompt caching:https://developers.openai.com/api/docs/guides/prompt-caching ↩
  5. OpenAI 文档,Using GPT-6.2:https://developers.openai.com/api/docs/guides/latest-model ↩
  6. Anthropic 文档,Prompt caching:https://platform.claude.com/docs/en/build-with-claude/prompt-caching ↩
  7. Google 文档,Gemini API context caching:https://ai.google.dev/gemini-api/docs/caching ↩
  8. LiteLLM,Cost Update: OpenAI’s GPT-6.2 caching change may increase input costs:https://docs.litellm.ai/blog/gpt-6-2-instructions-caching-incident ↩
  9. openai/codex issue #62312:https://github.com/openai/codex/issues/62312 ↩
  10. OpenCode issue #64783:https://github.com/anomalyco/opencode/issues/64783 ↩
  11. Codex rust-v0.170.0 release notes:https://github.com/openai/codex/releases/tag/rust-v0.170.0 ↩
  12. Codex rust-v0.171.0 release notes:https://github.com/openai/codex/releases/tag/rust-v0.171.0 ↩
  13. Claude Code v2.1.328 至 v2.1.330 release notes:https://github.com/anthropics/claude-code/releases/tag/v2.1.328、https://github.com/anthropics/claude-code/releases/tag/v2.1.330 ↩
  14. Qwen Code v0.28.3 release notes:https://github.com/QwenLM/qwen-code/releases/tag/v0.28.3 ↩
  15. Goose v1.60.1 release notes:https://github.com/block/goose/releases/tag/v1.60.1 ↩