المتصفح (مُدار بواسطة OpenClaw)

يمكن لـ OpenClaw تشغيل ملف تعريف مخصص لـ Chrome/Brave/Edge/Chromium يتحكم فيه الوكيل. إنه معزول عن متصفحك الشخصي ويُدار من خلال خدمة تحكم محلية صغيرة داخل Gateway (loopback فقط).

نظرة للمبتدئين:

  • فكر فيه كمتصفح منفصل خاص بالوكيل فقط
  • ملف تعريف openclaw لا يمس ملف تعريف متصفحك الشخصي
  • يمكن للوكيل فتح التبويبات، قراءة الصفحات، النقر، والكتابة في بيئة آمنة
  • ملف التعريف الافتراضي chrome يستخدم متصفح Chromium الافتراضي عبر extension relay؛ قم بالتبديل إلى openclaw للمتصفح المُدار المعزول

ما تحصل عليه

  • ملف تعريف متصفح منفصل اسمه openclaw (لون برتقالي افتراضيًا)
  • تحكم حتمي في التبويبات (list/open/focus/close)
  • إجراءات الوكيل (click/type/drag/select)، snapshots، screenshots، PDFs
  • دعم متعدد الملفات الشخصية اختياري (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

إذا حصلت على "Browser disabled"، قم بتمكينه في الإعدادات (انظر أدناه) وأعد تشغيل Gateway.

الملفات الشخصية: openclaw مقابل chrome

  • openclaw: متصفح مُدار ومعزول (لا يحتاج extension)
  • chrome: extension relay إلى متصفح النظام الخاص بك (يتطلب توصيل إضافة OpenClaw بتبويب)

قم بتعيين browser.defaultProfile: "openclaw" إذا كنت تريد الوضع المُدار افتراضيًا.

الإعدادات

إعدادات المتصفح موجودة في ~/.openclaw/openclaw.json:

{
  browser: {
    enabled: true, // افتراضي: true
    remoteCdpTimeoutMs: 1500, // مهلة HTTP لـ CDP البعيد (ms)
    remoteCdpHandshakeTimeoutMs: 3000, // مهلة WebSocket handshake لـ CDP البعيد (ms)
    defaultProfile: "chrome",
    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" },
      remote: { cdpUrl: "http://10.0.0.42:9222", color: "#00AA00" },
    },
  },
}

ملاحظات:

  • خدمة التحكم في المتصفح تربط على loopback على منفذ مشتق من gateway.port
  • الافتراضي: 18791 (gateway + 2)، relay يستخدم المنفذ التالي (18792)
  • attachOnly: true يعني "لا تقم أبدًا بإطلاق متصفح محلي؛ اتصل فقط إذا كان قيد التشغيل بالفعل"
  • color + color لكل ملف تعريف يصبغ واجهة المتصفح حتى تتمكن من رؤية الملف النشط
  • الملف الافتراضي هو chrome (extension relay). استخدم defaultProfile: "openclaw" للمتصفح المُدار

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

إذا كان متصفحك الافتراضي للنظام قائمًا على Chromium (Chrome/Brave/Edge/etc)، يستخدمه OpenClaw تلقائيًا. قم بتعيين browser.executablePath لتجاوز الكشف التلقائي:

// 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 خدمة التحكم في loopback ويمكنه إطلاق متصفح محلي
  • التحكم البعيد (node host): قم بتشغيل node host على الجهاز الذي يحتوي على المتصفح؛ يقوم Gateway بتوكيل إجراءات المتصفح إليه
  • CDP البعيد: قم بتعيين browser.profiles.<name>.cdpUrl للاتصال بمتصفح Chromium بعيد

الأمان

  • التحكم في المتصفح يعمل على loopback فقط؛ الوصول يمر عبر مصادقة Gateway أو إقران node
  • احتفظ بـ Gateway وأي node hosts على شبكة خاصة (Tailscale)؛ تجنب التعرض العام
  • عامل URLs/tokens لـ CDP البعيد كأسرار؛ فضّل متغيرات البيئة أو مديري الأسرار

مرجع CLI السريع

الأساسيات:

openclaw browser status
openclaw browser start
openclaw browser stop
openclaw browser tabs
openclaw browser open https://example.com

الفحص:

openclaw browser screenshot
openclaw browser screenshot --full-page
openclaw browser snapshot
openclaw browser snapshot --interactive
openclaw browser snapshot --efficient

الإجراءات:

openclaw browser navigate https://example.com
openclaw browser click 12 --double
openclaw browser type 23 "hello" --submit
openclaw browser press Enter
openclaw browser wait --text "Done"

Snapshots و refs

يدعم OpenClaw نوعين من "snapshot":

1. AI snapshot (refs رقمية): openclaw browser snapshot

  • المخرجات: snapshot نصي يتضمن refs رقمية
  • الإجراءات: openclaw browser click 12
  • داخليًا، يتم حل ref عبر aria-ref في Playwright

2. Role snapshot (refs الأدوار مثل e12): --interactive

  • المخرجات: قائمة/شجرة قائمة على الأدوار مع [ref=e12]
  • الإجراءات: openclaw browser click e12
  • داخليًا، يتم الحل عبر getByRole(...)

سلوك Ref:

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

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

  • قد يحتوي ملف تعريف متصفح openclaw على جلسات تسجيل دخول؛ عامله كحساس
  • browser act kind=evaluate و wait --fn ينفذان JavaScript تعسفيًا في سياق الصفحة. يمكن لـ prompt injection توجيه هذا. قم بتعطيله باستخدام browser.evaluateEnabled=false إذا لم تكن بحاجة إليه
  • احتفظ بـ Gateway/node host خاصًا (loopback أو tailnet فقط)
  • نقاط CDP البعيدة قوية؛ قم بعمل نفق وحمايتها

استكشاف الأخطاء

بالنسبة لمشكلات Linux الخاصة (خاصة snap Chromium)، انظر استكشاف أخطاء المتصفح.

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

يحصل الوكيل على أداة واحدة لأتمتة المتصفح:

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

كيف يعمل التعيين:

  • browser snapshot يعيد شجرة UI مستقرة (AI أو ARIA)
  • browser act يستخدم IDs الـ ref من snapshot للنقر/الكتابة/السحب/التحديد
  • browser screenshot يلتقط البكسلات (صفحة كاملة أو عنصر)
  • browser يقبل:
    • profile لاختيار ملف تعريف متصفح مسمى
    • target (sandbox | host | node) لتحديد مكان المتصفح
    • في الجلسات المعزولة، target: "host" يتطلب agents.defaults.sandbox.browser.allowHostControl=true

هذا يحافظ على حتمية الوكيل ويتجنب المحددات الهشة.