Prompt 缓存

Prompt Caching（提示缓存）是一项减少 LLM API 重复计算成本的优化技术。它通过缓存系统提示词等不变部分，避免每次请求都重新处理相同内容。

工作原理

当 Agent 多次调用同一模型时，系统提示词（System Prompt）、工具定义等内容在每次请求中都是相同的。Prompt 缓存将这些不变部分的计算结果进行缓存，后续请求直接复用。

首次请求:
[系统提示词 2000 Token] + [对话历史] + [用户消息] → 全量计算

后续请求（命中缓存）:
[系统提示词 ← 缓存命中] + [对话历史] + [用户消息] → 仅计算新内容

成本节省

Prompt 缓存可节省系统提示词部分 50-90% 的费用，对使用长系统提示词的场景效果显著。

支持的服务商

服务商	缓存支持	缓存方式	折扣
Anthropic（Claude）	✅ 原生支持	前缀匹配	缓存 Token 90% 折扣
OpenAI（GPT-4o）	✅ 自动缓存	前缀匹配	缓存 Token 50% 折扣
DeepSeek	✅ 支持	前缀匹配	缓存 Token 折扣
通义千问	❌ 暂不支持	—	—

缓存机制详解

前缀哈希匹配

服务商对请求的前缀部分计算哈希值：

请求 1: [System Prompt A][History 1][User Msg 1]
请求 2: [System Prompt A][History 2][User Msg 2]
                ↑
        相同前缀 → 缓存命中

Anthropic 缓存规则

• 缓存最小单位：1024 Token
• 缓存有效期：5 分钟（自上次使用起）
• 缓存写入成本：比正常 Token 价格高 25%
• 缓存读取成本：比正常 Token 价格低 90%

OpenAI 缓存规则

• 自动缓存，无需额外配置
• 缓存最小单位：1024 Token
• 缓存读取折扣：50%
• 缓存在低流量时可能被清除

配置

基础配置

# openclaw.config.yaml
model:
  promptCaching:
    enabled: true

Anthropic 高级配置

providers:
  anthropic:
    caching:
      enabled: true
      breakpoints:
        - after: 'system'     # 系统提示词后设置缓存断点
        - after: 'tools'      # 工具定义后设置缓存断点

OpenClaw 会自动在系统提示词中注入 cache_control 标记：

{
  "system": [
    {
      "type": "text",
      "text": "你是一个专业助手...",
      "cache_control": { "type": "ephemeral" }
    }
  ]
}

缓存命中率

查看缓存命中率统计：

# 查看缓存统计
openclaw usage cache-stats

# 示例输出
# Cache Hit Rate: 87.3%
# Tokens Saved: 1,234,567
# Cost Saved: $12.34

提高命中率的策略

1. 保持系统提示词稳定 — 频繁修改会导致缓存失效
2. 合理排列提示词 — 将稳定部分放在前面
3. 保持请求频率 — 低频率可能导致缓存过期
4. 使用固定工具集 — 工具定义变更会破坏缓存

缓存失效场景

以下情况会导致缓存失效：修改系统提示词、变更工具列表、切换模型版本、超过缓存有效期。

成本节省计算

假设一个 Agent 每天处理 1000 条消息，系统提示词 2000 Token：

场景	每日 Token 消耗	每日费用（GPT-4o）
无缓存	2,000,000 输入 Token	$5.00
有缓存（90% 命中）	200,000 全价 + 1,800,000 半价	$2.75
节省		$2.25 / 天

长期收益

对于生产环境中的高频调用场景，Prompt 缓存每月可节省数百到数千美元的 API 费用。