المتصفح (تديره OpenClaw)

يمكن لـ OpenClaw تشغيل ملف شخصي مخصص في Chrome/Brave/Edge/Chromium يتحكم فيه الوكيل. ويعمل من خلال خدمة تحكم محلية صغيرة داخل Gateway (على واجهة الاسترجاع فقط)، ويكون معزولًا عن متصفحك الشخصي.

• اعتبره متصفحًا منفصلًا مخصصًا للوكيل فقط. لا يتعامل الملف الشخصي openclaw مطلقًا مع ملف متصفحك الشخصي.
• يفتح الوكيل علامات التبويب، ويقرأ الصفحات، وينقر، ويكتب ضمن هذه البيئة المعزولة.
• أما الملف الشخصي المضمّن user فيتصل بدلًا من ذلك بجلسة Chrome الحقيقية التي سجلت الدخول إليها، عبر Chrome DevTools MCP.

ما الذي تحصل عليه

• ملف متصفح شخصي منفصل باسم openclaw (بتمييز برتقالي افتراضيًا).
• تحكم حتمي في علامات التبويب (السرد/الفتح/التركيز/الإغلاق).
• إجراءات الوكيل (النقر/الكتابة/السحب/التحديد)، واللقطات، ولقطات الشاشة، وملفات PDF.
• تحفظ الملفات الشخصية المدعومة من Playwright عمليات الانتقال المباشر إلى المرفقات ضمن دليل التنزيلات المُدار، وتُرجع بيانات { url, suggestedFilename, path } الوصفية بعد التحقق من سياسة عنوان URL النهائي.
• تُرجع إجراءات الوكيل المدعومة من Playwright مصفوفة downloads تحتوي على البيانات الوصفية المُدارة نفسها عندما يبدأ الإجراء فورًا تنزيلًا واحدًا أو أكثر.
• مهارة browser-automation مضمّنة تعلّم الوكلاء حلقة استرداد اللقطة، وعلامة التبويب الثابتة، والمرجع القديم، والعائق اليدوي عند تمكين Plugin المتصفح.
• دعم اختياري لملفات شخصية متعددة (openclaw، وwork، وremote، ...).

هذا المتصفح ليس متصفحك اليومي. بل هو سطح آمن ومعزول لأتمتة الوكيل والتحقق.

في macOS، يمكنك نسخ ملفات تعريف الارتباط صراحةً من ملف نظام شخصي تابع لعائلة Chrome إلى ملف شخصي مُدار منفصل. يظل المتصفح المُدار يستخدم دليل بيانات المستخدم الخاص به؛ ولا تُنسخ إلا ملفات تعريف الارتباط المحددة، بينما يظل التخزين المحلي وIndexedDB دون نسخ. راجع الملفات الشخصية أو مرجع CLI الخاص بـ openclaw browser للاطلاع على أوامر الاستيراد والقيود.

البدء السريع

openclaw browser --browser-profile openclaw doctoropenclaw browser --browser-profile openclaw doctor --deepopenclaw browser --browser-profile openclaw statusopenclaw browser --browser-profile openclaw startopenclaw browser --browser-profile openclaw open https://example.comopenclaw browser --browser-profile openclaw snapshot

تعني عبارة "المتصفح معطّل" أن Plugin أو browser.enabled متوقف؛ راجع الإعداد والتحكم في Plugin.

إذا كان openclaw browser مفقودًا تمامًا، أو أفاد الوكيل بأن أداة المتصفح غير متاحة، فانتقل إلى أمر المتصفح أو أداته مفقودان.

التحكم في Plugin

الأداة الافتراضية browser هي Plugin مضمّن. عطّله لاستبداله بـ Plugin آخر يسجّل اسم الأداة browser نفسه:

{  plugins: {    entries: {      browser: {        enabled: false,      },    },  },}

تحتاج الإعدادات الافتراضية إلى كل من plugins.entries.browser.enabled وbrowser.enabled=true. يؤدي تعطيل Plugin وحده إلى إزالة CLI ‏openclaw browser، وطريقة Gateway ‏browser.request، وأداة الوكيل، وخدمة التحكم كوحدة واحدة؛ بينما يظل إعداد browser.* سليمًا لاستخدامه مع البديل.

تتطلب تغييرات إعداد المتصفح إعادة تشغيل Gateway لكي يتمكن Plugin من إعادة تسجيل خدمته.

إرشادات الوكيل

ملاحظة حول ملف الأدوات الشخصي: يتضمن tools.profile: "coding" كلًا من web_search و web_fetch، لكن ليس أداة browser الكاملة. للسماح للوكيل أو لوكيل فرعي مُنشأ باستخدام أتمتة المتصفح، أضف المتصفح في مرحلة الملف الشخصي:

{  tools: {    profile: "coding",    alsoAllow: ["browser"],  },}

بالنسبة إلى وكيل واحد، استخدم agents.list[].tools.alsoAllow: ["browser"]. لا يكفي tools.subagents.tools.allow: ["browser"] وحده لأن سياسة الوكيل الفرعي تُطبَّق بعد تصفية الملف الشخصي.

يتضمن Plugin المتصفح مستويين من إرشادات الوكيل:

• يحمل وصف الأداة browser العقد الموجز الدائم: اختر الملف الشخصي الصحيح، وأبقِ المراجع في علامة التبويب نفسها، واستخدم tabId/التسميات لاستهداف علامات التبويب، وحمّل مهارة المتصفح للعمل متعدد الخطوات.
• تحمل مهارة browser-automation المضمّنة حلقة التشغيل الأطول: تحقّق أولًا من الحالة/علامات التبويب، وسمِّ علامات تبويب المهمة، والتقط لقطة قبل التنفيذ، وأعد التقاط لقطة بعد تغييرات واجهة المستخدم، واستعد المراجع القديمة مرة واحدة، وأبلغ عن عوائق تسجيل الدخول/المصادقة الثنائية/اختبار CAPTCHA أو الكاميرا/الميكروفون باعتبارها إجراءً يدويًا بدلًا من التخمين.

تُدرج المهارات المضمّنة في Plugin ضمن المهارات المتاحة للوكيل عند تمكين Plugin. وتُحمَّل تعليمات المهارة الكاملة عند الطلب، لذا لا تتحمل التفاعلات الاعتيادية تكلفة الرموز المميزة الكاملة.

أمر المتصفح أو أداته مفقودان

إذا كان openclaw browser غير معروف بعد ترقية، أو كان browser.request مفقودًا، أو أفاد الوكيل بأن أداة المتصفح غير متاحة، فالسبب المعتاد هو قائمة plugins.allow لا تتضمن browser مع عدم وجود كتلة إعداد browser في الجذر. أضفها:

{  plugins: {    allow: ["telegram", "browser"],  },}

تؤدي كتلة الجذر الصريحة browser (أي مفتاح ضمن browser، مثل browser.enabled=true أو browser.profiles.<name>) إلى تنشيط Plugin المتصفح المضمّن حتى في ظل plugins.allow مقيّد، بما يتطابق مع سلوك إعداد القناة المضمّنة. ولا يحل plugins.entries.browser.enabled=true و tools.alsoAllow: ["browser"] بمفردهما محل العضوية في قائمة السماح. كما تؤدي إزالة plugins.allow بالكامل إلى استعادة الإعداد الافتراضي.

الملفات الشخصية: openclaw، وuser، وchrome

• openclaw: متصفح مُدار ومعزول (لا يتطلب إضافة).
• user: ملف شخصي مضمّن للاتصال عبر Chrome DevTools MCP بجلسة Chrome الحقيقية التي سجلت الدخول إليها. يعرض Chrome مطالبة حاجبة بعنوان "Allow remote debugging?" في المرة الأولى التي يتصل فيها OpenClaw، لذا يجب أن يكون شخص ما أمام الحاسوب.
• chrome: ملف شخصي مضمّن لـ إضافة Chrome مخصص لجلسة Chrome الحقيقية التي سجلت الدخول إليها. يعمل من الهاتف دون وجود أحد أمام المكتب، لأنه يتحكم في علامات التبويب من خلال إضافة متصفح OpenClaw بدلًا من منفذ تصحيح الأخطاء عن بُعد، ولذلك لا تظهر مطالبة "Allow remote debugging?".

بالنسبة إلى استدعاءات أداة المتصفح التي يجريها الوكيل:

• الإعداد الافتراضي: استخدم متصفح openclaw المعزول.
• فضّل profile="chrome" (الإضافة) عندما تكون جلسات تسجيل الدخول الحالية مهمة ويكون المستخدم بعيدًا عن الحاسوب (Telegram، وWhatsApp، وما إلى ذلك).
• فضّل profile="user" (Chrome MCP) عندما تكون جلسات تسجيل الدخول الحالية مهمة ويكون المستخدم أمام الحاسوب للموافقة على مطالبة الاتصال.
• يمثل profile التجاوز الصريح عندما تريد وضع متصفح محددًا.

عيّن browser.defaultProfile: "openclaw" إذا كنت تريد الوضع المُدار افتراضيًا.

الإعداد

توجد إعدادات المتصفح في ~/.openclaw/openclaw.json.

{  browser: {    enabled: true, // الافتراضي: true    evaluateEnabled: true, // الافتراضي: true؛ تؤدي false إلى تعطيل act:evaluate (تعليمة JavaScript عشوائية)    ssrfPolicy: {      // dangerouslyAllowPrivateNetwork: true, // اشترك فقط للوصول الموثوق إلى الشبكة الخاصة      // hostnameAllowlist: ["*.example.com", "example.com"],      // allowedHostnames: ["localhost"],    },    // cdpUrl: "http://127.0.0.1:18792", // تجاوز قديم للملف الشخصي الواحد    remoteCdpTimeoutMs: 1500, // مهلة HTTP البعيدة لـ CDP (مللي ثانية)    remoteCdpHandshakeTimeoutMs: 3000, // مهلة مصافحة WebSocket البعيدة لـ CDP (مللي ثانية)    localLaunchTimeoutMs: 15000, // مهلة اكتشاف Chrome المُدار المحلي (مللي ثانية)    localCdpReadyTimeoutMs: 8000, // مهلة جاهزية CDP المحلية بعد التشغيل المُدار (مللي ثانية)    actionTimeoutMs: 60000, // مهلة إجراء المتصفح الافتراضية (مللي ثانية)    tabCleanup: {      enabled: true, // الافتراضي: true      idleMinutes: 120, // عيّن 0 لتعطيل تنظيف الخمول      maxTabsPerSession: 8, // عيّن 0 لتعطيل الحد الأقصى لكل جلسة      sweepMinutes: 5,    },    // snapshotDefaults: { mode: "efficient" }, // وضع اللقطة الافتراضي عندما لا يحدده المستدعي    defaultProfile: "openclaw",    color: "#FF4500",    headless: false,    noSandbox: false,    attachOnly: false,    executablePath: "/Applications/Brave Browser.app/Contents/MacOS/Brave Browser",    profiles: {      openclaw: { cdpPort: 18800, color: "#FF4500" },      work: {        cdpPort: 18801,        color: "#0066CC",        headless: true,        executablePath: "/Applications/Google Chrome.app/Contents/MacOS/Google Chrome",      },      user: {        driver: "existing-session",        attachOnly: true,        color: "#00AA00",      },      brave: {        driver: "existing-session",        attachOnly: true,        userDataDir: "~/Library/Application Support/BraveSoftware/Brave-Browser",        color: "#FB542B",      },      remote: { cdpUrl: "http://10.0.0.42:9222", color: "#00AA00" },    },  },}

يغيّر browser.snapshotDefaults.mode: "efficient" وضع الاستخراج الافتراضي snapshot عندما لا يمرر المستدعي snapshotFormat أو mode صريحًا؛ راجع واجهة API للتحكم في المتصفح للاطلاع على خيارات اللقطة لكل استدعاء.

الرؤية في لقطات الشاشة (دعم النماذج النصية فقط)

عندما يكون النموذج الرئيسي نصيًا فقط (من دون دعم الرؤية/الوسائط المتعددة)، تُرجع لقطات شاشة المتصفح كتل صور لا يستطيع النموذج قراءتها. تعيد لقطات شاشة المتصفح استخدام إعداد فهم الصور الحالي، بحيث يمكن لنموذج صور مُعد لفهم الوسائط وصف لقطات الشاشة نصيًا من دون أي إعدادات نموذج خاصة بالمتصفح.

{  tools: {    media: {      image: {        models: [          { provider: "bytedance", model: "doubao-seed-2.0-pro" },          // أضف خيارات احتياطية؛ أول نجاح هو المعتمد          { provider: "openai", model: "gpt-4o" },        ],      },      // تعمل نماذج الوسائط المشتركة أيضًا عند وسمها لدعم الصور.      // models: [{ provider: "openai", model: "gpt-4o", capabilities: ["image"] }],    },  },  agents: {    defaults: {      // تُراعى أيضًا الإعدادات الافتراضية الحالية لنموذج الصور.      // imageModel: { primary: "openai/gpt-4o" },    },  },}

آلية العمل:

1. يستدعي الوكيل browser screenshot وتُلتقط صورة إلى القرص كالمعتاد.
2. تسأل أداة المتصفح بيئة تشغيل فهم الصور الحالية عما إذا كان بإمكانها وصف لقطة الشاشة باستخدام نماذج صور الوسائط المُعدّة، أو نماذج الوسائط المشتركة، أو الإعدادات الافتراضية لنموذج الصور، أو موفر صور مدعوم بالمصادقة.
3. يُرجع نموذج الرؤية وصفًا نصيًا، ويُغلّف بـ wrapExternalContent (حماية من حقن المطالبات)، ثم يُعاد إلى الوكيل ككتلة نصية بدلًا من كتلة صورة.
4. إذا لم يكن فهم الصور متاحًا، أو جرى تخطيه، أو فشل، يعود المتصفح إلى إرجاع كتلة الصورة الأصلية.

كتل صور لقطات الشاشة هي نتائج خاصة للأداة: يمكن للوكيل فحصها، لكن OpenClaw لا يرفقها تلقائيًا بردود القنوات. لمشاركة لقطة شاشة، اطلب من الوكيل إرسالها صراحةً باستخدام أداة الرسائل.

استخدم حقول tools.media.image / tools.media.models الحالية للخيارات الاحتياطية للنماذج، والمهل الزمنية، وحدود البايتات، والملفات الشخصية، وإعدادات طلبات الموفّر.

إذا كان النموذج الرئيسي النشط يدعم الرؤية بالفعل ولم يُعدّ أي نموذج صريح لفهم الصور، يحتفظ OpenClaw بنتيجة الصورة العادية كي يتمكن النموذج الرئيسي من قراءة لقطة الشاشة مباشرةً.

استخدام Brave أو متصفح آخر مبني على Chromium

إذا كان متصفح النظام الافتراضي لديك مبنيًا على Chromium ‏(Chrome/Brave/Edge/إلخ)، فسيستخدمه OpenClaw تلقائيًا. اضبط browser.executablePath لتجاوز الاكتشاف التلقائي. تقبل قيم executablePath على المستوى الأعلى ولكل ملف تعريف ~ لمجلد المستخدم الرئيسي في نظام التشغيل:

openclaw config set browser.executablePath "/usr/bin/google-chrome"openclaw config set browser.profiles.work.executablePath "/Applications/Google Chrome.app/Contents/MacOS/Google Chrome"

أو اضبطه في الإعداد، لكل منصة:

{browser: {executablePath: "/Applications/Brave Browser.app/Contents/MacOS/Brave Browser",},}

{browser: {executablePath: "C:\\Program Files\\BraveSoftware\\Brave-Browser\\Application\\brave.exe",},}

{browser: {executablePath: "/usr/bin/brave-browser",},}

لا يؤثر executablePath الخاص بكل ملف تعريف إلا في ملفات التعريف المحلية المُدارة التي يشغّلها OpenClaw. تتصل ملفات تعريف existing-session بمتصفح قيد التشغيل بالفعل بدلًا من ذلك، وتستخدم ملفات تعريف CDP البعيدة المتصفح الموجود خلف cdpUrl.

التحكم المحلي مقابل البعيد

• التحكم المحلي (الافتراضي): يبدأ Gateway خدمة التحكم على عنوان الاسترجاع المحلي ويمكنه تشغيل متصفح محلي.
• التحكم البعيد (مضيف Node): شغّل مضيف Node على الجهاز الذي يحتوي على المتصفح؛ ويمرر Gateway إجراءات المتصفح إليه عبر وكيل.
• CDP البعيد: اضبط browser.profiles.<name>.cdpUrl (أو browser.cdpUrl) للاتصال بمتصفح بعيد مبني على Chromium. في هذه الحالة، لن يشغّل OpenClaw متصفحًا محليًا.
• بالنسبة إلى خدمات CDP المُدارة خارجيًا على عنوان الاسترجاع المحلي (على سبيل المثال Browserless في Docker والمنشورة على 127.0.0.1)، اضبط أيضًا attachOnly: true. يُعامل CDP عبر الاسترجاع المحلي من دون attachOnly على أنه ملف تعريف متصفح محلي يديره OpenClaw.
• لا يؤثر headless إلا في ملفات التعريف المحلية المُدارة التي يشغّلها OpenClaw. ولا يعيد تشغيل متصفحات الجلسات الموجودة أو CDP البعيدة ولا يغيّرها.
• يتبع executablePath قاعدة ملف التعريف المحلي المُدار نفسها. يؤدي تغييره في ملف تعريف محلي مُدار وقيد التشغيل إلى وضع علامة على ملف التعريف لإعادة التشغيل/التسوية حتى يستخدم التشغيل التالي الملف التنفيذي الجديد.

يختلف سلوك الإيقاف حسب وضع ملف التعريف:

• ملفات التعريف المحلية المُدارة: يوقف openclaw browser stop عملية المتصفح التي شغّلها OpenClaw
• ملفات تعريف الاتصال فقط وCDP البعيدة: يغلق openclaw browser stop جلسة التحكم النشطة ويحرر تجاوزات محاكاة Playwright/CDP (إطار العرض، ونظام الألوان، والإعدادات المحلية، والمنطقة الزمنية، ووضع عدم الاتصال، والحالات المشابهة)، رغم أن OpenClaw لم يشغّل أي عملية متصفح

يمكن أن تتضمن عناوين URL البعيدة لـ CDP مصادقة:

• رموز الاستعلام (مثل https://provider.example?token=<token>)
• مصادقة HTTP الأساسية (مثل https://user:pass@provider.example)

يحافظ OpenClaw على المصادقة عند استدعاء نقاط نهاية /json/* وعند الاتصال بـ CDP WebSocket. يُفضّل استخدام متغيرات البيئة أو مديري الأسرار للرموز بدلًا من حفظها في ملفات الإعداد.

وكيل متصفح Node (إعداد افتراضي بلا تهيئة)

إذا شغّلت مضيف Node على الجهاز الذي يحتوي على متصفحك، فيمكن لـ OpenClaw توجيه استدعاءات أداة المتصفح تلقائيًا إلى ذلك الـ Node من دون أي إعداد إضافي للمتصفح. وهذا هو المسار الافتراضي للبوابات البعيدة.

ملاحظات:

• يُتيح مضيف Node خادم التحكم المحلي في المتصفح عبر أمر وكيل.
• تأتي الملفات الشخصية من إعداد browser.profiles الخاص بالـ Node نفسه (كما في الوضع المحلي).
• لا يسمح أمر الوكيل مطلقًا بإجراء تعديلات دائمة على الملفات الشخصية (create-profile، delete-profile، reset-profile) بغض النظر عن allowProfiles؛ أجرِ هذه التغييرات مباشرةً على الـ Node.
• nodeHost.browserProxy.allowProfiles اختياري. اتركه فارغًا للسلوك القديم/الافتراضي: تظل جميع الملفات الشخصية المُعدّة قابلة للوصول عبر الوكيل.
• إذا عيّنت nodeHost.browserProxy.allowProfiles، فسيتعامل OpenClaw معه بوصفه حدًا لأقل الامتيازات يقيّد أسماء الملفات الشخصية التي سيستهدفها الوكيل.
• عطّله إذا لم تكن تريده:
  • على الـ Node: nodeHost.browserProxy.enabled=false
  • على Gateway: gateway.nodes.browser.mode="off" (يقبل أيضًا "auto" لاختيار Node متصفح متصل واحد، أو "manual" لطلب معامل Node صريح)

Browserless (‏CDP بعيد مُستضاف)

Browserless خدمة Chromium مُستضافة تتيح عناوين URL لاتصال CDP عبر HTTPS وWebSocket. يمكن لـ OpenClaw استخدام أيٍّ من الصيغتين، لكن أبسط خيار لملف متصفح بعيد هو عنوان WebSocket URL المباشر من وثائق الاتصال الخاصة بـ Browserless.

مثال:

{  browser: {    enabled: true,    defaultProfile: "browserless",    remoteCdpTimeoutMs: 2000,    remoteCdpHandshakeTimeoutMs: 4000,    profiles: {      browserless: {        cdpUrl: "wss://production-sfo.browserless.io?token=<BROWSERLESS_API_KEY>",        color: "#00AA00",      },    },  },}

ملاحظات:

• استبدل <BROWSERLESS_API_KEY> برمز Browserless الحقيقي الخاص بك.
• اختر نقطة نهاية المنطقة المطابقة لحساب Browserless الخاص بك (راجع وثائقهم).
• إذا زوّدك Browserless بعنوان HTTPS أساسي، فيمكنك إما تحويله إلى wss:// لاتصال CDP مباشر أو الاحتفاظ بعنوان HTTPS وترك OpenClaw يكتشف /json/version.

Browserless Docker على المضيف نفسه

عند استضافة Browserless ذاتيًا في Docker وتشغيل OpenClaw على المضيف، تعامل مع Browserless بوصفه خدمة CDP مُدارة خارجيًا:

{  browser: {    enabled: true,    defaultProfile: "browserless",    profiles: {      browserless: {        cdpUrl: "ws://127.0.0.1:3000",        attachOnly: true,        color: "#00AA00",      },    },  },}

يجب أن يكون العنوان في browser.profiles.browserless.cdpUrl قابلًا للوصول من عملية OpenClaw. ويجب أيضًا أن يعلن Browserless عن نقطة نهاية مطابقة يمكن الوصول إليها؛ عيّن EXTERNAL في Browserless إلى قاعدة WebSocket نفسها المتاحة علنًا لـ OpenClaw، مثل ws://127.0.0.1:3000 أو ws://browserless:3000 أو عنوان ثابت على شبكة Docker خاصة. إذا أعاد /json/version القيمة webSocketDebuggerUrl مشيرةً إلى عنوان لا يستطيع OpenClaw الوصول إليه، فقد يبدو CDP عبر HTTP سليمًا بينما يظل إرفاق WebSocket يفشل.

لا تترك attachOnly من دون تعيين لملف Browserless على عنوان الاسترجاع المحلي. من دون attachOnly، يتعامل OpenClaw مع منفذ الاسترجاع المحلي بوصفه ملف متصفح محليًا مُدارًا وقد يبلغ بأن المنفذ قيد الاستخدام لكنه غير مملوك لـ OpenClaw.

موفّرو CDP عبر WebSocket المباشر

تتيح بعض خدمات المتصفح المُستضافة نقطة نهاية WebSocket مباشرة بدلًا من الاكتشاف القياسي لـ CDP المعتمد على HTTP‏ (/json/version). يقبل OpenClaw ثلاثة أشكال لعناوين CDP URL ويختار استراتيجية الاتصال المناسبة تلقائيًا:

• الاكتشاف عبر HTTP(S) - ‏http://host[:port] أو https://host[:port]. يستدعي OpenClaw ‏/json/version لاكتشاف عنوان مصحح WebSocket، ثم يتصل به. لا يوجد رجوع احتياطي إلى WebSocket.
• نقاط نهاية WebSocket المباشرة - ‏ws://host[:port]/devtools/<kind>/<id> أو wss://... مع مسار /devtools/browser|page|worker|shared_worker|service_worker/<id>. يتصل OpenClaw مباشرةً عبر مصافحة WebSocket ويتجاوز /json/version بالكامل.
• جذور WebSocket المجرّدة - ‏ws://host[:port] أو wss://host[:port] من دون مسار /devtools/... (مثل Browserless، Browserbase). يحاول OpenClaw أولًا الاكتشاف عبر HTTP باستخدام /json/version (مع تطبيع المخطط إلى http/https)؛ فإذا أعاد الاكتشاف webSocketDebuggerUrl، يُستخدم، وإلا يرجع OpenClaw إلى مصافحة WebSocket مباشرة عند الجذر المجرّد. وإذا رفضت نقطة نهاية WebSocket المُعلنة مصافحة CDP لكن الجذر المجرّد المُعدّ قبلها، فإن OpenClaw يرجع إلى ذلك الجذر أيضًا. يتيح ذلك لعنوان ws:// مجرّد يشير إلى Chrome محلي أن يتصل، لأن Chrome لا يقبل ترقيات WebSocket إلا على المسار المحدد لكل هدف من /json/version، بينما يمكن للموفّرين المُستضافين الاستمرار في استخدام نقطة نهاية WebSocket الجذرية عندما تعلن نقطة نهاية الاكتشاف الخاصة بهم عن عنوان URL قصير العمر غير مناسب لـ Playwright CDP.

يستخدم openclaw browser doctor منطق الاكتشاف أولًا ثم الرجوع إلى WebSocket نفسه المستخدم في الإرفاق وقت التشغيل، لذلك لا تُبلغ أدوات التشخيص عن عنوان URL لجذر مجرّد نجح اتصاله على أنه غير قابل للوصول.

Browserbase

Browserbase منصة سحابية لتشغيل متصفحات بلا واجهة رسومية، مع حل CAPTCHA ووضع التخفي والوكلاء السكنيين المضمّنة.

{  browser: {    enabled: true,    defaultProfile: "browserbase",    remoteCdpTimeoutMs: 3000,    remoteCdpHandshakeTimeoutMs: 5000,    profiles: {      browserbase: {        cdpUrl: "wss://connect.browserbase.com?apiKey=<BROWSERBASE_API_KEY>",        color: "#F97316",      },    },  },}

ملاحظات:

• سجّل وانسخ API Key من لوحة معلومات Overview.
• استبدل <BROWSERBASE_API_KEY> بمفتاح API الحقيقي لحساب Browserbase.
• ينشئ Browserbase جلسة متصفح تلقائيًا عند اتصال WebSocket، لذلك لا حاجة إلى خطوة يدوية لإنشاء الجلسة.
• راجع الأسعار لمعرفة الحدود الحالية للمستوى المجاني والخطط المدفوعة.
• راجع وثائق Browserbase للاطلاع على مرجع API الكامل وأدلة SDK وأمثلة التكامل.

Notte

Notte منصة سحابية لتشغيل متصفحات بلا واجهة رسومية، مع التخفي والوكلاء السكنيين وبوابة WebSocket أصلية لـ CDP مضمّنة.

{  browser: {    enabled: true,    defaultProfile: "notte",    remoteCdpTimeoutMs: 3000,    remoteCdpHandshakeTimeoutMs: 5000,    profiles: {      notte: {        cdpUrl: "wss://us-prod.notte.cc/sessions/connect?token=<NOTTE_API_KEY>",        color: "#7C3AED",      },    },  },}

ملاحظات:

• سجّل وانسخ API Key من صفحة إعدادات وحدة التحكم.
• استبدل <NOTTE_API_KEY> بمفتاح API الحقيقي لحساب Notte.
• ينشئ Notte جلسة متصفح تلقائيًا عند اتصال WebSocket، لذلك لا حاجة إلى خطوة يدوية لإنشاء الجلسة. تُتلف الجلسة عند قطع اتصال WebSocket.
• راجع الأسعار لمعرفة الحدود الحالية للمستوى المجاني والخطط المدفوعة.
• راجع وثائق Notte للاطلاع على مرجع API الكامل وأدلة SDK وأمثلة التكامل.

الأمان

أفكار أساسية:

• يقتصر التحكم في المتصفح على عنوان الاسترجاع المحلي؛ ويمر الوصول عبر مصادقة Gateway أو إقران Node.
• تستخدم واجهة HTTP المستقلة للمتصفح على عنوان الاسترجاع المحلي مصادقة السر المشترك فقط: مصادقة حامل رمز Gateway، أو x-openclaw-password، أو مصادقة HTTP الأساسية باستخدام كلمة مرور Gateway المُعدّة.
• لا تقوم ترويسات هوية Tailscale Serve ولا gateway.auth.mode: "trusted-proxy" بمصادقة واجهة المتصفح المستقلة هذه على عنوان الاسترجاع المحلي.
• إذا كان التحكم في المتصفح مفعّلًا ولم تُعدّ مصادقة بسر مشترك، فإن OpenClaw يُنشئ بيانات اعتماد للتحكم في المتصفح تلقائيًا ويخزّنها عند بدء التشغيل: رمزًا عندما تكون gateway.auth.mode هي none، أو كلمة مرور عندما تكون trusted-proxy (وتُخزّن عبر gateway.auth.password كي تتمكن عملاء الاسترجاع المحلي خارج العملية من تحديدها). يُتخطى الإنشاء التلقائي عندما تكون بيانات اعتماد نصية صريحة مُعدّة بالفعل لذلك الوضع، أو عندما تكون gateway.auth.mode هي password.
• أعدّ gateway.auth.token أو gateway.auth.password أو OPENCLAW_GATEWAY_TOKEN أو OPENCLAW_GATEWAY_PASSWORD صراحةً إذا كنت تريد سرًا ثابتًا تتحكم فيه بدلًا من السر المُنشأ.

نصائح CDP البعيد:

• فضّل نقاط النهاية المشفّرة (HTTPS أو WSS) والرموز قصيرة العمر حيثما أمكن.
• تجنّب تضمين الرموز طويلة العمر مباشرةً في ملفات الإعداد.
• أبقِ Gateway وأي مضيفات Node على شبكة خاصة (Tailscale)؛ وتجنّب إتاحتها للعامة.
• تعامل مع عناوين URL/رموز CDP البعيد بوصفها أسرارًا؛ وفضّل متغيرات البيئة أو مديرًا للأسرار.

الملفات الشخصية (متصفحات متعددة)

يدعم OpenClaw عدة ملفات شخصية مسمّاة (إعدادات توجيه). يمكن أن تكون الملفات الشخصية:

• مُدارة بواسطة OpenClaw: مثيل متصفح مخصص قائم على Chromium وله دليل بيانات مستخدم خاص به + منفذ CDP
• بعيدة: عنوان CDP URL صريح (متصفح قائم على Chromium يعمل في مكان آخر)
• جلسة حالية: ملف Chrome الحالي عبر الاتصال التلقائي بـ Chrome DevTools MCP

الإعدادات الافتراضية:

• يُنشأ الملف الشخصي openclaw تلقائيًا إذا لم يكن موجودًا.
• الملف الشخصي user مضمّن لإرفاق جلسة حالية عبر Chrome MCP.
• الملفات الشخصية للجلسات الحالية اختيارية باستثناء user؛ أنشئها باستخدام --driver existing-session.
• تُخصّص منافذ CDP المحلية من النطاق 18800-18899 افتراضيًا.
• يؤدي حذف ملف شخصي إلى نقل دليل بياناته المحلي إلى سلة المهملات.

تقبل جميع نقاط نهاية التحكم ?profile=<name>؛ وتستخدم CLI ‏--browser-profile.

جلسة حالية عبر Chrome DevTools MCP

يمكن لـ OpenClaw أيضًا الإرفاق بملف متصفح قيد التشغيل قائم على Chromium عبر خادم Chrome DevTools MCP الرسمي. يعيد ذلك استخدام علامات التبويب وحالة تسجيل الدخول المفتوحة بالفعل في ملف المتصفح هذا.

مراجع رسمية للخلفية والإعداد:

• Chrome للمطوّرين: استخدام Chrome DevTools MCP مع جلسة متصفحك
• ملف README لـ Chrome DevTools MCP

الملف الشخصي المضمّن: user. أنشئ ملف جلسة حالية مخصصًا إذا كنت تريد اسمًا أو لونًا أو دليل بيانات متصفح مختلفًا.

يستخدم الملف الشخصي المضمّن user افتراضيًا الاتصال التلقائي لـ Chrome MCP، الذي يستهدف ملف Google Chrome المحلي الافتراضي. استخدم userDataDir مع Brave أو Edge أو Chromium أو ملف Chrome غير افتراضي. يتم توسيع ~ إلى دليل المنزل في نظام التشغيل:

{  browser: {    profiles: {      brave: {        driver: "existing-session",        attachOnly: true,        userDataDir: "~/Library/Application Support/BraveSoftware/Brave-Browser",        color: "#FB542B",      },    },  },}

ثم في المتصفح المطابق:

1. افتح صفحة الفحص الخاصة بذلك المتصفح لتصحيح الأخطاء عن بُعد.
2. فعّل تصحيح الأخطاء عن بُعد.
3. أبقِ المتصفح قيد التشغيل ووافق على مطالبة الاتصال عند إرفاق OpenClaw.

صفحات الفحص الشائعة:

• Chrome: ‏chrome://inspect/#remote-debugging
• Brave: ‏brave://inspect/#remote-debugging
• Edge: ‏edge://inspect/#remote-debugging

اختبار دخان للإرفاق المباشر:

openclaw browser --browser-profile user startopenclaw browser --browser-profile user statusopenclaw browser --browser-profile user tabsopenclaw browser --browser-profile user snapshot --format ai

مظاهر النجاح:

• status يعرض driver: existing-session
• status يعرض transport: chrome-mcp
• status يعرض running: true
• tabs يسرد علامات تبويب المتصفح المفتوحة بالفعل
• snapshot يعيد المراجع من علامة التبويب النشطة المحددة

ما يجب التحقق منه إذا لم يعمل الإرفاق:

• إصدار المتصفح المستهدف المستند إلى Chromium هو 144+
• تمكين تصحيح الأخطاء عن بُعد في صفحة الفحص الخاصة بذلك المتصفح
• عرض المتصفح مطالبة الموافقة على الإرفاق وقبولك لها
• إذا شُغّل Chrome باستخدام --remote-debugging-port صريح، فاضبط browser.profiles.<name>.cdpUrl على نقطة نهاية DevTools تلك بدلًا من الاعتماد على الاتصال التلقائي لـ Chrome MCP
• openclaw doctor ينقل إعدادات المتصفح القديمة المستندة إلى الإضافة ويتحقق من تثبيت Chrome محليًا لملفات الاتصال التلقائي الافتراضية، لكنه لا يستطيع تمكين تصحيح الأخطاء عن بُعد من جانب المتصفح نيابةً عنك

استخدام الوكيل:

• استخدم profile="user" عند الحاجة إلى حالة متصفح المستخدم الذي سجّل الدخول.
• إذا كنت تستخدم ملف جلسة حالية مخصصًا، فمرّر اسم ذلك الملف صراحةً.
• اختر هذا الوضع فقط عندما يكون المستخدم أمام الحاسوب للموافقة على مطالبة الإرفاق.
• يمكن لمضيف Gateway أو Node تشغيل npx chrome-devtools-mcp@latest --autoConnect.

ملاحظات:

• هذا المسار أعلى خطورة من ملف openclaw المعزول لأنه يستطيع تنفيذ إجراءات داخل جلسة المتصفح التي سجّلت الدخول فيها.
• لا يشغّل OpenClaw المتصفح لبرنامج التشغيل هذا؛ بل يتصل به فقط.
• يستخدم OpenClaw هنا تدفق --autoConnect الرسمي لـ Chrome DevTools MCP. إذا ضُبط userDataDir، فسيُمرّر لاستهداف دليل بيانات المستخدم ذلك.
• يمكن للجلسة الحالية الاتصال على المضيف المحدد أو من خلال Node متصفح متصل. إذا كان Chrome موجودًا في مكان آخر ولم يكن أي Node متصفح متصلًا، فاستخدم CDP البعيد أو مضيف Node بدلًا من ذلك.
• تقتصر أهداف Chrome MCP ومراجع اللقطات على عملية MCP فرعية واحدة. بعد إعادة تشغيل تلك العملية، شغّل browser tabs مرة أخرى، وحدد صراحةً هدفًا جديدًا قبل العمل الخاص بالهدف، والتقط لقطة جديدة قبل استخدام المراجع. لا يكون كل مرجع صالحًا إلا لهدفه وأحدث لقطة له. لا تُنقل الأسماء البديلة القديمة إلى علامة تبويب بديلة، حتى عندما يتطابق عنوان URL الخاص بها.
• يوجّه Chrome DevTools MCP حاليًا أدوات الصفحة باستخدام معرّف صفحة رقمي محلي للعملية. تمنع المقابض المقيدة بنطاق العملية إعادة الاستخدام عند استبدال العملية الفرعية، لكن استبدال سياق المتصفح داخل العملية بين استدعاءين متجاورين للأداة قد يظل يعيد توجيه الإجراء إلى هدف آخر. يتطلب التوجيه الذري بالكامل دعم أدوات الصفحة في المنبع لمعرّفات أهداف مستقرة.

تشغيل Chrome MCP مخصص

تجاوز خادم Chrome DevTools MCP الذي يتم تشغيله لكل ملف عندما لا يكون تدفق npx chrome-devtools-mcp@latest الافتراضي هو المطلوب (المضيفون غير المتصلين، الإصدارات المثبتة، الملفات التنفيذية المضمّنة):

عند ضبط cdpUrl في ملف جلسة حالية، يتخطى OpenClaw --autoConnect ويمرّر نقطة النهاية تلقائيًا إلى Chrome MCP:

• http(s)://... ← --browserUrl <url> (نقطة نهاية اكتشاف DevTools عبر HTTP).
• ws(s)://... ← --wsEndpoint <url> (WebSocket مباشر لـ CDP).

لا يمكن الجمع بين علامات نقطة النهاية وuserDataDir: عند ضبط cdpUrl، يُتجاهل userDataDir عند تشغيل Chrome MCP، لأن Chrome MCP يتصل بالمتصفح قيد التشغيل خلف نقطة النهاية بدلًا من فتح دليل ملف.

ضمانات العزل

• دليل مخصص لبيانات المستخدم: لا يمس ملف متصفحك الشخصي مطلقًا.
• منافذ مخصصة: يتجنب 9222 لمنع التعارض مع سير عمل التطوير.
• تحكم حتمي في علامات التبويب: يعيد tabs أولًا suggestedTargetId، ثم مقابض tabId مستقرة مثل t1، وتسميات اختيارية، وtargetId الخام. ينبغي للوكلاء إعادة استخدام suggestedTargetId؛ وتظل المعرّفات الخام متاحة لتصحيح الأخطاء والتوافق.

اختيار المتصفح

عند التشغيل محليًا، يختار OpenClaw أول متصفح متاح:

1. Chrome
2. Brave
3. Edge
4. Chromium
5. Chrome Canary

يمكن التجاوز باستخدام browser.executablePath.

المنصات:

• macOS: يتحقق من /Applications و~/Applications.
• Linux: يتحقق من المواقع الشائعة لـ Chrome وBrave وEdge وChromium ضمن /usr/bin و/snap/bin و/opt/google و/opt/brave.com و/usr/lib/chromium و /usr/lib/chromium-browser، بالإضافة إلى Chromium المُدار بواسطة Playwright ضمن PLAYWRIGHT_BROWSERS_PATH أو ~/.cache/ms-playwright.
• Windows: يتحقق من مواقع التثبيت الشائعة.

واجهة API للتحكم (اختيارية)

لأغراض البرمجة النصية وتصحيح الأخطاء، يوفّر Gateway واجهة API صغيرة للتحكم عبر HTTP مقتصرة على عنوان الاسترجاع المحلي، بالإضافة إلى CLI ‏openclaw browser مطابقة (اللقطات، والمراجع، وتعزيزات الانتظار، ومخرجات JSON، وسير عمل تصحيح الأخطاء). راجع واجهة API للتحكم في المتصفح للاطلاع على المرجع الكامل.

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

للمشكلات الخاصة بـ Linux (وخاصة Chromium عبر snap)، راجع استكشاف أخطاء المتصفح وإصلاحها.

لإعدادات WSL2 Gateway مع Windows Chrome على مضيفين منفصلين، راجع استكشاف أخطاء WSL2 + Windows + Chrome CDP البعيد وإصلاحها.

فشل بدء CDP مقابل حظر SSRF للتنقل

هاتان فئتان مختلفتان من الفشل، وتشيران إلى مسارين مختلفين في التعليمات البرمجية.

• يعني فشل بدء CDP أو جاهزيته أن OpenClaw لا يستطيع التأكد من سلامة مستوى التحكم في المتصفح.
• يعني حظر SSRF للتنقل أن مستوى التحكم في المتصفح سليم، لكن السياسة ترفض هدف تنقل الصفحة.

أمثلة شائعة:

• فشل بدء CDP أو جاهزيته:
  • Chrome CDP websocket for profile "openclaw" is not reachable after start
  • Remote CDP for profile "<name>" is not reachable at <cdpUrl>
  • Port <port> is in use for profile "<name>" but not by openclaw عند إعداد خدمة CDP خارجية على عنوان الاسترجاع المحلي من دون attachOnly: true
• حظر SSRF للتنقل:
  • تفشل تدفقات open أو navigate أو اللقطة أو فتح علامة التبويب بخطأ في سياسة المتصفح/الشبكة، بينما يظل start وtabs يعملان

استخدم هذا التسلسل الأدنى للتمييز بينهما:

openclaw browser --browser-profile openclaw startopenclaw browser --browser-profile openclaw tabsopenclaw browser --browser-profile openclaw open https://example.com

كيفية قراءة النتائج:

• إذا فشل start مع not reachable after start، فاستكشف جاهزية CDP وأصلحها أولًا.
• إذا نجح start لكن فشل tabs، فلا يزال مستوى التحكم غير سليم. تعامل مع ذلك كمشكلة في إمكانية الوصول إلى CDP، لا كمشكلة في تنقل الصفحة.
• إذا نجح start وtabs لكن فشل open أو navigate، فإن مستوى التحكم في المتصفح يعمل ويكمن الفشل في سياسة التنقل أو الصفحة المستهدفة.
• إذا نجحت start وtabs وopen جميعها، فمسار التحكم الأساسي في المتصفح المُدار سليم.

تفاصيل سلوكية مهمة:

• تستخدم إعدادات المتصفح افتراضيًا كائن سياسة SSRF مغلقًا عند الفشل حتى عندما لا تضبط browser.ssrfPolicy.
• بالنسبة إلى ملف openclaw المُدار على عنوان الاسترجاع المحلي، تتخطى فحوصات سلامة CDP عمدًا فرض إمكانية الوصول وفق سياسة SSRF للمتصفح على مستوى التحكم المحلي الخاص بـ OpenClaw.
• حماية التنقل منفصلة. لا تعني النتيجة الناجحة لـ start أو tabs السماح بهدف لاحق لـ open أو navigate.

إرشادات الأمان:

• لا تخفف سياسة SSRF للمتصفح افتراضيًا.
• فضّل استثناءات المضيف الضيقة مثل hostnameAllowlist أو allowedHostnames على الوصول الواسع إلى الشبكة الخاصة.
• استخدم dangerouslyAllowPrivateNetwork: true فقط في البيئات الموثوقة عمدًا حيث يكون وصول المتصفح إلى الشبكة الخاصة مطلوبًا وخاضعًا للمراجعة.

أدوات الوكيل + آلية التحكم

يحصل الوكيل على أداة واحدة لأتمتة المتصفح:

• browser - الفحص/الحالة/البدء/الإيقاف/علامات التبويب/الفتح/التركيز/الإغلاق/اللقطة/لقطة الشاشة/التنقل/التنفيذ

كيفية الربط:

• browser snapshot تُرجع شجرة واجهة مستخدم مستقرة (AI أو ARIA).
• browser act تستخدم معرّفات ref الخاصة باللقطة للنقر/الكتابة/السحب/التحديد.
• browser screenshot تلتقط وحدات البكسل (الصفحة كاملةً أو عنصرًا أو مراجع ذات تسميات).
• browser doctor تتحقق من جاهزية Gateway وPlugin والملف الشخصي والمتصفح وعلامة التبويب.
• browser تقبل:
  • profile لاختيار ملف شخصي مُسمّى للمتصفح (openclaw أو chrome أو CDP بعيد).
  • target (sandbox | host | node) لتحديد مكان تشغيل المتصفح.
  • في الجلسات المعزولة، يتطلب target: "host" وجود agents.defaults.sandbox.browser.allowHostControl=true.
  • إذا أُغفل target: تستخدم الجلسات المعزولة sandbox افتراضيًا، بينما تستخدم الجلسات غير المعزولة host افتراضيًا.
  • إذا كانت هناك Node تدعم المتصفح ومتصلة، فقد تُوجّه الأداة تلقائيًا إليها ما لم تثبّت target="host" أو target="node".

يحافظ هذا على حتمية الوكيل ويتجنب المحددات الهشة.

ذو صلة

• نظرة عامة على الأدوات - جميع أدوات الوكيل المتاحة
• العزل - التحكم في المتصفح ضمن البيئات المعزولة
• الأمان - مخاطر التحكم في المتصفح وتعزيز أمانه