الانتقال إلى المحتوى الرئيسي

​
openclaw browser

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

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

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

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

openclaw browser profiles
openclaw browser --browser-profile openclaw start
openclaw browser --browser-profile openclaw open https://example.com
openclaw browser --browser-profile openclaw snapshot
يمكن للوكلاء تشغيل فحص الجاهزية نفسه باستخدام browser({ action: "doctor" }).

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

إذا فشل start مع not reachable after start، فاستكشف جاهزية CDP أولاً. إذا نجح start وtabs لكن فشل open أو navigate، فإن مستوى التحكم في المتصفح سليم ويكون الفشل عادةً بسبب سياسة SSRF للتنقل. الحد الأدنى من التسلسل: 
openclaw browser --browser-profile openclaw doctor
openclaw browser --browser-profile openclaw start
openclaw browser --browser-profile openclaw tabs
openclaw browser --browser-profile openclaw open https://example.com
إرشادات مفصلة: استكشاف أخطاء المتصفح

​
دورة الحياة

openclaw browser status
openclaw browser doctor
openclaw browser doctor --deep
openclaw browser start
openclaw browser start --headless
openclaw browser stop
openclaw 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 profiles
openclaw browser create-profile --name work --color "#FF5A36"
openclaw browser create-profile --name chrome-live --driver existing-session
openclaw browser create-profile --name remote --cdp-url https://browser-host.example.com
openclaw browser delete-profile --name work
استخدام ملف تعريفي محدد: 
openclaw browser --browser-profile work tabs

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

openclaw browser tabs
openclaw browser tab new --label docs
openclaw browser tab label t1 docs
openclaw browser tab select 2
openclaw browser tab close 2
openclaw browser open https://docs.openclaw.ai --label docs
openclaw browser focus docs
openclaw 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 snapshot
openclaw browser snapshot --urls
لقطة شاشة: 
openclaw browser screenshot
openclaw browser screenshot --full-page
openclaw browser screenshot --ref e12
openclaw 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.com
openclaw browser click <ref>
openclaw browser click-coords 120 340
openclaw browser type <ref> "hello"
openclaw browser press Enter
openclaw browser hover <ref>
openclaw browser scrollintoview <ref>
openclaw browser drag <startRef> <endRef>
openclaw browser select <ref> OptionA OptionB
openclaw 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 waitfordownload
openclaw browser download <ref> report.pdf
openclaw browser dialog --accept
openclaw 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 720
openclaw browser set viewport 1280 720
openclaw browser set offline on
openclaw browser set media dark
openclaw browser set timezone Europe/London
openclaw browser set locale en-GB
openclaw browser set geo 51.5074 -0.1278 --accuracy 25
openclaw browser set device "iPhone 14"
openclaw browser set headers '{"x-test":"1"}'
openclaw browser set credentials myuser mypass
ملفات تعريف الارتباط + التخزين: 
openclaw browser cookies
openclaw browser cookies set session abc123 --url https://example.com
openclaw browser cookies clear
openclaw browser storage local get
openclaw browser storage local set token abc123
openclaw browser storage session clear

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

openclaw browser console --level error
openclaw browser pdf
openclaw browser responsebody "**/api"
openclaw browser highlight <ref>
openclaw browser errors --clear
openclaw browser requests --filter api
openclaw browser trace start
openclaw browser trace stop --out trace.zip

​
Chrome الحالي عبر MCP

استخدم الملف التعريفي المدمج user، أو أنشئ ملف existing-session تعريفي خاصاً بك: 
openclaw browser --browser-profile user tabs
openclaw browser create-profile --name chrome-live --driver existing-session
openclaw 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:9222
openclaw 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، الأمان

​
ذو صلة