CPA 中转：主会话 1h 缓存保活、子代理 5m 缓存

OpenCode v2 + 自建 Claude 中转（CPA）上，缓存 TTL 到底谁说了算：思路、验证方法、配置和踩坑，留给以后的自己查

前言

先放结论：在 OpenCode v2 + CPA 这条链上，「主会话缓存 1 小时并保活、子代理缓存 5 分钟」我已经配出来了，配置层和中转层都实测过。但还没开一个新会话完整跑一遍真实对话，保活在真实环境里也只触发过一次，所以这篇是思路和步骤的笔记，不是「已稳定跑通」的战报。没验证的我单独放在「没验证 / 没做完」那一节。

我的目的很朴素：Claude Sonnet 5.5 当主会话，想让缓存尽量多被「读」到、少被重新「写」。办法是让主会话的提示缓存（把前面发过的长前缀存起来，下次只读不重算）活够久，并且快过期前有人帮它续一下；子代理活儿短，5 分钟的缓存就够。

先把几个简称说清楚，后面不再解释：

• CPA：CLIProxyAPI，我自建的 Claude 订阅中转，开了 Claude Code CLI 指纹模式。
• bili：billion-context，OpenCode 的上下文管理插件。
• omo slim：oh-my-opencode-slim，给 orchestrator、oracle 这些角色分别指定模型的插件。

• CPA 中转：主会话 1h 缓存保活、子代理 5m 缓存
  • 前言
  • 先看结论：最终配置要点
  • Warming 是什么：先读文档和源码，别靠猜
  • 协议路径：用 OpenAI 包设 TTL，等于没设
  • CPA 指纹：1 小时是中转「送」的，5 分钟要靠请求头换
  • 分流方案：同一个中转，配两个 provider
  • V2 原生写法：顺手把配置整体搬过来
  • 验证：配置层看什么，保活怎么盯
  • 停止保活：退出 TUI 不管用
  • 踩过的小坑
    • 旧会话报 Model unavailable
    • /model 选择器里分不清哪个是主会话那一路
    • 缓存匹配规则：这是理解，没有现场验证
  • 没验证 / 没做完
  • 结语
  • 参考与外链

先看结论：最终配置要点

计费倍率按 Anthropic 官方口径（我没另外核对）：5 分钟缓存写入 1.25×，1 小时缓存写入 2×，读取 0.1×（Sonnet/Opus 5.5 是 0.05×，Fable 是 0.025×）。所以 1 小时档写一次更贵，要靠后面反复「读」把它摊薄，这也是为什么它要配保活：写得贵，就得让它活久一点、读得多一点。

下面按我折腾的顺序写：先搞懂 Warming，再踩协议路径的坑，再发现 1 小时其实是中转「送」的，然后分流、改 V2 写法、验证、学会怎么停。

Warming 是什么：先读文档和源码，别靠猜

官方文档在这里：OpenCode Warming。我是对着文档和源码一起看的，下面是我整理出来的规则。

保活不会让缓存「不过期」，它是在缓存快过期之前自动再发一次请求，让计时从头开始。几条要记住的规则：

• 只作用于顶层会话，子代理会话被跳过。这是官方设计，源码里按 parentID 判断。所以子代理本来就不会被保活，5 分钟就是它的自然状态，不用管。注意这个「自然状态」依赖子代理那一路固定带 X-Claude-Code-Agent-Id；不带头的话，在我这台中转上会被抬成 1h（见下文「CPA 指纹」一节）。
• duration 是总窗口，从「最近一次真实请求发出时」开始算，保活本身不延长窗口。
• interval: auto 取缓存 TTL 的 0.9 倍，1 小时缓存就是 54 分钟一次。如果 0.9×ttl 已经 ≥ duration，auto 会直接跳过。
• 保活响应里缓存读取 < 缓存写入，就判定未命中，立刻停止后续保活。
• 配置优先级：模型的 settings.cache.warming > provider 级 > 顶层 warming。
• variant 里写的 cache 设置会被丢弃，所以没法用 variant 区分 TTL，只能靠不同的 provider。
• 每次真实请求、压缩、generate 都会重置窗口；保活本身、子代理请求、Esc 不会。
• 关闭要显式写 cache.warming: false。删掉字段会回退到上层默认，"0" 也不是有效的关闭写法。

我用 duration: 2 hours、interval: auto（54 分钟）算了一下：第 54、108 分钟各触发一次，第 162 分钟已经超出窗口，不触发。缓存最长撑到最后一次保活后再过 1 小时，即约 168 分钟（2 小时 48 分）。如果写成 duration: 1 hour，只会保 1 次。这是按规则推算的，不是我等满 168 分钟看到的。

协议路径：用 OpenAI 包设 TTL，等于没设

我最初的 provider 用的是 OpenAI 包（Responses 协议）。这条路径上，缓存设置只会变成请求里的 prompt_cache_options 字段，实测怎么写 TTL 都设不出 1 小时；翻日志，这一路清一色是 /v1/responses。这个字段具体在哪一层被丢弃，我没完全查清（读中转源码时看到它会剥掉该字段，但没有逐层验证）。

解决办法是换成 Anthropic 包（@opencode/ai/providers/anthropic），请求走 /v1/messages。

想控制 TTL，先确认请求实际走的是哪个协议端点，再去纠结配置写没写对。这一步我白白多绕了一圈。

CPA 指纹：1 小时是中转「送」的，5 分钟要靠请求头换

换成 Anthropic 包以后我又冒出一个疑问：设的 TTL 真的生效了吗？我干脆绕过 OpenCode，直接拿 Anthropic Messages 请求打中转，看响应 usage 里 cache_creation 的 5m/1h 拆分，一项一项试。

只有加上 X-Claude-Code-Agent-Id（Claude Code 用来标记「这是子代理」的头）以后，5m 才真的记成 5m。我接着读了 CPA 的源码印证：它在 CLI 指纹模式下，对「非子代理」请求，会给没写 ttl 的缓存标记补成 1h，还会重写首条用户消息、丢掉显式写的 TTL；带了子代理头就不补。

所以结论有点反直觉：

• 主会话 1h、子代理 5m 这套行为，是 CPA 的指纹逻辑给的。
• 不是 bili 干的，也不是 OpenCode 里 ttl 配置直接决定的。至少在我这台中转上，显式写 5m 也会被抬成 1h。
• 想要 5m，得靠加子代理头得到。

bili 这边我也查了配置：只开了 promptCache.routing（一个让缓存键保持稳定的开关），它不改 TTL，它自动打的缓存断点也不带 ttl。bili 自带的 cacheKeepalive 默认是关的，别和 OpenCode 的 Warming 同时开：两套机制互相不知情，不会去重。

自己复查可以照下面的思路做。这只是示意，地址和 key 换成你自己的，不是我当时的原命令：

# 示意：向中转的 /v1/messages 发一个带 cache_control 的长系统提示请求
curl -s https://<你的中转地址>/v1/messages \
  -H "x-api-key: <你的中转 key>" \
  -H "anthropic-version: 2023-06-01" \
  -H "content-type: application/json" \
  -d '{
    "model": "claude-sonnet-5-5",
    "max_tokens": 16,
    "system": [{
      "type": "text",
      "text": "<一段足够长的系统提示>",
      "cache_control": {"type": "ephemeral", "ttl": "5m"}
    }],
    "messages": [{"role": "user", "content": "hi"}]
  }'

同样的请求连发两次，看 usage 里：

• cache_creation.ephemeral_5m_input_tokens / ephemeral_1h_input_tokens：第一次写入记在了哪一档；
• cache_read_input_tokens：第二次有没有读到。

想验证「子代理头」的效果，就在第二组请求里多加一行 -H "X-Claude-Code-Agent-Id: opencode-subagent"，对比 5m/1h 两栏。

分流方案：同一个中转，配两个 provider

既然 5m 要靠请求头，主会话不能带头，子代理必须带头，那就同一个中转地址配两个 provider：

• 主会话那一路：缓存 ttl: 1h + 保活（interval: auto、duration: 2 hours），不加子代理头。
• 子代理那一路：缓存 ttl: 5m，不配保活，固定加请求头 X-Claude-Code-Agent-Id。

两个 provider 的模型集一致：sonnet-5-5、opus-5-5、fable-5-2、haiku-5-5。另外我在 Claude 模型上补了上下文/输出上限（context 1,000,000 / output 128,000）和能力声明（文本+图片输入，推理档位 low/medium/high/xhigh/max），否则缺省会回退到 200,000/32,000。

opencode.json（V2 写法，只摘缓存和分流相关的片段，其余省略；配置带注释，所以是 JSONC）：

{
  "providers": {
    // 主会话那一路：1h 缓存 + 保活，不带子代理头
    "claude_orz": {
      "package": "@opencode/ai/providers/anthropic",
      "name": "Claude 主会话 (1h)",
      "settings": {
        "baseURL": "https://<你的中转地址>/v1",
        "apiKey": "<你的中转 key>",
        "cache": {
          "ttl": "1h",
          "warming": { "interval": "auto", "duration": "2 hours" }
        }
      },
      "models": {
        "claude-sonnet-5-5": {
          "name": "Sonnet 5.5 · 主会话",
          "limit": { "context": 1000000, "output": 128000 },
          "capabilities": {
            "tools": true,
            "input": ["text", "image"],
            "output": ["text"],
            "reasoning": {
              "supported": true,
              "effort": ["low", "medium", "high", "xhigh", "max"]
            }
          }
        }
        // opus-5-5 / fable-5-2 / haiku-5-5 写法相同，省略
      }
    },

    // 子代理那一路：5m 缓存，无保活，固定带子代理头
    "claude_orz_sub": {
      "package": "@opencode/ai/providers/anthropic",
      "name": "Claude 子代理 (5m)",
      "headers": { "X-Claude-Code-Agent-Id": "opencode-subagent" },
      "settings": {
        "baseURL": "https://<你的中转地址>/v1",
        "apiKey": "<你的中转 key>",
        "cache": { "ttl": "5m" }
      },
      "models": {
        "claude-sonnet-5-5": {
          "name": "Sonnet 5.5 · 子代理",
          "limit": { "context": 1000000, "output": 128000 },
          "capabilities": { /* 同上，省略 */ }
        }
        // opus-5-5 / fable-5-2 / haiku-5-5 写法相同，省略
      }
    }

    // 另一个走 OpenAI 协议的 provider（explorer 等用），不参与缓存方案，省略
  }
}

oh-my-opencode-slim.json（只摘角色到模型的指向，skills、mcps、prompt 等省略）：

{
  "preset": "claude",
  "presets": {
    "claude": {
      "orchestrator": { "model": "claude_orz/claude-sonnet-5-5",     "variant": "high" },
      "oracle":       { "model": "claude_orz_sub/claude-opus-5-5",   "variant": "high" },
      "designer":     { "model": "claude_orz_sub/claude-sonnet-5-5", "variant": "high" },
      "fixer":        { "model": "claude_orz_sub/claude-sonnet-5-5", "variant": "high" },
      // explorer 这类轻量角色用另一个走 OpenAI 协议的中转，不参与缓存方案
      "explorer":     { "model": "openai_orz/gpt-6.1-sol",           "variant": "low" }
    }
  },
  "agents": {
    // fast-generic 同理，保持用 OpenAI 协议那一路
    "fast-generic": { "model": "openai_orz/gpt-6.1-sol", "variant": "low" }
  }
}

V2 原生写法：顺手把配置整体搬过来

分流的时候我顺手把整份配置改成了 OpenCode V2 原生写法。V2 会在内存里把 V1 写法规范化，不会改写你的源文件，也没有 opencode migrate 这类子命令，所以只能手改。对应关系：

我的流程是：改之前先备份；改完用能解析 JSONC 的解析器校验（配置里有注释，普通 JSON 解析会被注释卡住）；再做两项验收：

• opencode debug config：看有没有警告；
• opencode api model.list：看模型和它们的 settings。注意这个输出带凭据，要先用程序过滤，只留你要看的字段，别直接打在屏幕上。

验证：配置层看什么，保活怎么盯

模型层面我核对过：model.list 里主会话那一路 settings.cache 是 ttl 1h + warming auto / 2 hours，没有额外请求头；子代理那一路是 cache 5m + 头 X-Claude-Code-Agent-Id。

实时观察保活，去 OpenCode 日志目录下的 opencode.log，tail -F 并过滤关键字：

tail -F <OpenCode 日志目录>/opencode.log | grep -E "warming|failed to warm session"

关键句有四个：

• scheduled session warming：给某个会话排上了保活；
• warming session：这一次保活发出去了；
• stopped warming session after a cache miss：判定未命中，停止后续保活；
• failed to warm session：保活本身失败。

保活请求的特征：末尾带一条临时用户文本「保活，仅回复 OK」，没有专用请求头。另外，没有「列出当前活跃保活循环 / 剩余窗口」这样的接口，想知道还剩多久，只能自己按规则算。

停止保活：退出 TUI 不管用

这一条我经常忘。退出 TUI 停不了保活，定时器在后台服务里。只有删会话才会取消该会话的保活循环；Esc、归档、切模型、移目录、fork 都不会取消。

opencode session export <id> > backup.json   # 先导出备份
opencode session delete <id>                 # 删会话才会取消该会话的保活循环
opencode service status                      # 全局后台服务：status / restart / stop
opencode service restart
opencode service stop

配置里关闭则显式写 cache.warming: false。要注意，热加载后旧循环仍然带着旧参数，要等下次请求，或者 service restart 才会清掉。

如果想让某个会话按新配置重新判定，可以 opencode run --session <id> "…" 发一次请求，但必须先把 warming 关掉，否则这次请求本身会重置、延长窗口，多出一次真实请求。

踩过的小坑

旧会话报 Model unavailable

改完配置后，旧会话报 Model unavailable: <被我删掉的模型>。原因是会话里保存的模型优先于 agent 配置，而旧会话存的正好是我已经删掉的模型。处理：开新会话，或者把这个会话的模型改回现有的。

/model 选择器里分不清哪个是主会话那一路

选择器标题只显示模型的 name，provider 名只出现在分组标题或搜索态下，两个 provider 的同名模型很难区分。我的处理是：给 8 个 Claude 模型的 name 都加上「主会话 / 子代理」字样，provider 也起了带「1h」「5m」的 name。provider 没法在选择器里隐藏，把模型设成 disabled 会让 omo slim 引用不到，所以这条路走不通。

缓存匹配规则：这是理解，没有现场验证

以下是我对 Anthropic 官方规则的理解，没有现场验证，当「排查线索」用：

• 缓存按「前缀内容」匹配，不按会话。键是从头到某个断点的内容（工具定义 → 系统提示 → 历史消息）；同账号体系下，前缀逐字相同，别的会话也能命中。
• 一个会话的每个断点各留一份缓存。短前缀读不到长缓存；长请求可以往回找，命中更短的已缓存前缀（往回约 20 个内容块）。
• 工具、系统提示、历史（折叠、压缩、改写）或模型变了，变化位置之后就读不到。
• 缓存按账号隔离。中转如果在多个账号间轮换，换账号就读不到。我没查我的中转有几个账号。

没验证 / 没做完

• 还没开一个新会话完整跑一遍「主会话写入 1h、子代理 5m、请求走 /v1/messages」的真实对话。目前验证到的是配置层和中转层的实测。
• 保活在真实环境只触发过一次，且那一次被判为未命中、随即停止，原因还没查清。手上只有一条未证实的线索，属于推测：保活走的可能是另一条生成路径，omo slim 的系统提示/历史转换看起来只注册在正常请求的钩子上，保活不经过它；而闲置之后第一笔请求，折叠标识和系统提示似乎会被重新构造。这些都是读源码得到的印象，没有拿两次请求逐字对比过。保活能否稳定命中，我还在观察。
• CPA 对「带子代理头 + 显式 1h」会落到哪一档，没实测（我测的是带头时显式 5m 和不写 ttl，都是 5m）。
• prompt_cache_options 字段在中转上无效的原因，没查清。
• 中转有几个 Claude 账号、是否轮换，没查。

结语

回头看，这次实打实做成的是分流：主会话 1h 缓存加保活、子代理 5m 缓存，配置层和中转层都对上了。保活在真实对话里能不能稳定命中，我还在观察，详细没验证的清单不重复了，都在上面的「没验证 / 没做完」里。

下一步就是补第一条：开个新会话，主会话和子代理各跑几轮，对着 usage 看 5m/1h 两栏和读取量，再盯着日志看保活那一次到底会不会命中。如果你也在 CPA 上试过「带子代理头 + 显式 1h」，结果是哪一档，欢迎告诉我。

保活这东西最气人的一点，是它在后台悄悄转，而我连「现在有几个循环在转」都查不到。

参考与外链

• OpenCode Warming 官方文档：保活的窗口、间隔、未命中判定。
• billion-context（bili）：上下文管理插件与它自带的缓存保活。