مصادقة الوكيل الموثوق

متى يُستخدم

• تشغّل OpenClaw خلف وكيل مدرك للهوية (Pomerium، أو Caddy + OAuth، أو nginx + oauth2-proxy، أو Traefik + مصادقة مُمرّرة).
• يتولى وكيلك جميع عمليات المصادقة ويمرر هوية المستخدم عبر الترويسات.
• تعمل في بيئة Kubernetes أو حاويات يكون فيها الوكيل هو المسار الوحيد إلى Gateway.
• تواجه أخطاء WebSocket من نوع 1008 unauthorized لأن المتصفحات لا تستطيع تمرير الرموز المميزة في حمولات WS.

متى يجب عدم استخدامه

• لا يصادق وكيلك المستخدمين (بل يعمل فقط كنقطة إنهاء TLS أو موازن حمل).
• يوجد أي مسار إلى Gateway يتجاوز الوكيل (ثغرات في جدار الحماية أو وصول عبر الشبكة الداخلية).
• لست متأكدًا مما إذا كان وكيلك يزيل الترويسات المُمرّرة أو يستبدلها بشكل صحيح.
• لا تحتاج إلا إلى وصول شخصي لمستخدم واحد (فكّر في استخدام Tailscale Serve + local loopback بدلًا من ذلك).

آلية العمل

الإعداد

{  gateway: {    // Trusted-proxy auth expects the proxy's source IP to be non-loopback by default    bind: "lan",     // CRITICAL: Only add your proxy's IP(s) here    trustedProxies: ["10.0.0.1", "172.17.0.1"],     auth: {      mode: "trusted-proxy",      trustedProxy: {        // Header containing authenticated user identity (required)        userHeader: "x-forwarded-user",         // Optional: headers that MUST be present (proxy verification)        requiredHeaders: ["x-forwarded-proto", "x-forwarded-host"],         // Optional: restrict to specific users (empty = allow all)        allowUsers: ["nick@example.com", "admin@company.org"],         // Optional: allow a same-host loopback proxy after explicit opt-in        allowLoopback: false,      },    },  },}

مرجع الإعداد

سلوك إقران واجهة التحكم

عندما يكون gateway.auth.mode = "trusted-proxy" نشطًا ويجتاز الطلب عمليات تحقق الوكيل الموثوق، يمكن لجلسات WebSocket الخاصة بواجهة التحكم الاتصال دون هوية إقران الجهاز.

الآثار المتعلقة بالنطاق:

• تتصل جلسات WebSocket الخاصة بواجهة التحكم التي لا ترتبط بجهاز، لكنها لا تتلقى افتراضيًا أي نطاقات للمشغّل. يمسح OpenClaw قائمة النطاقات المطلوبة إلى [] لكي لا تتمكن جلسة غير مرتبطة بجهاز أو رمز مميز مقترن ومعتمد من التصريح بأذوناتها ذاتيًا.
• إذا فشلت الأساليب برسالة missing scope بعد نجاح اتصال WebSocket، فاستخدم HTTPS لكي يتمكن المتصفح من إنشاء هوية الجهاز وإكمال الإقران. راجع استخدام HTTP غير الآمن لواجهة التحكم.
• للاستخدام الطارئ فقط: يحافظ gateway.controlUi.dangerouslyDisableDeviceAuth=true على النطاقات المطلوبة حتى دون هوية جهاز. يمثل هذا خفضًا أمنيًا شديدًا؛ تراجع عنه بسرعة. راجع استخدام HTTP غير الآمن لواجهة التحكم.

تقييد النطاقات عبر الوكيل العكسي: إذا أرسل وكيلك x-openclaw-scopes في طلب ترقية WebSocket الخاص بواجهة التحكم، يقيّد OpenClaw نطاقات الجلسة إلى تقاطع النطاقات المطلوبة مع النطاقات المعلنة. لا تمنح هذه الترويسة نطاقات؛ بل تضيّق فقط ما يمكن للجلسة الاحتفاظ به.

الآثار:

• لم يعد الإقران هو البوابة الأساسية للوصول إلى واجهة التحكم في هذا الوضع.
• تصبح سياسة المصادقة في وكيلك العكسي وallowUsers آلية التحكم الفعلية في الوصول.
• أبقِ حركة المرور الواردة إلى Gateway مقصورة على عناوين IP للوكلاء الموثوقين فقط (gateway.trustedProxies + جدار الحماية).

عملاء WebSocket المخصصون ليسوا جلسات لواجهة التحكم. لا يمنح gateway.controlUi.dangerouslyDisableDeviceAuth نطاقات لعملاء عشوائيين يستخدمون client.mode: "backend" أو يتخذون شكل عملاء CLI. يجب أن تستخدم الأتمتة المخصصة هوية الجهاز والإقران، أو مسار مساعد الواجهة الخلفية المحلي المباشر المحجوز client.id: "gateway-client"، أو Plugin استدعاء HTTP RPC الإداري عندما تكون واجهة طلب/استجابة HTTP أنسب.

ترويسة نطاقات المشغّل

مصادقة الوكيل الموثوق هي وضع HTTP يحمل الهوية، لذلك يمكن للمتصلين اختياريًا إعلان نطاقات المشغّل باستخدام x-openclaw-scopes في طلبات HTTP API.

ملاحظة: تحدد مصافحة بروتوكول Gateway وربط هوية الجهاز نطاقات WebSocket. في طلبات ترقية WebSocket الخاصة بواجهة التحكم، لا تمثل x-openclaw-scopes سوى حد أقصى لنطاقات الجلسة المتفاوض عليها، وليست منحة. راجع سلوك إقران واجهة التحكم.

أمثلة:

• x-openclaw-scopes: operator.read
• x-openclaw-scopes: operator.read,operator.write
• x-openclaw-scopes: operator.admin,operator.write

السلوك:

• عندما تكون الترويسة موجودة، يحترم OpenClaw مجموعة النطاقات المعلنة.
• عندما تكون الترويسة موجودة لكنها فارغة، يعلن الطلب عدم وجود أي نطاقات للمشغّل.
• عندما تكون الترويسة غائبة، ترجع واجهات HTTP API العادية الحاملة للهوية إلى مجموعة نطاقات المشغّل الافتراضية القياسية (operator.admin وoperator.read وoperator.write وoperator.approvals وoperator.pairing وoperator.talk.secrets).
• تكون مسارات HTTP الخاصة بالـ Plugin والمصادَق عليها عبر Gateway أضيق افتراضيًا: عند غياب x-openclaw-scopes، يرجع نطاق وقت التشغيل الخاص بها إلى operator.write فقط.
• يجب أن تجتاز طلبات HTTP الصادرة من المتصفح gateway.controlUi.allowedOrigins (أو وضع الرجوع المتعمد إلى ترويسة Host) حتى بعد نجاح مصادقة الوكيل الموثوق.

قاعدة عملية: أرسل x-openclaw-scopes صراحةً عندما تريد أن يكون طلب الوكيل الموثوق أضيق من الإعدادات الافتراضية، أو عندما يحتاج مسار Plugin مصادَق عليه عبر Gateway إلى صلاحية أقوى من نطاق الكتابة.

إنهاء TLS وHSTS

استخدم نقطة واحدة لإنهاء TLS وطبّق HSTS فيها.

Strict-Transport-Security: max-age=31536000; includeSubDomains

{  gateway: {    tls: { enabled: true },    http: {      securityHeaders: {        strictTransportSecurity: "max-age=31536000; includeSubDomains",      },    },  },}

إرشادات الطرح

• ابدأ أولًا بعمر أقصى قصير (مثل max-age=300) أثناء التحقق من حركة المرور.
• زِد القيمة إلى مدة طويلة (مثل max-age=31536000) فقط بعد اكتساب ثقة عالية.
• أضف includeSubDomains فقط إذا كانت جميع النطاقات الفرعية جاهزة لاستخدام HTTPS.
• استخدم التحميل المسبق فقط إذا كنت تستوفي عمدًا متطلباته لمجموعة نطاقاتك الكاملة.
• لا تستفيد بيئة التطوير المحلية التي تقتصر على local loopback من HSTS.

أمثلة على إعداد الوكيل

{  gateway: {    bind: "lan",    trustedProxies: ["10.0.0.1"], // Pomerium's IP    auth: {      mode: "trusted-proxy",      trustedProxy: {        userHeader: "x-pomerium-claim-email",        requiredHeaders: ["x-pomerium-jwt-assertion"],      },    },  },}

routes:  - from: https://openclaw.example.com    to: http://openclaw-gateway:18789    policy:      - allow:          or:            - email:                is: nick@example.com    pass_identity_headers: true

{  gateway: {    bind: "lan",    trustedProxies: ["10.0.0.1"], // عنوان IP لوكيل Caddy/sidecar    auth: {      mode: "trusted-proxy",      trustedProxy: {        userHeader: "x-forwarded-user",      },    },  },}

openclaw.example.com {    authenticate with oauth2_provider    authorize with policy1     reverse_proxy openclaw:18789 {        header_up X-Forwarded-User {http.auth.user.email}    }}

{  gateway: {    bind: "lan",    trustedProxies: ["10.0.0.1"], // عنوان IP لـ nginx/oauth2-proxy    auth: {      mode: "trusted-proxy",      trustedProxy: {        userHeader: "x-auth-request-email",      },    },  },}

location / {    auth_request /oauth2/auth;    auth_request_set $user $upstream_http_x_auth_request_email;     proxy_pass http://openclaw:18789;    proxy_set_header X-Auth-Request-Email $user;    proxy_http_version 1.1;    proxy_set_header Upgrade $http_upgrade;    proxy_set_header Connection "upgrade";}

{  gateway: {    bind: "lan",    trustedProxies: ["172.17.0.1"], // عنوان IP لحاوية Traefik    auth: {      mode: "trusted-proxy",      trustedProxy: {        userHeader: "x-forwarded-user",      },    },  },}

إعداد الرموز المميّزة المختلط

يرفض بدء تشغيل Gateway مصادقة الوكيل الموثوق إذا كان رمز مميّز مشترك مُعدًّا أيضًا (gateway.auth.token أو OPENCLAW_GATEWAY_TOKEN). الخياران متنافيان، لأن الرمز المميّز المشترك سيسمح للمتصلين من المضيف نفسه بالمصادقة عبر مسار مختلف تمامًا عن الهوية التي تحقق منها الوكيل، والتي صُمم هذا الوضع لفرضها.

إذا فشل بدء التشغيل برسالة خطأ مثل gateway auth mode is trusted-proxy, but a shared token is also configured:

• أزل الرمز المميّز المشترك عند استخدام وضع الوكيل الموثوق، أو
• غيّر gateway.auth.mode إلى "token" إذا كنت تقصد استخدام المصادقة المستندة إلى رمز مميّز.

تظل ترويسات هوية الوكيل الموثوق عبر local loopback تفشل بشكل مغلق: لا تتم مصادقة المتصلين من المضيف نفسه ضمنيًا كمستخدمي الوكيل. ويمكن لمتصلِي OpenClaw الداخليين الذين يتجاوزون الوكيل المصادقة باستخدام gateway.auth.password / OPENCLAW_GATEWAY_PASSWORD بدلًا من ذلك. يظل الرجوع إلى الرمز المميّز غير مدعوم عمدًا في وضع الوكيل الموثوق.

قائمة التحقق الأمنية

قبل تمكين مصادقة الوكيل الموثوق، تحقق مما يلي:

• [ ] الوكيل هو المسار الوحيد: منفذ Gateway محمي بجدار ناري من كل شيء باستثناء وكيلك.
• [ ] trustedProxies في حدها الأدنى: عناوين IP الفعلية لوكيلك فقط، وليس شبكات فرعية كاملة.
• [ ] مصدر وكيل local loopback مقصود: تفشل مصادقة الوكيل الموثوق بشكل مغلق للطلبات ذات مصدر local loopback ما لم يُمكّن gateway.auth.trustedProxy.allowLoopback صراحةً لوكيل على المضيف نفسه.
• [ ] الوكيل يزيل الترويسات: يستبدل وكيلك ترويسات x-forwarded-* الواردة من العملاء، ولا يلحقها.
• [ ] إنهاء TLS: يتولى وكيلك TLS؛ ويتصل المستخدمون عبر HTTPS.
• [ ] allowedOrigins محددة صراحةً: تستخدم واجهة التحكم غير المتصلة عبر local loopback قيمة صريحة لـ gateway.controlUi.allowedOrigins.
• [ ] allowUsers مضبوطة (موصى به): اقصر الوصول على المستخدمين المعروفين بدلًا من السماح لأي مستخدم تمت مصادقته.
• [ ] لا يوجد إعداد مختلط للرمز المميّز: لا تضبط كلًا من gateway.auth.token وgateway.auth.mode: "trusted-proxy".
• [ ] الرجوع المحلي إلى كلمة المرور خاص: إذا أعددت gateway.auth.password للمتصلين الداخليين المباشرين، فأبقِ منفذ Gateway محميًا بجدار ناري بحيث لا يتمكن العملاء البعيدون غير المارين بالوكيل من الوصول إليه مباشرةً.

التدقيق الأمني

يُبلغ openclaw security audit عن مصادقة الوكيل الموثوق كنتيجة ذات خطورة حرجة. هذا مقصود؛ فهو تذكير بأنك تفوض الأمان إلى إعداد وكيلك.

يتحقق التدقيق مما يلي:

• التحذير/التذكير الحرج الأساسي gateway.trusted_proxy_auth.
• غياب إعداد trustedProxies.
• غياب إعداد userHeader.
• كون allowUsers فارغة (ما يسمح لأي مستخدم تمت مصادقته).
• تمكين allowLoopback لمصادر الوكيل الموجودة على المضيف نفسه.

تنطبق أيضًا نتائج منفصلة غير خاصة بالوكيل الموثوق كلما كانت واجهة التحكم مكشوفة: استخدام حرف بدل أو غياب gateway.controlUi.allowedOrigins، والرجوع إلى أصل ترويسة Host.

استكشاف الأخطاء وإصلاحها

الترحيل من مصادقة الرمز المميّز

ذات صلة

• الإعداد — مرجع الإعدادات
• نطاقات المشغّل — الأدوار والنطاقات وعمليات تحقق الموافقة
• الوصول عن بُعد — أنماط أخرى للوصول عن بُعد
• الأمان — دليل الأمان الكامل
• Tailscale — بديل أبسط للوصول المقصور على tailnet