دليل تشغيل تعريض Gateway

يحوّل دليل التشغيل هذا إرشادات الأمان الأوسع إلى قائمة تحقق للمشغلين بشأن الوصول عن بعد وتعريض المراسلة.

اختر نمط التعريض

فضّل أضيق نمط يلبّي سير العمل.

تجنب إعادة توجيه منفذ عام مباشرة إلى Gateway. إذا كنت تحتاج إلى وصول عام، فضع وكيلًا مدركًا للهوية أمامه واجعل الوكيل هو مسار الشبكة الوحيد إلى Gateway.

جرد ما قبل التشغيل

سجّل هذه العناصر قبل تغيير سياسة الربط أو الوكيل أو Tailscale أو القناة:

• مضيف Gateway، ومستخدم نظام التشغيل، ودليل الحالة.
• عنوان URL لـ Gateway ووضع الربط.
• وضع المصادقة، أو مصدر الرمز/كلمة المرور، أو مصدر هوية الوكيل الموثوق.
• كل القنوات المفعلة وما إذا كانت تقبل الرسائل المباشرة أو المجموعات أو Webhook.
• الوكلاء الذين يمكن للمرسلين غير المحليين الوصول إليهم.
• ملف تعريف الأدوات، ووضع العزل، وسياسة الأدوات ذات الصلاحيات المرتفعة لكل وكيل يمكن الوصول إليه.
• بيانات الاعتماد الخارجية المتاحة لهؤلاء الوكلاء.
• موقع النسخة الاحتياطية لـ ~/.openclaw/openclaw.json وبيانات الاعتماد.

إذا كان بإمكان أكثر من شخص واحد مراسلة البوت، فتعامل مع هذا على أنه صلاحية أدوات مشتركة ومفوّضة، وليس عزل مضيف لكل مستخدم.

فحوصات خط الأساس

شغّل هذه الأوامر قبل فتح الوصول:

openclaw doctoropenclaw security auditopenclaw security audit --deepopenclaw health

عالج النتائج الحرجة أولًا. قد تكون التحذيرات مقبولة فقط عندما تكون مقصودة وموثقة لعملية النشر.

للتحقق من CLI عن بعد، مرّر بيانات الاعتماد صراحة:

openclaw gateway probe --url ws://127.0.0.1:18789 --token "$OPENCLAW_GATEWAY_TOKEN"

لا تفترض أن بيانات اعتماد الإعداد المحلي تنطبق على عنوان URL بعيد صريح.

الحد الأدنى الآمن لخط الأساس

استخدم هذا الشكل كنقطة بداية لعمليات النشر المكشوفة:

{  gateway: {    bind: "loopback",    auth: {      mode: "token",      token: "replace-with-a-long-random-token",    },  },  session: {    dmScope: "per-channel-peer",  },  agents: {    defaults: {      sandbox: { mode: "non-main" },    },  },  tools: {    profile: "messaging",    exec: { security: "deny", ask: "always" },    elevated: { enabled: false },  },}

ثم وسّع عنصر تحكم واحدًا في كل مرة. على سبيل المثال، أضف قائمة سماح لقناة محددة قبل تفعيل أدوات قادرة على الكتابة، أو فعّل وكيلًا عكسيًا قبل قبول حركة واجهة التحكم عن بعد.

يحظر خط الأساس الصارم exec.security: "deny" كل استدعاءات exec، بما في ذلك التشخيصات غير الضارة. إذا كانت التشخيصات أو الأوامر منخفضة المخاطر مطلوبة، فلا تخفف هذا إلا بعد اختيار المرسلين والوكلاء والأوامر ووضع الموافقة المحددين المطابقين لنموذج التهديد لديك.

تعريض الرسائل المباشرة والمجموعات

قنوات المراسلة أسطح إدخال غير موثوقة. قبل السماح بالرسائل المباشرة أو المجموعات:

• فضّل dmPolicy: "pairing" أو قوائم allowFrom صارمة.
• تجنب dmPolicy: "open" إلا إذا كان كل مرسل موثوقًا.
• لا تدمج قوائم سماح "*" مع وصول واسع إلى الأدوات.
• اطلب الإشارات في المجموعات إلا إذا كانت الغرفة محكومة بإحكام.
• استخدم session.dmScope: "per-channel-peer" عندما يمكن لعدة أشخاص إرسال رسائل مباشرة إلى البوت.
• وجّه القنوات المشتركة إلى وكلاء بأدوات محدودة ومن دون بيانات اعتماد شخصية.

توافق المزاوجة على تمكين المرسل من تشغيل البوت. لكنها لا تجعل ذلك المرسل حدًا أمنيًا منفصلًا للمضيف.

فحوصات الوكيل العكسي

للوكلاء المدركين للهوية:

• يجب أن يصادق الوكيل المستخدمين قبل إعادة التوجيه إلى Gateway.
• يجب حظر الوصول المباشر إلى منفذ Gateway عبر الجدار الناري أو سياسة الشبكة.
• يجب أن يحتوي gateway.trustedProxies على عناوين IP الخاصة بمصدر الوكيل فقط.
• يجب أن يزيل الوكيل أو يستبدل ترويسات الهوية وإعادة التوجيه المقدمة من العميل.
• ينبغي أن يسرد gateway.auth.trustedProxy.allowUsers المستخدمين المتوقعين عندما يخدم الوكيل أكثر من جمهور واحد.
• ينبغي أن يستخدم وضع وكيل loopback على المضيف نفسه allowLoopback فقط عندما تكون العمليات المحلية موثوقة ويملك الوكيل ترويسات الهوية.

شغّل openclaw security audit --deep بعد تغييرات الوكيل. نتائج الوكيل الموثوق عالية الإشارة عمدًا لأن الوكيل يصبح حد المصادقة.

مراجعة الأدوات والعزل

قبل تعريض وكيل لمرسلين عن بعد:

• تأكد من أي الجلسات تعمل على المضيف مقابل العزل.
• ارفض exec على المضيف أو اطلب موافقة له.
• أبقِ الأدوات ذات الصلاحيات المرتفعة معطلة إلا إذا احتاج إليها مرسل محدد وموثوق.
• تجنب أدوات المتصفح، وcanvas، وnode، وcron، وgateway، وإنشاء الجلسات لأسطح المراسلة المفتوحة أو شبه المفتوحة.
• أبقِ عمليات bind mount ضيقة وتجنب بيانات الاعتماد، ودليل المنزل، ومقبس Docker، ومسارات النظام.
• استخدم بوابات أو مستخدمي نظام تشغيل أو مضيفين منفصلين لحدود الثقة المختلفة ماديًا.

إذا لم يكن المستخدمون عن بعد موثوقين بالكامل، فيجب أن يأتي العزل من عمليات نشر منفصلة، وليس فقط من التعليمات أو تسميات الجلسات.

التحقق بعد التغيير

بعد كل تغيير تعريض:

1. أعد تشغيل openclaw security audit --deep.
2. اختبر اتصالًا مخولًا ناجحًا.
3. اختبر رفض مرسل غير مخول أو جلسة متصفح غير مخولة.
4. تأكد من أن السجلات تخفي الأسرار.
5. تأكد من أن توجيه الرسائل المباشرة/المجموعات يصل فقط إلى الوكيل المقصود.
6. تأكد من أن الأدوات عالية الأثر تطلب الموافقة أو تُرفض.
7. وثّق التحذيرات المتبقية المقبولة.

لا تنتقل إلى تغيير التعريض التالي حتى تفهم الحالي.

خطة التراجع

إذا كان Gateway قد يكون مكشوفًا أكثر من اللازم:

{  gateway: {    bind: "loopback",  },  channels: {    whatsapp: { dmPolicy: "disabled" },    telegram: { dmPolicy: "disabled" },    discord: { dmPolicy: "disabled" },    slack: { dmPolicy: "disabled" },  },  tools: {    exec: { security: "deny", ask: "always" },    elevated: { enabled: false },  },}

ثم:

1. أوقف إعادة التوجيه العام، أو Tailscale Funnel، أو مسارات الوكيل العكسي.
2. دوّر رموز/كلمات مرور Gateway وبيانات اعتماد التكامل المتأثرة.
3. أزل "*" والمرسلين غير المتوقعين من قوائم السماح.
4. راجع سجلات التدقيق الحديثة، وسجل التشغيل، واستدعاءات الأدوات، وتغييرات الإعداد.
5. أعد تشغيل openclaw security audit --deep.
6. أعد تفعيل الوصول بأضيق نمط يلبّي سير العمل.

قائمة تحقق المراجعة

• يبقى Gateway مقتصرًا على loopback إلا إذا كان هناك سبب موثق.
• وصول غير loopback لديه مصادقة، وجدار ناري، ولا يوجد مسار عام مباشر.
• عمليات نشر الوكيل الموثوق لديها عناوين IP صارمة للوكيل وعناصر تحكم في الترويسات.
• تستخدم الرسائل المباشرة المزاوجة أو قوائم السماح، وليس الوصول المفتوح افتراضيًا.
• تتطلب المجموعات إشارات أو قوائم سماح صريحة.
• لا تصل القنوات المشتركة إلى بيانات اعتماد شخصية.
• تعمل الجلسات غير الرئيسية في وضع العزل.
• يتم رفض exec على المضيف والأدوات ذات الصلاحيات المرتفعة أو تقييدها بالموافقة.
• تخفي السجلات الأسرار.
• تمت معالجة نتائج التدقيق الحرجة.
• تم اختبار خطوات التراجع وتوثيقها.