プロンプトキャッシング

agents:
  defaults:
    models:
      "anthropic/claude-opus-4-6":
        params:
          cacheRetention: "short" # none | short | long

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

agents:
  defaults:
    contextPruning:
      mode: "cache-ttl"
      ttl: "1h"
```完全な動作については、[セッション プルーニング](/concepts/session-pruning) を参照してください。

### ハートビートの保温

ハートビートは、キャッシュ ウィンドウを暖かく保ち、アイドル ギャップ後のキャッシュ書き込みの繰り返しを減らすことができます。

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

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"

diagnostics:
  cacheTrace:
    enabled: true
    filePath: "~/.openclaw/logs/cache-trace.jsonl" # optional
    includeMessages: false # default true
    includePrompt: false # default true
    includeSystem: false # default true
```デフォルト:

- `filePath`: `$OPENCLAW_STATE_DIR/logs/cache-trace.jsonl`
- `includeMessages`: `true`
- `includePrompt`: `true`
- `includeSystem`: `true`

### 環境切り替え (1 回限りのデバッグ)

- `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` は、プロンプト テキストのキャプチャを切り替えます。
- `OPENCLAW_CACHE_TRACE_SYSTEM=0|1` は、システム プロンプト キャプチャを切り替えます。

### 何を検査するか

- キャッシュ トレース イベントは JSONL であり、`session:loaded`、`prompt:before`、`stream:context`、`session:after` などのステージングされたスナップショットが含まれます。
- ターンごとのキャッシュ トークンの影響は、`cacheRead` および `cacheWrite` を介して通常の使用状況に表示されます (たとえば、`/usage full` およびセッション使用状況の概要)。

## 簡単なトラブルシューティング

- ほとんどのターンで高い `cacheWrite` : 揮発性のシステム プロンプト入力をチェックし、モデル/プロバイダーがキャッシュ設定をサポートしていることを確認します。
- `cacheRetention` による影響なし: モデル キーが `agents.defaults.models["provider/model"]` と一致することを確認します。
- キャッシュ設定を使用した Bedrock Nova/Mistral リクエスト: ランタイム強制は `none` になることが予想されます。

関連ドキュメント:

- [人族](/providers/anthropic)
- [トークンの使用とコスト](/reference/token-use)
- [セッションのプルーニング](/concepts/session-pruning)
- [ゲートウェイ構成リファレンス](/gateway/configuration-reference)