ربط API نموذج ذكاء اصطناعي بوكيل هاتف أندرويد داخل FoneClaw
دليل آمن لإعداد API Base URL وAPI Key وmodel ID داخل FoneClaw، اختبار اتصال النموذج، إصلاح أخطاء 401 و404 والمهلة، ثم تنفيذ إجراء Android محكوم.
- يمكن استخدام FoneClaw مباشرة بالنموذج الافتراضي المجاني، أو ربط نموذج متوافق عبر API Base URL وAPI Key وmodel ID داخل إعدادات FoneClaw.
- API Base URL يحدد نقطة خدمة النموذج، وAPI Key يثبت صلاحية الطلب، وmodel ID يختار النموذج؛ هذه القيم لا تمنح أذونات Android ولا ينبغي كشفها في لقطات أو أمثلة حقيقية.
- نجاح رد نصي من النموذج لا يثبت أن إجراءات الهاتف تعمل؛ يجب اختبار الاتصال أولا، ثم تجربة إجراء Android منخفض المخاطر عبر أداة مدعومة وموافقة واضحة عند الحاجة.
- وفق القدرات الحالية المتاحة في FoneClaw، أصبحت ضوابط كل أداة وتجاوزات الموافقة واسترداد الأذونات أوضح عند تحويل خطة النموذج إلى فعل Android مرئي.
استخدم النموذج الافتراضي أو اربط API خاصا بك
إذا كنت تريد ربط API نموذج ذكاء اصطناعي بوكيل هاتف أندرويد، فابدأ من حقيقة بسيطة: FoneClaw لا يجبرك على إحضار مفتاح API. يمكنك استخدام النموذج الافتراضي المجاني داخل FoneClaw، أو إعداد نموذج متوافق من مزود آخر عبر API Base URL وAPI Key وmodel ID. في الحالتين، يظل FoneClaw هو runtime لوكيل الهاتف: النموذج يفهم ويخطط، وFoneClaw يحكم أدوات Android المدعومة والأذونات والموافقة والنتيجة المرئية.
هذا الفصل يمنع خطأ شائعا. عند إعداد نموذج مخصص لوكيل الهاتف، أنت لا تجعل تطبيق نموذج خارجي يعمل مع تطبيق FoneClaw كتطبيقين منفصلين. أنت تضبط endpoint داخل FoneClaw حتى يستخدمه الوكيل في التفكير. أما فتح تطبيق Android، أو تجهيز مسودة، أو قراءة حالة شاشة، أو طلب إذن، فهي خطوات تنفذها طبقة FoneClaw ضمن الأدوات المدعومة.
| المسار | متى تختاره؟ | ما الذي يبقى كما هو؟ |
|---|---|---|
| النموذج الافتراضي المجاني | عندما تريد البدء بسرعة من دون مفاتيح أو إعداد مزود خارجي. | FoneClaw يظل مسؤولا عن أدوات Android والأذونات والموافقة. |
| نموذج متوافق عبر API | عندما تحتاج نموذجا محددا، تكلفة مختلفة، أداء معينا، أو endpoint خاصا. | النموذج يخطط داخل FoneClaw، لكنه لا يحصل تلقائيا على أذونات Android. |
إذا كان هدفك فهم طبقة التنفيذ بعد إعداد النموذج، فدليل التحكم في الهاتف بواسطة وكيل ذكاء اصطناعي: كيف يعمل وكيل أندرويد بأمان؟ يشرح كيف ينتقل الطلب من نية المستخدم إلى أداة Android مدعومة ومراجعة مرئية.
شرح API Base URL وAPI Key وmodel ID
قبل فتح إعدادات FoneClaw، افهم القيم الثلاث التي ستحتاجها. API Base URL هو عنوان خدمة النموذج المتوافقة. ليس بالضرورة الصفحة الرئيسية للمزود، وليس بالضرورة رابط لوحة التحكم. هو المسار الذي تستقبل عليه الخدمة طلبات النموذج. بعض المزودين يقدمون توافقا مع مكتبات OpenAI عبر Base URL خاص بهم؛ تعرض وثائق Gemini API للتوافق مع OpenAI مثالا على أن المزود قد يستخدم عنوانا خاصا به مع اسم نموذج محدد، ولا يعني ذلك أن كل المزودين يستخدمون المسار نفسه.
API Key هو السر الذي يثبت أن الطلب صادر من حساب مسموح له باستخدام الخدمة. تعامل معه ككلمة مرور تقنية: لا تضعه في مقالة، لا ترسله في محادثة عامة، لا تعرضه في لقطة شاشة، ولا تستخدم مفتاحا منسوخا من مصدر لا تثق به. توضح مرجعية مصادقة OpenAI API فكرة مفاتيح API ومصادقة Bearer، لكن كل مزود قد يضيف سياساته وحدوده وطريقة إدارة المفاتيح الخاصة به.
model ID هو اسم النموذج الذي تريد تشغيله عند ذلك المزود. قد يكون لديك Base URL صحيح وAPI Key صحيح، لكن model ID غير متاح لحسابك أو مكتوب بطريقة خاطئة. عندها لن يكون فشل الاتصال مشكلة Android، بل مشكلة اختيار النموذج أو صلاحية الحساب. اقرأ اسم النموذج كما يقدمه المزود، ولا تفترض أن الاسم التسويقي في الصفحة العامة هو نفسه model ID المطلوب في API.
استخدم أمثلة وهمية فقط عند التوثيق الشخصي: https://api.example.com/v1 كـ API Base URL، وsk-REPLACE_WITH_YOUR_KEY كمفتاح غير حقيقي، وexample-model-id كنموذج تجريبي. لا تستخدم هذه القيم فعليا. الأخطاء الشائعة تشمل حذف https://، إضافة مسار زائد، نسخ مفتاح منتهي، وضع مسافات قبل المفتاح، أو اختيار نموذج لا يدعم الصيغة التي يحتاجها وكيل الهاتف.
إعداد نموذج داخل FoneClaw خطوة بخطوة
إعداد API Key للنموذج على الهاتف يجب أن يكون هادئا ومنظما. جهّز القيم من مزودك أولا: API Base URL، API Key، وmodel ID. لا تبدأ بنسخ أسرار من تطبيقات مراسلة أو ملاحظات غير محمية. إذا كان المزود يسمح بإنشاء مفتاح محدود أو قابل للإلغاء، استخدم مفتاحا مخصصا لـFoneClaw حتى تستطيع تعطيله لاحقا دون التأثير في خدمات أخرى.
داخل FoneClaw، انتقل إلى إعدادات الوكيل أو إعدادات النموذج، واختر مسار تكوين نموذج متوافق بدلا من النموذج الافتراضي إذا كنت تريد استخدام endpoint خارجي. أدخل API Base URL كما يحدده المزود، ثم أدخل API Key في الحقل المخصص له، ثم اكتب model ID بدقة. لا تضف علامات اقتباس حول القيم، ولا تضع JSON كاملا إذا كانت الواجهة تطلب حقولا منفصلة.
بعد الحفظ، اجعل النموذج الجديد هو النموذج المختار للتجربة. لا تحذف إعداد النموذج الافتراضي من ذهنك؛ احتفظ به كمسار رجوع إذا فشل المزود الخارجي أو كان بطيئا أو لا يدعم نمط الأداة المطلوب. الإعداد الجيد ليس مجرد نجاح الحفظ، بل وجود خطة عودة واضحة.
- تأكد من أن اتصال الهاتف بالإنترنت مستقر.
- افتح إعدادات النموذج داخل FoneClaw.
- اختر استخدام نموذج متوافق بدلا من النموذج الافتراضي إذا كنت تريد endpoint خاصا.
- أدخل API Base URL من مزودك كما هو، مع HTTPS عندما يطلبه المزود.
- أدخل API Key في الحقل المخصص، من دون عرضه أو مشاركته.
- أدخل model ID المتاح لحسابك.
- احفظ الإعداد ثم شغّل اختبارا نصيا بسيطا قبل أي إجراء Android.
إذا كنت تفكر في توجيه أكثر من نموذج حسب نوع المهمة، فلا تجعل هذه الصفحة تتحول إلى جدول نماذج طويل. دليل Kimi K3 وDeepSeek V4 وGLM-5.2 لوكلاء الهاتف: كيف تختار النموذج؟ يتناول اختيار النماذج وتوجيهها بتفصيل أوسع.
اختبر اتصال النموذج قبل التحكم في الهاتف
اختبار الاتصال يجب أن يسبق أي تحكم في Android. ابدأ بطلب نصي آمن مثل: "اكتب جملة قصيرة تؤكد أن الاتصال يعمل". إذا رد النموذج، فهذا يثبت أن Base URL والمفتاح واسم النموذج يعملون مبدئيا. لكنه لا يثبت بعد أن أدوات الهاتف تعمل. النموذج قد ينجح في الدردشة ويفشل عند tool calling، أو قد يعطي خطة جيدة بينما الأداة المطلوبة غير مدعومة أو تحتاج إذنا من Android.
بعد الاختبار النصي، جرّب مهمة منخفضة المخاطر داخل FoneClaw: فتح تطبيق غير حساس، قراءة حالة ظاهرة، أو تجهيز مسودة لا تُرسل. لا تبدأ بإرسال بريد أو تغيير إعداد أو حذف شيء. الهدف في هذه المرحلة هو عزل الطبقات: هل الاتصال بالنموذج ناجح؟ هل يفهم النموذج الطلب؟ هل يختار أداة مناسبة؟ هل يستطيع FoneClaw تنفيذ الأداة المدعومة؟ وهل تظهر النتيجة للمستخدم؟
إذا نجحت المهمة النصية وفشل إجراء الهاتف، فلا تغيّر API Key مباشرة. افحص أولا هل الأداة مدعومة، هل الإذن مطلوب، وهل Android يعرض نافذة موافقة. API النموذج لا يمنح إذن الموقع أو الإشعارات أو الملفات. هذه طبقات منفصلة. نجاح endpoint يعني أن التفكير يعمل؛ نجاح إجراء الهاتف يعني أن FoneClaw استطاع تحويل التفكير إلى أداة مدعومة ضمن السياسة والإذن.
اختبار جيد ينتج واحدة من ثلاث نتائج: نجاح واضح، طلب إذن مفهوم، أو فشل قابل للتشخيص. إذا حصلت على نتيجة غامضة، قلل المهمة إلى خطوة أصغر. بدلا من "رتب يومي"، جرّب "افتح التقويم". بدلا من "اكتب وأرسل"، جرّب "اكتب مسودة فقط". بهذا تختبر ربط API نموذج ذكاء اصطناعي بوكيل هاتف أندرويد دون تعريض بيانات أو حسابات حساسة للخطر.
إصلاح أخطاء 401 و404 والمهلة والنموذج والأذونات
عند فشل الإعداد، لا تفترض أن المشكلة في FoneClaw أو في المزود وحده. اقرأ العرض أولا: هل الخطأ ظهر عند اختبار النص؟ أم عند تنفيذ أداة Android؟ أخطاء API عادة تظهر قبل الوصول إلى الهاتف، بينما أخطاء Android تظهر عند الأداة أو الإذن أو حالة التطبيق. فصل المكان يوفر وقتا كبيرا.
| العرض | السبب المحتمل | الإصلاح العملي |
|---|---|---|
| 401 أو Unauthorized | API Key خاطئ، منتهي، غير مفعل، أو لا يملك صلاحية المزود. | أنشئ مفتاحا جديدا من مزودك، انسخه دون مسافات، ولا تعرضه في أي لقطة. |
| 404 أو Not Found | API Base URL غير صحيح، مسار غير متوافق، أو model ID غير موجود في ذلك endpoint. | راجع مسار المزود المتوافق واسم النموذج بدقة، ولا تفترض أن كل المزودين يستخدمون المسار نفسه. |
| Timeout أو انتظار طويل | شبكة الهاتف، خادم بطيء، نموذج ثقيل، أو مهلة مزود قصيرة. | اختبر اتصالا أبسط، جرّب شبكة مستقرة، أو اختر نموذجا أسرع للمهام اليومية. |
| رد نصي ناجح لكن لا توجد أداة | النموذج لا يخرج صيغة مناسبة للأدوات، أو المهمة خارج أدوات FoneClaw المدعومة. | جرّب أمرا أبسط، وراجع ميزات FoneClaw لمعرفة مسارات Android المدعومة. |
| النموذج يرد لكن إجراء Android يفشل | إذن Android غير ممنوح، التطبيق في حالة مختلفة، أو الهدف غامض. | امنح الإذن عند الطلب، افتح التطبيق الصحيح، وحدد الهدف بدقة. |
| خطأ في model ID | اسم النموذج غير متاح للحساب أو مكتوب كاسم تسويقي لا كمعرّف API. | انسخ model ID من وثائق المزود أو لوحة التحكم، ثم أعد اختبارا نصيا قصيرا. |
| تكلفة أو استهلاك أعلى من المتوقع | نموذج كبير لمهام قصيرة أو طلبات طويلة غير ضرورية. | استخدم النموذج الافتراضي أو نموذجا أسرع للمهام البسيطة، واحتفظ بالنموذج الأقوى للتخطيط الصعب. |
قاعدة التشخيص: API Key يعالج المصادقة، وAPI Base URL يعالج مكان الخدمة، وmodel ID يعالج أي نموذج سيعمل، وأذونات Android تعالج ما يسمح به الهاتف. لا يملك أي حقل منها سلطة الآخر. مفتاح صحيح لا يفتح إذن Android، وإذن Android صحيح لا يصلح مفتاح API خاطئا.
اختيار نموذج مناسب لإجراءات Android
هل يدعم FoneClaw نموذجا مخصصا؟ نعم، عندما يكون النموذج متوافقا ويمكن ضبطه عبر API Base URL وAPI Key داخل FoneClaw. لكن اختيار النموذج لا ينبغي أن يكون سباق أسماء. اسأل عن المهمة: هل تريد أوامر قصيرة وسريعة؟ هل تحتاج فهم شاشة؟ هل تحتاج تخطيطا متعدد الخطوات؟ هل التكلفة مهمة لأنك ستكرر الطلبات كثيرا؟ وهل المزود موثوق في منطقتك وشبكتك؟
النموذج الأسرع لا يضمن دائما أسرع نتيجة على الهاتف. زمن التنفيذ يشمل فهم الطلب، اختيار الأداة، حالة Android، الإذن، الموافقة، والتحقق من النتيجة. قد يوفر نموذج سريع ثواني في التفكير ثم يخسرها كلها إذا اختار أداة غير مناسبة. وقد يكون نموذج أعمق أبطأ في الرد الأول لكنه يقلل إعادة المحاولة في المهام المعقدة. لذلك اختبر الأداء end-to-end، لا زمن الرد النصي فقط.
للمهام اليومية مثل فتح تطبيق أو تجهيز مسودة قصيرة، ابدأ بنموذج سريع ومستقر أو بالنموذج الافتراضي المجاني. للمهام التي تحتاج تحليل طويل أو اختيار بين عدة أدوات، اختبر نموذجا أقوى. وإذا أردت أمثلة موفري نماذج بعينها دون تحويل هذه الصفحة إلى مقارنة مزودين، فراجع هل يستطيع DeepSeek التحكم في هاتف Android؟ ما يستطيع فعله وما يحتاج إلى طبقة تنفيذ وهل يستطيع Grok التحكم في هاتف Android؟ المكالمات والمساعد الأساسي ودور FoneClaw. الفكرة في الحالتين واحدة: النموذج يساعد على التخطيط، وFoneClaw يحكم الفعل المدعوم على Android.
حوّل النموذج المتصل إلى إجراء هاتف محكوم
بعد أن ينجح الاتصال وتختار النموذج، لا تجعل أول اختبار فعلي إجراء حساسا. اطلب من FoneClaw مهمة بسيطة: فتح تطبيق، قراءة حالة ظاهرة، أو تجهيز نص غير مرسل. راقب السلسلة: الطلب يدخل، النموذج يخطط، FoneClaw يختار أداة مدعومة، Android يطلب إذنا إذا احتاج، ثم تظهر النتيجة أو سبب الفشل. هذا هو الفرق بين إعداد API نموذج عام وبين وكيل هاتف محكوم.
وفق أحدث معلومات FoneClaw المتاحة حتى الآن، أصبحت ضوابط كل أداة وتجاوزات الموافقة واسترداد الأذونات ومعالجة الفشل أوضح للمستخدم. لذلك يمكن أن تضبط الأداة منخفضة الأثر بشكل أسرع، مع إبقاء الموافقة الصريحة للخطوات التي ترسل أو تغير أو تحذف أو تشارك. السرعة لا تعني إخفاء الأذونات؛ السرعة الصحيحة تعني تقليل الاحتكاك غير الضروري مع بقاء الفعل الحساس مرئيا.
لخطوتك التالية، راجع ميزات FoneClaw لفهم 100+ built-in tools ومسارات Android المدعومة، ثم اختبر مهمة واحدة قابلة للمراجعة قبل بناء سير عمل أطول. إذا ظهر حد غير مدعوم، اعتبره نتيجة مفيدة: النموذج قد يكون متصلا، لكن الفعل ما زال يحتاج أداة Android مناسبة، إذنا في السياق، وموافقة واضحة عند الأثر.