> ## Documentation Index
> Fetch the complete documentation index at: https://docs.ruapi.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Claude 自动缓存：不打 cache_control 也按缓存价收费

> RuAPI 会给没打缓存标记的 Claude 请求自动打上 cache_control，重复发送的上下文按缓存价收。2026 年 11 月 18–20 日，RuAPI 打了标记的请求，输入 token 约九成从缓存读。

通过 RuAPI 调 Claude 时，如果请求里没打 `cache_control` 标记，RuAPI 的自动缓存会替你打上；两轮之间不超过 5 分钟，重复发送的上下文就按缓存价收，Claude Sonnet 5.5 读缓存只要普通输入价的 1/20。不用改任何设置。它和 Anthropic 说的「自动缓存」不是一回事：那是客户端自己在请求最外层打一个 `cache_control` 标记，RuAPI 的自动缓存主要在客户端一个标记都没打时起作用。

为什么需要这样：Claude 的提示缓存要客户端来开，请求里有 `cache_control` 标记，Anthropic 才会把重复发送的内容按缓存价收。Claude Code 等很多用原生 Anthropic 格式的工具会自己打；但很多工具用 OpenAI 兼容格式调 Claude 时不打，结果每多聊一轮，整段对话历史都按全价重新计费。

## 一段编程对话，用缓存和不用缓存差多少

编程工具每一轮都把整段对话重新发一遍：系统提示、文件内容、之前的回答和工具结果。对话越长，每一轮的输入就越大。

粗算一段 30 轮的对话，用 Claude Sonnet 5.5，上下文从 2 万 token 慢慢涨到 10 万，两轮之间都不超过 5 分钟。价格按[价格页](https://www.ruapi.ai/pricing?lng=zh-CN\&utm_source=docs\&utm_campaign=zh-claude-auto-cache) 2026 年 11 月 20 日的价，你账号的价格可能更低。

| | 30 轮的输入费用 |
| - | - |
| 不用缓存（输入 \$2.40／百万 token） | 约 \$4.30 |
| 用自动缓存（读 \$0.12、写 \$3.00／百万 token；第一轮按全价） | 约 \$0.55 |

Sonnet 5.5 读缓存的价格是普通输入的 1/20；写入比普通输入贵 25%，下一轮读到一次就回本。Opus 5.5 和 Fable 5.2 读缓存都是 \$0.24／百万 token，分别是普通输入的 1/20 和 1/40。

## 为什么用 OpenAI 兼容格式时常常没有缓存

* Anthropic 自己的 OpenAI 兼容接口不支持提示缓存（[Anthropic 文档](https://docs.anthropic.com/en/api/openai-sdk)，2026 年 10 月 15 日核对）。
* 很多编程工具和自己写的智能体，选「OpenAI Compatible」提供商时不发 `cache_control`。Cline 我们按源码核对过（2026 年 10 月 16 日）。这时就算网关支持缓存，也用不上。
* 我们自己的数据也一样：2026 年 11 月 4 日自动缓存上线前的 30 天里，用 OpenAI 格式调 Claude 的请求，没有一次读到缓存。

## RuAPI 怎么自动打标记

客户端一个标记都没打时，RuAPI 最多替你打 2 个标记，缓存有效期 5 分钟：

1. **系统提示（连同工具定义）**：同一个密钥、同一个模型 5 分钟内发过一模一样的，就打在系统提示上。这样新对话的第一轮、一连串单独的请求（比如批量处理），系统提示这部分也能从缓存读。
2. **最后一条用户消息或工具结果**：对话在接着聊、上一轮一般在 5 分钟内时打，整段历史就进了缓存。

写了缓存却连续 3 次不划算，就自动暂停，一般只停这段对话或这份系统提示 1 小时。另外按密钥和模型还有两道兜底：多付的钱累计封顶；前面的历史连续 3 次被改动时，还没读到过缓存的对话先不缓存历史。客户端自己打了标记，就按客户端的来；只有在它打了 1–2 个、离末尾很远、后面一大段没进缓存，又在 5 分钟内接着聊时，RuAPI 才在末尾补 1 个。

OpenAI 兼容格式（`/v1/chat/completions`）和原生格式（`/v1/messages`）都适用。完整规则见[提示缓存](https://docs.ruapi.ai/zh/prompt-caching.md#ruapi-自动缓存)。

## 自动缓存实际省了多少

2026 年 11 月 18 日晚自动缓存新版上线后，到 11 月 20 日早上：

* RuAPI 自动打了标记的 Claude 请求，输入 token 里约九成是从缓存读的。这是按 token 算的；写缓存要多付 25%，算成钱省下的比例会低一些。没打标记的请求（比如隔了很久才发的那一轮）不在这个统计里。
* 对话越长、两轮之间越少超过 5 分钟，省得越多。

## 在哪里看自己省了多少

* **控制台首页**：近 7 天确实省了钱时，首页会出现「缓存帮你省下」卡片，列出今天和近 7 天的金额，数据约每 5 分钟刷新。
* **使用日志**：点开一条记录，「缓存省下」这一行就是这次和不用缓存相比省下的钱，只有真的省了才显示；「缓存 Tokens」是从缓存读了多少。
* **接口返回**：OpenAI 格式看 `usage.prompt_tokens_details.cached_tokens`，Anthropic 格式看 `usage.cache_read_input_tokens`。

## 什么时候还是自己打标记更好

* **两轮之间常常隔很久**：自己打标记，用 1 小时缓存（`"ttl": "1h"`，写入价是普通输入的 2 倍）。
* **自己写代码调用**：OpenAI 兼容格式下，在最外层放一个 `cache_control` 就够了，RuAPI 会像 Anthropic 原生接口一样把它放到最后一条消息上。
* **编程工具里能选 Anthropic 提供商的，就选它**：原生格式下由工具自己管缓存，最稳。

代码示例见[提示缓存](https://docs.ruapi.ai/zh/prompt-caching.md)。

## 和 OpenRouter 有什么不同

按 OpenRouter 的文档，Claude 的缓存需要客户端自己打 `cache_control`：要么在最外层打一个（只在它文档列出的几家 Claude 服务商上有效），要么在内容块上最多打 4 个。文档里没有写「客户端不打时由它自动打」。

| | RuAPI | OpenRouter |
| - | - | - |
| 客户端没打标记的请求 | 自动打标记，按缓存价收 | 需要客户端自己打（文档未写自动打） |
| 客户端自己打了标记 | 按客户端的来；标记离末尾太远时补 1 个 | 按客户端的来 |

OpenRouter 的情况来自它的[官方文档](https://openrouter.ai/docs/features/prompt-caching)（2026 年 11 月 20 日核对）。

## 常见问题

> [accordion] 自动缓存要自己开吗？
>
> 不用，所有密钥都自动生效。

> [accordion] 自动缓存会不会反而多花钱？
>
> 写入缓存比普通输入贵 25%，所以 RuAPI 只在接下来大概率会读到时才打。写了缓存却不划算的情况连续出现，就自动暂停。

> [accordion] GPT、DeepSeek 也需要自动缓存吗？
>
> 不需要。它们的缓存会自动生效：请求开头有足够长的一段和上次相同，一般就会命中。

> [accordion] 自动缓存影响 Claude Code 吗？
>
> 不影响。Claude Code 自己会把标记打到最新一条消息上，RuAPI 不再加。

> [accordion] 为什么自动缓存没起作用？
>
> 常见原因：
>
> * 超过 5 分钟没有请求，缓存已经过期；
> * 这是新对话的第一轮：只有 5 分钟内用过的同一份系统提示和工具能读到缓存；
> * 客户端每轮都改前面的内容，比如在系统提示里加上当前时间；
> * 写了缓存却不划算的情况连续出现过，自动缓存暂停了；
> * 请求太短，没达到模型最小的缓存长度。

## 接下来

* [提示缓存](https://docs.ruapi.ai/zh/prompt-caching.md)：完整规则和代码示例。
* [Claude Code 和 Cline 怎么省钱](https://docs.ruapi.ai/zh/claude-code-cline-costs.md)：哪些操作会让缓存失效。
* [OpenAI 格式还是 Anthropic 格式](https://docs.ruapi.ai/zh/openai-vs-anthropic-format.md)：两种格式的区别。
* [价格](https://docs.ruapi.ai/zh/pricing.md)：各模型的输入、输出和缓存价。


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.