استخدام واجهة برمجة التطبيقات والتكاليف

خريطة بميزات 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 عند الحاجة.

واجهة التحكم → الاستخدام (تحليل عبر الجلسات)

• تعرض إجماليات الرموز والتكلفة التقديرية المستمدة من سجلات المحادثات للنطاق الزمني المحدد، مع تفصيل حسب الموفّر والنموذج والوكيل والقناة ونوع الرمز.
• تقارن نوافذ تقويمية أقصر تنتهي في تاريخ نهاية النطاق المحدد. تُحتسب التواريخ المفقودة كأيام تقويمية ذات استخدام صفري؛ ولا يجري تخطيها لإنشاء نافذة أكثر كثافة.
• تضع تسمية مباشرة لمقياس المخطط اليومي. تعني شارة √ أن ضغط الجذر التربيعي يحافظ على ظهور الأيام منخفضة الاستخدام.
• تصف هذه الإجماليات سجل الجلسات المحلي المتاح، وليس فاتورة الموفّر أو سجل فوترة مدى الحياة. تحذّر الواجهة عند فقدان التسعير لبعض الإدخالات.

نوافذ الاستخدام في CLI (حصص الموفّر، وليست تكلفة لكل رسالة)

• يعرض openclaw status --usage وopenclaw channels list نوافذ استخدام الموفّر بصيغة X% left.
• موفّرو نوافذ الاستخدام الحاليون: Anthropic وClawRouter وDeepSeek وGitHub Copilot وGemini CLI وMiniMax وOpenAI (يشمل مصادقة ChatGPT/Codex عبر OAuth/الرمز) وXiaomi وz.ai. راجع CLI للنماذج وCLI للقنوات للاطلاع على القائمة الكاملة للموفّرين/العلامات.
• تعرض حقول MiniMax الخام usage_percent / usagePercent الحصة المتبقية، لذلك يعكسها 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، وقد تصدّر المفتاح إلى بيئة عملية Skill.

الميزات التي يمكنها إنفاق المفاتيح

استجابات النموذج الأساسية (المحادثة + الأدوات)

يعمل كل رد أو استدعاء أداة على موفّر النموذج الحالي. وهذا هو المصدر الأساسي للاستخدام والتكلفة، بما في ذلك الخطط المستضافة القائمة على الاشتراك التي تُفوتر خارج واجهة OpenClaw المحلية: OpenAI Codex وAlibaba Cloud Model Studio Coding Plan وMiniMax Coding Plan وZ.AI/GLM Coding Plan ومسار تسجيل الدخول إلى Claude من Anthropic مع تمكين Extra Usage.

راجع النماذج لإعداد التسعير واستخدام الرموز والتكاليف للعرض.

فهم الوسائط (الصوت/الصورة/الفيديو)

يمكن تلخيص الوسائط الواردة أو نسخها نصيًا عبر واجهة API لأحد الموفّرين قبل تشغيل مسار معالجة الرد. يُسجّل دعم الموفّرين لكل Plugin ويتغير عند إضافة Plugins؛ راجع فهم الوسائط للاطلاع على القائمة والإعدادات الحالية.

إنشاء الصور والفيديو

يوجّه 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:

لا تزال مسارات الإعداد القديمة tools.web.search.* تُحمّل عبر طبقة توافق، لكنها لم تعد الواجهة الموصى بها.

الرصيد المجاني لـ Brave Search: تتضمن كل خطة رصيدًا مجانيًا متجددًا بقيمة 5 دولارات شهريًا. تبلغ تكلفة خطة Search خمسة دولارات لكل 1,000 طلب، لذا يغطي الرصيد 1,000 طلب شهريًا من دون رسوم. عيّن حدًا للاستخدام في لوحة معلومات Brave لتجنب الرسوم غير المتوقعة.

راجع أدوات الويب.

أداة جلب الويب (Firecrawl)

يمكن لـweb_fetch استدعاء Firecrawl بوصول ابتدائي من دون مفتاح؛ أضف FIRECRAWL_API_KEY (أو plugins.entries.firecrawl.config.webFetch.apiKey) للحصول على حدود أعلى. إذا لم يكن Firecrawl مُعدًّا، تعود الأداة إلى الجلب المباشر بالإضافة إلى Plugin ‏web-readability المضمّن (من دون API مدفوعة). عطّل plugins.entries.web-readability.enabled لتخطي الاستخراج المحلي باستخدام Readability.

راجع أدوات الويب.

لقطات استخدام الموفّر (الحالة/السلامة)

يستدعي 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. إذا استخدمت Skill هذا المفتاح مع واجهة API خارجية، فتتبع التكلفة موفّر Skill.

راجع Skills.

ذو صلة

• استخدام الرموز والتكاليف
• التخزين المؤقت للمطالبات
• تتبّع الاستخدام