# openclaw browser

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

ذات صلة:

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

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

• --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، تعمل الملفات الشخصية المحلية المُدارة بلا واجهة تلقائيًا ما لم يطلب 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 المتصفح المضمّن ضمن قائمة سماح Plugin تقييدية.

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

# الملفات الشخصية

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

• 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؛ وتُقبل التسميات ومعرّفات علامات التبويب ومعرّفات الهدف الخام والبادئات الفريدة لمعرّف الهدف كلها. عندما يستبدل 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 مراجع اللقطة الحالية فوق لقطة الشاشة.
• يضيف snapshot --urls وجهات الروابط المكتشفة إلى لقطات الذكاء الاصطناعي حتى يتمكن الوكلاء من اختيار أهداف تنقل مباشرة بدلًا من التخمين من نص الرابط وحده.

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

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>

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

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

openclaw browser upload /tmp/openclaw/uploads/file.pdf --ref <ref>
openclaw browser waitfordownload
openclaw browser download <ref> report.pdf
openclaw browser dialog --accept

تحفظ ملفات Chrome الشخصية المُدارة التنزيلات العادية الناتجة عن النقر في دليل تنزيلات OpenClaw (/tmp/openclaw/downloads افتراضيًا، أو جذر الملفات المؤقتة المضبوط). استخدم waitfordownload أو download عندما يحتاج الوكيل إلى انتظار ملف محدد وإعادة مساره؛ تمتلك أدوات الانتظار الصريحة هذه التنزيل التالي.

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

إطار العرض + المحاكاة:

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 --browser-profile chrome-live tabs

هذا المسار خاص بالمضيف فقط. بالنسبة إلى Docker أو الخوادم بلا واجهة أو Browserless أو الإعدادات البعيدة الأخرى، استخدم ملف CDP شخصيًا بدلًا من ذلك.

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

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

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

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

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

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

# ذات صلة

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