يمكن لـ OpenClaw تشغيل ملف تعريف مخصص لـ Chrome/Brave/Edge/Chromium يتحكم فيه الوكيل. وهو معزول عن متصفحك الشخصي، وتديره خدمة تحكم محلية صغيرة داخل Gateway (loopback فقط). نظرة المبتدئ:Documentation Index
Fetch the complete documentation index at: https://docs.openclaw.ai/llms.txt
Use this file to discover all available pages before exploring further.
- فكّر فيه بوصفه متصفحًا منفصلًا مخصصًا للوكيل فقط.
- لا يلمس ملف تعريف
openclawملف تعريف متصفحك الشخصي. - يستطيع الوكيل فتح علامات التبويب، وقراءة الصفحات، والنقر، والكتابة ضمن مسار آمن.
- يتصل ملف تعريف
userالمدمج بجلسة Chrome الحقيقية التي سجّلت الدخول إليها عبر Chrome MCP.
ما الذي تحصل عليه
- ملف تعريف متصفح منفصل باسم openclaw (بتمييز برتقالي افتراضيًا).
- تحكم حتمي في علامات التبويب (سرد/فتح/تركيز/إغلاق).
- إجراءات الوكيل (نقر/كتابة/سحب/تحديد)، ولقطات الحالة، ولقطات الشاشة، وملفات PDF.
- مهارة
browser-automationمرفقة تعلّم الوكلاء حلقة الاسترداد الخاصة بلقطة الحالة، وعلامة التبويب المستقرة، والمرجع القديم، والعائق اليدوي عند تفعيل Plugin المتصفح. - دعم اختياري لعدة ملفات تعريف (
openclaw، وwork، وremote، …).
البدء السريع
openclaw browser مفقودًا بالكامل، أو قال الوكيل إن أداة المتصفح
غير متاحة، فانتقل إلى أمر أو أداة المتصفح مفقودان.
التحكم في Plugin
أداةbrowser الافتراضية هي Plugin مرفق. عطّله لاستبداله بـ Plugin آخر يسجل اسم أداة browser نفسه:
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 الكاملة. إذا كان على الوكيل أو
الوكيل الفرعي المُنشأ استخدام أتمتة المتصفح، فأضف المتصفح في مرحلة ملف
التعريف:
agents.list[].tools.alsoAllow: ["browser"].
لا يكفي tools.subagents.tools.allow: ["browser"] وحده لأن سياسة الوكيل الفرعي
تُطبَّق بعد ترشيح ملف التعريف.
يوفر Plugin المتصفح مستويين من إرشادات الوكيل:
- يحمل وصف أداة
browserالعقد المختصر الدائم: اختر ملف التعريف الصحيح، وأبقِ المراجع على علامة التبويب نفسها، واستخدمtabId/التسميات لاستهداف علامات التبويب، وحمّل مهارة المتصفح للأعمال متعددة الخطوات. - تحمل مهارة
browser-automationالمرفقة حلقة التشغيل الأطول: افحص الحالة/علامات التبويب أولًا، وسمِّ علامات تبويب المهمة، وخذ لقطة حالة قبل التنفيذ، ثم أعد أخذ لقطة حالة بعد تغييرات واجهة المستخدم، واستعد المراجع القديمة مرة واحدة، وأبلغ عن تسجيل الدخول/2FA/captcha أو عوائق الكاميرا/الميكروفون كإجراء يدوي بدلًا من التخمين.
أمر أو أداة المتصفح مفقودان
إذا كانopenclaw browser غير معروف بعد ترقية، أو كان browser.request مفقودًا، أو أبلغ الوكيل أن أداة المتصفح غير متاحة، فالسبب المعتاد هو قائمة plugins.allow لا تتضمن browser ولا توجد كتلة إعدادات جذرية لـ browser. أضفها:
browser جذرية صريحة، مثل browser.enabled=true أو browser.profiles.<name>، تفعّل Plugin المتصفح المرفق حتى ضمن plugins.allow مقيّدة، بما يطابق سلوك إعدادات القناة. لا يحل plugins.entries.browser.enabled=true وtools.alsoAllow: ["browser"] محل عضوية قائمة السماح بذاتهما. كما أن إزالة plugins.allow بالكامل تستعيد الإعداد الافتراضي.
ملفات التعريف: openclaw مقابل user
openclaw: متصفح مُدار ومعزول (لا يتطلب إضافة).user: ملف تعريف Chrome MCP مدمج للاتصال بجلسة Chrome الحقيقية التي سجّلت الدخول إليها.
- الافتراضي: استخدم متصفح
openclawالمعزول. - فضّل
profile="user"عندما تكون جلسات تسجيل الدخول الحالية مهمة ويكون المستخدم أمام الكمبيوتر للنقر/الموافقة على أي مطالبة اتصال. profileهو التجاوز الصريح عندما تريد وضع متصفح محددًا.
browser.defaultProfile: "openclaw" إذا كنت تريد الوضع المُدار افتراضيًا.
الإعدادات
توجد إعدادات المتصفح في~/.openclaw/openclaw.json.
المنافذ وإمكانية الوصول
المنافذ وإمكانية الوصول
- ترتبط خدمة التحكم بـ loopback على منفذ مشتق من
gateway.port(افتراضيًا18791= Gateway + 2). يؤدي تجاوزgateway.portأوOPENCLAW_GATEWAY_PORTإلى نقل المنافذ المشتقة ضمن العائلة نفسها. - تعيّن ملفات تعريف
openclawالمحليةcdpPort/cdpUrlتلقائيًا؛ اضبط هذه القيم فقط لـ CDP البعيد. يكونcdpUrlافتراضيًا منفذ CDP المحلي المُدار عند عدم ضبطه. - ينطبق
remoteCdpTimeoutMsعلى فحوصات قابلية الوصول عبر HTTP لـ CDP البعيد وattachOnlyوطلبات HTTP لفتح علامات التبويب؛ وينطبقremoteCdpHandshakeTimeoutMsعلى مصافحات CDP WebSocket الخاصة بها. localLaunchTimeoutMsهو الميزانية الزمنية لعملية Chrome مُدارة ومُشغّلة محليًا حتى تعرض نقطة نهاية CDP HTTP الخاصة بها.localCdpReadyTimeoutMsهو الميزانية اللاحقة لجاهزية CDP websocket بعد اكتشاف العملية. ارفع هذه القيم على Raspberry Pi، أو خوادم VPS منخفضة المواصفات، أو العتاد الأقدم حيث يبدأ Chromium ببطء. يجب أن تكون القيم أعدادًا صحيحة موجبة حتى120000مللي ثانية؛ وتُرفض قيم الإعدادات غير الصالحة.- تُقطع دائرة إخفاقات تشغيل/جاهزية Chrome المُدار المتكررة لكل ملف تعريف. بعد عدة إخفاقات متتالية، يوقف OpenClaw محاولات التشغيل الجديدة مؤقتًا بدلًا من إنشاء Chromium عند كل استدعاء لأداة المتصفح. أصلح مشكلة بدء التشغيل، أو عطّل المتصفح إذا لم يكن مطلوبًا، أو أعد تشغيل Gateway بعد الإصلاح.
actionTimeoutMsهو الميزانية الافتراضية لطلباتactالخاصة بالمتصفح عندما لا يمرر المستدعيtimeoutMs. يضيف نقل العميل نافذة سماح صغيرة حتى تنتهي الانتظارات الطويلة بدلًا من انتهاء مهلتها عند حد HTTP.tabCleanupهو تنظيف بأفضل جهد لعلامات التبويب التي تفتحها جلسات متصفح الوكيل الأساسي. لا يزال تنظيف دورة حياة الوكيل الفرعي، وcron، وACP يغلق علامات التبويب المتتبعة الصريحة في نهاية الجلسة؛ وتُبقي الجلسات الأساسية علامات التبويب النشطة قابلة لإعادة الاستخدام، ثم تغلق علامات التبويب المتتبعة الخاملة أو الزائدة في الخلفية.
سياسة SSRF
سياسة SSRF
- تخضع ملاحة المتصفح وفتح علامات التبويب لحماية SSRF قبل الملاحة، مع إعادة فحص بأفضل جهد على عنوان URL النهائي
http(s)بعد ذلك. - في وضع SSRF الصارم، تُفحص أيضًا عملية اكتشاف نقطة نهاية CDP البعيدة ومجسات
/json/version(cdpUrl). - لا تقوم متغيرات البيئة
HTTP_PROXYوHTTPS_PROXYوALL_PROXYوNO_PROXYالخاصة بـ Gateway/الموفر بتمرير متصفح OpenClaw المُدار عبر الوكيل تلقائيًا. يبدأ Chrome المُدار باتصال مباشر افتراضيًا حتى لا تُضعف إعدادات وكيل الموفر فحوصات SSRF للمتصفح. - لتمرير المتصفح المُدار نفسه عبر وكيل، مرّر أعلام وكيل Chrome صريحة عبر
browser.extraArgs، مثل--proxy-server=...أو--proxy-pac-url=.... يمنع وضع SSRF الصارم توجيه وكيل المتصفح الصريح ما لم يُفعّل الوصول إلى متصفح الشبكة الخاصة عمدًا. browser.ssrfPolicy.dangerouslyAllowPrivateNetworkمتوقف افتراضيًا؛ فعّله فقط عندما يكون الوصول إلى متصفح الشبكة الخاصة موثوقًا عمدًا.- يظل
browser.ssrfPolicy.allowPrivateNetworkمدعومًا كاسم مستعار قديم.
سلوك ملف التعريف
سلوك ملف التعريف
- يعني
attachOnly: trueعدم تشغيل متصفح محلي مطلقا؛ بل الاتصال فقط إذا كان أحدها قيد التشغيل بالفعل. - يمكن تعيين
headlessعالميا أو لكل ملف تعريف محلي مدار. تتجاوز قيم كل ملف تعريفbrowser.headless، لذلك يمكن أن يبقى ملف تعريف مشغل محليا دون واجهة بينما يبقى آخر مرئيا. - يطلب
POST /start?headless=trueوopenclaw browser start --headlessتشغيلا مؤقتا لمرة واحدة دون واجهة لملفات التعريف المحلية المدارة دون إعادة كتابةbrowser.headlessأو إعدادات ملف التعريف. ترفض ملفات تعريف الجلسات القائمة، والاتصال فقط، وملفات تعريف CDP البعيدة هذا التجاوز لأن OpenClaw لا يشغل عمليات المتصفح تلك. - على مضيفات Linux التي لا تحتوي على
DISPLAYأوWAYLAND_DISPLAY، تعتمد ملفات التعريف المحلية المدارة الوضع دون واجهة تلقائيا عندما لا تختار البيئة ولا إعدادات ملف التعريف/الإعدادات العامة وضعا بواجهة صراحة. يبلغopenclaw browser status --jsonعنheadlessSourceكواحدة منenvأوprofileأوconfigأوrequestأوlinux-display-fallbackأوdefault. - يفرض
OPENCLAW_BROWSER_HEADLESS=1تشغيل الإطلاقات المحلية المدارة دون واجهة للعملية الحالية. يفرضOPENCLAW_BROWSER_HEADLESS=0وضع الواجهة للإطلاقات العادية ويعيد خطأ قابلا للتنفيذ على مضيفات Linux التي لا تحتوي على خادم عرض؛ ويظل طلبstart --headlessالصريح هو الفائز لذلك الإطلاق الواحد. - يمكن تعيين
executablePathعالميا أو لكل ملف تعريف محلي مدار. تتجاوز قيم كل ملف تعريفbrowser.executablePath، لذلك يمكن لملفات تعريف مدارة مختلفة تشغيل متصفحات مختلفة مبنية على Chromium. يقبل كلا الشكلين~للدليل الرئيسي لنظام التشغيل لديك. - يلون
color(على المستوى الأعلى ولكل ملف تعريف) واجهة مستخدم المتصفح حتى تتمكن من معرفة ملف التعريف النشط. - ملف التعريف الافتراضي هو
openclaw(مدار مستقل). استخدمdefaultProfile: "user"لاختيار متصفح المستخدم الذي تم تسجيل الدخول إليه. - ترتيب الاكتشاف التلقائي: متصفح النظام الافتراضي إذا كان مبنيا على Chromium؛ وإلا Chrome ← Brave ← Edge ← Chromium ← Chrome Canary.
- يستخدم
driver: "existing-session"Chrome DevTools MCP بدلا من CDP الخام. لا تضبطcdpUrlلذلك المشغل. - عيّن
browser.profiles.<name>.userDataDirعندما يجب أن يتصل ملف تعريف جلسة قائمة بملف تعريف مستخدم Chromium غير افتراضي (Brave وEdge وما إلى ذلك). يقبل هذا المسار أيضا~للدليل الرئيسي لنظام التشغيل لديك.
استخدام Brave أو متصفح آخر مبني على Chromium
إذا كان متصفح النظام الافتراضي لديك مبنيا على Chromium (Chrome/Brave/Edge/etc)، فسيستخدمه OpenClaw تلقائيا. عيّنbrowser.executablePath لتجاوز
الاكتشاف التلقائي. تقبل قيم executablePath على المستوى الأعلى ولكل ملف تعريف ~
للدليل الرئيسي لنظام التشغيل لديك:
- macOS
- Windows
- Linux
executablePath لكل ملف تعريف فقط على ملفات التعريف المحلية المدارة التي يشغلها
OpenClaw. تتصل ملفات تعريف existing-session بمتصفح قيد التشغيل بالفعل
بدلا من ذلك، وتستخدم ملفات تعريف CDP البعيدة المتصفح خلف cdpUrl.
التحكم المحلي مقابل البعيد
- التحكم المحلي (الافتراضي): يبدأ Gateway خدمة تحكم local loopback ويمكنه تشغيل متصفح محلي.
- التحكم البعيد (مضيف Node): شغّل مضيف Node على الجهاز الذي يحتوي على المتصفح؛ يمرر Gateway إجراءات المتصفح إليه.
- CDP البعيد: عيّن
browser.profiles.<name>.cdpUrl(أوbrowser.cdpUrl) من أجل الاتصال بمتصفح بعيد مبني على Chromium. في هذه الحالة، لن يشغل OpenClaw متصفحا محليا. - لخدمات CDP المدارة خارجيا على local loopback (على سبيل المثال Browserless في
Docker منشور إلى
127.0.0.1)، عيّن أيضاattachOnly: true. يعامل CDP على local loopback دونattachOnlyكملف تعريف متصفح محلي مدار بواسطة OpenClaw. - يؤثر
headlessفقط على ملفات التعريف المحلية المدارة التي يشغلها OpenClaw. ولا يعيد تشغيل أو يغير متصفحات الجلسات القائمة أو CDP البعيدة. - يتبع
executablePathقاعدة ملف التعريف المحلي المدار نفسها. يؤدي تغييره على ملف تعريف محلي مدار قيد التشغيل إلى وسم ذلك الملف لإعادة التشغيل/المواءمة بحيث يستخدم الإطلاق التالي الملف التنفيذي الجديد.
- ملفات التعريف المحلية المدارة: يوقف
openclaw browser stopعملية المتصفح التي شغلها OpenClaw - ملفات تعريف الاتصال فقط وCDP البعيد: يغلق
openclaw browser stopجلسة التحكم النشطة ويحرر تجاوزات محاكاة Playwright/CDP (إطار العرض، ونظام الألوان، واللغة، والمنطقة الزمنية، ووضع عدم الاتصال، والحالة المشابهة)، حتى لو لم يشغل OpenClaw أي عملية متصفح
- رموز الاستعلام (مثلا،
https://provider.example?token=<token>) - مصادقة HTTP Basic (مثلا،
https://user:pass@provider.example)
/json/* وعند الاتصال
بـ CDP WebSocket. فضّل متغيرات البيئة أو مديري الأسرار للرموز
بدلا من تثبيتها في ملفات الإعدادات.
وكيل متصفح Node (افتراضي بلا إعداد)
إذا شغّلت مضيف Node على الجهاز الذي يحتوي على متصفحك، يمكن لـ OpenClaw توجيه استدعاءات أدوات المتصفح تلقائيا إلى ذلك الـ Node دون أي إعدادات متصفح إضافية. هذا هو المسار الافتراضي للـ gateways البعيدة. ملاحظات:- يعرض مضيف Node خادم التحكم في متصفحه المحلي عبر أمر وكيل.
- تأتي ملفات التعريف من إعدادات
browser.profilesالخاصة بالـ Node نفسه (مثل المحلي). nodeHost.browserProxy.allowProfilesاختياري. اتركه فارغا للسلوك القديم/الافتراضي: تظل جميع ملفات التعريف المكونة قابلة للوصول عبر الوكيل، بما في ذلك مسارات إنشاء/حذف ملفات التعريف.- إذا عيّنت
nodeHost.browserProxy.allowProfiles، يعامله OpenClaw كحد أدنى من الامتيازات: يمكن استهداف ملفات التعريف المدرجة في قائمة السماح فقط، وتُحظر مسارات إنشاء/حذف ملفات التعريف الدائمة على سطح الوكيل. - عطّله إذا كنت لا تريده:
- على الـ Node:
nodeHost.browserProxy.enabled=false - على الـ gateway:
gateway.nodes.browser.mode="off"
- على الـ Node:
Browserless (CDP بعيد مستضاف)
Browserless هي خدمة Chromium مستضافة تعرض عناوين URL لاتصال CDP عبر HTTPS وWebSocket. يمكن لـ OpenClaw استخدام أي من الشكلين، لكن أبسط خيار لملف تعريف متصفح بعيد هو عنوان WebSocket URL المباشر من وثائق اتصال Browserless. مثال:- استبدل
<BROWSERLESS_API_KEY>برمز Browserless الحقيقي لديك. - اختر نقطة نهاية المنطقة التي تطابق حساب Browserless لديك (راجع وثائقهم).
- إذا أعطاك Browserless عنوان HTTPS أساسي، يمكنك إما تحويله إلى
wss://لاتصال CDP مباشر أو إبقاء عنوان HTTPS وترك OpenClaw يكتشف/json/version.
Browserless Docker على المضيف نفسه
عندما يكون Browserless مستضافا ذاتيا في Docker ويعمل OpenClaw على المضيف، تعامل مع Browserless كخدمة CDP مدارة خارجيا:browser.profiles.browserless.cdpUrl قابلا للوصول من عملية
OpenClaw. يجب أن يعلن Browserless أيضا عن نقطة نهاية مطابقة وقابلة للوصول؛
عيّن EXTERNAL في Browserless إلى أساس WebSocket نفسه العام إلى OpenClaw، مثل
ws://127.0.0.1:3000 أو ws://browserless:3000 أو عنوان شبكة Docker
خاص ثابت. إذا أعاد /json/version قيمة webSocketDebuggerUrl تشير إلى
عنوان لا يستطيع OpenClaw الوصول إليه، فقد يبدو HTTP الخاص بـ CDP سليما بينما يظل
اتصال WebSocket يفشل.
لا تترك attachOnly غير معين لملف تعريف Browserless على local loopback. بدون
attachOnly، يعامل OpenClaw منفذ local loopback كملف تعريف متصفح محلي مدار
وقد يبلغ أن المنفذ قيد الاستخدام لكنه ليس مملوكا لـ OpenClaw.
مزودو CDP عبر WebSocket مباشر
تعرض بعض خدمات المتصفح المستضافة نقطة نهاية WebSocket مباشرة بدلا من اكتشاف CDP القياسي المعتمد على HTTP (/json/version). يقبل OpenClaw ثلاثة
أشكال لعناوين URL الخاصة بـ CDP ويختار استراتيجية الاتصال الصحيحة تلقائيا:
- اكتشاف HTTP(S) -
http://host[:port]أوhttps://host[:port]. يستدعي OpenClaw/json/versionلاكتشاف عنوان WebSocket debugger URL، ثم يتصل. لا يوجد رجوع احتياطي إلى 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.
Browserbase
Browserbase منصة سحابية لتشغيل متصفحات دون واجهة مع حل CAPTCHA مدمج، ووضع التخفي، ووكلاء سكنيين.- سجّل وانسخ API Key من لوحة معلومات Overview.
- استبدل
<BROWSERBASE_API_KEY>بمفتاح Browserbase API الحقيقي لديك. - ينشئ Browserbase جلسة متصفح تلقائيا عند اتصال WebSocket، لذلك لا حاجة إلى خطوة إنشاء جلسة يدوية.
- تتيح الخطة المجانية جلسة متزامنة واحدة وساعة متصفح واحدة شهريا. راجع التسعير لمعرفة حدود الخطط المدفوعة.
- راجع وثائق Browserbase للحصول على مرجع API الكامل، وأدلة SDK، وأمثلة التكامل.
الأمان
الأفكار الرئيسية:- التحكم في المتصفح مقيّد بـ local loopback فقط؛ يمر الوصول عبر مصادقة Gateway أو إقران العقدة.
- تستخدم واجهة HTTP API المستقلة لمتصفح local loopback مصادقة السر المشترك فقط:
مصادقة حامل رمز Gateway، أو
x-openclaw-password، أو مصادقة HTTP Basic باستخدام كلمة مرور Gateway المهيأة. - لا تصادق رؤوس هوية Tailscale Serve و
gateway.auth.mode: "trusted-proxy"على واجهة API المستقلة هذه لمتصفح local loopback. - إذا كان التحكم في المتصفح ممكّنًا ولم تكن مصادقة السر المشترك مهيأة، فإن OpenClaw
ينشئ رمز Gateway خاصًا بوقت التشغيل فقط لذلك بدء التشغيل. هيّئ
gateway.auth.tokenأوgateway.auth.passwordأوOPENCLAW_GATEWAY_TOKENأوOPENCLAW_GATEWAY_PASSWORDصراحة إذا كانت العملاء تحتاج إلى سر ثابت عبر عمليات إعادة التشغيل. - لا ينشئ OpenClaw ذلك الرمز تلقائيًا عندما يكون
gateway.auth.modeهوpasswordأوnoneأوtrusted-proxyبالفعل. - أبقِ Gateway وأي مضيفي عقد على شبكة خاصة (Tailscale)؛ وتجنب التعريض العام.
- عامل عناوين URL/الرموز الخاصة بـ CDP البعيد كأسرار؛ وفضّل متغيرات البيئة أو مدير أسرار.
- فضّل نقاط النهاية المشفرة (HTTPS أو WSS) والرموز قصيرة العمر حيثما أمكن.
- تجنب تضمين الرموز طويلة العمر مباشرة في ملفات التهيئة.
الملفات الشخصية (متعددة المتصفحات)
يدعم OpenClaw عدة ملفات شخصية مسماة (تهيئات توجيه). يمكن أن تكون الملفات الشخصية:- مدارة بواسطة openclaw: مثيل متصفح مخصص قائم على Chromium مع دليل بيانات مستخدم خاص به + منفذ CDP
- بعيدة: عنوان URL صريح لـ CDP (متصفح قائم على 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 الرسمي. يعيد هذا استخدام الألسنة وحالة تسجيل الدخول المفتوحة بالفعل في ذلك الملف الشخصي للمتصفح. مراجع الخلفية والإعداد الرسمية: الملف الشخصي المدمج:user
- يستخدم ملف
userالشخصي المدمج الاتصال التلقائي بـ Chrome MCP، والذي يستهدف ملف Google Chrome المحلي الافتراضي.
userDataDir لـ Brave أو Edge أو Chromium أو ملف Chrome شخصي غير افتراضي.
يتوسع ~ إلى دليل المنزل في نظام التشغيل لديك:
- افتح صفحة الفحص لذلك المتصفح للتصحيح عن بُعد.
- مكّن التصحيح عن بُعد.
- أبقِ المتصفح قيد التشغيل ووافق على مطالبة الاتصال عندما يرفق OpenClaw.
- Chrome:
chrome://inspect/#remote-debugging - Brave:
brave://inspect/#remote-debugging - Edge:
edge://inspect/#remote-debugging
- يعرض
statusالقيمةdriver: existing-session - يعرض
statusالقيمةtransport: chrome-mcp - يعرض
statusالقيمةrunning: true - يسرد
tabsألسنة المتصفح المفتوحة لديك بالفعل - يعيد
snapshotمراجع من اللسان الحي المحدد
- المتصفح الهدف القائم على Chromium هو الإصدار
144+ - التصحيح عن بُعد ممكّن في صفحة الفحص لذلك المتصفح
- عرض المتصفح مطالبة موافقة الإرفاق وقبلتها
- يرحّل
openclaw doctorتهيئة المتصفح القديمة القائمة على الإضافة ويتحقق من أن Chrome مثبت محليًا لملفات الاتصال التلقائي الافتراضية، لكنه لا يستطيع تمكين التصحيح عن بُعد من جانب المتصفح نيابة عنك
- استخدم
profile="user"عندما تحتاج إلى حالة المتصفح المسجل دخوله الخاصة بالمستخدم. - إذا كنت تستخدم ملف جلسة موجودة مخصصًا، فمرر اسم الملف الشخصي الصريح ذلك.
- اختر هذا الوضع فقط عندما يكون المستخدم أمام الحاسوب للموافقة على مطالبة الإرفاق.
- يمكن لـ Gateway أو مضيف العقدة تشغيل
npx chrome-devtools-mcp@latest --autoConnect
- هذا المسار أعلى مخاطرة من ملف
openclawالشخصي المعزول لأنه يمكنه التصرف داخل جلسة المتصفح المسجل دخولها لديك. - لا يطلق OpenClaw المتصفح لهذا المشغل؛ إنه يرفق فقط.
- يستخدم OpenClaw تدفق
--autoConnectالرسمي الخاص بـ Chrome DevTools MCP هنا. إذا كانuserDataDirمضبوطًا، فيُمرر لاستهداف دليل بيانات المستخدم ذلك. - يمكن للجلسة الموجودة الإرفاق على المضيف المحدد أو عبر عقدة متصفح متصلة. إذا كان Chrome في مكان آخر ولم تكن أي عقدة متصفح متصلة، فاستخدم CDP البعيد أو مضيف عقدة بدلًا من ذلك.
تشغيل Chrome MCP مخصص
تجاوز خادم Chrome DevTools MCP الذي يتم تشغيله لكل ملف شخصي عندما لا يكون تدفقnpx chrome-devtools-mcp@latest الافتراضي هو ما تريده (مضيفون غير متصلين،
إصدارات مثبتة، ثنائيات موردة):
| الحقل | ما يفعله |
|---|---|
mcpCommand | الملف التنفيذي المراد تشغيله بدلًا من npx. يُحل كما هو؛ وتُحترم المسارات المطلقة. |
mcpArgs | مصفوفة الوسائط التي تمرر حرفيًا إلى mcpCommand. تستبدل وسائط chrome-devtools-mcp@latest --autoConnect الافتراضية. |
cdpUrl على ملف جلسة موجودة، يتخطى OpenClaw
--autoConnect ويمرر نقطة النهاية إلى Chrome MCP تلقائيًا:
http(s)://...→--browserUrl <url>(نقطة نهاية اكتشاف DevTools عبر HTTP).ws(s)://...→--wsEndpoint <url>(WebSocket مباشر لـ CDP).
userDataDir: عندما يُضبط cdpUrl،
يُتجاهل userDataDir عند تشغيل Chrome MCP، لأن Chrome MCP يرفق بالمتصفح
قيد التشغيل خلف نقطة النهاية بدلًا من فتح دليل ملف شخصي.
قيود ميزة الجلسة الموجودة
قيود ميزة الجلسة الموجودة
مقارنة بملف
openclaw الشخصي المدار، تكون مشغلات الجلسة الموجودة أكثر تقييدًا:- لقطات الشاشة - تعمل التقاطات الصفحة والتقاطات عنصر
--ref؛ أما محددات CSS--elementفلا تعمل. لا يمكن دمج--full-pageمع--refأو--element. لا يكون Playwright مطلوبًا للقطات شاشة الصفحة أو العناصر القائمة على المرجع. - الإجراءات - تتطلب
clickوtypeوhoverوscrollIntoViewوdragوselectمراجع snapshot (بدون محددات CSS). ينقرclick-coordsإحداثيات منفذ العرض المرئية ولا يتطلب مرجع snapshot.clickللزر الأيسر فقط. لا يدعمtypeالخيارslowly=true؛ استخدمfillأوpress. لا يدعمpressالخيارdelayMs. لا تدعمtypeوhoverوscrollIntoViewوdragوselectوfillوevaluateمهلات لكل استدعاء. يقبلselectقيمة واحدة. - الانتظار / الرفع / مربع الحوار - يدعم
wait --urlأنماط المطابقة الدقيقة والجزئية وglob؛ ولا يدعمwait --load networkidle. تتطلب خطافات الرفعrefأوinputRef، ملفًا واحدًا في كل مرة، بدون CSSelement. لا تدعم خطافات مربع الحوار تجاوزات المهلة. - الميزات الخاصة بالمتصفح المدار فقط - لا تزال إجراءات الدُفعات، وتصدير PDF، واعتراض التنزيل، و
responsebodyتتطلب مسار المتصفح المدار.
ضمانات العزل
- دليل بيانات مستخدم مخصص: لا يلمس ملف متصفحك الشخصي أبدًا.
- منافذ مخصصة: يتجنب
9222لمنع التعارضات مع سير عمل التطوير. - تحكم حتمي في الألسنة: يعيد
tabsأولًاsuggestedTargetId، ثم مقابضtabIdمستقرة مثلt1، وتسميات اختيارية، وtargetIdالخام. ينبغي للوكلاء إعادة استخدامsuggestedTargetId؛ وتظل المعرفات الخام متاحة للتصحيح والتوافق.
اختيار المتصفح
عند التشغيل محليًا، يختار OpenClaw أول متاح:- Chrome
- Brave
- Edge
- Chromium
- 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 واجهة HTTP API صغيرة للتحكم مقيدة بـ local loopback فقط بالإضافة إلى CLIopenclaw browser مطابق (لقطات، مراجع، تعزيزات انتظار،
مخرجات JSON، وسير عمل تصحيح). راجع
واجهة API للتحكم في المتصفح للمرجع الكامل.
استكشاف الأخطاء وإصلاحها
للمشكلات الخاصة بـ Linux (خصوصًا snap Chromium)، راجع استكشاف أخطاء المتصفح وإصلاحها. لإعدادات WSL2 Gateway + Windows Chrome على مضيفين منفصلين، راجع استكشاف أخطاء WSL2 + Windows + CDP بعيد لـ Chrome وإصلاحها.فشل بدء تشغيل CDP مقابل حظر SSRF للتنقل
هذه فئات فشل مختلفة وتشير إلى مسارات كود مختلفة.- فشل بدء تشغيل CDP أو الجاهزية يعني أن OpenClaw لا يستطيع تأكيد سلامة مستوى التحكم في المتصفح.
- حظر SSRF للتنقل يعني أن مستوى التحكم في المتصفح سليم، لكن هدف تنقل الصفحة مرفوض بالسياسة.
- فشل بدء تشغيل CDP أو الجاهزية:
Chrome CDP websocket for profile "openclaw" is not reachable after startRemote CDP for profile "<name>" is not reachable at <cdpUrl>Port <port> is in use for profile "<name>" but not by openclawعندما تكون خدمة CDP خارجية على loopback مهيأة دونattachOnly: true
- حظر SSRF للتنقل:
- تفشل تدفقات
openأوnavigateأو snapshot أو فتح اللسان مع خطأ سياسة متصفح/شبكة بينما يظلstartوtabsيعملان
- تفشل تدفقات
- إذا فشل
startمعnot reachable after start، فاستكشف جاهزية CDP أولًا. - إذا نجح
startلكن فشلtabs، فلا يزال مستوى التحكم غير سليم. عامل هذا كمشكلة قابلية وصول CDP، وليس كمشكلة تنقل صفحة. - إذا نجح
startوtabsلكن فشلopenأوnavigate، فإن مستوى التحكم في المتصفح يعمل والفشل في سياسة التنقل أو الصفحة الهدف. - إذا نجحت
startوtabsوopenجميعها، فإن مسار التحكم الأساسي في المتصفح المدار سليم.
- تعود تهيئة المتصفح افتراضيًا إلى كائن سياسة SSRF مغلق عند الفشل حتى عندما لا تهيئ
browser.ssrfPolicy. - بالنسبة إلى ملف
openclawالمدار عبر local loopback، تتخطى فحوصات صحة CDP عمدًا إنفاذ قابلية وصول SSRF للمتصفح على مستوى التحكم المحلي الخاص بـ OpenClaw. - حماية التنقل منفصلة. لا تعني نتيجة
startأوtabsالناجحة أن هدفopenأوnavigateلاحق مسموح به.
- لا تخفف سياسة SSRF للمتصفح افتراضيًا.
- فضّل استثناءات المضيف الضيقة مثل
hostnameAllowlistأوallowedHostnamesعلى الوصول الواسع إلى الشبكة الخاصة. - استخدم
dangerouslyAllowPrivateNetwork: trueفقط في البيئات الموثوقة عن قصد حيث يكون وصول المتصفح إلى الشبكة الخاصة مطلوبًا ومراجعًا.
أدوات الوكيل + كيفية عمل التحكم
يحصل الوكيل على أداة واحدة لأتمتة المتصفح:browser- التشخيص/الحالة/البدء/الإيقاف/علامات التبويب/الفتح/التركيز/الإغلاق/اللقطة/لقطة الشاشة/التنقل/التنفيذ
- يعيد
browser snapshotشجرة واجهة مستخدم مستقرة (ذكاء اصطناعي أو 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. - إذا كانت عقدة قادرة على تشغيل المتصفح متصلة، فقد توجّه الأداة إليها تلقائيًا ما لم تثبّت
target="host"أوtarget="node".
ذات صلة
- نظرة عامة على الأدوات - جميع أدوات الوكيل المتاحة
- العزل - التحكم بالمتصفح في البيئات المعزولة
- الأمان - مخاطر التحكم بالمتصفح وتقويته