API usage and costs

API usage and costs 문서는 OpenClaw 공식 문서(reference/api-usage-costs)를 한국어로 정리한 가이드입니다. Audit what can spend money, which keys are used, and how to view usage 명령·설정 키·코드 예시는 공식 문서를 그대로 보존하며, 해석과 절차 안내는 한국어로 제공합니다. 최종 동작은 설치된 CLI 버전과 공식 원문을 확인하세요.

핵심 요약

Audit what can spend money, which keys are used, and how to view usage

한국어 가이드 범위: reference/api-usage-costs 경로의 설정·명령·제약·예시를 학습용으로 재구성합니다.

문서 구성

공식 문서의 주요 섹션은 다음과 같습니다.

Where costs show up
How keys are discovered
Features that can spend keys
Core model responses (chat + tools)
Media understanding (audio/image/video)
Image and video generation
Memory embeddings and semantic search
Web search tool
Web fetch tool (Firecrawl)
Provider usage snapshots (status/health)
Compaction safeguard summarization
Model scan / probe
Talk (speech)
Skills (third-party APIs)
관련 문서

상세 내용

본문

Map of OpenClaw features that can call paid provider APIs, where each reads its credentials, and where the resulting cost shows up.

Where costs show up

See Token use and costs for detailed examples.

주요 항목:

Shows the current session model, context usage, and last-response tokens.
Adds an estimated cost for the last reply when OpenClaw has usage metadata and local pricing for the active model, including explicitly priced non-API-key providers such as Bedrock aws-sdk models.
If the live session snapshot is sparse, /status recovers token/cache counters and the active model label from the latest transcript usage entry. Existing nonzero live values win over transcript data; a prompt-sized transcript total can still win when the stored total is missing or smaller.
/usage full appends a usage footer to every reply, including estimated cost when local pricing is configured and usage metadata is available.
/usage tokens shows tokens only. Subscription-style OAuth/token and CLI runtimes show tokens only unless they supply compatible usage metadata plus an explicit local price.
/usage cost prints a local cost summary; /usage off disables the footer.
Gemini CLI note: both stream-json and legacy json output carry usage under stats. OpenClaw normalizes stats.cached into cacheRead and derives input tokens from stats.input_tokens - stats.cached when needed.
Shows transcript-derived token and estimated-cost totals for the selected date range, with breakdowns by provider, model, agent, channel, and token type.
Compares shorter calendar windows ending on the selected range end date. Missing dates count as zero-usage calendar days; they are not skipped to create a denser window.
Labels the daily chart scale directly. A √ badge means square-root compression is keeping low-usage days visible.
These totals describe the available local session history, not a provider invoice or lifetime billing ledger. The UI warns when pricing is missing for some entries.
openclaw status --usage and openclaw channels list show provider usage windows as X% left.
Current usage-window providers: Anthropic, ClawRouter, DeepSeek, GitHub Copilot, Gemini CLI, MiniMax, OpenAI (covers ChatGPT/Codex OAuth/token auth), Xiaomi, and z.ai. See Models CLI and Channels CLI for the full provider/flag list.
MiniMax's raw usage_percent / usagePercent fields report remaining quota, so OpenClaw inverts them; count-based fields win when present. If the response includes a model_remains array, OpenClaw picks the chat-model entry, derives the window label from timestamps when needed, and includes the model name in the plan label.
Usage auth comes from provider-specific hooks when available, otherwise OpenClaw falls back to matching OAuth/API-key credentials from auth profiles, env, or config.

How keys are discovered

주요 항목:

Auth profiles: per-agent, stored in auth-profiles.json.
Environment variables: for example OPENAI_API_KEY, BRAVE_API_KEY, FIRECRAWL_API_KEY.
Config: models.providers.*.apiKey, plugins.entries.*.config.webSearch.apiKey, plugins.entries.firecrawl.config.webFetch.apiKey, memory.search.*, talk.providers.*.apiKey.
Skills: skills.entries.<name>.apiKey, which may export the key to the skill process env.

Features that can spend keys

이 섹션의 세부 항목은 공식 문서 Features that can spend keys를 참고하세요.

Core model responses (chat + tools)

Every reply or tool call runs on the current model provider. This is the primary source of usage and cost, including subscription-style hosted plans that bill outside OpenClaw's local UI: OpenAI Codex, Alibaba Cloud Model Studio Coding Plan, MiniMax Coding Plan, Z.AI/GLM Coding Plan, and Anthropic's Claude-login path with Extra Usage enabled.

Media understanding (audio/image/video)

Inbound media can be summarized or transcribed via a provider API before the reply pipeline runs. Provider support is registered per plugin and changes as plugins are added; see Media understanding for the current list and config.

Image and video generation

image_generate and video_generate route to whichever authenticated provider is available. Both can infer an auth-backed provider default when their agents.defaults.mediaModels entry is unset.

Memory embeddings and semantic search

Semantic memory search uses embedding APIs when memory.search.provider names a remote adapter (for example openai, gemini, voyage, mistral, deepinfra, github-copilot, amazon-bedrock). memory.search.provider = "lmstudio" or "ollama" runs against a local/self-hosted server and typically has no hosted billing. memory.search.provider = "local" keeps everything on-device with no API usage. An optional memory.search.fallback provider can cover local-embedding failures.

Web search tool

web_search can incur usage charges depending on the selected provider. Each provider reads its key from an env var first, then plugins.entries..config.webSearch.apiKey:

Provider	Env var(s)
Brave Search	`BRAVE_API_KEY`
DuckDuckGo	key-free; unofficial, HTML-based, no billing
Exa	`EXA_API_KEY`
Firecrawl	`FIRECRAWL_API_KEY`
Gemini (Google Search)	`GEMINI_API_KEY`
Grok (xAI)	xAI OAuth profile or `XAI_API_KEY`
Kimi (Moonshot)	`KIMI_API_KEY` or `MOONSHOT_API_KEY`
MiniMax Search	`MINIMAX_CODE_PLAN_KEY`, `MINIMAX_CODING_API_KEY`, `MINIMAX_OAUTH_TOKEN`, or `MINIMAX_API_KEY`
Ollama Web Search	key-free for a reachable signed-in local host; direct `https://ollama.com` search uses `OLLAMA_API_KEY`; auth-protected hosts reuse normal Ollama provider bearer auth
Parallel	`PARALLEL_API_KEY`
Perplexity Search API	`PERPLEXITY_API_KEY` or `OPENROUTER_API_KEY`
SearXNG	`SEARXNG_BASE_URL`; key-free/self-hosted, no hosted billing
Tavily	`TAVILY_API_KEY`

Web fetch tool (Firecrawl)

web_fetch can call Firecrawl with keyless starter access; add FIRECRAWL_API_KEY (or plugins.entries.firecrawl.config.webFetch.apiKey) for higher limits. If Firecrawl isn't configured, the tool falls back to direct fetch plus the bundled web-readability plugin (no paid API). Disable plugins.entries.web-readability.enabled to skip local Readability extraction.

Provider usage snapshots (status/health)

openclaw status --usage and openclaw models status --json call provider usage endpoints to show quota windows or auth health. Calls are low-volume but still hit provider APIs.

Compaction safeguard summarization

The compaction safeguard can summarize session history using the current model, which invokes provider APIs when it runs.

Model scan / probe

openclaw models scan can probe OpenRouter models and uses OPENROUTER_API_KEY when probing is enabled.

Talk (speech)

Talk mode can invoke ElevenLabs when configured: ELEVENLABS_API_KEY or talk.providers.elevenlabs.apiKey.

Skills (third-party APIs)

Skills can store apiKey in skills.entries..apiKey. If a skill uses that key against an external API, cost follows the skill's provider.

실습 체크리스트

공식 문서와 로컬 버전을 대조합니다: https://docs.openclaw.ai/reference/api-usage-costs
관련 CLI는 openclaw --help 및 하위 명령 --help로 옵션을 확인합니다.
설정 변경 시 openclaw config / openclaw doctor로 유효성을 검사합니다.
Gateway·채널·플러그인 변경 후에는 필요 시 Gateway를 재시작합니다.

API usage and costs

핵심 요약

Audit what can spend money, which keys are used, and how to view usage

한국어 가이드 범위: reference/api-usage-costs 경로의 설정·명령·제약·예시를 학습용으로 재구성합니다.

문서 구성

공식 문서의 주요 섹션은 다음과 같습니다.

Where costs show up
How keys are discovered
Features that can spend keys
Core model responses (chat + tools)
Media understanding (audio/image/video)
Image and video generation
Memory embeddings and semantic search
Web search tool
Web fetch tool (Firecrawl)
Provider usage snapshots (status/health)
Compaction safeguard summarization
Model scan / probe
Talk (speech)
Skills (third-party APIs)
관련 문서

상세 내용

본문

Map of OpenClaw features that can call paid provider APIs, where each reads its credentials, and where the resulting cost shows up.

Where costs show up

See Token use and costs for detailed examples.

주요 항목:

Shows the current session model, context usage, and last-response tokens.
Adds an estimated cost for the last reply when OpenClaw has usage metadata and local pricing for the active model, including explicitly priced non-API-key providers such as Bedrock aws-sdk models.
If the live session snapshot is sparse, /status recovers token/cache counters and the active model label from the latest transcript usage entry. Existing nonzero live values win over transcript data; a prompt-sized transcript total can still win when the stored total is missing or smaller.
/usage full appends a usage footer to every reply, including estimated cost when local pricing is configured and usage metadata is available.
/usage tokens shows tokens only. Subscription-style OAuth/token and CLI runtimes show tokens only unless they supply compatible usage metadata plus an explicit local price.
/usage cost prints a local cost summary; /usage off disables the footer.
Gemini CLI note: both stream-json and legacy json output carry usage under stats. OpenClaw normalizes stats.cached into cacheRead and derives input tokens from stats.input_tokens - stats.cached when needed.
Shows transcript-derived token and estimated-cost totals for the selected date range, with breakdowns by provider, model, agent, channel, and token type.
Compares shorter calendar windows ending on the selected range end date. Missing dates count as zero-usage calendar days; they are not skipped to create a denser window.
Labels the daily chart scale directly. A √ badge means square-root compression is keeping low-usage days visible.
These totals describe the available local session history, not a provider invoice or lifetime billing ledger. The UI warns when pricing is missing for some entries.
openclaw status --usage and openclaw channels list show provider usage windows as X% left.
Current usage-window providers: Anthropic, ClawRouter, DeepSeek, GitHub Copilot, Gemini CLI, MiniMax, OpenAI (covers ChatGPT/Codex OAuth/token auth), Xiaomi, and z.ai. See Models CLI and Channels CLI for the full provider/flag list.
MiniMax's raw usage_percent / usagePercent fields report remaining quota, so OpenClaw inverts them; count-based fields win when present. If the response includes a model_remains array, OpenClaw picks the chat-model entry, derives the window label from timestamps when needed, and includes the model name in the plan label.
Usage auth comes from provider-specific hooks when available, otherwise OpenClaw falls back to matching OAuth/API-key credentials from auth profiles, env, or config.

How keys are discovered

주요 항목:

Auth profiles: per-agent, stored in auth-profiles.json.
Environment variables: for example OPENAI_API_KEY, BRAVE_API_KEY, FIRECRAWL_API_KEY.
Config: models.providers.*.apiKey, plugins.entries.*.config.webSearch.apiKey, plugins.entries.firecrawl.config.webFetch.apiKey, memory.search.*, talk.providers.*.apiKey.
Skills: skills.entries.<name>.apiKey, which may export the key to the skill process env.

Features that can spend keys

이 섹션의 세부 항목은 공식 문서 Features that can spend keys를 참고하세요.

Core model responses (chat + tools)

Media understanding (audio/image/video)

Image and video generation

image_generate and video_generate route to whichever authenticated provider is available. Both can infer an auth-backed provider default when their agents.defaults.mediaModels entry is unset.

Memory embeddings and semantic search

Web search tool

web_search can incur usage charges depending on the selected provider. Each provider reads its key from an env var first, then plugins.entries..config.webSearch.apiKey:

Provider	Env var(s)
Brave Search	`BRAVE_API_KEY`
DuckDuckGo	key-free; unofficial, HTML-based, no billing
Exa	`EXA_API_KEY`
Firecrawl	`FIRECRAWL_API_KEY`
Gemini (Google Search)	`GEMINI_API_KEY`
Grok (xAI)	xAI OAuth profile or `XAI_API_KEY`
Kimi (Moonshot)	`KIMI_API_KEY` or `MOONSHOT_API_KEY`
MiniMax Search	`MINIMAX_CODE_PLAN_KEY`, `MINIMAX_CODING_API_KEY`, `MINIMAX_OAUTH_TOKEN`, or `MINIMAX_API_KEY`
Ollama Web Search	key-free for a reachable signed-in local host; direct `https://ollama.com` search uses `OLLAMA_API_KEY`; auth-protected hosts reuse normal Ollama provider bearer auth
Parallel	`PARALLEL_API_KEY`
Perplexity Search API	`PERPLEXITY_API_KEY` or `OPENROUTER_API_KEY`
SearXNG	`SEARXNG_BASE_URL`; key-free/self-hosted, no hosted billing
Tavily	`TAVILY_API_KEY`

Web fetch tool (Firecrawl)

Provider usage snapshots (status/health)

openclaw status --usage and openclaw models status --json call provider usage endpoints to show quota windows or auth health. Calls are low-volume but still hit provider APIs.

Compaction safeguard summarization

The compaction safeguard can summarize session history using the current model, which invokes provider APIs when it runs.

Model scan / probe

openclaw models scan can probe OpenRouter models and uses OPENROUTER_API_KEY when probing is enabled.

Talk (speech)

Talk mode can invoke ElevenLabs when configured: ELEVENLABS_API_KEY or talk.providers.elevenlabs.apiKey.

Skills (third-party APIs)

Skills can store apiKey in skills.entries..apiKey. If a skill uses that key against an external API, cost follows the skill's provider.

실습 체크리스트

공식 문서와 로컬 버전을 대조합니다: https://docs.openclaw.ai/reference/api-usage-costs
관련 CLI는 openclaw --help 및 하위 명령 --help로 옵션을 확인합니다.
설정 변경 시 openclaw config / openclaw doctor로 유효성을 검사합니다.
Gateway·채널·플러그인 변경 후에는 필요 시 Gateway를 재시작합니다.

API usage and costs

핵심 요약

문서 구성

상세 내용

본문

Where costs show up

How keys are discovered

Features that can spend keys

Core model responses (chat + tools)

Media understanding (audio/image/video)

Image and video generation

Memory embeddings and semantic search

Web search tool

Web fetch tool (Firecrawl)

Provider usage snapshots (status/health)

Compaction safeguard summarization

Model scan / probe

Talk (speech)

Skills (third-party APIs)

관련 문서

실습 체크리스트

관련 링크

관련 가이드

API usage and costs

핵심 요약

문서 구성

상세 내용

본문

Where costs show up

How keys are discovered

Features that can spend keys

Core model responses (chat + tools)

Media understanding (audio/image/video)

Image and video generation

Memory embeddings and semantic search

Web search tool

Web fetch tool (Firecrawl)

Provider usage snapshots (status/health)

Compaction safeguard summarization

Model scan / probe

Talk (speech)

Skills (third-party APIs)

관련 문서

실습 체크리스트

관련 링크

관련 가이드