Lưu lời nhắc vào bộ nhớ đệm

Documentation Index

Fetch the complete documentation index at: https://docs.openclaw.ai/llms.txt

Use this file to discover all available pages before exploring further.

• Lưu cache prompt của Anthropic: https://platform.claude.com/docs/en/build-with-claude/prompt-caching
• Lưu cache prompt của OpenAI: https://developers.openai.com/api/docs/guides/prompt-caching
• Header API và ID yêu cầu của OpenAI: https://developers.openai.com/api/reference/overview
• ID yêu cầu và lỗi của Anthropic: https://platform.claude.com/docs/en/api/errors

​

Các nút điều chỉnh chính

​

cacheRetention (mặc định toàn cục, mô hình, và theo agent)

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

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

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

1. agents.defaults.params (mặc định toàn cục — áp dụng cho mọi mô hình)
2. agents.defaults.models["provider/model"].params (ghi đè theo mô hình)
3. agents.list[].params (ID agent khớp; ghi đè theo khóa)

​

contextPruning.mode: "cache-ttl"

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

​

Giữ ấm Heartbeat

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

​

Hành vi nhà cung cấp

​

Anthropic (API trực tiếp)

• cacheRetention được hỗ trợ.
• Với hồ sơ xác thực bằng khóa API Anthropic, OpenClaw khởi tạo cacheRetention: "short" cho tham chiếu mô hình Anthropic khi chưa đặt.
• Phản hồi Messages gốc của Anthropic cung cấp cả cache_read_input_tokens và cache_creation_input_tokens, nên OpenClaw có thể hiển thị cả cacheRead và cacheWrite.
• Với yêu cầu Anthropic gốc, cacheRetention: "short" ánh xạ tới cache tạm thời mặc định 5 phút, và cacheRetention: "long" nâng cấp lên TTL 1 giờ chỉ trên các máy chủ api.anthropic.com trực tiếp.

​

OpenAI (API trực tiếp)

• Lưu cache prompt là tự động trên các mô hình gần đây được hỗ trợ. OpenClaw không cần chèn marker cache cấp khối.
• OpenClaw dùng prompt_cache_key để giữ định tuyến cache ổn định qua các lượt và chỉ dùng prompt_cache_retention: "24h" khi cacheRetention: "long" được chọn trên các máy chủ OpenAI trực tiếp.
• Các nhà cung cấp Completions tương thích OpenAI chỉ nhận prompt_cache_key khi cấu hình mô hình của họ đặt rõ compat.supportsPromptCacheKey: true; cacheRetention: "none" vẫn chặn nó.
• Phản hồi OpenAI cung cấp token prompt đã lưu cache qua usage.prompt_tokens_details.cached_tokens (hoặc input_tokens_details.cached_tokens trên sự kiện Responses API). OpenClaw ánh xạ giá trị đó thành cacheRead.
• OpenAI không cung cấp bộ đếm token ghi cache riêng, nên cacheWrite giữ nguyên 0 trên các đường dẫn OpenAI ngay cả khi nhà cung cấp đang làm ấm cache.
• OpenAI trả về các header hữu ích cho truy vết và giới hạn tốc độ như x-request-id, openai-processing-ms, và x-ratelimit-*, nhưng việc tính toán cache hit nên lấy từ payload sử dụng, không phải từ header.
• Trong thực tế, OpenAI thường hoạt động như cache tiền tố ban đầu hơn là tái sử dụng toàn bộ lịch sử di động kiểu Anthropic. Các lượt văn bản tiền tố dài ổn định có thể đạt gần mức ổn định 4864 token đã lưu cache trong các phép thăm dò live hiện tại, trong khi transcript nhiều công cụ hoặc kiểu MCP thường ổn định gần 4608 token đã lưu cache ngay cả khi lặp lại chính xác.

​

Anthropic Vertex

• Các mô hình Anthropic trên Vertex AI (anthropic-vertex/*) hỗ trợ cacheRetention giống như Anthropic trực tiếp.
• cacheRetention: "long" ánh xạ tới TTL cache prompt 1 giờ thật trên endpoint Vertex AI.
• Thời hạn giữ cache mặc định cho anthropic-vertex khớp với mặc định Anthropic trực tiếp.
• Yêu cầu Vertex được định tuyến qua shaping cache nhận biết ranh giới để việc tái sử dụng cache luôn khớp với những gì nhà cung cấp thật sự nhận.

​

Amazon Bedrock

• Tham chiếu mô hình Anthropic Claude (amazon-bedrock/*anthropic.claude*) hỗ trợ truyền qua cacheRetention rõ ràng.
• Các mô hình Bedrock không phải Anthropic bị buộc thành cacheRetention: "none" tại runtime.

​

Mô hình OpenRouter

​

Nhà cung cấp khác

​

API trực tiếp Google Gemini

• Transport Gemini trực tiếp (api: "google-generative-ai") báo cáo cache hit qua cachedContentTokenCount upstream; OpenClaw ánh xạ giá trị đó thành cacheRead.
• Khi cacheRetention được đặt trên mô hình Gemini trực tiếp, OpenClaw tự động tạo, tái sử dụng, và làm mới tài nguyên cachedContents cho prompt hệ thống trên các lần chạy Google AI Studio. Điều này nghĩa là bạn không còn cần tạo trước một handle cached-content theo cách thủ công.
• Bạn vẫn có thể truyền một handle cached-content Gemini đã tồn tại qua params.cachedContent (hoặc params.cached_content cũ) trên mô hình đã cấu hình.
• Điều này tách biệt với cache tiền tố prompt của Anthropic/OpenAI. Với Gemini, OpenClaw quản lý một tài nguyên cachedContents gốc của nhà cung cấp thay vì chèn marker cache vào yêu cầu.

​

Mức sử dụng JSON Gemini CLI

• Đầu ra JSON của Gemini CLI cũng có thể hiển thị cache hit qua stats.cached; OpenClaw ánh xạ giá trị đó thành cacheRead.
• Nếu CLI bỏ qua giá trị stats.input trực tiếp, OpenClaw suy ra token đầu vào từ stats.input_tokens - stats.cached.
• Đây chỉ là chuẩn hóa mức sử dụng. Nó không có nghĩa OpenClaw đang tạo marker cache prompt kiểu Anthropic/OpenAI cho Gemini CLI.

​

Ranh giới cache prompt hệ thống

• Các tệp ngữ cảnh dự án workspace ổn định được sắp xếp trước HEARTBEAT.md để thay đổi Heartbeat không phá tiền tố ổn định.
• Ranh giới được áp dụng trên các họ Anthropic, họ OpenAI, Google, và shaping transport CLI để mọi nhà cung cấp được hỗ trợ đều hưởng lợi từ cùng độ ổn định tiền tố.
• Các yêu cầu Codex Responses và Anthropic Vertex được định tuyến qua shaping cache nhận biết ranh giới để việc tái sử dụng cache luôn khớp với những gì nhà cung cấp thật sự nhận.
• Dấu vân tay prompt hệ thống được chuẩn hóa (khoảng trắng, kết thúc dòng, ngữ cảnh do hook thêm, thứ tự capability runtime) để các prompt không đổi về mặt ngữ nghĩa dùng chung KV/cache qua các lượt.

​

Bộ bảo vệ ổn định cache của OpenClaw

• Catalog công cụ MCP đi kèm được sắp xếp xác định trước khi đăng ký công cụ, để thay đổi thứ tự listTools() không làm biến động khối công cụ và phá tiền tố cache prompt.
• Các phiên cũ có khối ảnh được lưu giữ sẽ giữ nguyên 3 lượt hoàn tất gần đây nhất; các khối ảnh cũ hơn đã xử lý có thể được thay bằng marker để các lượt theo sau nhiều ảnh không tiếp tục gửi lại payload cũ lớn.

​

Mẫu tinh chỉnh

​

Lưu lượng hỗn hợp (mặc định khuyến nghị)

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"

​

Baseline ưu tiên chi phí

• Đặt baseline cacheRetention: "short".
• Bật contextPruning.mode: "cache-ttl".
• Giữ Heartbeat thấp hơn TTL của bạn chỉ cho các agent hưởng lợi từ cache ấm.

​

Chẩn đoán cache

​

Kiểm thử hồi quy live

• src/agents/live-cache-regression.live.test.ts
• src/agents/live-cache-regression-baseline.ts

OPENCLAW_LIVE_TEST=1 OPENCLAW_LIVE_CACHE_TEST=1 pnpm test:live:cache

​

Kỳ vọng live Anthropic

• Kỳ vọng các lần ghi warmup rõ ràng qua cacheWrite.
• Kỳ vọng tái sử dụng gần như toàn bộ lịch sử trên các lượt lặp lại vì cache control của Anthropic đẩy breakpoint cache tiến qua cuộc hội thoại.
• Các assertion live hiện tại vẫn dùng ngưỡng tỷ lệ hit cao cho các đường dẫn ổn định, công cụ, và ảnh.

​

Kỳ vọng live OpenAI

• Chỉ kỳ vọng cacheRead. cacheWrite vẫn là 0.
• Xem việc tái sử dụng cache qua các lượt lặp lại là một ngưỡng ổn định theo từng provider, không phải là tái sử dụng toàn bộ lịch sử di chuyển kiểu Anthropic.
• Các xác nhận live hiện tại dùng các kiểm tra ngưỡng sàn thận trọng, được suy ra từ hành vi live đã quan sát trên gpt-5.4-mini:
  • tiền tố ổn định: cacheRead >= 4608, tỷ lệ trúng >= 0.90
  • bản ghi công cụ: cacheRead >= 4096, tỷ lệ trúng >= 0.85
  • bản ghi hình ảnh: cacheRead >= 3840, tỷ lệ trúng >= 0.82
  • bản ghi kiểu MCP: cacheRead >= 4096, tỷ lệ trúng >= 0.85

• tiền tố ổn định: cacheRead=4864, tỷ lệ trúng 0.966
• bản ghi công cụ: cacheRead=4608, tỷ lệ trúng 0.896
• bản ghi hình ảnh: cacheRead=4864, tỷ lệ trúng 0.954
• bản ghi kiểu MCP: cacheRead=4608, tỷ lệ trúng 0.891

• Anthropic cung cấp các điểm ngắt cache rõ ràng và tái sử dụng lịch sử hội thoại di chuyển.
• Cache prompt của OpenAI vẫn nhạy với tiền tố chính xác, nhưng tiền tố có thể tái sử dụng hiệu quả trong lưu lượng Responses live có thể đạt ngưỡng ổn định sớm hơn toàn bộ prompt.
• Vì vậy, so sánh Anthropic và OpenAI bằng một ngưỡng phần trăm duy nhất giữa các provider sẽ tạo ra hồi quy giả.

​

Cấu hình diagnostics.cacheTrace

diagnostics:
  cacheTrace:
    enabled: true
    filePath: "~/.openclaw/logs/cache-trace.jsonl" # tùy chọn
    includeMessages: false # mặc định true
    includePrompt: false # mặc định true
    includeSystem: false # mặc định true

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

​

Công tắc env (gỡ lỗi một lần)

• OPENCLAW_CACHE_TRACE=1 bật truy vết cache.
• OPENCLAW_CACHE_TRACE_FILE=/path/to/cache-trace.jsonl ghi đè đường dẫn đầu ra.
• OPENCLAW_CACHE_TRACE_MESSAGES=0|1 bật/tắt ghi lại toàn bộ payload thông điệp.
• OPENCLAW_CACHE_TRACE_PROMPT=0|1 bật/tắt ghi lại văn bản prompt.
• OPENCLAW_CACHE_TRACE_SYSTEM=0|1 bật/tắt ghi lại system prompt.

​

Những gì cần kiểm tra

• Sự kiện truy vết cache là JSONL và bao gồm các ảnh chụp nhanh theo giai đoạn như session:loaded, prompt:before, stream:context và session:after.
• Tác động token cache theo từng lượt hiển thị trong các bề mặt sử dụng thông thường qua cacheRead và cacheWrite (ví dụ /usage full và tóm tắt sử dụng phiên).
• Với Anthropic, kỳ vọng có cả cacheRead và cacheWrite khi cache đang hoạt động.
• Với OpenAI, kỳ vọng có cacheRead khi trúng cache và cacheWrite vẫn là 0; OpenAI không công bố trường token ghi cache riêng.
• Nếu cần truy vết request, hãy ghi log ID request và header giới hạn tốc độ riêng biệt với chỉ số cache. Đầu ra cache-trace hiện tại của OpenClaw tập trung vào hình dạng prompt/phiên và mức sử dụng token đã chuẩn hóa thay vì header phản hồi provider thô.

​

Khắc phục sự cố nhanh

• cacheWrite cao ở hầu hết các lượt: kiểm tra các đầu vào system-prompt dễ thay đổi và xác minh model/provider hỗ trợ cài đặt cache của bạn.
• cacheWrite cao trên Anthropic: thường có nghĩa là điểm ngắt cache đang nằm trên nội dung thay đổi theo từng request.
• cacheRead thấp trên OpenAI: xác minh tiền tố ổn định nằm ở đầu, tiền tố lặp lại có ít nhất 1024 token và cùng một prompt_cache_key được tái sử dụng cho các lượt nên dùng chung cache.
• cacheRetention không có tác dụng: xác nhận khóa model khớp với agents.defaults.models["provider/model"].
• Request Bedrock Nova/Mistral có cài đặt cache: dự kiến runtime sẽ ép thành none.

• Anthropic
• Mức dùng token và chi phí
• Cắt tỉa phiên
• Tài liệu tham chiếu cấu hình Gateway

​

Liên quan

• Mức dùng token và chi phí
• Mức dùng API và chi phí