API Usage and Costs in OpenClaw

Map of OpenClaw features that call paid provider APIs, the credential source for each, and where the resulting cost is displayed.

Where costs show up

/status (per-session snapshot)

Displays the active session model, context usage, and token count from the last response.
When OpenClaw has usage metadata and local pricing for the current model, it adds an estimated cost for the previous reply, covering explicitly priced non-API-key providers like Bedrock aws-sdk models.
If the live session snapshot lacks detail, /status pulls token/cache counters and the active model label from the most recent transcript usage entry. Nonzero live values take precedence over transcript data; a prompt-sized transcript total can still take priority when the stored total is absent or smaller.

/usage (per-message footer)

/usage full attaches a usage footer to each reply, with estimated cost included when local pricing is set and usage metadata exists.
/usage tokens displays only tokens. Subscription-style OAuth/token and CLI runtimes show tokens only unless they provide compatible usage metadata plus an explicit local price.
/usage cost outputs a local cost summary; /usage off turns off the footer.
Gemini CLI note: both stream-json and legacy json output carry usage under stats. OpenClaw converts stats.cached into cacheRead and computes input tokens from stats.input_tokens - stats.cached when necessary.

Control UI → Usage (cross-session analysis)

Shows transcript-derived token and estimated-cost totals for the chosen date range, broken down by provider, model, agent, channel, and token type.
Compares shorter calendar windows that end on the selected range's 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 indicates square-root compression is keeping low-usage days visible.
These totals reflect the available local session history, not a provider invoice or lifetime billing ledger. The UI warns when pricing is missing for some entries.

CLI usage windows (provider quotas, not per-message cost)

openclaw status --usage and openclaw channels list display provider usage windows as X% left.
Current usage-window providers: Anthropic, ClawRouter, DeepSeek, GitHub Copilot, 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 selects 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.

See Token use and costs for detailed examples.

Note

Anthropic has confirmed that Claude CLI reuse (including claude -p) is a sanctioned integration pattern unless it publishes a new policy. Anthropic does not expose a per-message dollar estimate, so /usage full cannot show cost for Claude CLI usage.

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

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.

See Models for pricing config and Token use and costs for display.

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.

See Image generation and Video generation for the current provider list.

Memory embeddings and semantic search

Semantic memory search triggers embedding APIs when memory.search.provider points to a remote adapter, such as openai, gemini, voyage, mistral, deepinfra, github-copilot, or amazon-bedrock. When memory.search.provider = "lmstudio" or "ollama" targets a local or self-hosted server, it usually operates without any hosted billing. With memory.search.provider = "local", everything stays on the device, so no API calls occur. An optional memory.search.fallback provider can step in if local embeddings fail.

Refer to Memory for details.

Web search tool

Depending on the provider you choose, web_search may generate usage fees. Every provider checks its environment variable for the key first, then falls back to plugins.entries.<id>.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`

Older tools.web.search.* configuration paths still work through a compatibility layer, though they are no longer the suggested approach.

Brave Search free credit: every plan comes with $5/month in credit that renews automatically. Since the Search plan charges $5 per 1,000 requests, that credit pays for 1,000 requests each month at no cost. To prevent surprise charges, set a usage limit in the Brave dashboard.

Check Web tools for more.

Web fetch tool (Firecrawl)

web_fetch can invoke Firecrawl with keyless starter access; for larger quotas, add FIRECRAWL_API_KEY (or plugins.entries.firecrawl.config.webFetch.apiKey). Without Firecrawl configured, the tool reverts to a direct fetch combined with the included web-readability plugin, which needs no paid API. Turn off plugins.entries.web-readability.enabled to bypass local Readability extraction.

See Web tools.

Provider usage snapshots (status/health)

To display quota windows or authentication health, openclaw status --usage and openclaw models status --json hit provider usage endpoints. These calls occur infrequently, yet they still reach provider APIs.

Consult Models CLI.

Compaction safeguard summarization

When the compaction safeguard runs, it can condense session history via the active model, which triggers provider API calls.

Read Session management and compaction for more.

Model scan / probe

With probing enabled, openclaw models scan can test OpenRouter models and relies on OPENROUTER_API_KEY for that purpose.

See Models CLI.

Talk (speech)

When set up, talk mode can trigger ElevenLabs through either ELEVENLABS_API_KEY or talk.providers.elevenlabs.apiKey.

Refer to Talk mode.

Skills (third-party APIs)

Skills have the ability to store apiKey inside skills.entries.<name>.apiKey. If a skill uses that key with an external API, the charges depend on the skill's provider.

See Skills.