openclaw browser

إدارة سطح التحكم في المتصفح في OpenClaw وتشغيل إجراءات المتصفح (دورة الحياة، الملفات التعريفية، علامات التبويب، اللقطات، لقطات الشاشة، التنقل، الإدخال، محاكاة الحالة، وتصحيح الأخطاء).

ذات صلة:

• أداة المتصفح + API: أداة المتصفح

العلامات الشائعة

• --url <gatewayWsUrl>: عنوان URL لـ WebSocket في Gateway (يستخدم الإعدادات افتراضياً).
• --token <token>: رمز Gateway (إذا كان مطلوباً).
• --timeout <ms>: مهلة الطلب (ms).
• --expect-final: الانتظار لاستجابة Gateway نهائية.
• --browser-profile <name>: اختيار ملف تعريفي للمتصفح (الافتراضي من الإعدادات).
• --json: إخراج قابل للقراءة آلياً (حيثما يكون مدعوماً).

البدء السريع (محلي)

openclaw browser profilesopenclaw browser --browser-profile openclaw startopenclaw browser --browser-profile openclaw open https://example.comopenclaw browser --browser-profile openclaw snapshot

يمكن للوكلاء تشغيل فحص الجاهزية نفسه باستخدام browser({ action: "doctor" }).

استكشاف الأخطاء سريعاً

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

الحد الأدنى من التسلسل:

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

إرشادات مفصلة: استكشاف أخطاء المتصفح

دورة الحياة

openclaw browser statusopenclaw browser doctoropenclaw browser doctor --deepopenclaw browser startopenclaw browser start --headlessopenclaw browser stopopenclaw browser --browser-profile openclaw reset-profile

ملاحظات:

• يضيف doctor --deep فحص لقطة حي. يكون مفيداً عندما تكون جاهزية CDP الأساسية خضراء لكنك تريد دليلاً على أن علامة التبويب الحالية قابلة للفحص.
• بالنسبة إلى ملفات attachOnly وملفات CDP البعيدة، يغلق openclaw browser stop جلسة التحكم النشطة ويمسح تجاوزات المحاكاة المؤقتة حتى عندما لا يكون OpenClaw قد شغّل عملية المتصفح بنفسه.
• بالنسبة إلى الملفات التعريفية المحلية المُدارة، يوقف openclaw browser stop عملية المتصفح التي تم إنشاؤها.
• يطبّق openclaw browser start --headless على طلب البدء هذا فقط و فقط عندما يشغّل OpenClaw متصفحاً محلياً مُداراً. لا يعيد كتابة browser.headless أو إعدادات الملف التعريفي، ولا يفعل شيئاً لمتصفح يعمل بالفعل.
• على مضيفي Linux من دون DISPLAY أو WAYLAND_DISPLAY، تعمل الملفات التعريفية المحلية المُدارة بوضع headless تلقائياً ما لم يطلب OPENCLAW_BROWSER_HEADLESS=0 أو browser.headless=false أو browser.profiles.<name>.headless=false متصفحاً مرئياً صراحةً.

إذا كان الأمر مفقوداً

إذا كان openclaw browser أمراً غير معروف، فتحقق من plugins.allow في ~/.openclaw/openclaw.json.

عندما يكون plugins.allow موجوداً، أدرج Plugin المتصفح المضمّن صراحةً ما لم تكن الإعدادات تحتوي بالفعل على كتلة browser جذرية:

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

كتلة browser جذرية صريحة، مثل browser.enabled=true أو browser.profiles.<name>، تنشّط أيضاً Plugin المتصفح المضمّن ضمن قائمة سماح Plugins مقيّدة.

ذات صلة: أداة المتصفح

الملفات التعريفية

الملفات التعريفية هي إعدادات توجيه متصفح مسماة. عملياً:

• openclaw: يشغّل مثيل Chrome مخصصاً تديره OpenClaw أو يتصل به (دليل بيانات مستخدم معزول).
• user: يتحكم في جلسة Chrome الحالية المسجَّل دخولك إليها عبر Chrome DevTools MCP.
• ملفات CDP التعريفية المخصصة: تشير إلى نقطة نهاية CDP محلية أو بعيدة.

openclaw browser profilesopenclaw browser create-profile --name work --color "#FF5A36"openclaw browser create-profile --name chrome-live --driver existing-sessionopenclaw browser create-profile --name remote --cdp-url https://browser-host.example.comopenclaw browser delete-profile --name work

استخدام ملف تعريفي محدد:

openclaw browser --browser-profile work tabs

علامات التبويب

openclaw browser tabsopenclaw browser tab new --label docsopenclaw browser tab label t1 docsopenclaw browser tab select 2openclaw browser tab close 2openclaw browser open https://docs.openclaw.ai --label docsopenclaw browser focus docsopenclaw browser close t1

يعيد tabs أولاً suggestedTargetId، ثم tabId المستقر مثل t1، والتسمية الاختيارية، وtargetId الخام. يجب على الوكلاء تمرير suggestedTargetId مرة أخرى إلى focus وclose واللقطات والإجراءات. يمكنك تعيين تسمية باستخدام open --label أو tab new --label أو tab label؛ وتُقبل التسميات ومعرّفات علامات التبويب ومعرّفات الأهداف الخام وبادئات target-id الفريدة كلها. لا يزال حقل الطلب مسمى targetId للتوافق، لكنه يقبل مراجع علامات التبويب هذه. تعامل مع معرّفات الأهداف الخام كمقابض تشخيصية، لا كذاكرة وكيل دائمة. عندما يستبدل Chromium الهدف الخام الأساسي أثناء تنقل أو إرسال نموذج، تبقي OpenClaw tabId/التسمية المستقرة مرتبطة بعلامة التبويب البديلة عندما تستطيع إثبات التطابق. تبقى معرّفات الأهداف الخام متقلبة؛ فضّل suggestedTargetId.

اللقطة / لقطة الشاشة / الإجراءات

لقطة:

openclaw browser snapshotopenclaw browser snapshot --urls

لقطة شاشة:

openclaw browser screenshotopenclaw browser screenshot --full-pageopenclaw browser screenshot --ref e12openclaw browser screenshot --labels

ملاحظات:

• --full-page مخصص لالتقاط الصفحات فقط؛ لا يمكن دمجه مع --ref أو --element.
• تدعم ملفات existing-session / user التعريفية لقطات شاشة للصفحة ولقطات شاشة --ref من إخراج اللقطة، لكنها لا تدعم لقطات شاشة CSS --element.
• يضيف --labels طبقة تراكب لمراجع اللقطة الحالية على لقطة الشاشة. في الملفات التعريفية المدعومة بـ Playwright، يعمل مع --full-page (طبقة تسمية لكامل الصفحة)، و--ref (طبقة تسمية لقص عنصر حسب مرجع ARIA)، و--element (طبقة تسمية لقص عنصر حسب محدد CSS)؛ في أوضاع قص العناصر، تُسقط التسميات نسبياً إلى العنصر. تتضمن الاستجابة أيضاً مصفوفة annotations تحتوي على مربع الإحاطة لكل مرجع. يحتوي كل عنصر على ref، وnumber، وrole، وname اختياري، وbox: {x, y, width, height}؛ تكون الإحداثيات في مساحة الصورة الملتقطة (منفذ العرض / الصفحة الكاملة / نسبية إلى العنصر). يُحذف الحقل عندما يكون فارغاً. تعرض ملفات existing-session التعريفية طبقة تراكب chrome-mcp على لقطات شاشة الصفحة لكنها لا تستخدم مساعد إسقاط Playwright ولا تتضمن annotations؛ لقطات شاشة CSS --element غير مدعومة هناك. من دون Playwright أو chrome-mcp، لا تتوفر لقطات الشاشة ذات التسميات. كانت الإصدارات السابقة تتجاهل --full-page و--ref و--element في لقطات شاشة Playwright ذات التسميات وتعيد دائماً التقاطاً لمنفذ العرض؛ أصبحت لقطات الشاشة ذات التسميات الآن تحترم تلك النطاقات.
• يضيف snapshot --urls وجهات الروابط المكتشفة إلى لقطات AI بحيث يستطيع الوكلاء اختيار أهداف تنقل مباشرة بدلاً من التخمين من نص الرابط وحده.

التنقل/النقر/الكتابة (أتمتة واجهة المستخدم المستندة إلى المرجع):

openclaw browser navigate https://example.comopenclaw browser click <ref>openclaw browser click-coords 120 340openclaw browser type <ref> "hello"openclaw browser press Enteropenclaw browser hover <ref>openclaw browser scrollintoview <ref>openclaw browser drag <startRef> <endRef>openclaw browser select <ref> OptionA OptionBopenclaw browser fill --fields '[{"ref":"1","value":"Ada"}]'openclaw browser wait --text "Done"openclaw browser evaluate --fn '(el) => el.textContent' --ref <ref>openclaw browser evaluate --fn 'const title = document.title; return title;'openclaw browser evaluate --timeout-ms 30000 --fn 'async () => { await window.ready; return true; }'

يقبل evaluate --fn مصدر دالة، أو تعبيراً، أو جسم عبارة. تُغلّف أجسام العبارات كدوال async، لذا استخدم return للقيمة التي تريد إرجاعها. استخدم evaluate --timeout-ms <ms> عندما قد تحتاج الدالة على جانب الصفحة إلى وقت أطول من مهلة evaluate الافتراضية.

تعيد استجابات الإجراءات targetId الخام الحالي بعد استبدال الصفحة المشغّل بالإجراء عندما تستطيع OpenClaw إثبات علامة التبويب البديلة. ينبغي للسكربتات مع ذلك تخزين وتمرير suggestedTargetId/التسميات لسير العمل طويل الأمد.

مساعدات الملفات + مربعات الحوار:

openclaw browser upload /tmp/openclaw/uploads/file.pdf --ref <ref>openclaw browser upload media://inbound/file.pdf --ref <ref>openclaw browser waitfordownloadopenclaw browser download <ref> report.pdfopenclaw browser dialog --acceptopenclaw browser dialog --dismiss --dialog-id d1

تحفظ ملفات Chrome التعريفية المُدارة التنزيلات العادية الناتجة عن النقر في دليل تنزيلات OpenClaw (/tmp/openclaw/downloads افتراضياً، أو جذر temp المُعد). استخدم waitfordownload أو download عندما يحتاج الوكيل إلى انتظار ملف محدد وإرجاع مساره؛ تمتلك أدوات الانتظار الصريحة هذه التنزيل التالي. تقبل عمليات الرفع الملفات من جذر الرفع المؤقت في OpenClaw والوسائط الواردة المُدارة من OpenClaw، بما في ذلك مراجع media://inbound/<id> و media/inbound/<id> النسبية إلى sandbox. تظل مراجع الوسائط المتداخلة، واجتياز المسارات، والمسارات المحلية العشوائية مرفوضة. عندما يفتح إجراء مربع حوار modal، تعيد استجابة الإجراء blockedByDialog مع browserState.dialogs.pending؛ مرر --dialog-id للإجابة عنه مباشرة. تظهر مربعات الحوار التي تمت معالجتها خارج OpenClaw ضمن browserState.dialogs.recent.

الحالة والتخزين

منفذ العرض + المحاكاة:

openclaw browser resize 1280 720openclaw browser set viewport 1280 720openclaw browser set offline onopenclaw browser set media darkopenclaw browser set timezone Europe/Londonopenclaw browser set locale en-GBopenclaw browser set geo 51.5074 -0.1278 --accuracy 25openclaw browser set device "iPhone 14"openclaw browser set headers '{"x-test":"1"}'openclaw browser set credentials myuser mypass

ملفات تعريف الارتباط + التخزين:

openclaw browser cookiesopenclaw browser cookies set session abc123 --url https://example.comopenclaw browser cookies clearopenclaw browser storage local getopenclaw browser storage local set token abc123openclaw browser storage session clear

تصحيح الأخطاء

openclaw browser console --level erroropenclaw browser pdfopenclaw browser responsebody "**/api"openclaw browser highlight <ref>openclaw browser errors --clearopenclaw browser requests --filter apiopenclaw browser trace startopenclaw browser trace stop --out trace.zip

Chrome الحالي عبر MCP

استخدم الملف التعريفي المدمج user، أو أنشئ ملف existing-session تعريفي خاصاً بك:

openclaw browser --browser-profile user tabsopenclaw browser create-profile --name chrome-live --driver existing-sessionopenclaw browser create-profile --name brave-live --driver existing-session --user-data-dir "~/Library/Application Support/BraveSoftware/Brave-Browser"openclaw browser create-profile --name chrome-port --driver existing-session --cdp-url http://127.0.0.1:9222openclaw browser --browser-profile chrome-live tabs

مسار existing-session الافتراضي هو اتصال Chrome MCP تلقائي خاص بالمضيف فقط. إذا كان المتصفح يعمل بالفعل مع نقطة نهاية DevTools، فمرر --cdp-url لكي يتصل Chrome MCP بتلك النقطة بدلاً من ذلك. بالنسبة إلى Docker أو Browserless أو إعدادات بعيدة أخرى حيث لا تكون دلالات Chrome MCP مطلوبة، استخدم ملف CDP تعريفي.

حدود existing-session الحالية:

• تستخدم الإجراءات المعتمدة على اللقطات المراجع، وليس محددات CSS
• يضبط browser.actionTimeoutMs طلبات act المدعومة افتراضيًا على 60000 مللي ثانية عندما يحذف المستدعون timeoutMs؛ وتظل قيمة timeoutMs لكل استدعاء هي الغالبة.
• click للنقر بالزر الأيسر فقط
• لا يدعم type الخيار slowly=true
• لا يدعم press الخيار delayMs
• ترفض hover وscrollintoview وdrag وselect وfill وevaluate تجاوزات المهلة لكل استدعاء
• يدعم select قيمة واحدة فقط
• لا يُدعم wait --load networkidle في ملفات تعريف الجلسات الحالية (يعمل على CDP المُدار والخام/البعيد)
• تتطلب عمليات رفع الملفات --ref / --input-ref، ولا تدعم CSS --element، وتدعم حاليًا ملفًا واحدًا في كل مرة
• لا تدعم خطاطيف مربعات الحوار --timeout
• تدعم لقطات الشاشة التقاط الصفحة و--ref، ولكن لا تدعم CSS --element
• لا تزال responsebody، واعتراض التنزيلات، وتصدير PDF، والإجراءات الدفعية تتطلب متصفحًا مُدارًا أو ملف تعريف CDP خامًا

التحكم في المتصفح عن بُعد (وكيل مضيف node)

إذا كان Gateway يعمل على جهاز مختلف عن المتصفح، فشغّل مضيف node على الجهاز الذي يحتوي على Chrome/Brave/Edge/Chromium. سيقوم Gateway بتمرير إجراءات المتصفح عبر وكيل إلى تلك العقدة (لا يلزم خادم منفصل للتحكم في المتصفح).

استخدم gateway.nodes.browser.mode للتحكم في التوجيه التلقائي، وgateway.nodes.browser.node لتثبيت عقدة محددة إذا كانت هناك عدة عقد متصلة.

الأمان + الإعداد عن بُعد: أداة المتصفح، الوصول عن بُعد، Tailscale، الأمان

ذو صلة

• مرجع CLI
• المتصفح