API usage and costs — openclaw

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

/status (per-session snapshot)

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 (per-message footer)

/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.

Control UI → Usage (cross-session analysis)

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.

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

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.

See Token use and costs for detailed examples.

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, agents.defaults.memorySearch.*, 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 configured provider is available. Image generation can infer an auth-backed provider default when agents.defaults.imageGenerationModel is unset; video generation requires an explicit agents.defaults.videoGenerationModel (for example qwen/wan2.6-t2v).

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

Memory embeddings and semantic search

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

See Memory.

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.<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`

Legacy tools.web.search.* config paths still load through a compatibility shim but are no longer the recommended surface.

Brave Search free credit: each plan includes $5/month in renewing free credit. The Search plan costs $5 per 1,000 requests, so the credit covers 1,000 requests/month at no charge. Set a usage limit in the Brave dashboard to avoid unexpected charges.

See Web tools.

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.

See Web tools.

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.

See Models CLI.