Technical reference
استفاده از API و هزینهها
نقشهٔ قابلیتهای OpenClaw که میتوانند APIهای پولی ارائهدهندگان را فراخوانی کنند، محل خواندن اعتبارنامههای هرکدام و محل نمایش هزینهٔ حاصل.
هزینهها کجا نمایش داده میشوند
/status (نمای لحظهای هر نشست)
- مدل فعلی نشست، میزان استفاده از زمینه و توکنهای آخرین پاسخ را نشان میدهد.
- وقتی OpenClaw فرادادهٔ مصرف و قیمتگذاری محلی مدل فعال را در اختیار داشته باشد، هزینهٔ تخمینی آخرین پاسخ را اضافه میکند؛ این شامل ارائهدهندگان بدون کلید API با قیمتگذاری صریح، مانند مدلهای Bedrock مبتنی بر
aws-sdkنیز میشود. - اگر نمای لحظهای نشست زنده اطلاعات کمی داشته باشد،
/statusشمارندههای توکن/حافظهٔ نهان و برچسب مدل فعال را از جدیدترین ورودی مصرف در رونوشت بازیابی میکند. مقادیر زندهٔ غیرصفر موجود بر دادههای رونوشت اولویت دارند؛ بااینحال، اگر مجموع ذخیرهشده وجود نداشته باشد یا کوچکتر باشد، مجموع رونوشت در اندازهٔ پرامپت همچنان میتواند اولویت پیدا کند.
/usage (پاورقی هر پیام)
/usage fullبه هر پاسخ یک پاورقی مصرف اضافه میکند که در صورت پیکربندی قیمتگذاری محلی و دردسترسبودن فرادادهٔ مصرف، هزینهٔ تخمینی را نیز شامل میشود./usage tokensفقط توکنها را نشان میدهد. محیطهای اجرای CLI و OAuth/توکن مبتنی بر اشتراک، فقط توکنها را نشان میدهند؛ مگر اینکه فرادادهٔ مصرف سازگار همراه با قیمت محلی صریح ارائه کنند./usage costخلاصهٔ هزینهٔ محلی را چاپ میکند؛/usage offپاورقی را غیرفعال میکند.- نکته دربارهٔ Gemini CLI: هر دو خروجی
stream-jsonوjsonقدیمی، اطلاعات مصرف را درstatsحمل میکنند. OpenClaw مقدارstats.cachedرا بهcacheReadنرمالسازی میکند و در صورت نیاز، توکنهای ورودی را ازstats.input_tokens - stats.cachedبه دست میآورد.
رابط کنترل → مصرف (تحلیل میاننشستی)
- مجموع توکنها و هزینهٔ تخمینی استخراجشده از رونوشت را برای بازهٔ زمانی انتخابشده، همراه با تفکیک بر اساس ارائهدهنده، مدل، عامل، کانال و نوع توکن نشان میدهد.
- بازههای تقویمی کوتاهتری را که در تاریخ پایان بازهٔ انتخابشده خاتمه مییابند مقایسه میکند. تاریخهای فاقد مصرف، روزهای تقویمی با مصرف صفر محسوب میشوند و برای ایجاد بازهای متراکمتر نادیده گرفته نمیشوند.
- مقیاس نمودار روزانه را مستقیماً برچسبگذاری میکند. نشان
√یعنی فشردهسازی ریشهٔ دوم باعث میشود روزهای کممصرف قابل مشاهده بمانند. - این مجموعها تاریخچهٔ نشست محلی موجود را توصیف میکنند، نه صورتحساب ارائهدهنده یا دفتر کل صورتحساب مادامالعمر. رابط کاربری در صورت نبود قیمتگذاری برای برخی ورودیها هشدار میدهد.
بازههای مصرف CLI (سهمیههای ارائهدهنده، نه هزینهٔ هر پیام)
openclaw status --usageوopenclaw channels listبازههای مصرف ارائهدهنده را بهشکلX% leftنشان میدهند.- ارائهدهندگان فعلی بازهٔ مصرف عبارتاند از: Anthropic، ClawRouter، DeepSeek، GitHub Copilot، Gemini CLI، MiniMax، OpenAI (شامل احراز هویت OAuth/توکنی ChatGPT/Codex)، Xiaomi و z.ai. برای فهرست کامل ارائهدهندگان/پرچمها به CLI مدلها و CLI کانالها مراجعه کنید.
- فیلدهای خام
usage_percent/usagePercentدر MiniMax سهمیهٔ باقیمانده را گزارش میکنند، بنابراین OpenClaw آنها را معکوس میکند؛ در صورت وجود، فیلدهای مبتنی بر تعداد اولویت دارند. اگر پاسخ شامل آرایهٔmodel_remainsباشد، OpenClaw ورودی مدل گفتگو را انتخاب میکند، در صورت نیاز برچسب بازه را از مُهرهای زمانی به دست میآورد و نام مدل را در برچسب طرح میگنجاند. - احراز هویت مصرف در صورت وجود از قلابهای ویژهٔ ارائهدهنده میآید؛ در غیر این صورت، OpenClaw به اعتبارنامههای OAuth/کلید API منطبق در پروفایلهای احراز هویت، محیط یا پیکربندی رجوع میکند.
برای نمونههای تفصیلی به مصرف توکن و هزینهها مراجعه کنید.
کلیدها چگونه کشف میشوند
- پروفایلهای احراز هویت: مختص هر عامل و ذخیرهشده در
auth-profiles.json. - متغیرهای محیطی: برای مثال
OPENAI_API_KEY،BRAVE_API_KEY،FIRECRAWL_API_KEY. - پیکربندی:
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که ممکن است کلید را به محیط فرایند مهارت صادر کند.
قابلیتهایی که میتوانند کلیدها را مصرف کنند
پاسخهای مدل اصلی (گفتگو + ابزارها)
هر پاسخ یا فراخوانی ابزار روی ارائهدهندهٔ مدل فعلی اجرا میشود. این منبع اصلی مصرف و هزینه است و طرحهای میزبانیشدهٔ مبتنی بر اشتراک را نیز شامل میشود که صورتحسابشان خارج از رابط محلی OpenClaw صادر میشود: OpenAI Codex، Alibaba Cloud Model Studio Coding Plan، MiniMax Coding Plan، Z.AI/GLM Coding Plan و مسیر ورود Claude متعلق به Anthropic با Extra Usage فعال.
برای پیکربندی قیمتگذاری به مدلها و برای نحوهٔ نمایش به مصرف توکن و هزینهها مراجعه کنید.
درک رسانه (صدا/تصویر/ویدئو)
رسانهٔ ورودی میتواند پیش از اجرای خط لولهٔ پاسخ، از طریق API یک ارائهدهنده خلاصه یا رونویسی شود. پشتیبانی ارائهدهندگان برای هر Plugin ثبت میشود و با افزودهشدن Pluginها تغییر میکند؛ برای فهرست و پیکربندی فعلی به درک رسانه مراجعه کنید.
تولید تصویر و ویدئو
image_generate و video_generate به هر ارائهدهندهٔ پیکربندیشدهای که دردسترس باشد هدایت میشوند. اگر agents.defaults.imageGenerationModel تنظیم نشده باشد، تولید تصویر میتواند یک ارائهدهندهٔ پیشفرض دارای پشتوانهٔ احراز هویت را استنباط کند؛ تولید ویدئو به تنظیم صریح agents.defaults.videoGenerationModel نیاز دارد (برای مثال qwen/wan2.6-t2v).
برای فهرست فعلی ارائهدهندگان به تولید تصویر و تولید ویدئو مراجعه کنید.
تعبیههای حافظه و جستوجوی معنایی
جستوجوی معنایی حافظه زمانی از APIهای تعبیه استفاده میکند که agents.defaults.memorySearch.provider نام یک سازگارگر راهدور را مشخص کند (برای مثال openai، gemini، voyage، mistral، deepinfra، github-copilot، amazon-bedrock). تنظیم memorySearch.provider = "lmstudio" یا "ollama" از یک سرور محلی/خودمیزبان استفاده میکند و معمولاً هزینهٔ میزبانیشده ندارد. تنظیم memorySearch.provider = "local" همهچیز را بدون مصرف API روی دستگاه نگه میدارد. یک ارائهدهندهٔ اختیاری memorySearch.fallback میتواند خرابیهای تعبیهٔ محلی را پوشش دهد.
به حافظه مراجعه کنید.
ابزار جستوجوی وب
web_search بسته به ارائهدهندهٔ انتخابشده میتواند هزینهٔ مصرف ایجاد کند. هر ارائهدهنده ابتدا کلید خود را از یک متغیر محیطی و سپس از plugins.entries.<id>.config.webSearch.apiKey میخواند:
| ارائهدهنده | متغیر(های) محیطی |
|---|---|
| Brave Search | BRAVE_API_KEY |
| DuckDuckGo | بدون کلید؛ غیررسمی، مبتنی بر HTML، بدون هزینه |
| Exa | EXA_API_KEY |
| Firecrawl | FIRECRAWL_API_KEY |
| Gemini (Google Search) | GEMINI_API_KEY |
| Grok (xAI) | پروفایل OAuth متعلق به xAI یا XAI_API_KEY |
| Kimi (Moonshot) | KIMI_API_KEY یا MOONSHOT_API_KEY |
| MiniMax Search | MINIMAX_CODE_PLAN_KEY، MINIMAX_CODING_API_KEY، MINIMAX_OAUTH_TOKEN یا MINIMAX_API_KEY |
| Ollama Web Search | برای میزبان محلی دردسترس که وارد حساب شده باشد، بدون کلید؛ جستوجوی مستقیم https://ollama.com از OLLAMA_API_KEY استفاده میکند؛ میزبانهای محافظتشده با احراز هویت از احراز هویت حامل معمول ارائهدهندهٔ Ollama دوباره استفاده میکنند |
| Parallel | PARALLEL_API_KEY |
| Perplexity Search API | PERPLEXITY_API_KEY یا OPENROUTER_API_KEY |
| SearXNG | SEARXNG_BASE_URL؛ بدون کلید/خودمیزبان، بدون هزینهٔ میزبانیشده |
| Tavily | TAVILY_API_KEY |
مسیرهای پیکربندی قدیمی tools.web.search.* همچنان از طریق یک لایهٔ سازگاری بارگذاری میشوند، اما دیگر سطح توصیهشده نیستند.
اعتبار رایگان Brave Search: هر طرح شامل ۵ دلار اعتبار رایگان ماهانه با تمدید دورهای است. هزینهٔ طرح Search برای هر ۱٬۰۰۰ درخواست ۵ دلار است، بنابراین این اعتبار ماهانه ۱٬۰۰۰ درخواست را بدون هزینه پوشش میدهد. برای جلوگیری از هزینههای غیرمنتظره، در پیشخوان Brave محدودیت مصرف تنظیم کنید.
به ابزارهای وب مراجعه کنید.
ابزار واکشی وب (Firecrawl)
web_fetch میتواند Firecrawl را با دسترسی آغازین بدون کلید فراخوانی کند؛ برای سقفهای بالاتر FIRECRAWL_API_KEY (یا plugins.entries.firecrawl.config.webFetch.apiKey) را اضافه کنید. اگر Firecrawl پیکربندی نشده باشد، ابزار به واکشی مستقیم بههمراه Plugin همراه web-readability رجوع میکند (بدون API پولی). برای ردکردن استخراج محلی خوانایی، plugins.entries.web-readability.enabled را غیرفعال کنید.
به ابزارهای وب مراجعه کنید.
نماهای لحظهای مصرف ارائهدهنده (وضعیت/سلامت)
openclaw status --usage و openclaw models status --json نقاط پایانی مصرف ارائهدهنده را فراخوانی میکنند تا بازههای سهمیه یا سلامت احراز هویت را نشان دهند. حجم فراخوانیها کم است، اما همچنان APIهای ارائهدهنده را فراخوانی میکنند.
به CLI مدلها مراجعه کنید.
خلاصهسازی محافظ Compaction
محافظ Compaction میتواند تاریخچهٔ نشست را با استفاده از مدل فعلی خلاصه کند که هنگام اجرا APIهای ارائهدهنده را فراخوانی میکند.
به مدیریت نشست و Compaction مراجعه کنید.
پویش / کاوش مدل
openclaw models scan میتواند مدلهای OpenRouter را کاوش کند و هنگام فعالبودن کاوش از OPENROUTER_API_KEY استفاده میکند.
به CLI مدلها مراجعه کنید.
گفتار (صدا)
حالت گفتار در صورت پیکربندی میتواند ElevenLabs را فراخوانی کند: ELEVENLABS_API_KEY یا talk.providers.elevenlabs.apiKey.
به حالت گفتار مراجعه کنید.
Skills (APIهای شخص ثالث)
Skills میتوانند apiKey را در skills.entries.<name>.apiKey ذخیره کنند. اگر مهارتی از آن کلید برای یک API خارجی استفاده کند، هزینه تابع ارائهدهندهٔ آن مهارت است.
به Skills مراجعه کنید.
