Technical reference
استفاده از API و هزینهها
نقشهای از قابلیتهای OpenClaw که میتوانند APIهای ارائهدهندگان پولی را فراخوانی کنند، محل خواندن اعتبارنامههای هرکدام و محل نمایش هزینه حاصل.
هزینهها کجا نمایش داده میشوند
/status (نمای لحظهای هر نشست)
- مدل نشست فعلی، میزان استفاده از زمینه و توکنهای آخرین پاسخ را نشان میدهد.
- وقتی OpenClaw فراداده استفاده و قیمتگذاری محلی مدل فعال را در اختیار داشته باشد، هزینه تخمینی آخرین پاسخ را اضافه میکند؛ این شامل ارائهدهندگان بدون کلید API با قیمتگذاری صریح، مانند مدلهای Bedrock
aws-sdkنیز میشود. - اگر نمای لحظهای نشست زنده اطلاعات کمی داشته باشد،
/statusشمارندههای توکن/کش و برچسب مدل فعال را از جدیدترین ورودی استفاده در رونوشت بازیابی میکند. مقادیر زنده غیرصفر موجود بر دادههای رونوشت اولویت دارند؛ وقتی مجموع ذخیرهشده وجود نداشته باشد یا کوچکتر باشد، مجموع رونوشت بهاندازه پرامپت همچنان میتواند اولویت پیدا کند.
/usage (پاورقی هر پیام)
/usage fullیک پاورقی استفاده به هر پاسخ اضافه میکند که در صورت پیکربندی قیمتگذاری محلی و در دسترس بودن فراداده استفاده، هزینه تخمینی را نیز شامل میشود./usage tokensفقط توکنها را نشان میدهد. OAuth/توکن اشتراکی و محیطهای اجرای CLI فقط توکنها را نشان میدهند، مگر اینکه فراداده استفاده سازگار را همراه با قیمت محلی صریح ارائه کنند./usage costخلاصه هزینه محلی را چاپ میکند؛/usage offپاورقی را غیرفعال میکند.- نکته Gemini CLI: خروجیهای
stream-jsonو نسخه قدیمیjsonهر دو اطلاعات استفاده را درstatsقرار میدهند. OpenClaw مقدارstats.cachedرا بهcacheReadنرمالسازی میکند و در صورت نیاز، توکنهای ورودی را ازstats.input_tokens - stats.cachedبه دست میآورد.
Control UI → Usage (تحلیل بیننشستی)
- مجموع توکنها و هزینه تخمینی بهدستآمده از رونوشتها را برای بازه زمانی انتخابشده، با تفکیک بر اساس ارائهدهنده، مدل، عامل، کانال و نوع توکن نشان میدهد.
- بازههای تقویمی کوتاهتر را که در تاریخ پایان بازه انتخابشده خاتمه مییابند مقایسه میکند. تاریخهای فاقد استفاده، روزهای تقویمی با استفاده صفر محسوب میشوند؛ آنها برای ایجاد بازهای متراکمتر نادیده گرفته نمیشوند.
- مقیاس نمودار روزانه را مستقیماً برچسبگذاری میکند. نشان
√یعنی فشردهسازی ریشه دوم، روزهای کماستفاده را قابل مشاهده نگه میدارد. - این مجموعها تاریخچه نشست محلی موجود را توصیف میکنند، نه صورتحساب ارائهدهنده یا دفتر کل صورتحساب مادامالعمر. رابط کاربری هنگامی که قیمتگذاری برخی ورودیها موجود نباشد هشدار میدهد.
بازههای استفاده 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،memory.search.*،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.mediaModels آنها تنظیم نشده است، ارائهدهنده پیشفرضی را بر اساس احراز هویت استنتاج کنند.
برای فهرست فعلی ارائهدهندگان، تولید تصویر و تولید ویدئو را ببینید.
تعبیههای حافظه و جستوجوی معنایی
جستوجوی معنایی حافظه هنگامی از APIهای تعبیه استفاده میکند که memory.search.provider یک آداپتور راهدور را مشخص کند (برای مثال openai، gemini، voyage، mistral، deepinfra، github-copilot، amazon-bedrock). memory.search.provider = "lmstudio" یا "ollama" روی یک سرور محلی/خودمیزبان اجرا میشود و معمولاً هزینه میزبانیشده ندارد. memory.search.provider = "local" همهچیز را بدون استفاده از API روی دستگاه نگه میدارد. یک ارائهدهنده اختیاری memory.search.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 استفاده میکند؛ میزبانهای محافظتشده با احراز هویت، احراز هویت bearer عادی ارائهدهنده 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: هر طرح شامل $5 اعتبار رایگان ماهانه با تمدید خودکار است. طرح Search بهازای هر 1,000 درخواست $5 هزینه دارد، بنابراین این اعتبار ماهانه 1,000 درخواست را بدون هزینه پوشش میدهد. برای جلوگیری از هزینههای غیرمنتظره، در داشبورد Brave محدودیت استفاده تنظیم کنید.
ابزارهای وب را ببینید.
ابزار واکشی وب (Firecrawl)
web_fetch میتواند Firecrawl را با دسترسی آغازین بدون کلید فراخوانی کند؛ برای محدودیتهای بالاتر، FIRECRAWL_API_KEY (یا plugins.entries.firecrawl.config.webFetch.apiKey) را اضافه کنید. اگر Firecrawl پیکربندی نشده باشد، ابزار به واکشی مستقیم بههمراه Plugin همراه web-readability متوسل میشود (بدون API پولی). برای نادیده گرفتن استخراج محلی Readability، 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 را ببینید.
