English简体中文繁體中文日本語EspañolPortuguês (BR)한국어DeutschFrançaisالعربيةItalianoTiếng ViệtNederlandsTürkçeУкраїнськаBahasa IndonesiaPolskiفارسیไทย

Technical reference

토큰 사용량 및 비용

OpenClaw는 문자가 아니라 토큰을 추적합니다. 토큰은 모델마다 다르지만, 대부분의 OpenAI 스타일 모델은 영어 텍스트에서 토큰당 평균 약 4자입니다.

시스템 프롬프트가 구성되는 방식

OpenClaw는 실행할 때마다 자체 시스템 프롬프트를 조립합니다. 여기에는 다음이 포함됩니다.

  • 도구 목록 + 짧은 설명
  • Skills 목록(메타데이터만 포함, 지침은 필요할 때 read로 로드됨). 압축된 Skills 블록은 skills.limits.maxSkillsPromptChars로 제한되며, 선택적으로 에이전트별 재정의를 agents.list[].skillsLimits.maxSkillsPromptChars에서 설정할 수 있습니다.
  • 자체 업데이트 지침
  • 작업공간 + 부트스트랩 파일(AGENTS.md, SOUL.md, TOOLS.md, IDENTITY.md, USER.md, HEARTBEAT.md, BOOTSTRAP.md(새로운 경우), 그리고 존재하는 경우 MEMORY.md). 소문자 루트 memory.md는 주입되지 않으며, MEMORY.md와 함께 있을 때 openclaw doctor --fix의 레거시 복구 입력으로만 사용됩니다. 큰 파일은 agents.defaults.bootstrapMaxChars(기본값: 12000)로 잘리며, 전체 부트스트랩 주입은 agents.defaults.bootstrapTotalMaxChars(기본값: 60000)로 제한됩니다. memory/*.md 일일 파일은 일반 부트스트랩 프롬프트의 일부가 아니며, 일반 턴에서는 메모리 도구를 통해 필요할 때만 사용됩니다. 다만 재설정/시작 모델 실행은 첫 턴에 한해 최근 일일 메모리가 포함된 일회성 시작 컨텍스트 블록을 앞에 붙일 수 있습니다. 단순 채팅 /new 및 /reset 명령은 모델을 호출하지 않고 확인됩니다. 시작 서문은 agents.defaults.startupContext로 제어됩니다.
  • 시간(UTC + 사용자 시간대)
  • 응답 태그 + Heartbeat 동작
  • 런타임 메타데이터(호스트/OS/모델/사고)

전체 세부 내용은 시스템 프롬프트를 참고하세요.

컨텍스트 창에 포함되는 것

모델이 받는 모든 항목은 컨텍스트 한도에 포함됩니다.

  • 시스템 프롬프트(위에 나열된 모든 섹션)
  • 대화 기록(사용자 + 어시스턴트 메시지)
  • 도구 호출 및 도구 결과
  • 첨부 파일/트랜스크립트(이미지, 오디오, 파일)
  • Compaction 요약 및 가지치기 산출물
  • 제공자 래퍼 또는 안전 헤더(보이지 않지만 여전히 계산됨)

일부 런타임 사용량이 큰 표면에는 자체 명시적 한도가 있습니다.

  • agents.defaults.contextLimits.memoryGetMaxChars
  • agents.defaults.contextLimits.memoryGetDefaultLines
  • agents.defaults.contextLimits.toolResultMaxChars
  • agents.defaults.contextLimits.postCompactionMaxChars

에이전트별 재정의는 agents.list[].contextLimits 아래에 있습니다. 이러한 조정값은 제한된 런타임 발췌와 런타임 소유 주입 블록을 위한 것입니다. 부트스트랩 한도, 시작 컨텍스트 한도, Skills 프롬프트 한도와는 별개입니다.

이미지의 경우, OpenClaw는 제공자 호출 전에 트랜스크립트/도구 이미지 페이로드를 다운스케일합니다. 이를 조정하려면 agents.defaults.imageMaxDimensionPx(기본값: 1200)를 사용하세요.

  • 낮은 값은 보통 비전 토큰 사용량과 페이로드 크기를 줄입니다.
  • 높은 값은 OCR/UI 중심 스크린샷에서 더 많은 시각적 세부 정보를 보존합니다.

실용적인 세부 분석(주입된 파일별, 도구, Skills, 시스템 프롬프트 크기)을 보려면 /context list 또는 /context detail을 사용하세요. 컨텍스트를 참고하세요.

현재 토큰 사용량을 확인하는 방법

채팅에서 다음을 사용하세요.

  • /status → 세션 모델, 컨텍스트 사용량, 마지막 응답 입력/출력 토큰, 예상 비용(API 키만 해당)이 포함된 이모지가 풍부한 상태 카드.
  • /usage off|tokens|full → 모든 응답에 응답별 사용량 바닥글을 추가합니다.
    • 세션별로 유지됩니다(responseUsage로 저장됨).
    • OAuth 인증은 비용을 숨깁니다(토큰만 표시).
  • /usage cost → OpenClaw 세션 로그에서 로컬 비용 요약을 표시합니다.

기타 표면:

  • TUI/Web TUI: /status + /usage가 지원됩니다.
  • CLI: openclaw status --usage 및 openclaw channels list는 정규화된 제공자 할당량 창(X% left, 응답별 비용 아님)을 표시합니다. 현재 사용량 창 제공자: Anthropic, GitHub Copilot, Gemini CLI, OpenAI Codex, MiniMax, Xiaomi, z.ai.

사용량 표면은 표시 전에 일반적인 제공자 네이티브 필드 별칭을 정규화합니다. OpenAI 계열 Responses 트래픽의 경우, 여기에는 input_tokens / output_tokens와 prompt_tokens / completion_tokens가 모두 포함되므로, 전송 방식별 필드 이름은 /status, /usage, 세션 요약을 변경하지 않습니다. Gemini CLI JSON 사용량도 정규화됩니다. 응답 텍스트는 response에서 오며, stats.cached는 cacheRead에 매핑되고, CLI가 명시적 stats.input 필드를 생략하면 stats.input_tokens - stats.cached가 사용됩니다. 네이티브 OpenAI 계열 Responses 트래픽의 경우 WebSocket/SSE 사용량 별칭도 같은 방식으로 정규화되며, total_tokens가 없거나 0이면 총합은 정규화된 입력 + 출력으로 대체됩니다. 현재 세션 스냅샷이 희소한 경우, /status와 session_status는 가장 최근 트랜스크립트 사용량 로그에서 토큰/캐시 카운터와 활성 런타임 모델 레이블도 복구할 수 있습니다. 기존의 0이 아닌 라이브 값은 여전히 트랜스크립트 대체 값보다 우선하며, 저장된 총합이 없거나 더 작은 경우 더 큰 프롬프트 중심 트랜스크립트 총합이 우선할 수 있습니다. 제공자 할당량 창의 사용량 인증은 가능한 경우 제공자별 훅에서 가져옵니다. 그렇지 않으면 OpenClaw는 인증 프로필, 환경 변수 또는 설정에서 일치하는 OAuth/API 키 자격 증명으로 대체합니다. 어시스턴트 트랜스크립트 항목은 활성 모델에 가격이 설정되어 있고 제공자가 사용량 메타데이터를 반환하는 경우 usage.cost를 포함하여 동일한 정규화된 사용량 형태를 유지합니다. 이는 라이브 런타임 상태가 사라진 뒤에도 /usage cost와 트랜스크립트 기반 세션 상태에 안정적인 소스를 제공합니다.

OpenClaw는 제공자 사용량 집계를 현재 컨텍스트 스냅샷과 별도로 유지합니다. 제공자 usage.total에는 캐시된 입력, 출력, 여러 도구 루프 모델 호출이 포함될 수 있으므로, 비용 및 텔레메트리에는 유용하지만 라이브 컨텍스트 창을 과대평가할 수 있습니다. 컨텍스트 표시와 진단은 context.used에 대해 최신 프롬프트 스냅샷(promptTokens, 또는 프롬프트 스냅샷이 없는 경우 마지막 모델 호출)을 사용합니다.

비용 추정(표시되는 경우)

비용은 모델 가격 설정에서 추정됩니다.

models.providers.<provider>.models[].cost

이는 input, output, cacheRead, cacheWrite에 대한 토큰 100만 개당 USD입니다. 가격이 없으면 OpenClaw는 토큰만 표시합니다. OAuth 토큰은 달러 비용을 절대 표시하지 않습니다.

사이드카와 채널이 Gateway 준비 경로에 도달하면, OpenClaw는 아직 로컬 가격이 없는 설정된 모델 참조에 대해 선택적 백그라운드 가격 부트스트랩을 시작합니다. 이 부트스트랩은 원격 OpenRouter 및 LiteLLM 가격 카탈로그를 가져옵니다. 오프라인 또는 제한된 네트워크에서 이러한 카탈로그 가져오기를 건너뛰려면 models.pricing.enabled: false를 설정하세요. 명시적 models.providers.*.models[].cost 항목은 계속 로컬 비용 추정을 구동합니다.

캐시 TTL 및 가지치기 영향

제공자 프롬프트 캐싱은 캐시 TTL 창 내에서만 적용됩니다. OpenClaw는 선택적으로 캐시 TTL 가지치기를 실행할 수 있습니다. 캐시 TTL이 만료되면 세션을 가지치기한 다음 캐시 창을 재설정하여 이후 요청이 전체 기록을 다시 캐싱하는 대신 새로 캐싱된 컨텍스트를 재사용할 수 있게 합니다. 이렇게 하면 세션이 TTL을 지나 유휴 상태가 되었을 때 캐시 쓰기 비용을 낮게 유지할 수 있습니다.

Gateway 설정에서 설정하고, 동작 세부 사항은 세션 가지치기를 참고하세요.

Heartbeat는 유휴 간격 동안 캐시를 따뜻하게 유지할 수 있습니다. 모델 캐시 TTL이 1h인 경우 Heartbeat 간격을 그보다 약간 짧게(예: 55m) 설정하면 전체 프롬프트를 다시 캐싱하지 않아 캐시 쓰기 비용을 줄일 수 있습니다.

다중 에이전트 구성에서는 하나의 공유 모델 설정을 유지하고 agents.list[].params.cacheRetention으로 에이전트별 캐시 동작을 조정할 수 있습니다.

전체 조정값별 가이드는 프롬프트 캐싱을 참고하세요.

Anthropic API 가격의 경우, 캐시 읽기는 입력 토큰보다 훨씬 저렴한 반면 캐시 쓰기는 더 높은 배율로 청구됩니다. 최신 요율 및 TTL 배율은 Anthropic의 프롬프트 캐싱 가격을 참고하세요. https://docs.anthropic.com/docs/build-with-claude/prompt-caching

예시: Heartbeat로 1시간 캐시를 따뜻하게 유지

agents:
  defaults:
    model:
      primary: "anthropic/claude-opus-4-6"
    models:
      "anthropic/claude-opus-4-6":
        params:
          cacheRetention: "long"
    heartbeat:
      every: "55m"

예시: 에이전트별 캐시 전략이 있는 혼합 트래픽

agents:
  defaults:
    model:
      primary: "anthropic/claude-opus-4-6"
    models:
      "anthropic/claude-opus-4-6":
        params:
          cacheRetention: "long" # default baseline for most agents
  list:
    - id: "research"
      default: true
      heartbeat:
        every: "55m" # keep long cache warm for deep sessions
    - id: "alerts"
      params:
        cacheRetention: "none" # avoid cache writes for bursty notifications

agents.list[].params는 선택된 모델의 params 위에 병합되므로, cacheRetention만 재정의하고 다른 모델 기본값은 변경 없이 상속할 수 있습니다.

예시: Anthropic 1M 컨텍스트 베타 헤더 활성화

Anthropic의 1M 컨텍스트 창은 현재 베타 게이트가 적용되어 있습니다. OpenClaw는 지원되는 Opus 또는 Sonnet 모델에서 context1m을 활성화하면 필요한 anthropic-beta 값을 주입할 수 있습니다.

agents:
  defaults:
    models:
      "anthropic/claude-opus-4-6":
        params:
          context1m: true

이는 Anthropic의 context-1m-2025-08-07 베타 헤더에 매핑됩니다.

이는 해당 모델 항목에 context1m: true가 설정된 경우에만 적용됩니다.

요구 사항: 자격 증명이 장문 컨텍스트 사용 자격을 갖추고 있어야 합니다. 그렇지 않으면 Anthropic은 해당 요청에 대해 제공자 측 속도 제한 오류로 응답합니다.

OAuth/구독 토큰(sk-ant-oat-*)으로 Anthropic에 인증하는 경우, OpenClaw는 context-1m-* 베타 헤더를 건너뜁니다. Anthropic이 현재 해당 조합을 HTTP 401로 거부하기 때문입니다.

토큰 압박을 줄이는 팁

  • 긴 세션을 요약하려면 /compact를 사용하세요.
  • 워크플로에서 큰 도구 출력을 줄이세요.
  • 스크린샷이 많은 세션에서는 agents.defaults.imageMaxDimensionPx를 낮추세요.
  • Skill 설명을 짧게 유지하세요(Skill 목록은 프롬프트에 주입됨).
  • 장황하고 탐색적인 작업에는 더 작은 모델을 선호하세요.

정확한 Skill 목록 오버헤드 공식은 Skills를 참고하세요.

관련 항목