技术参考

API 使用与成本

本文档帮你理清哪些功能会消耗 API 密钥，以及成本会显示在哪些地方。重点介绍那些可能产生供应商调用费用或付费 API 请求的 OpenClaw 功能。

成本显示位置（聊天 + CLI）

每会话成本快照

  • /status 显示当前会话使用的模型、上下文占用情况，以及上次响应消耗的令牌数。
  • 如果模型使用 API 密钥认证，/status 还会显示上次回复的预估成本。

每条消息的成本页脚

  • /usage full 会在每次回复后附带一个使用情况页脚，包含预估成本（仅限 API 密钥认证）。
  • /usage tokens 仅显示令牌数；OAuth 认证方式会隐藏金额成本。

CLI 使用量窗口（供应商配额）

  • openclaw status --usage 和 openclaw channels list 显示供应商的使用量窗口（配额快照，而非单条消息成本）。

详细说明和示例请参阅令牌使用与成本。

密钥从哪里来

OpenClaw 可以从以下位置获取凭据：

  • 认证配置文件（按智能体存储，位于 auth-profiles.json 中）。
  • 环境变量（例如 OPENAI_API_KEY、BRAVE_API_KEY、FIRECRAWL_API_KEY）。
  • 配置文件（models.providers.*.apiKey、tools.web.search.*、tools.web.fetch.firecrawl.*、memorySearch.*、talk.apiKey）。
  • 技能（skills.entries.<name>.apiKey），这些密钥可能会导出到技能进程的环境变量中。

会消耗密钥的功能

1) 核心模型响应（聊天 + 工具）

每次回复或工具调用都会使用当前模型供应商（OpenAI、Anthropic 等）。这是使用量和成本的主要来源。定价配置请参阅模型，显示方式请参阅令牌使用与成本。

2) 媒体理解（音频/图像/视频）

接收到的媒体内容可能在生成回复之前先进行摘要或转录。这会调用模型/供应商 API。

  • 音频：OpenAI / Groq / Deepgram（现在检测到密钥时会自动启用）。
  • 图像：OpenAI / Anthropic / Google。
  • 视频：Google。

请参阅媒体理解。

3) 记忆嵌入 + 语义搜索

当配置为远程供应商时，语义记忆搜索会调用嵌入 API：

  • memorySearch.provider = "openai" → OpenAI 嵌入
  • memorySearch.provider = "gemini" → Gemini 嵌入
  • memorySearch.provider = "voyage" → Voyage 嵌入
  • memorySearch.provider = "mistral" → Mistral 嵌入
  • memorySearch.provider = "ollama" → Ollama 嵌入（本地/自托管；通常不产生托管 API 费用）
  • 本地嵌入失败时可选择回退到远程供应商

你可以通过设置 memorySearch.provider = "local" 保持本地运行（不产生 API 使用量）。请参阅记忆。

4) 网络搜索工具

web_search 使用 API 密钥，根据你的供应商可能会产生使用费用：

  • Perplexity Search API: PERPLEXITY_API_KEY
  • Brave Search API: BRAVE_API_KEY 或 tools.web.search.apiKey
  • Gemini (Google Search): GEMINI_API_KEY
  • Grok (xAI): XAI_API_KEY
  • Kimi (Moonshot): KIMI_API_KEY 或 MOONSHOT_API_KEY

请参阅网络工具。

5) 网页抓取工具（Firecrawl）

当存在 API 密钥时，web_fetch 可以调用 Firecrawl：

  • FIRECRAWL_API_KEY 或 tools.web.fetch.firecrawl.apiKey

如果未配置 Firecrawl，该工具会回退到直接抓取 + readability（无付费 API）。请参阅网络工具。

6) 供应商使用量快照（状态/健康检查）

某些状态命令会调用供应商使用量端点来显示配额窗口或认证健康状态。这些调用通常流量很小，但仍会访问供应商 API：

  • openclaw status --usage
  • openclaw models status --json

请参阅模型 CLI。

7) 压缩保护摘要

压缩保护功能可以使用当前模型来总结会话历史，运行时会调用供应商 API。请参阅会话管理与压缩。

8) 模型扫描/探测

openclaw models scan 可以探测 OpenRouter 模型，启用探测时会使用 OPENROUTER_API_KEY。请参阅模型 CLI。

9) 语音对话

配置后，语音对话模式可以调用 ElevenLabs：

  • ELEVENLABS_API_KEY 或 talk.apiKey

请参阅语音对话模式。

10) 技能（第三方 API）

技能可以在 skills.entries.<name>.apiKey 中存储 apiKey。如果技能使用该密钥调用外部 API，则可能根据技能的供应商产生费用。请参阅技能。

提示词缓存记录整理