API 사용량 및 비용
이 문서는 API 키를 호출할 수 있는 기능과 해당 비용이 어디에 표시되는지를 정리합니다. 이 문서는 provider 사용량이나 유료 API 호출을 발생시킬 수 있는 OpenClaw 기능에 초점을 맞춥니다.비용이 표시되는 위치 (채팅 + CLI)
세션별 비용 스냅샷/status는 현재 세션 모델, 컨텍스트 사용량, 마지막 응답 토큰을 표시합니다.- 모델이 API 키 인증을 사용하는 경우
/status는 마지막 응답에 대한 추정 비용도 표시합니다. - 라이브 세션 메타데이터가 충분하지 않으면
/status는 최신 transcript usage 항목에서 토큰/캐시 카운터와 활성 runtime 모델 레이블을 복구할 수 있습니다. 기존의 0이 아닌 라이브 값이 여전히 우선하며, 저장된 총계가 없거나 더 작을 때는 prompt 크기의 transcript 총계가 우선될 수 있습니다.
/usage full은 추정 비용(API 키 전용)을 포함한 사용량 푸터를 모든 응답에 추가합니다./usage tokens는 토큰만 표시합니다. subscription 스타일 OAuth/토큰 및 CLI 흐름에서는 달러 비용을 숨깁니다.- Gemini CLI 참고: CLI가 JSON 출력을 반환하면 OpenClaw는
stats에서 사용량을 읽고,stats.cached를cacheRead로 정규화하며, 필요할 때stats.input_tokens - stats.cached에서 입력 토큰을 계산합니다.
claude -p 사용을 이 통합에서 허용된 것으로 취급합니다.
Anthropic은 여전히 OpenClaw가 /usage full에 표시할 수 있는 메시지별 달러 추정치를 제공하지 않습니다.
CLI 사용량 기간(provider 할당량)
openclaw status --usage와openclaw channels list는 provider 사용량 기간 (메시지별 비용이 아닌 할당량 스냅샷)을 표시합니다.- 사람이 읽는 출력은 provider 전반에 걸쳐
X% 남음형식으로 정규화됩니다. - 현재 사용량 기간 provider: Anthropic, GitHub Copilot, Gemini CLI, OpenAI Codex, MiniMax, Xiaomi, z.ai.
- MiniMax 참고: 원시
usage_percent/usagePercent필드는 남은 할당량을 의미하므로 OpenClaw는 표시 전에 이를 반전합니다. 개수 기반 필드가 있으면 여전히 그것이 우선합니다. provider가model_remains를 반환하면 OpenClaw는 chat-model 항목을 우선하고, 필요하면 타임스탬프에서 기간 레이블을 계산하며, plan 레이블에 모델 이름을 포함합니다. - 해당 할당량 기간의 usage 인증은 가능하면 provider별 hook에서 가져오며, 그렇지 않으면 OpenClaw는 auth profile, env 또는 config에서 일치하는 OAuth/API 키 자격 증명으로 대체합니다.
키가 검색되는 방식
OpenClaw는 다음 위치에서 자격 증명을 가져올 수 있습니다.- Auth profile (에이전트별,
auth-profiles.json에 저장). - 환경 변수 (예:
OPENAI_API_KEY,BRAVE_API_KEY,FIRECRAWL_API_KEY). - Config (
models.providers.*.apiKey,plugins.entries.*.config.webSearch.apiKey,plugins.entries.firecrawl.config.webFetch.apiKey,memorySearch.*,talk.providers.*.apiKey). - Skills (
skills.entries.<name>.apiKey) — 키를 skill 프로세스 env로 내보낼 수 있습니다.
키 비용이 발생할 수 있는 기능
1) 코어 모델 응답 (채팅 + 도구)
모든 응답 또는 도구 호출은 현재 모델 provider(OpenAI, Anthropic 등)를 사용합니다. 이것이 사용량과 비용의 주요 원인입니다. 여기에는 OpenClaw의 로컬 UI 바깥에서 여전히 과금되는 subscription 스타일 hosted provider도 포함되며, 예를 들어 OpenAI Codex, Alibaba Cloud Model Studio Coding Plan, MiniMax Coding Plan, Z.AI / GLM Coding Plan, 그리고 Extra Usage가 활성화된 Anthropic의 OpenClaw Claude-login 경로가 있습니다. 표시 방식은 Models의 가격 설정과 토큰 사용량 및 비용을 참조하세요.2) 미디어 이해 (오디오/이미지/비디오)
수신된 미디어는 응답이 실행되기 전에 요약/전사될 수 있습니다. 이 과정에서 모델/provider API를 사용합니다.- 오디오: OpenAI / Groq / Deepgram / Google / Mistral.
- 이미지: OpenAI / OpenRouter / Anthropic / Google / MiniMax / Moonshot / Qwen / Z.AI.
- 비디오: Google / Qwen / Moonshot.
3) 이미지 및 비디오 생성
공유 생성 기능도 provider 키 비용을 발생시킬 수 있습니다.- 이미지 생성: OpenAI / Google / fal / MiniMax
- 비디오 생성: Qwen
agents.defaults.imageGenerationModel이 설정되지 않은 경우
이미지 생성은 auth 기반 provider 기본값을 추론할 수 있습니다. 현재 비디오 생성은
qwen/wan2.6-t2v와 같은 명시적인 agents.defaults.videoGenerationModel이 필요합니다.
이미지 생성, Qwen Cloud,
Models를 참조하세요.
4) 메모리 임베딩 + 시맨틱 검색
시맨틱 메모리 검색은 원격 provider로 구성된 경우 임베딩 API를 사용합니다.memorySearch.provider = "openai"→ OpenAI 임베딩memorySearch.provider = "gemini"→ Gemini 임베딩memorySearch.provider = "voyage"→ Voyage 임베딩memorySearch.provider = "mistral"→ Mistral 임베딩memorySearch.provider = "lmstudio"→ LM Studio 임베딩 (로컬/셀프 호스팅)memorySearch.provider = "ollama"→ Ollama 임베딩 (로컬/셀프 호스팅, 일반적으로 hosted API 과금 없음)- 로컬 임베딩이 실패할 경우 선택적으로 원격 provider로 대체 가능
memorySearch.provider = "local"로 설정하면 로컬로 유지할 수 있습니다(API 사용 없음).
Memory를 참조하세요.
5) 웹 검색 도구
web_search는 provider에 따라 사용 요금이 발생할 수 있습니다.
- Brave Search API:
BRAVE_API_KEY또는plugins.entries.brave.config.webSearch.apiKey - Exa:
EXA_API_KEY또는plugins.entries.exa.config.webSearch.apiKey - Firecrawl:
FIRECRAWL_API_KEY또는plugins.entries.firecrawl.config.webSearch.apiKey - Gemini (Google Search):
GEMINI_API_KEY또는plugins.entries.google.config.webSearch.apiKey - Grok (xAI):
XAI_API_KEY또는plugins.entries.xai.config.webSearch.apiKey - Kimi (Moonshot):
KIMI_API_KEY,MOONSHOT_API_KEY, 또는plugins.entries.moonshot.config.webSearch.apiKey - MiniMax Search:
MINIMAX_CODE_PLAN_KEY,MINIMAX_CODING_API_KEY,MINIMAX_API_KEY, 또는plugins.entries.minimax.config.webSearch.apiKey - Ollama Web Search: 기본적으로 키가 필요 없지만, 접근 가능한 Ollama 호스트와
ollama signin이 필요합니다. 호스트에 인증이 필요한 경우 일반 Ollama provider bearer auth를 재사용할 수도 있습니다. - Perplexity Search API:
PERPLEXITY_API_KEY,OPENROUTER_API_KEY, 또는plugins.entries.perplexity.config.webSearch.apiKey - Tavily:
TAVILY_API_KEY또는plugins.entries.tavily.config.webSearch.apiKey - DuckDuckGo: 키 없는 대체 수단(API 과금 없음, 하지만 비공식적이며 HTML 기반)
- SearXNG:
SEARXNG_BASE_URL또는plugins.entries.searxng.config.webSearch.baseUrl(키 없음/셀프 호스팅, hosted API 과금 없음)
tools.web.search.* provider 경로도 임시 호환성 shim을 통해 여전히 로드되지만, 더 이상 권장되는 config 표면은 아닙니다.
Brave Search 무료 크레딧: 각 Brave 요금제에는 매월 갱신되는
$5의 무료 크레딧이 포함됩니다. Search 요금제 비용은 요청 1,000건당 $5이므로, 이 크레딧으로
매월 1,000건의 요청을 무료로 처리할 수 있습니다. 예상치 못한 과금을 방지하려면 Brave 대시보드에서 사용 한도를 설정하세요.
웹 도구를 참조하세요.
5) 웹 가져오기 도구 (Firecrawl)
web_fetch는 API 키가 있으면 Firecrawl을 호출할 수 있습니다.
FIRECRAWL_API_KEY또는plugins.entries.firecrawl.config.webFetch.apiKey
6) Provider 사용량 스냅샷 (상태/헬스)
일부 상태 명령은 할당량 기간이나 인증 상태를 표시하기 위해 provider 사용량 엔드포인트를 호출합니다. 이들은 일반적으로 호출량이 적지만 여전히 provider API를 호출합니다.openclaw status --usageopenclaw models status --json
7) Compaction 안전장치 요약
Compaction 안전장치는 세션 기록을 현재 모델로 요약할 수 있으며, 실행 시 provider API를 호출합니다. 세션 관리 + Compaction을 참조하세요.8) 모델 스캔 / 프로브
openclaw models scan은 OpenRouter 모델을 프로브할 수 있으며,
프로브가 활성화되면 OPENROUTER_API_KEY를 사용합니다.
Models CLI를 참조하세요.
9) Talk (음성)
Talk 모드는 구성된 경우 ElevenLabs를 호출할 수 있습니다.ELEVENLABS_API_KEY또는talk.providers.elevenlabs.apiKey
10) Skills (서드파티 API)
Skills는skills.entries.<name>.apiKey에 apiKey를 저장할 수 있습니다. skill이 해당 키를 외부
API에 사용하면, 그 skill의 provider에 따라 비용이 발생할 수 있습니다.
Skills를 참조하세요.