الانتقال إلى المحتوى الرئيسي
كل طلب يصل إلى OrcaRouter يحمل مفتاح API. هذا المفتاح ليس مجرد بيانات اعتماد — إنه إعلان نطاق: أي النماذج يجوز للمتصل استخدامها، وأي عناوين IP يجوز تقديمه، وكم يجوز إنفاقه، وبالضبط أي سياسة حواجز حماية وجدار حماية تحكم حركة مروره. تشرح هذه الصفحة التسلسل الهرمي بثلاثة مستويات وكيف تُحَل السياسات في وقت الطلب.

​
1. النطاقات الثلاثة

ثلاثة مفاهيم متداخلة بعضها داخل بعض:
  • مساحة العمل — حد المستأجر. كل عضو في مساحة عمل يشارك نفس كتالوج حواجز الحماية وسياسات جدار الحماية. لا شيء يعبر حدود مساحات العمل — سياسة أُلِّفت في مساحة العمل A غير مرئية لمساحة العمل B.
  • السياسة — مجموعة قواعد مسمّاة ضمن نطاق مساحة العمل (حاجز حماية أو سياسة جدار حماية). تحرير سياسة يحدث أثره على كل مفتاح مرتبط بها في الطلب التالي، دون إعادة نشر.
  • المفتاح — الهوية بالإضافة إلى المرفقات. يحمل المفتاح قيوده الخاصة ويُشير إلى السياسات التي تحكمه.
مساحة العمل هي الحد الخارجي؛ السياسات هي موارد مشتركة داخلها؛ المفاتيح هي هويات لكل وكيل تربط القيود والسياسات معاً.

​
2. ما يحمله المفتاح

كل مفتاح API هو حزمة من الحدود والمرفقات. اضبطها في محرر المفتاح (/console/token) — إنشاء أو تحرير المفاتيح يتطلب دور Developer أو أعلى.
الحقلما يحدّهالدور الأدنى للضبط
model_limitsيقصر المفتاح على قائمة محددة من النماذج — يُرفض أي استدعاء خارج تلك القائمة قبل مغادرة البوابة.Developer
allow_ipsقائمة سماح IP. تُرفض الطلبات من أي عنوان غير مدرج على مستوى المصادقة. فارغ يعني السماح لجميع عناوين IP.Developer
credit_limit_usdسقف إنفاق بالدولار الأمريكي. 0 يعني غير محدود. تطبّق البوابة هذا مقابل إجمالي إنفاق المفتاح مدى الحياة.Developer
expired_timeطابع زمني للانتهاء المطلق. -1 يعني المفتاح لا ينتهي أبداً.Developer
environmentوسم حر (مثل prod، staging، dev) لتنظيم المفاتيح وتصفية السجلات.Developer
guardrail_idيُرفق حاجز حماية محدداً بهذا المفتاح. كل استدعاء يصدره هذا المفتاح يُفحص بذلك الحاجز.Developer
firewall_policy_idيُرفق سياسة جدار حماية محددة بهذا المفتاح. كل استدعاء أداة يصدره هذا المفتاح يُقيَّم بتلك السياسة.Developer
is_firewall_gatewayيُعلّم المفتاح كرمز ضمن نطاق بوابة — مطلوب لاستدعاء مسارات إرسال MCP وخطّاف التقييم. مفتاح عادي يحصل على 403 على تلك المسارات. قراءة نص مفتاح بوابة الصريح تتطلب Admin.Admin (للتفعيل ولقراءة النص الصريح)
المفاتيح مُقنَّعة في العرض بوحدة التحكم. النص الصريح يُظهَر مرة واحدة عند الإنشاء؛ المفاتيح ضمن نطاق البوابة تتطلب Admin لاسترجاعه مرة أخرى.

​
3. ترتيب حل السياسات

لأي طلب، يحل OrcaRouter حاجز الحماية النشط وسياسة جدار الحماية بشكل مستقل:
  1. ربط المفتاح — إذا كان للمفتاح guardrail_id صريح (أو firewall_policy_id) وتلك السياسة موجودة ومفعّلة، فإنها تنطبق.
  2. افتراضي مساحة العمل — إذا لم يكن للمفتاح ربط، تنطبق حواجز الحماية is_default المفعّلة (أو السياسة) لمساحة العمل.
  3. لا تطبيق — إذا لم يُضبط أيٌّ منهما، يمر الطلب دون فحص محتوى أو تطبيق لاستدعاء الأداة.
يختلف المستويان عندما يكون للسياسة المرتبطة حالة مُعطَّلة:
  • ربط حاجز حماية معطَّل أو محذوف يعني المفتاح لا يحصل على أي حاجز حماية — تعطيله هو مفتاح الإيقاف؛ لا يتراجع إلى افتراضي مساحة العمل.
  • ربط جدار الحماية المعطَّل يتراجع إلى سياسة جدار الحماية الافتراضية لمساحة العمل — لذا تعطيل ربط جدار حماية يُرجع المفتاح للافتراضي لمساحة العمل، ولا يُطفئ التطبيق.
ربط مفقود (0/غير مضبوط) يتراجع دائماً لافتراضي مساحة العمل؛ لا أيٍّ منهما يعني لا تطبيق.
يمكن لحاجز حماية واحد وسياسة جدار حماية واحدة على الأكثر لكل مساحة عمل أن يكونا الافتراضيَين في أي وقت. ترقية افتراضي جديد يُنزّل القديم في نفس المعاملة — لا يمكنك أبداً وجود افتراضيَين عن طريق الخطأ.

​
4. مفاتيح أقل صلاحية — مفتاح واحد لكل وكيل

أكثر ضبط أماناً هو إعطاء كل وكيل مفتاحه الخاص المحدد النطاق بدلاً من مشاركة مفتاح مساحة عمل واحد عبر جميع المتصلين. مفتاح محدد النطاق جيداً لوكيل يستدعي نموذجاً واحداً فقط ويشغّل مهاماً مجدولة قد يبدو هكذا:
  • model_limits: ["openai/gpt-4o-mini"] — لا يستطيع الوكيل التبديل إلى نموذج أغلى أو أكثر قدرة.
  • allow_ips: CIDR خروج الجدولة — لا مصدر آخر يستطيع تقديم هذا المفتاح.
  • credit_limit_usd: سقف ميزانية أسبوعي — حلقة متهالكة لا تستطيع استنفاد رصيد مساحة عملك.
  • expired_time: نهاية الـ sprint أو دورة حياة النشر — المفتاح ينتهي تلقائياً ولا يمكن إعادة استخدامه.
  • guardrail_id: حاجز حماية محدد لحساسية بيانات هذا الوكيل — أكثر صرامة من افتراضي مساحة العمل.
  • firewall_policy_id: سياسة تضع قائمة سماح فقط للأدوات التي يحتاجها هذا الوكيل شرعياً.
عندما يُخترق هذا الوكيل عبر حقن مطالبة، يكون نطاق الأضرار محدوداً: يستطيع فقط استدعاء نموذج واحد، من نطاق IP واحد فقط، حتى سقف إنفاقه فقط، وفقط الأدوات التي تسمح بها سياسة جدار الحمايته. بقية مساحة العمل غير متأثرة.
أنشئ مفاتيح ضمن نطاق البوابة (is_firewall_gateway) فقط لسطح إرسال MCP أو خطّاف التقييم — أبداً لحركة مرور الاستدلال العامة. مفتاح بوابة على مسار الاستدلال يمنح المتصل وصولاً لمسارات /api/v1/firewall/*، وهي قدرة أوسع مما يحتاج. مفتاح واحد، غرض واحد.

​
5. أين تُؤلَّف السياسات

حواجز الحماية وسياسات جدار الحماية كلاهما ضمن نطاق مساحة العمل ومشتركان عبر جميع الأعضاء، لكن التغييرات تتطلب الدور الصحيح:
  • قراءة أي حاجز حماية أو سياسة أو مفتاح — أي عضو في مساحة العمل.
  • إنشاء أو تغيير حواجز الحماية وسياسات جدار الحماية وخوادم MCP ومستويات الاستقلالية وإجراءات الموافقة ومفاتيح API العادية — Developer+.
  • تفعيل is_firewall_gateway على مفتاح؛ قراءة النص الصريح لمفتاح بوابة — Admin+.
مساحة العمل هي حد التعاون: يستطيع الجميع رؤية كتالوج السياسات؛ المطورون وما فوق فقط يستطيعون تغييره؛ المسؤولون فقط يستطيعون إصدار بيانات اعتماد البوابة.

​
6. الخطوات التالية

خط الأساس للوكلاء الآمنين

الموقف الابتدائي الموصى به — مفتاح تبديل مستوى استقلالية واحد، ثم الضبط من حركة المرور الحقيقية.

احصل على مفتاح API

أنشئ مفتاحك الأول وارتبط بحاجز حماية أو سياسة جدار حماية في وحدة التحكم.
النطاق هو أساس مجموعة التحكم. كلما كان نطاق كل مفتاح أضيق، كان نطاق الأضرار أصغر إذا اختُرق أي وكيل واحد — وأوضح مسار التدقيق الذي يُظهر ما كان كل وكيل مُخوَّلاً بفعله.