openclaw browser
أدِر سطح التحكم في متصفح OpenClaw ونفّذ إجراءات المتصفح: دورة الحياة، والملفات الشخصية، وعلامات التبويب، واللقطات، ولقطات الشاشة، والتنقل، والإدخال، ومحاكاة الحالة، وتصحيح الأخطاء.
ذو صلة: أداة المتصفح
العلامات الشائعة
--url <gatewayWsUrl>: عنوان URL لـ WebSocket الخاص بـ Gateway (الإعداد الافتراضي من التهيئة).--token <token>: رمز Gateway المميز (إذا كان مطلوبًا).--timeout <ms>: مهلة الطلب بالمللي ثانية (الإعداد الافتراضي:30000).--expect-final: الانتظار لاستجابة نهائية من Gateway.--browser-profile <name>: اختيار ملف شخصي للمتصفح (الإعداد الافتراضي:openclaw، أوbrowser.defaultProfile).--json: إخراج قابل للقراءة آليًا (حيثما يكون مدعومًا). هذا خيار على مستوى المتصفح، لذا ضعه قبل الأمر الفرعي للحصول على صيغة واضحة لا لبس فيها، مثلopenclaw browser --json status. ويعمل أيضًا وضعه في النهاية، مثلopenclaw browser status --json، عندما لا يعرّف الأمر الفرعي المحدد--jsonخاصًا به.
بدء سريع (محلي)
browser({ action: "doctor" }).
استكشاف سريع للأخطاء وإصلاحها
إذا فشلstart مع not reachable after start، فابدأ باستكشاف جاهزية CDP وإصلاحها. إذا نجح start وtabs ولكن فشل open أو navigate، فهذا يعني أن مستوى التحكم في المتصفح سليم وأن الفشل غالبًا ما يكون حظرًا من سياسة SSRF الخاصة بالتنقل.
الحد الأدنى من الخطوات:
دورة الحياة
doctor --deepيضيف مسبار لقطة مباشرًا: وهو مفيد عندما تكون جاهزية CDP الأساسية سليمة، لكنك تريد إثباتًا على إمكانية فحص علامة التبويب الحالية.- بالنسبة إلى ملف شخصي محلي مُدار وقيد التشغيل، يعرض
statusوdoctorتشخيصات الرسومات المخزنة مؤقتًا من Chrome: تصنيف العتاد/البرمجيات، والمصيّر، والواجهة الخلفية، والجهاز/برنامج التشغيل، وتفاصيل الميزات وحالات تعطيلها، وإمكانات الفيديو المسرّع. يعيدopenclaw browser --json statusالحمولة المنظمة الكاملة. لا تُشغّل الحالة السلبية Chrome لمجرد جمع هذه المعلومات. stopيغلق جلسة التحكم النشطة ويمسح تجاوزات المحاكاة المؤقتة حتى لملفاتattachOnlyوملفات CDP الشخصية البعيدة التي لم يشغّل فيها OpenClaw عملية المتصفح بنفسه. بالنسبة إلى الملفات الشخصية المحلية المُدارة، يوقفstopأيضًا عملية المتصفح التي جرى تشغيلها.start --headlessينطبق فقط على طلب البدء ذاك، وفقط عندما يشغّل OpenClaw متصفحًا محليًا مُدارًا. ولا يعيد كتابةbrowser.headlessأو تهيئة الملف الشخصي، ولا يكون له أي تأثير على متصفح قيد التشغيل بالفعل.- على مضيفات Linux التي لا تحتوي على
DISPLAYأوWAYLAND_DISPLAY، تعمل الملفات الشخصية المحلية المُدارة تلقائيًا دون واجهة رسومية ما لم يطلبOPENCLAW_BROWSER_HEADLESS=0أوbrowser.headless=falseأوbrowser.profiles.<name>.headless=falseصراحةً متصفحًا مرئيًا.
إذا كان الأمر مفقودًا
إذا كانopenclaw browser أمرًا غير معروف، فتحقق من plugins.allow في ~/.openclaw/openclaw.json. عند وجود plugins.allow، أدرج Plugin المتصفح المضمّن صراحةً ما لم تتضمن التهيئة بالفعل كتلة browser جذرية:
browser الجذرية الصريحة (مثل browser.enabled=true أو browser.profiles.<name>) أيضًا إلى تنشيط Plugin المتصفح المضمّن ضمن قائمة سماح مقيّدة للـ Plugin.
ذو صلة: أداة المتصفح
الملفات الشخصية
الملفات الشخصية هي تهيئات مسماة لتوجيه المتصفح:openclaw(الإعداد الافتراضي): يشغّل نسخة Chrome مخصصة يديرها OpenClaw أو يتصل بها (دليل بيانات مستخدم معزول).user: يتحكم في جلسة Chrome الحالية التي سجّلت الدخول إليها عبر Chrome DevTools MCP.- ملفات CDP الشخصية المخصصة: تشير إلى نقطة نهاية CDP محلية أو بعيدة.
--browser-profile <name> مع أي أمر فرعي، مثل openclaw browser --browser-profile work tabs.
على macOS، يسرد system-profiles ملفات Chrome أو Brave أو Edge أو Chromium الفعلية المتاحة على المضيف. يفك import-profile تشفير ملفات تعريف الارتباط الخاصة بها بعد مطالبة واحدة بالموافقة عبر macOS Keychain/Touch ID، ثم يحقنها في ملف شخصي جديد يديره OpenClaw. وهو يستورد ملفات تعريف الارتباط فقط؛ ولا تتغير مساحة التخزين المحلية وIndexedDB. تستخدم بعض جلسات Google بيانات اعتماد جلسة مرتبطة بالجهاز (DBSC)، وقد تظل تتطلب إعادة المصادقة بعد الاستيراد.
عندما يستخدم تطبيق macOS بوابة Gateway محلية، يمكنه عرض هذا الاستيراد مرة واحدة وجعل الملف الشخصي المعزول المستورد هو الإعداد الافتراضي لتصفح الوكيل. يتطلب الاستيراد دائمًا نقرة صريحة؛ ويؤدي نجاح الاستيراد أو رفضه إلى منع المطالبات التلقائية اللاحقة، ويظل Settings → General → Browser login متاحًا لإعادة الاستيراد.
يكون استيراد الملف الشخصي للنظام مفعّلًا افتراضيًا. اضبط browser.allowSystemProfileImport=false لتعطيل عمليات الاستيراد التي تبدأ عبر CLI أو الوكيل. يكون الاستيراد محليًا على المضيف ولا يمكن تشغيله عبر وكيل Node الخاص بالمتصفح.
علامات التبويب
tabs أولًا suggestedTargetId، ثم tabId المستقر (مثل t1)، والتسمية الاختيارية، وtargetId الخام. مرّر suggestedTargetId مرة أخرى إلى focus وclose واللقطات والإجراءات. عيّن تسمية باستخدام open --label أو tab new --label أو tab label؛ إذ تُقبل جميع التسمية ومعرّفات علامات التبويب ومعرّفات الأهداف الخام والبادئات الفريدة لمعرّفات الأهداف. لا يزال حقل الطلب يحمل الاسم targetId للتوافق، لكنه يقبل أيًا من مراجع علامات التبويب هذه.
معرّفات الأهداف الخام مقابض تشخيصية متقلبة وليست ذاكرة دائمة للوكيل: عندما يستبدل Chromium الهدف الخام الأساسي أثناء التنقل أو إرسال نموذج، يُبقي OpenClaw tabId/التسمية المستقرة مرتبطة بعلامة التبويب البديلة عندما يمكنه إثبات التطابق. يُفضّل استخدام suggestedTargetId.
اللقطة / لقطة الشاشة / الإجراءات
اللقطة:--full-pageمخصص لالتقاط الصفحات فقط؛ ولا يمكن دمجه مع--refأو--element.- تدعم ملفات
existing-session/userالشخصية لقطات شاشة الصفحات ولقطات شاشة--refمن إخراج اللقطة، لكنها لا تدعم لقطات شاشة--elementفي CSS. --labelsيضع مراجع اللقطة الحالية فوق لقطة الشاشة. في الملفات الشخصية المدعومة بواسطة Playwright، يعمل مع--full-page(تراكب كامل الصفحة)، و--ref(تراكب مقتطع للعنصر حسب مرجع ARIA)، و--element(تراكب مقتطع للعنصر حسب محدد CSS)؛ وفي أوضاع اقتطاع العنصر، تُسقط التسميات نسبةً إلى العنصر. تتضمن الاستجابة أيضًا مصفوفةannotations(تُحذف عندما تكون فارغة) تحتوي على المربع المحيط بكل مرجع:refوnumberوroleوnameالاختياري وbox: {x, y, width, height}في فضاء إحداثيات الصورة الملتقطة (إطار العرض / الصفحة الكاملة / نسبةً إلى العنصر). تعرض ملفاتexisting-sessionالشخصية تراكب chrome-mcp على لقطات شاشة الصفحة، لكنها لا تستخدم مساعد الإسقاط في Playwright ولا تتضمنannotations؛ ولا تدعم هناك لقطات شاشة--elementفي CSS. لا تتوفر لقطات الشاشة ذات التسميات من دون Playwright أو chrome-mcp.snapshot --urlsيلحق وجهات الروابط المكتشفة بلقطات الذكاء الاصطناعي حتى يتمكن الوكلاء من اختيار أهداف تنقل مباشرة بدلًا من التخمين اعتمادًا على نص الرابط وحده.
evaluate --fn مصدر دالة أو تعبيرًا أو نص مجموعة عبارات. تُغلّف مجموعات العبارات كدوال غير متزامنة، لذا استخدم return للقيمة التي تريد إعادتها. استخدم --timeout-ms عندما تحتاج الدالة من جانب الصفحة إلى وقت أطول من مهلة التقييم الافتراضية. يعطّل browser.evaluateEnabled=false (الإعداد الافتراضي: true) كلًا من evaluate وwait --fn.
تعيد استجابات الإجراءات targetId الخام الحالي بعد استبدال الصفحة الناتج عن الإجراء عندما يستطيع OpenClaw إثبات علامة التبويب البديلة. مع ذلك، ينبغي للنصوص البرمجية تخزين وتمرير suggestedTargetId/التسميات لسير العمل طويل الأمد.
مساعدات الملفات ومربعات الحوار:
/tmp/openclaw/downloads افتراضيًا، أو جذر الملفات المؤقتة المهيأ). استخدم waitfordownload أو download عندما يحتاج الوكيل إلى انتظار ملف محدد وإعادة مساره؛ إذ تمتلك أدوات الانتظار الصريحة هذه التنزيل التالي. تقبل عمليات الرفع الملفات من جذر عمليات الرفع المؤقتة في OpenClaw والوسائط الواردة التي يديرها OpenClaw، بما في ذلك مراجع media://inbound/<id> وmedia/inbound/<id> النسبية إلى بيئة الحماية. تُرفض مراجع الوسائط المتداخلة واجتياز المسارات والمسارات المحلية الاعتباطية.
عندما يفتح إجراء مربع حوار نمطيًا، تعيد استجابة الإجراء blockedByDialog مع browserState.dialogs.pending؛ مرّر --dialog-id للرد عليه مباشرةً. تظهر مربعات الحوار التي عولجت خارج OpenClaw ضمن browserState.dialogs.recent.
الحالة والتخزين
إطار العرض والمحاكاة:تصحيح الأخطاء
Chrome الحالي عبر MCP
استخدم ملف التعريف المضمّنuser، أو أنشئ ملف تعريف existing-session خاصًا بك:
--cdp-url كي يتصل Chrome MCP بنقطة النهاية تلك بدلًا من ذلك. بالنسبة إلى Docker أو Browserless أو إعدادات بعيدة أخرى لا تحتاج إلى دلالات Chrome MCP، استخدم ملف تعريف CDP بدلًا من ذلك.
القيود الحالية للجلسة الحالية:
- تستخدم الإجراءات المعتمدة على اللقطات المراجع، لا محددات CSS.
browser.actionTimeoutMsيعيّن الطلبات المدعومةactافتراضيًا إلى 60000 ms عندما يحذف المستدعونtimeoutMs؛ وتظل قيمةtimeoutMsلكل استدعاء هي ذات الأولوية.clickيدعم النقر بزر الفأرة الأيسر فقط.typeلا يدعمslowly=true.pressلا يدعمdelayMs.hoverوscrollintoviewوdragوselectوfillترفض تجاوزات المهلة لكل استدعاء؛ ويقبلevaluateالقيمة--timeout-ms.selectيدعم قيمة واحدة فقط.wait --load networkidleغير مدعوم (يعمل مع ملفات تعريف CDP المُدارة والخام/البعيدة).- تتطلب عمليات رفع الملفات
--ref/--input-ref، ولا تدعم--elementفي CSS، وتدعم ملفًا واحدًا في كل مرة. - لا تدعم خطافات مربعات الحوار
--timeout. - تدعم لقطات الشاشة التقاط الصفحة و
--ref، لكن ليس--elementفي CSS. - لا تزال
responsebodyواعتراض التنزيل وتصدير PDF والإجراءات المجمّعة تتطلب متصفحًا مُدارًا أو ملف تعريف CDP خامًا.
التحكم في المتصفح عن بُعد (وكيل مضيف Node)
إذا كان Gateway يعمل على جهاز مختلف عن المتصفح، فشغّل مضيف Node على الجهاز الذي يحتوي على Chrome/Brave/Edge/Chromium. يمرّر Gateway إجراءات المتصفح بالوكالة إلى مضيف Node هذا؛ ولا يلزم خادم منفصل للتحكم في المتصفح. استخدمgateway.nodes.browser.mode للتحكم في التوجيه التلقائي وgateway.nodes.browser.node لتثبيت مضيف Node محدد إذا كانت عدة مضيفات متصلة.
الأمان + الإعداد عن بُعد: أداة المتصفح، الوصول عن بُعد، Tailscale، الأمان