本页是 OpenClaw Prompt Caching 的完整配置参考。Prompt Caching 允许模型提供商复用未改变的 Prompt 前缀，避免每轮对话都重新处理相同的系统指令，从而降低 Token 成本、加快响应速度。本页覆盖 cacheRetention 三级配置、contextPruning 修剪、心跳保温、各提供商行为差异和缓存诊断工具。

Prompt Caching 配置参考

Prompt Caching 让模型提供商可以复用未改变的 Prompt 前缀（通常是系统/开发者指令和其他稳定上下文），而不是每轮都重新处理。OpenClaw 将提供商的用量归一化为 cacheRead 和 cacheWrite（上游 API 暴露这些计数器时）。

为什么重要：降低 Token 成本、加快响应速度、让长期运行的会话更可预测。没有缓存时，即使大部分输入没有变化，重复的 Prompt 每轮都要付全额 Prompt 费用。

提供商参考文档：

Anthropic：Prompt Caching
OpenAI：Prompt Caching Guide

主要配置项

`cacheRetention`（全局默认、模型级、Agent 级）

设置全局默认缓存保留：

yaml

agents:
  defaults:
    params:
      cacheRetention: "long" # none | short | long

值	缓存时长	说明
`none`	不缓存	禁用 Prompt Caching
`short`	5 分钟	API Key 认证的 Anthropic 默认值
`long`	1 小时	长期缓存（需要直接 api.anthropic.com 或支持该功能的端点）

按模型覆盖：

yaml

agents:
  defaults:
    models:
      "anthropic/claude-opus-4-6":
        params:
          cacheRetention: "short"

按 Agent 覆盖：

yaml

agents:
  list:
    - id: "alerts"
      params:
        cacheRetention: "none"

配置优先级（从低到高）：

agents.defaults.params（全局默认）
agents.defaults.models["provider/model"].params（模型级覆盖）
agents.list[].params（Agent 级覆盖）

`contextPruning.mode: "cache-ttl"`

在缓存 TTL 窗口到期后修剪旧工具结果上下文，防止空闲后的请求重新缓存过大的历史：

yaml

agents:
  defaults:
    contextPruning:
      mode: "cache-ttl"
      ttl: "1h"

详见会话修剪。

心跳保温

心跳可以保持缓存窗口热态，减少空闲间隔后的重复缓存写入：

yaml

agents:
  defaults:
    heartbeat:
      every: "55m"

也支持按 Agent 配置心跳：agents.list[].heartbeat。

各提供商行为

Anthropic（直接 API）

支持 cacheRetention
使用 API Key auth profile 时，OpenClaw 默认为 Anthropic 模型添加 cacheRetention: "short"
Anthropic 原生 Messages 响应同时暴露 cache_read_input_tokens 和 cache_creation_input_tokens，因此可以显示 cacheRead 和 cacheWrite
cacheRetention: "short" 对应 5 分钟临时缓存；"long" 升级为 1 小时 TTL（仅限直接 api.anthropic.com 主机）

OpenAI（直接 API）

在支持的近期模型上自动缓存，无需注入块级缓存标记
OpenClaw 使用 prompt_cache_key 保持缓存路由跨轮稳定，仅在 cacheRetention: "long" 时注入 prompt_cache_retention: "24h"
OpenAI 响应通过 usage.prompt_tokens_details.cached_tokens 暴露缓存命中，OpenClaw 映射到 cacheRead
OpenAI 不暴露独立的缓存写入 token 计数器，所以 OpenAI 路径上 cacheWrite 始终为 0

Anthropic Vertex

与直接 Anthropic 同样支持 cacheRetention
cacheRetention: "long" 在 Vertex AI 端点映射到真正的 1 小时 Prompt Cache TTL
默认缓存保留与直接 Anthropic 一致

Amazon Bedrock

Anthropic Claude 模型（amazon-bedrock/*anthropic.claude*）支持显式 cacheRetention 透传
非 Anthropic Bedrock 模型在运行时强制为 cacheRetention: "none"

OpenRouter Anthropic 模型

对 openrouter/anthropic/* 模型，只有在请求仍指向已验证的 OpenRouter 路由时（openrouter.ai 上），OpenClaw 才注入 Anthropic cache_control 以提升缓存复用。指向任意 OpenAI 兼容代理 URL 时停止注入。

Google Gemini 直接 API

通过 cachedContentTokenCount 上报缓存命中，映射到 cacheRead
设置 cacheRetention 时，OpenClaw 自动为 Google AI Studio 运行创建、复用和刷新系统 Prompt 的 cachedContents 资源（无需预先手动创建）
仍可通过 params.cachedContent 传入预先存在的 Gemini 缓存内容句柄
这与 Anthropic/OpenAI 的 Prompt 前缀缓存不同——对 Gemini，OpenClaw 管理的是提供商原生 cachedContents 资源，而非在请求中注入缓存标记

Gemini CLI JSON 用量

Gemini CLI JSON 输出也可通过 stats.cached 展示缓存命中，OpenClaw 映射到 cacheRead
如果 CLI 未直接输出 stats.input，OpenClaw 从 stats.input_tokens - stats.cached 推导 input token 数
这只是用量归一化——不代表 OpenClaw 在为 Gemini CLI 注入 Anthropic/OpenAI 风格的缓存标记

系统 Prompt 缓存边界

OpenClaw 将系统 Prompt 分为稳定前缀和可变后缀，由内部缓存前缀边界分隔：

边界上方（工具定义、Skills 元数据、工作区文件等相对静态的内容）保持字节一致，跨轮不变
边界下方（如 HEARTBEAT.md、运行时时间戳等每轮变化的元数据）允许改变，不会让缓存前缀失效

关键设计：稳定的工作区项目上下文文件排在 HEARTBEAT.md 之前，使心跳轮动不会破坏稳定前缀。边界应用于 Anthropic、OpenAI、Google 和 CLI 传输层，所有支持的提供商都受益于相同的前缀稳定性。

OpenClaw 缓存稳定性守卫

OpenClaw 在请求到达提供商前还会对缓存敏感的载荷保持确定性：

MCP 工具目录在工具注册前按确定性顺序排序，避免 listTools() 顺序变化冲击工具块、破坏 Prompt Cache 前缀
包含持久化图片块的旧会话保留最近 3 轮完整已完成轮次；更早的已处理图片块可能替换为标记符，避免图片密集的跟进请求重复发送大型过期载荷

缓存诊断

`diagnostics.cacheTrace` 配置

yaml

diagnostics:
  cacheTrace:
    enabled: true
    filePath: "~/.openclaw/logs/cache-trace.jsonl"
    includeMessages: false
    includePrompt: false
    includeSystem: false

环境变量开关（一次性调试）

OPENCLAW_CACHE_TRACE=1：启用缓存追踪
OPENCLAW_CACHE_TRACE_FILE=/path/to/cache-trace.jsonl：覆盖输出路径
OPENCLAW_CACHE_TRACE_MESSAGES=0|1：切换完整消息载荷捕获
OPENCLAW_CACHE_TRACE_PROMPT=0|1：切换 Prompt 文本捕获
OPENCLAW_CACHE_TRACE_SYSTEM=0|1：切换系统 Prompt 捕获

调优示例

混合流量（推荐默认）

主 Agent 保持长期缓存基准，突发通知 Agent 禁用缓存：

yaml

agents:
  defaults:
    model:
      primary: "anthropic/claude-opus-4-6"
    models:
      "anthropic/claude-opus-4-6":
        params:
          cacheRetention: "long"
  list:
    - id: "research"
      default: true
      heartbeat:
        every: "55m"
    - id: "alerts"
      params:
        cacheRetention: "none"

成本优先基准

设置基准 cacheRetention: "short"
启用 contextPruning.mode: "cache-ttl"
只对确实受益于热缓存的 Agent 保持心跳低于 TTL

快速故障排查

现象	排查方向
大多数轮次 `cacheWrite` 高	检查系统 Prompt 中的可变输入，确认模型/提供商支持缓存设置
Anthropic `cacheWrite` 高	通常意味着缓存断点落在每次请求都变化的内容上
OpenAI `cacheRead` 低	确认稳定前缀在最前面，重复前缀至少 1024 tokens，且相同 `prompt_cache_key` 被跨轮复用
`cacheRetention` 无效果	确认模型键与 `agents.defaults.models["provider/model"]` 匹配
Bedrock Nova/Mistral 有缓存设置	预期会在运行时被强制为 `none`

常见问题

Q: cacheRetention 设为 long（1小时）和 short（5分钟）的费用差异在哪里？

A: Anthropic 对 cacheWrite（缓存写入）收费，但 cacheRead（缓存命中）比正常 input token 便宜得多。long 缓存减少了在同一小时内重复写入的次数，对于系统 Prompt 长且稳定的场景（如固定任务 Agent），用 long 可以显著减少缓存写入费用。对于内容变化快的会话，用 short 或 none 更合适。

Q: 我怎么知道缓存是否真的命中了？

A: 使用 /usage full 查看每条回复的 cacheRead 值，非零值表示有缓存命中。也可以启用 diagnostics.cacheTrace 获取详细的 JSONL 追踪日志，查看每轮的 cacheRead 和 cacheWrite 详情。

Q: 心跳（heartbeat）和 Prompt Caching 是什么关系？

A: 心跳定期向模型发送轻量级请求，目的是在缓存 TTL 到期之前"续期"，避免下一次真实请求重新付缓存写入费用。设置 heartbeat.every: "55m" 配合 cacheRetention: "long"（1小时 TTL）可以保持缓存持续命中。

Prompt Caching 配置参考 ​

主要配置项 ​

cacheRetention（全局默认、模型级、Agent 级） ​

contextPruning.mode: "cache-ttl" ​

心跳保温 ​

各提供商行为 ​

Anthropic（直接 API） ​

OpenAI（直接 API） ​

Anthropic Vertex ​

Amazon Bedrock ​

OpenRouter Anthropic 模型 ​

Google Gemini 直接 API ​

Gemini CLI JSON 用量 ​

系统 Prompt 缓存边界 ​

OpenClaw 缓存稳定性守卫 ​

缓存诊断 ​

diagnostics.cacheTrace 配置 ​

环境变量开关（一次性调试） ​

调优示例 ​

混合流量（推荐默认） ​

成本优先基准 ​

快速故障排查 ​

常见问题 ​

Prompt Caching 配置参考

主要配置项

`cacheRetention`（全局默认、模型级、Agent 级）

`contextPruning.mode: "cache-ttl"`

心跳保温

各提供商行为

Anthropic（直接 API）

OpenAI（直接 API）

Anthropic Vertex

Amazon Bedrock

OpenRouter Anthropic 模型

Google Gemini 直接 API

Gemini CLI JSON 用量

系统 Prompt 缓存边界

OpenClaw 缓存稳定性守卫

缓存诊断

`diagnostics.cacheTrace` 配置

环境变量开关（一次性调试）

调优示例

混合流量（推荐默认）

成本优先基准

快速故障排查

常见问题