​

المتصفح (بإدارة openclaw)

• فكّر فيه على أنه متصفح منفصل مخصص للوكيل فقط.
• لا يلمس ملف تعريف openclaw ملف تعريف متصفحك الشخصي.
• يمكن للوكيل فتح علامات التبويب وقراءة الصفحات والنقر والكتابة ضمن مسار آمن.
• يتصل ملف التعريف المدمج user بجلسة Chrome الحقيقية المسجّل دخولك فيها عبر Chrome MCP.

​

ما الذي ستحصل عليه

• ملف تعريف متصفح منفصل باسم openclaw (بتمييز برتقالي افتراضيًا).
• تحكم حتمي في علامات التبويب (عرض/فتح/تركيز/إغلاق).
• إجراءات الوكيل (نقر/كتابة/سحب/تحديد)، ولقطات snapshot، ولقطات شاشة، وPDF.
• دعم اختياري لعدة ملفات تعريف (openclaw وwork وremote و…).

​

البدء السريع

openclaw browser --browser-profile openclaw status
openclaw browser --browser-profile openclaw start
openclaw browser --browser-profile openclaw open https://example.com
openclaw browser --browser-profile openclaw snapshot

​

التحكم عبر plugin

{
  plugins: {
    entries: {
      browser: {
        enabled: false,
      },
    },
  },
}

• ألا يكون plugins.entries.browser.enabled معطّلًا
• وأن تكون browser.enabled=true

​

أمر المتصفح أو الأداة مفقود

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

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

• لا تكفي browser.enabled=true وحدها عند تعيين plugins.allow.
• لا تكفي plugins.entries.browser.enabled=true وحدها أيضًا عند تعيين plugins.allow.
• لا تقوم tools.alsoAllow: ["browser"] بتحميل plugin المتصفح المجمّع. بل تضبط سياسة الأدوات فقط بعد تحميل plugin بالفعل.
• إذا لم تكن بحاجة إلى قائمة سماح مقيّدة لـ plugin، فإن إزالة plugins.allow تعيد أيضًا سلوك المتصفح المجمّع الافتراضي.

• openclaw browser أمر غير معروف.
• browser.request مفقود.
• يبلّغ الوكيل أن أداة المتصفح غير متاحة أو مفقودة.

​

ملفات التعريف: openclaw مقابل user

• openclaw: متصفح مُدار ومعزول (لا يحتاج إلى extension).
• user: ملف تعريف مدمج للاتصال بجلسة Chrome MCP الخاصة بجلسة Chrome الحقيقية المسجّل دخولك فيها.

• الافتراضي: استخدام متصفح openclaw المعزول.
• يُفضَّل profile="user" عندما تكون جلسات تسجيل الدخول الحالية مهمة ويكون المستخدم أمام الكمبيوتر للنقر/الموافقة على أي مطالبة اتصال.
• profile هو التجاوز الصريح عندما تريد وضع متصفح محددًا.

​

التهيئة

{
  browser: {
    enabled: true, // default: true
    ssrfPolicy: {
      dangerouslyAllowPrivateNetwork: true, // default trusted-network mode
      // allowPrivateNetwork: true, // legacy alias
      // hostnameAllowlist: ["*.example.com", "example.com"],
      // allowedHostnames: ["localhost"],
    },
    // cdpUrl: "http://127.0.0.1:18792", // legacy single-profile override
    remoteCdpTimeoutMs: 1500, // remote CDP HTTP timeout (ms)
    remoteCdpHandshakeTimeoutMs: 3000, // remote CDP WebSocket handshake timeout (ms)
    defaultProfile: "openclaw",
    color: "#FF4500",
    headless: false,
    noSandbox: false,
    attachOnly: false,
    executablePath: "/Applications/Brave Browser.app/Contents/MacOS/Brave Browser",
    profiles: {
      openclaw: { cdpPort: 18800, color: "#FF4500" },
      work: { cdpPort: 18801, color: "#0066CC" },
      user: {
        driver: "existing-session",
        attachOnly: true,
        color: "#00AA00",
      },
      brave: {
        driver: "existing-session",
        attachOnly: true,
        userDataDir: "~/Library/Application Support/BraveSoftware/Brave-Browser",
        color: "#FB542B",
      },
      remote: { cdpUrl: "http://10.0.0.42:9222", color: "#00AA00" },
    },
  },
}

• ترتبط خدمة التحكم بالمتصفح بعنوان local loopback على منفذ مشتق من gateway.port (الافتراضي: 18791، أي gateway + 2).
• إذا تجاوزت منفذ Gateway (gateway.port أو OPENCLAW_GATEWAY_PORT)، فإن منافذ المتصفح المشتقة تتغير لتبقى ضمن “العائلة” نفسها.
• تكون القيمة الافتراضية لـ cdpUrl هي منفذ CDP المحلي المُدار عندما لا يتم تعيينها.
• ينطبق remoteCdpTimeoutMs على فحوصات الوصول إلى CDP البعيد (غير local loopback).
• ينطبق remoteCdpHandshakeTimeoutMs على فحوصات الوصول إلى WebSocket الخاص بـ CDP البعيد.
• تكون عملية التنقل/فتح علامة التبويب في المتصفح محمية من SSRF قبل التنقل ويُعاد التحقق منها قدر الإمكان على عنوان http(s) النهائي بعد التنقل.
• في وضع SSRF الصارم، يتم أيضًا التحقق من اكتشاف/فحص نقاط نهاية CDP البعيدة (cdpUrl، بما في ذلك عمليات البحث في /json/version).
• تكون القيمة الافتراضية لـ browser.ssrfPolicy.dangerouslyAllowPrivateNetwork هي true (نموذج الشبكة الموثوقة). عيّنها إلى false للتصفح العام الصارم فقط.
• لا يزال browser.ssrfPolicy.allowPrivateNetwork مدعومًا كاسم بديل قديم للتوافق.
• تعني attachOnly: true “عدم تشغيل متصفح محلي مطلقًا؛ والاتصال فقط إذا كان يعمل بالفعل.”
• يلوّن color وcolor لكل ملف تعريف واجهة المتصفح لتتمكن من معرفة أي ملف تعريف نشط.
• ملف التعريف الافتراضي هو openclaw (متصفح مستقل مُدار من OpenClaw). استخدم defaultProfile: "user" للاشتراك في متصفح المستخدم المسجّل دخوله.
• ترتيب الاكتشاف التلقائي: متصفح النظام الافتراضي إذا كان قائمًا على Chromium؛ وإلا Chrome ← Brave ← Edge ← Chromium ← Chrome Canary.
• تقوم ملفات تعريف openclaw المحلية بتعيين cdpPort/cdpUrl تلقائيًا — عيّن هذه القيم فقط لـ CDP البعيد.
• يستخدم driver: "existing-session" Chrome DevTools MCP بدلًا من CDP الخام. لا تعيّن cdpUrl لهذا المشغّل.
• عيّن browser.profiles.<name>.userDataDir عندما يجب على ملف تعريف existing-session الاتصال بملف تعريف مستخدم Chromium غير افتراضي مثل Brave أو Edge.

​

استخدام Brave (أو متصفح آخر قائم على Chromium)

openclaw config set browser.executablePath "/usr/bin/google-chrome"

// macOS
{
  browser: {
    executablePath: "/Applications/Brave Browser.app/Contents/MacOS/Brave Browser"
  }
}

// Windows
{
  browser: {
    executablePath: "C:\\Program Files\\BraveSoftware\\Brave-Browser\\Application\\brave.exe"
  }
}

// Linux
{
  browser: {
    executablePath: "/usr/bin/brave-browser"
  }
}

​

التحكم المحلي مقابل البعيد

• التحكم المحلي (الافتراضي): يبدأ Gateway خدمة التحكم على local loopback ويمكنه تشغيل متصفح محلي.
• التحكم البعيد (مضيف node): شغّل مضيف node على الجهاز الذي يحتوي على المتصفح؛ وسيقوم Gateway بتمرير إجراءات المتصفح إليه.
• CDP البعيد: عيّن browser.profiles.<name>.cdpUrl (أو browser.cdpUrl) من أجل الاتصال بمتصفح بعيد قائم على Chromium. في هذه الحالة، لن يشغّل OpenClaw متصفحًا محليًا.

• ملفات التعريف المحلية المُدارة: يقوم openclaw browser stop بإيقاف عملية المتصفح التي شغّلها OpenClaw
• ملفات attach-only وCDP البعيدة: يقوم openclaw browser stop بإغلاق جلسة التحكم النشطة وتحرير تجاوزات محاكاة Playwright/CDP (منفذ العرض، ونظام الألوان، واللغة، والمنطقة الزمنية، ووضع عدم الاتصال، والحالة المشابهة)، حتى لو لم يُشغّل OpenClaw أي عملية متصفح

• رموز استعلام (مثل https://provider.example?token=<token>)
• مصادقة HTTP Basic (مثل https://user:pass@provider.example)

​

وكيل متصفح node (افتراضي بلا تهيئة)

• يكشف مضيف node عن خادم التحكم المحلي في المتصفح عبر أمر وكيل.
• تأتي ملفات التعريف من تهيئة browser.profiles الخاصة بالـ node نفسه (كما في الوضع المحلي).
• nodeHost.browserProxy.allowProfiles اختياري. اتركه فارغًا للحصول على السلوك القديم/الافتراضي: تظل جميع ملفات التعريف المهيأة قابلة للوصول عبر الوكيل، بما في ذلك مسارات إنشاء/حذف ملفات التعريف.
• إذا عيّنت nodeHost.browserProxy.allowProfiles، فإن OpenClaw يتعامل معه كحد أقل الامتيازات: لا يمكن استهداف إلا ملفات التعريف الموجودة في قائمة السماح، وتُحظر مسارات إنشاء/حذف ملفات التعريف الدائمة على سطح الوكيل.
• عطّله إذا كنت لا تريده:
  • على الـ node: nodeHost.browserProxy.enabled=false
  • على الـ gateway: ‏gateway.nodes.browser.mode="off"

​

Browserless (CDP بعيد مستضاف)

{
  browser: {
    enabled: true,
    defaultProfile: "browserless",
    remoteCdpTimeoutMs: 2000,
    remoteCdpHandshakeTimeoutMs: 4000,
    profiles: {
      browserless: {
        cdpUrl: "wss://production-sfo.browserless.io?token=<BROWSERLESS_API_KEY>",
        color: "#00AA00",
      },
    },
  },
}

• استبدل <BROWSERLESS_API_KEY> برمز Browserless الحقيقي الخاص بك.
• اختر نقطة نهاية المنطقة التي تطابق حساب Browserless الخاص بك (راجع وثائقهم).
• إذا منحك Browserless عنوان HTTPS أساسيًا، فيمكنك إما تحويله إلى wss:// لاتصال CDP مباشر أو الاحتفاظ بعنوان HTTPS وترك OpenClaw يكتشف /json/version.

​

موفرو WebSocket CDP المباشر

• نقاط النهاية HTTP(S) — يستدعي OpenClaw ‏/json/version لاكتشاف عنوان WebSocket debugger، ثم يتصل به.
• نقاط النهاية WebSocket (ws:// / wss://) — يتصل OpenClaw مباشرة، متجاوزًا /json/version. استخدم هذا لخدمات مثل Browserless، وBrowserbase، أو أي موفر يزوّدك بعنوان WebSocket.

​

Browserbase

{
  browser: {
    enabled: true,
    defaultProfile: "browserbase",
    remoteCdpTimeoutMs: 3000,
    remoteCdpHandshakeTimeoutMs: 5000,
    profiles: {
      browserbase: {
        cdpUrl: "wss://connect.browserbase.com?apiKey=<BROWSERBASE_API_KEY>",
        color: "#F97316",
      },
    },
  },
}

• أنشئ حسابًا وانسخ API Key من لوحة معلومات Overview.
• استبدل <BROWSERBASE_API_KEY> بمفتاح API الحقيقي الخاص بـ Browserbase.
• ينشئ Browserbase جلسة متصفح تلقائيًا عند الاتصال عبر WebSocket، لذا لا حاجة إلى خطوة إنشاء جلسة يدويًا.
• تتيح الخطة المجانية جلسة متزامنة واحدة وساعة متصفح واحدة شهريًا. راجع الأسعار لمعرفة حدود الخطط المدفوعة.
• راجع وثائق Browserbase للحصول على المرجع الكامل لـ API، وأدلة SDK، وأمثلة التكامل.

​

الأمان

• التحكم بالمتصفح متاح على local loopback فقط؛ ويعبر الوصول من خلال مصادقة Gateway أو إقران node.
• يستخدم HTTP API المستقل للمتصفح على local loopback مصادقة السر المشترك فقط: مصادقة bearer لرمز gateway، أو x-openclaw-password، أو HTTP Basic auth مع كلمة مرور gateway المهيأة.
• لا تقوم رؤوس هوية Tailscale Serve وgateway.auth.mode: "trusted-proxy" بمصادقة HTTP API المستقل هذا للمتصفح على local loopback.
• إذا كان التحكم بالمتصفح ممكّنًا ولم تُهيأ أي مصادقة بالسر المشترك، فسيقوم OpenClaw بإنشاء gateway.auth.token تلقائيًا عند بدء التشغيل وحفظه في التهيئة.
• لا ينشئ OpenClaw هذا الرمز تلقائيًا عندما يكون gateway.auth.mode مضبوطًا بالفعل على password أو none أو trusted-proxy.
• أبقِ Gateway وأي مضيفات node على شبكة خاصة (Tailscale)؛ وتجنب تعريضها للعامة.
• تعامل مع عناوين/رموز CDP البعيدة باعتبارها أسرارًا؛ وفضّل متغيرات البيئة أو مدير أسرار.

• فضّل نقاط النهاية المشفرة (HTTPS أو WSS) والرموز قصيرة العمر حيثما أمكن.
• تجنّب تضمين الرموز طويلة العمر مباشرة في ملفات التهيئة.

​

ملفات التعريف (متصفحات متعددة)

• بإدارة OpenClaw: مثيل متصفح مخصص قائم على Chromium مع دليل بيانات مستخدم ومنفذ CDP خاصين به
• بعيد: عنوان CDP صريح (متصفح قائم على Chromium يعمل في مكان آخر)
• جلسة موجودة: ملف تعريف Chrome الحالي لديك عبر الاتصال التلقائي بـ Chrome DevTools MCP

• يُنشأ ملف التعريف openclaw تلقائيًا إذا كان مفقودًا.
• ملف التعريف user مدمج للاتصال بـ Chrome MCP existing-session.
• تكون ملفات تعريف existing-session اختيارية فيما عدا user؛ أنشئها باستخدام --driver existing-session.
• تخصص منافذ CDP المحلية من 18800–18899 افتراضيًا.
• يؤدي حذف ملف تعريف إلى نقل دليل بياناته المحلي إلى سلة المهملات.

​

existing-session عبر Chrome DevTools MCP

• Chrome for Developers: Use Chrome DevTools MCP with your browser session
• Chrome DevTools MCP README

• user

• يستخدم ملف التعريف المدمج user الاتصال التلقائي عبر Chrome MCP، والذي يستهدف ملف تعريف Google Chrome المحلي الافتراضي.

{
  browser: {
    profiles: {
      brave: {
        driver: "existing-session",
        attachOnly: true,
        userDataDir: "~/Library/Application Support/BraveSoftware/Brave-Browser",
        color: "#FB542B",
      },
    },
  },
}

1. افتح صفحة inspect الخاصة بذلك المتصفح للتصحيح عن بُعد.
2. فعّل التصحيح عن بُعد.
3. أبقِ المتصفح قيد التشغيل ووافق على مطالبة الاتصال عندما يتصل OpenClaw.

• Chrome: chrome://inspect/#remote-debugging
• Brave: brave://inspect/#remote-debugging
• Edge: edge://inspect/#remote-debugging

openclaw browser --browser-profile user start
openclaw browser --browser-profile user status
openclaw browser --browser-profile user tabs
openclaw browser --browser-profile user snapshot --format ai

• يعرض status القيمة driver: existing-session
• يعرض status القيمة transport: chrome-mcp
• يعرض status القيمة running: true
• يسرد tabs علامات التبويب المفتوحة بالفعل في متصفحك
• يعيد snapshot مراجع refs من علامة التبويب الحية المحددة

• أن يكون إصدار المتصفح المستهدف القائم على Chromium هو 144+
• أن يكون التصحيح عن بُعد ممكّنًا في صفحة inspect لذلك المتصفح
• أن يكون المتصفح قد أظهر مطالبة موافقة الاتصال وأنك قبلتها
• ينقل openclaw doctor تهيئة المتصفح القديمة المعتمدة على extension ويتحقق من تثبيت Chrome محليًا لملفات تعريف الاتصال التلقائي الافتراضية، لكنه لا يستطيع تمكين التصحيح عن بُعد من جهة المتصفح نيابةً عنك

• استخدم profile="user" عندما تحتاج إلى حالة المتصفح المسجّل دخول المستخدم فيها.
• إذا كنت تستخدم ملف تعريف existing-session مخصصًا، فمرر اسم ملف التعريف هذا صراحةً.
• اختر هذا الوضع فقط عندما يكون المستخدم أمام الكمبيوتر للموافقة على مطالبة الاتصال.
• يمكن لـ Gateway أو مضيف node تشغيل npx chrome-devtools-mcp@latest --autoConnect

• هذا المسار أعلى خطورة من ملف التعريف المعزول openclaw لأنه يمكنه العمل داخل جلسة المتصفح المسجّل دخولك فيها.
• لا يشغّل OpenClaw المتصفح لهذا المشغّل؛ بل يتصل بجلسة موجودة فقط.
• يستخدم OpenClaw هنا تدفق --autoConnect الرسمي لـ Chrome DevTools MCP. إذا تم تعيين userDataDir، فسيقوم OpenClaw بتمريره لاستهداف دليل بيانات مستخدم Chromium الصريح هذا.
• تدعم لقطات شاشة existing-session التقاط الصفحات والتقاط العناصر باستخدام --ref من مخرجات snapshot، ولكنها لا تدعم محددات CSS ‏--element.
• تعمل لقطات شاشة الصفحات في existing-session من دون Playwright عبر Chrome MCP. كما تعمل هناك أيضًا لقطات شاشة العناصر المستندة إلى ref (--ref)، لكن لا يمكن دمج --full-page مع --ref أو --element.
• لا تزال إجراءات existing-session أكثر محدودية من مسار المتصفح المُدار:
  • تتطلب click وtype وhover وscrollIntoView وdrag وselect مراجع snapshot بدلًا من محددات CSS
  • تدعم click الزر الأيسر فقط (من دون تجاوزات للأزرار أو modifiers)
  • لا تدعم type الخيار slowly=true؛ استخدم fill أو press
  • لا تدعم press الخيار delayMs
  • لا تدعم hover وscrollIntoView وdrag وselect وfill وevaluate تجاوزات المهلة لكل استدعاء
  • تدعم select حاليًا قيمة واحدة فقط
• يدعم wait --url في existing-session الأنماط المطابقة التامة، والجزئية، وglob مثل بقية مشغّلات المتصفح. لا يزال wait --load networkidle غير مدعوم.
• تتطلب خطافات الرفع في existing-session استخدام ref أو inputRef، وتدعم ملفًا واحدًا في كل مرة، ولا تدعم الاستهداف عبر CSS ‏element.
• لا تدعم خطافات مربعات الحوار في existing-session تجاوزات المهلة.
• لا تزال بعض الميزات تتطلب مسار المتصفح المُدار، بما في ذلك إجراءات الدفعات، وتصدير PDF، واعتراض التنزيلات، وresponsebody.
• يكون existing-session محليًا على المضيف. إذا كان Chrome موجودًا على جهاز مختلف أو ضمن مساحة اسم شبكة مختلفة، فاستخدم CDP البعيد أو مضيف node بدلًا من ذلك.

​

ضمانات العزل

• دليل بيانات مستخدم مخصص: لا يلمس ملف تعريف متصفحك الشخصي مطلقًا.
• منافذ مخصصة: يتجنب 9222 لمنع التعارض مع مسارات عمل التطوير.
• تحكم حتمي في علامات التبويب: استهدف علامات التبويب عبر targetId، وليس “آخر علامة تبويب”.

​

اختيار المتصفح

1. Chrome
2. Brave
3. Edge
4. Chromium
5. Chrome Canary

• macOS: يتحقق من /Applications و~/Applications.
• Linux: يبحث عن google-chrome وbrave وmicrosoft-edge وchromium وغيرها.
• Windows: يتحقق من مواقع التثبيت الشائعة.

​

Control API ‏(اختياري)

• الحالة/البدء/الإيقاف: GET /، POST /start، POST /stop
• علامات التبويب: GET /tabs، POST /tabs/open، POST /tabs/focus، DELETE /tabs/:targetId
• snapshot/لقطة الشاشة: GET /snapshot، POST /screenshot
• الإجراءات: POST /navigate، POST /act
• الخطافات: POST /hooks/file-chooser، POST /hooks/dialog
• التنزيلات: POST /download، POST /wait/download
• التصحيح: GET /console، POST /pdf
• التصحيح: GET /errors، GET /requests، POST /trace/start، POST /trace/stop، POST /highlight
• الشبكة: POST /response/body
• الحالة: GET /cookies، POST /cookies/set، POST /cookies/clear
• الحالة: GET /storage/:kind، POST /storage/:kind/set، POST /storage/:kind/clear
• الإعدادات: POST /set/offline، POST /set/headers، POST /set/credentials، POST /set/geolocation، POST /set/media، POST /set/timezone، POST /set/locale، POST /set/device

• Authorization: Bearer <gateway token>
• x-openclaw-password: <gateway password> أو HTTP Basic auth باستخدام كلمة المرور نفسها

• لا يستهلك HTTP API المستقل للمتصفح على local loopback أوضاع trusted-proxy أو رؤوس هوية Tailscale Serve.
• إذا كانت قيمة gateway.auth.mode هي none أو trusted-proxy، فإن مسارات المتصفح هذه على local loopback لا ترث أوضاع الهوية الحاملة هذه؛ لذا أبقها على local loopback فقط.

​

متطلب Playwright

• لقطات ARIA
• لقطات شاشة الصفحات لمتصفح openclaw المُدار عندما يكون WebSocket CDP لكل علامة تبويب متاحًا
• لقطات شاشة الصفحات لملفات تعريف existing-session / Chrome MCP
• لقطات شاشة existing-session المعتمدة على ref (--ref) من مخرجات snapshot

• navigate
• act
• AI snapshots / role snapshots
• لقطات شاشة العناصر بمحددات CSS ‏(--element)
• تصدير PDF الكامل للمتصفح

​

تثبيت Playwright في Docker

docker compose run --rm openclaw-cli \
  node /app/node_modules/playwright-core/cli.js install chromium

​

كيف يعمل (داخليًا)

• يقبل خادم تحكم صغير طلبات HTTP.
• ويتصل بالمتصفحات القائمة على Chromium (Chrome/Brave/Edge/Chromium) عبر CDP.
• وللإجراءات المتقدمة (النقر/الكتابة/snapshot/PDF)، فإنه يستخدم Playwright فوق CDP.
• وعند غياب Playwright، لا تتوفر إلا العمليات التي لا تعتمد على Playwright.

​

مرجع CLI سريع

• openclaw browser status
• openclaw browser start
• openclaw browser stop
• openclaw browser tabs
• openclaw browser tab
• openclaw browser tab new
• openclaw browser tab select 2
• openclaw browser tab close 2
• openclaw browser open https://example.com
• openclaw browser focus abcd1234
• openclaw browser close abcd1234

• openclaw browser screenshot
• openclaw browser screenshot --full-page
• openclaw browser screenshot --ref 12
• openclaw browser screenshot --ref e12
• openclaw browser snapshot
• openclaw browser snapshot --format aria --limit 200
• openclaw browser snapshot --interactive --compact --depth 6
• openclaw browser snapshot --efficient
• openclaw browser snapshot --labels
• openclaw browser snapshot --selector "#main" --interactive
• openclaw browser snapshot --frame "iframe#main" --interactive
• openclaw browser console --level error

• بالنسبة إلى ملفات التعريف attach-only وCDP البعيدة، يظل openclaw browser stop هو أمر التنظيف الصحيح بعد الاختبارات. فهو يغلق جلسة التحكم النشطة ويمسح تجاوزات المحاكاة المؤقتة بدلًا من قتل المتصفح الأساسي.
• openclaw browser errors --clear
• openclaw browser requests --filter api --clear
• openclaw browser pdf
• openclaw browser responsebody "**/api" --max-chars 5000

• openclaw browser navigate https://example.com
• openclaw browser resize 1280 720
• openclaw browser click 12 --double
• openclaw browser click e12 --double
• openclaw browser type 23 "hello" --submit
• openclaw browser press Enter
• openclaw browser hover 44
• openclaw browser scrollintoview e12
• openclaw browser drag 10 11
• openclaw browser select 9 OptionA OptionB
• openclaw browser download e12 report.pdf
• openclaw browser waitfordownload report.pdf
• openclaw browser upload /tmp/openclaw/uploads/file.pdf
• openclaw browser fill --fields '[{"ref":"1","type":"text","value":"Ada"}]'
• openclaw browser dialog --accept
• openclaw browser wait --text "Done"
• openclaw browser wait "#main" --url "**/dash" --load networkidle --fn "window.ready===true"
• openclaw browser evaluate --fn '(el) => el.textContent' --ref 7
• openclaw browser highlight e12
• openclaw browser trace start
• openclaw browser trace stop

• 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 theme dark
• openclaw browser storage session clear
• openclaw browser set offline on
• openclaw browser set headers --headers-json '{"X-Debug":"1"}'
• openclaw browser set credentials user pass
• openclaw browser set credentials --clear
• openclaw browser set geo 37.7749 -122.4194 --origin "https://example.com"
• openclaw browser set geo --clear
• openclaw browser set media dark
• openclaw browser set timezone America/New_York
• openclaw browser set locale en-US
• openclaw browser set device "iPhone 14"

• إن upload وdialog هما استدعاءا تجهيز مسبق؛ شغّلهما قبل النقر/الضغط الذي يطلق أداة اختيار الملف/مربع الحوار.
• تُقيّد مسارات إخراج التنزيل والتتبع بجذور مجلدات OpenClaw المؤقتة:
  • التتبعات: /tmp/openclaw (البديل: ${os.tmpdir()}/openclaw)
  • التنزيلات: /tmp/openclaw/downloads (البديل: ${os.tmpdir()}/openclaw/downloads)
• تُقيّد مسارات الرفع بجذر OpenClaw المؤقت الخاص بالرفع:
  • عمليات الرفع: /tmp/openclaw/uploads (البديل: ${os.tmpdir()}/openclaw/uploads)
• يمكن لـ upload أيضًا تعيين مدخلات الملفات مباشرة عبر --input-ref أو --element.
• snapshot:
  • --format ai (الافتراضي عند تثبيت Playwright): يعيد AI snapshot مع مراجع رقمية (aria-ref="<n>").
  • --format aria: يعيد شجرة إمكانية الوصول (من دون مراجع؛ للفحص فقط).
  • --efficient (أو --mode efficient): إعداد مسبق مضغوط لـ role snapshot ‏(interactive + compact + depth + maxChars أقل).
  • الإعداد الافتراضي في التهيئة (للأداة/CLI فقط): عيّن browser.snapshotDefaults.mode: "efficient" لاستخدام snapshots الفعّالة عندما لا يمرر المستدعي وضعًا (راجع تهيئة Gateway).
  • تفرض خيارات role snapshot ‏(--interactive و--compact و--depth و--selector) لقطة قائمة على الأدوار مع مراجع مثل ref=e12.
  • يقيّد --frame "<iframe selector>" role snapshots إلى iframe محدد (ويقترن بمراجع أدوار مثل e12).
  • ينتج --interactive قائمة مسطحة وسهلة الاختيار للعناصر التفاعلية (الأفضل لتوجيه الإجراءات).
  • يضيف --labels لقطة شاشة لمنفذ العرض فقط مع تراكب تسميات المراجع (ويطبع MEDIA:<path>).
• تتطلب click/type/إلخ ref من snapshot (إما رقميًا 12 أو مرجع دور e12). لا تُدعم محددات CSS عمدًا للإجراءات.

​

snapshots والمراجع

• AI snapshot (مراجع رقمية): ‏openclaw browser snapshot (الافتراضي؛ --format ai)
  • الإخراج: لقطة نصية تتضمن مراجع رقمية.
  • الإجراءات: openclaw browser click 12، ‏openclaw browser type 23 "hello".
  • داخليًا، يتم حل المرجع عبر aria-ref الخاص بـ Playwright.
• Role snapshot (مراجع أدوار مثل e12): ‏openclaw browser snapshot --interactive (أو --compact أو --depth أو --selector أو --frame)
  • الإخراج: قائمة/شجرة قائمة على الأدوار تتضمن [ref=e12] (ومع [nth=1] اختياريًا).
  • الإجراءات: openclaw browser click e12، ‏openclaw browser highlight e12.
  • داخليًا، يُحل المرجع عبر getByRole(...) ‏(مع nth() للتكرارات).
  • أضف --labels لتضمين لقطة شاشة لمنفذ العرض مع تراكب تسميات e12.

• لا تكون المراجع مستقرة عبر عمليات التنقل؛ إذا فشل شيء ما، فأعد تشغيل snapshot واستخدم مرجعًا جديدًا.
• إذا أُخذ role snapshot باستخدام --frame، فستُقيّد مراجع الأدوار إلى ذلك iframe حتى role snapshot التالي.

​

تحسينات الانتظار

• الانتظار لعنوان URL ‏(مع دعم glob من Playwright):
  • openclaw browser wait --url "**/dash"
• الانتظار لحالة التحميل:
  • openclaw browser wait --load networkidle
• الانتظار لمُسند JS:
  • openclaw browser wait --fn "window.ready===true"
• الانتظار حتى يصبح محدد مرئيًا:
  • openclaw browser wait "#main"

openclaw browser wait "#main" \
  --url "**/dash" \
  --load networkidle \
  --fn "window.ready===true" \
  --timeout-ms 15000

​

مسارات عمل التصحيح

1. openclaw browser snapshot --interactive
2. استخدم click <ref> / type <ref> (فضّل مراجع الأدوار في الوضع interactive)
3. إذا استمر الفشل: استخدم openclaw browser highlight <ref> لمعرفة ما الذي يستهدفه Playwright
4. إذا كان سلوك الصفحة غريبًا:
   • openclaw browser errors --clear
   • openclaw browser requests --filter api --clear
5. للتصحيح العميق: سجّل تتبعًا:
   • openclaw browser trace start
   • أعد إنتاج المشكلة
   • openclaw browser trace stop (يطبع TRACE:<path>)

​

إخراج JSON

openclaw browser status --json
openclaw browser snapshot --interactive --json
openclaw browser requests --filter api --json
openclaw browser cookies --json

​

مفاتيح الحالة والبيئة

• ملفات تعريف الارتباط: cookies وcookies set وcookies clear
• التخزين: storage local|session get|set|clear
• عدم الاتصال: set offline on|off
• الرؤوس: set headers --headers-json '{"X-Debug":"1"}' (لا يزال set headers --json '{"X-Debug":"1"}' القديم مدعومًا)
• مصادقة HTTP basic: ‏set credentials user pass (أو --clear)
• الموقع الجغرافي: set geo <lat> <lon> --origin "https://example.com" (أو --clear)
• الوسائط: set media dark|light|no-preference|none
• المنطقة الزمنية / اللغة المحلية: set timezone ...، ‏set locale ...
• الجهاز / منفذ العرض:
  • set device "iPhone 14" (إعدادات أجهزة Playwright المسبقة)
  • set viewport 1280 720

​

الأمان والخصوصية

• قد يحتوي ملف تعريف متصفح openclaw على جلسات مسجّل دخولها؛ لذا تعامل معه على أنه حساس.
• ينفذ browser act kind=evaluate / openclaw browser evaluate وwait --fn JavaScript عشوائيًا في سياق الصفحة. ويمكن لحقن prompt توجيه هذا السلوك. عطّله باستخدام browser.evaluateEnabled=false إذا لم تكن بحاجة إليه.
• لملاحظات تسجيل الدخول ومكافحة الروبوتات (X/Twitter، إلخ)، راجع تسجيل الدخول إلى المتصفح + النشر على X/Twitter.
• أبقِ Gateway/مضيف node خاصًا (على local loopback أو داخل tailnet فقط).
• نقاط نهاية CDP البعيدة قوية التأثير؛ قم بتمريرها عبر نفق واحمها.

{
  browser: {
    ssrfPolicy: {
      dangerouslyAllowPrivateNetwork: false,
      hostnameAllowlist: ["*.example.com", "example.com"],
      allowedHostnames: ["localhost"], // optional exact allow
    },
  },
}

​

استكشاف الأخطاء وإصلاحها

​

أدوات الوكيل + كيفية عمل التحكم

• browser — status/start/stop/tabs/open/focus/close/snapshot/screenshot/navigate/act

• يعيد browser snapshot شجرة UI مستقرة (AI أو ARIA).
• يستخدم browser act معرّفات ref من snapshot من أجل النقر/الكتابة/السحب/التحديد.
• يلتقط browser screenshot البكسلات (صفحة كاملة أو عنصر).
• يقبل browser:
  • profile لاختيار ملف تعريف متصفح مسمى (openclaw أو chrome أو remote CDP).
  • target ‏(sandbox | host | node) لتحديد مكان وجود المتصفح.
  • في الجلسات المعزولة، يتطلب target: "host" أن تكون agents.defaults.sandbox.browser.allowHostControl=true.
  • إذا لم يتم تحديد target: تستخدم الجلسات المعزولة القيمة الافتراضية sandbox، وتستخدم الجلسات غير المعزولة القيمة الافتراضية host.
  • إذا كان node قادر على تشغيل المتصفح متصلًا، فقد تُوجَّه الأداة إليه تلقائيًا ما لم تثبّت target="host" أو target="node".

​

ذو صلة

• نظرة عامة على الأدوات — جميع أدوات الوكيل المتاحة
• العزل — التحكم بالمتصفح في البيئات المعزولة
• الأمان — مخاطر التحكم بالمتصفح ووسائل التقوية