الانتقال إلى المحتوى الرئيسي
لتشغيل استدعاءات الأدوات عبر جدار حماية الوكيل من خارج ترحيل النموذج — حلقة وكيلك الخاصة تستدعي خطّاف evaluate، أو عميل MCP يتصل بـ بوابة MCP — تصادق بمفتاح مخصص ضمن نطاق بوابة جدار الحماية، وليس مفتاح ترحيل sk-orca-… عادياً. مفتاح عادي يحصل على 403 على مسارات بوابة جدار الحماية المُصادَق عليها بالرمز (استدعاء الموافقة هو الاستثناء الوحيد — إنه موقَّع بـ HMAC، وليس محكوماً بالرمز). تغطي هذه الصفحة ما هو مفتاح api لبوابة جدار الحماية، وكيف تسكك واحداً، ولماذا النطاق محكوم بـ Admin+. للمحرك نفسه، انظر نظرة عامة على جدار الحماية والمرجع العميق في جدار الحماية.

​
1. ما هو مفتاح api لبوابة جدار الحماية

كل رمز (مفتاح API) في مساحة عملك يحمل علامة is_firewall_gateway. عندما تكون true، يُسمَح للمفتاح بالوصول إلى سطح بوابة جدار الحماية:
المسارماذا يفعل
POST /api/v1/firewall/evaluateحكم ما قبل الإرسال لاستدعاء أداة واحد.
POST /api/v1/firewall/evaluate_planفحص ما قبل التنفيذ لخطة متعددة الخطوات.
ANY /api/v1/firewall/mcpنقطة نهاية بوابة MCP الموحَّدة.
GET /api/v1/firewall/mcp_serversعدّد خوادم MCP المسجّلة لمساحة العمل (يعيد مصادقة الأعلى مفكوكة التشفير).
GET /api/v1/firewall/approvals/:idاستطلع حالة موافقة استدعاء مُعلَّق.
مفتاح بـ is_firewall_gateway = false (الافتراضي) مفتاح ترحيل عادي — يخدم حركة مرور نموذج /v1/*، وإذا ربطت سياسة عبر firewall_policy_id، فإن استدعاءات أدواته تُحكَم مضمّناً. لكنه لا يمكنه استدعاء مسارات البوابة أعلاه.
مفتاحان مختلفان، مهمتان مختلفتان. مفتاح الترحيل (مع firewall_policy_id مربوط) هو ما يستخدمه وكيلك للتحدث إلى النماذج — يحكم جدار الحماية استدعاءات أدواته تلقائياً. مفتاح بوابة جدار الحماية هو ما يستخدمه زمن تشغيل وكيلك ليسأل جدار الحماية عن حكم مباشرةً، أو ليوكّل tools/call لـ MCP عبر البوابة. معظم مساحات العمل تحتاج مفتاح بوابة فقط بمجرد تبنّيها خطّاف evaluate أو بوابة MCP.

​
2. لماذا يحصل مفتاح عادي على 403

نطاق البوابة يفتح قدرتين حساستين للأسرار، فهو معزول عمداً عن المفاتيح العادية:
  • /evaluate يقبل request_id يوفّره المستدعي يتدفّق إلى حدث جدار الحماية وسجلات الموافقة. قدرة أي مفتاح نموذج على تزوير أحداث تدقيق أو استكشاف نتائج السياسة صامتاً ستقوّض الأثر.
  • /mcp_servers يعيد اعتمادات الأعلى مفكوكة التشفير فيمكن لوكيل SDK الإرسال إلى خوادم MCP المسجّلة. تلك قراءة اعتماد، وليست استدعاء نموذج.
لهذا، يفحص المعالج علامة is_firewall_gateway للرمز المقدَّم ويعيد HTTP 403 عند غيابها: 
{
  "success": false,
  "message": "token lacks firewall_gateway scope — mint a dedicated gateway token"
}
لا تعد استخدام مفتاح ترحيل عالي الحركة كمفتاح بوابة، ولا تعد استخدام مفتاح بوابة لحركة ترحيل. أبقِ مفتاح مستوى الإجراء منفصلاً فيكون نصف قطر انفجاره وتدويره مستقلين عن مفاتيح نماذجك.

​
3. اسكك واحداً — محكوم بالدور إلى Admin+

ضبط is_firewall_gateway = true يتطلب Admin مساحة العمل أو أعلى. يمكن لـ Developer إنشاء وتحرير المفاتيح العادية، لكن لا يمكنه سكّ واحد ضمن نطاق بوابة — العلامة شأن إدارة أسرار، فتقع فوق دور كتابة الرمز العادي. تضبط المفاتيح في وحدة التحكم، تحت مفاتيح API لمساحة عملك. لسكّ مفتاح بوابة:
1

افتح مفاتيح API كـ Admin

سجّل دخول كـ Admin مساحة عمل (أو أعلى) وافتح صفحة مفاتيح API في وحدة التحكم.
2

أنشئ مفتاحاً بنطاق البوابة

أنشئ مفتاحاً جديداً وفعّل نطاق firewall gateway خاصته (is_firewall_gateway). جلسة بدور Developer لن ترى النطاق يحدث أثره — يبقي الخادم العلامة false لغير المسؤولين.
3

انسخ المفتاح مرة واحدة

انسخ قيمة المفتاح الكاملة عند الإنشاء. بعدها تـخفي وحدة التحكم المفتاح عند العرض، وقراءة النص العادي لمفتاح بوابة عائداً هي نفسها Admin+ — غير المسؤولين تُحذَف صفوف البوابة من استجابة “اجلب مفاتيحي”.
خفض العلامة أكثر تساهلاً من رفعها: مسح is_firewall_gateway (تنزيل مفتاح بوابة عائداً إلى مفتاح عادي) مفتوح لأي دور يمكنه تحرير المفتاح. فقط رفعها إلى true هو Admin+.

​
بوابات الأدوار في لمحة

الإجراءالدور
إنشاء/تحرير مفتاح عاديDeveloper+
ضبط is_firewall_gateway = trueAdmin+
قراءة النص العادي لمفتاح بوابة عائداًAdmin+
مسح is_firewall_gateway (تنزيل)أي محرِّر مفاتيح

​
4. مثال ملموس واحد

تشغّل حلقة وكيل وتريد فحص استدعاء أداة قبل إرساله. كـ Admin، اسكك مفتاح بوابة في وحدة التحكم، ثم استدعِ خطّاف evaluate من زمن تشغيلك بذلك المفتاح: 
curl https://api.orcarouter.ai/api/v1/firewall/evaluate \
  -H "Authorization: Bearer sk-orca-GATEWAY-KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "tool_name": "shell.exec",
    "arguments": { "command": "rm -rf /" },
    "request_id": "run-42-step-3"
  }'
يحل جدار الحماية سياسة مساحة عملك النشطة ويعيد الحكم — allow أو audit أو deny أو sanitize أو pending_approval أو حل cap_cost. يتصرّف وكيلك بناءً عليه: أرسل عند allow، تخطّ عند deny، استطلع معرّف الموافقة عند pending_approval. نفس مفتاح البوابة يصادق مساري استطلاع الموافقة وMCP.
توجّه عميل MCP (Claude Desktop، Cursor، إطار عمل وكيل) إلى https://api.orcarouter.ai/api/v1/firewall/mcp؟ استخدم مفتاح البوابة كرمزه الحامل. عندها يُقيَّم كل tools/call على سطح mcp قبل إعادة توجيهه للأعلى.

​
5. أين يقع

مفتاح بوابة يصادق مسارات البوابة. إنه لا يستبدل جلسة وحدة التحكم التي تستخدمها لـ تأليف السياسة: إنشاء السياسات، وتحرير القواعد، وتسجيل خوادم MCP، وحل الموافقات كلها تعمل تحت جلستك على /api/workspace/firewall/* (قراءات الإعدادات والسياسة والأدوات المكتشفة مفتوحة لكل عضو؛ صندوق رمل الاختبار التجريبي وكل الكتابات تتطلب Developer+). مفتاح البوابة يحمل فقط طلبات الحكم وإرسال MCP من زمن تشغيلك من آلة إلى آلة.

النطاق: المفاتيح، السياسات، مساحات العمل

كيف يرتبط firewall_policy_id لمفتاح ونطاق بوابة بحدّ مساحة العمل.

الموافقات

تدفّق الاستدعاء المُعلَّق الذي يستطلعه مفتاح بوابتك ويعيد تقديمه.

webhook الموافقة

الاستدعاء الموقَّع بـ HMAC الذي يحل استدعاءً مُعلَّقاً خارج النطاق.

خوادم MCP

سجّل واحكم خوادم MCP خلف نقطة نهاية البوابة.

​
6. الأسئلة الشائعة

رفع is_firewall_gateway إلى true هو Admin+. كتابة بدور Developer تضبط العلامة تُبقى صامتاً عند false (فإعادة تسمية أو تحرير حصة غير ذي صلة على نفس الطلب لا يزال ينجح) — المفتاح فقط لن يحمل النطاق. أعد إنشاءه أو حرّره كـ Admin.
المفتاح المقدَّم ليس ضمن نطاق بوابة. أكّد أنه سُكَّ بـ is_firewall_gateway = true من قبل Admin — مفتاح ترحيل عادي يحصل دائماً على 403 على هذه المسارات. انظر §2.
تقنياً مفتاح ضمن نطاق بوابة يمكنه أيضاً خدمة حركة ترحيل /v1/*، لكن أبقِهما منفصلين: مفتاح ترحيل واحد (مع firewall_policy_id مربوط) للنماذج، ومفتاح بوابة واحد لمسارات evaluate/MCP/الموافقة. تدوير مستقل، نصف قطر انفجار أصغر.
تُخفى المفاتيح بعد الإنشاء، وقراءة النص العادي لمفتاح بوابة هي Admin+. إذا لم تنسخه وقت السكّ، أنشئ مفتاح بوابة جديداً وأحِل القديم للتقاعد.