OpenClaw v2026.3.13은 OpenAI 토큰 비용 절감을 위해 에이전트별 캐시 보존 설정을 추가합니다.

v2026.3.13의 변경 사항

OpenClaw 버전 2026.3.13은 에이전트별 항목에 대한 params.cacheRetention의 적절한 구성 유효성 검사를 추가했습니다. 이를 통해 openclaw.json 구성 파일에서 캐시 보존을 선언적으로 설정할 수 있습니다.

기본 캐시 동작의 문제점

OpenAI는 API에서 prompt_cache_retention: "24h"를 통해 확장된 프롬프트 캐시 보존(24시간)을 지원하며, 이는 기본 5-10분 대신 24시간 동안 프롬프트 접두사를 캐시에 유지합니다. 캐시된 입력 토큰은 50% 할인된 가격으로 청구됩니다.

10분보다 긴 하트비트 주기로 에이전트를 실행하는 경우(소스에서는 "기본적으로 모든 사람"이라고 언급), 캐시는 매 턴 사이에 완전히 차가워집니다. 이는 매 하트비트마다 전체 입력 컨텍스트에 대해 정가를 지불한다는 의미입니다.

소스에서는 60-90분마다 하트비트를 실행하는 GPT-5.2 기반 15개 에이전트 설정을 설명하며, 모든 하트비트가 보장된 콜드 스타트였습니다. 시스템 프롬프트, 부트스트랩 컨텍스트, HEARTBEAT.md, AGENTS.md, SOUL.md, 도구 정의 등 모든 것이 캐시가 하트비트 간격에 만료되어 매 주기마다 정가로 재전송되었습니다.

구성 방법

이제 openclaw.json에서 캐시 보존을 설정할 수 있습니다:

{
  "agents": {
    "list": [
      {
        "agentId": "my-agent",
        "params": {
          "cacheRetention": "long"
        }
      }
    ]
  }
}

"long" 값은 pi-ai 라이브러리를 통해 OpenAI의 prompt_cache_retention: "24h"에 매핑됩니다.

중요한 주의사항: 런타임 패치 필요

OpenClaw의 resolveCacheRetention() 함수는 기본적으로 OpenAI 제공자를 차단하는 가드 절을 포함하고 있습니다. Anthropic과 Bedrock만 허용합니다. 따라서 구성이 설정되어 있어도 값이 API에 도달하기 전에 필터링됩니다.

작동시키려면 이슈 #27515의 런타임 패치가 필요합니다. 이 패치는 가드 절의 허용된 제공자 목록에 OpenAI를 추가합니다. 구성과 패치 모두 없으면 아무 일도 일어나지 않습니다.

소스 작성자는 패치를 적용한 지 몇 주가 지났지만 구성 값을 설정하지 않았다고 언급했습니다. 즉, 패치가 extraParams?.cacheRetention !== void 0를 확인하고 undefined를 받아 여전히 OpenAI를 차단하고 있었습니다. 패치는 구성 없이는 아무 역할도 하지 않았습니다.

비용 절감 가능성

15개의 에이전트가 하트비트를 실행하며, 각각 턴당 약 128K-170K 입력 토큰을 전송하는 경우:

• 24시간 캐시 없음: 매 턴마다 전체 가격으로 입력 토큰의 100%를 지불합니다. 캐시는 하트비트 간 약 60-90분 간격에 소멸됩니다.
• 24시간 캐시 있음: 안정적인 접두사(시스템 프롬프트, 에이전트 구성, 도구 정의 — 일반적으로 입력의 80-90%)가 하트비트 간에 캐시에 유지됩니다. 해당 토큰은 반값으로 청구됩니다.

전체 업무일 동안 15개의 에이전트를 실행하는 시스템에서는 대량의 입력 토큰이 정가에서 반값으로 전환되는 하루에 수백 번의 하트비트 주기가 발생합니다. 입력 비용 감소가 빠르게 누적됩니다.