واجهة API للتحكم في المتصفح

​

واجهة Control API ‏(اختيارية)

• الحالة/البدء/الإيقاف: ‏GET / وPOST /start وPOST /stop
• علامات التبويب: ‏GET /tabs وPOST /tabs/open وPOST /tabs/focus وDELETE /tabs/:targetId
• اللقطة/لقطة الشاشة: ‏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 باستخدام تلك الكلمة

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

​

عقد الأخطاء في /act

{ "error": "<message>", "code": "ACT_*" }

• ACT_KIND_REQUIRED ‏(HTTP 400): kind مفقود أو غير معروف.
• ACT_INVALID_REQUEST ‏(HTTP 400): فشل تطبيع أو التحقق من حمولة الإجراء.
• ACT_SELECTOR_UNSUPPORTED ‏(HTTP 400): تم استخدام selector مع نوع إجراء غير مدعوم.
• ACT_EVALUATE_DISABLED ‏(HTTP 403): تم تعطيل evaluate ‏(أو wait --fn) عبر الإعدادات.
• ACT_TARGET_ID_MISMATCH ‏(HTTP 403): يتعارض targetId الأعلى مستوى أو المجمع مع هدف الطلب.
• ACT_EXISTING_SESSION_UNSUPPORTED ‏(HTTP 501): الإجراء غير مدعوم لملفات existing-session.

​

متطلب Playwright

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

• navigate
• act
• لقطات AI / لقطات الأدوار
• لقطات عناصر CSS selector ‏(--element)
• تصدير PDF الكامل للمتصفح

​

تثبيت Playwright في Docker

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

​

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

​

مرجع CLI سريع

openclaw browser status
openclaw browser start
openclaw browser stop            # also clears emulation on attach-only/remote CDP
openclaw browser tabs
openclaw browser tab             # shortcut for current 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        # or --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
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           # or e12 for role refs
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            # --clear to remove
openclaw browser set geo 37.7749 -122.4194 --origin "https://example.com"
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 هما استدعاءان من نوع arming؛ شغّلهما قبل النقر/الضغط الذي يفتح منتقي الملفات/مربع الحوار.
• تتطلب click/type/إلخ وجود ref من snapshot ‏(رقمي 12 أو مرجع دور e12). ولا يتم دعم محددات CSS عمدًا للإجراءات.
• تكون مسارات التنزيل، والتتبع، والرفع مقيّدة إلى جذور temp الخاصة بـ OpenClaw: ‏/tmp/openclaw{,/downloads,/uploads} ‏(والرجوع الاحتياطي: ${os.tmpdir()}/openclaw/...).
• يمكن لـ upload أيضًا ضبط مدخلات الملفات مباشرة عبر --input-ref أو --element.

• --format ai ‏(الافتراضي مع Playwright): لقطة AI مع refs رقمية (aria-ref="<n>").
• --format aria: شجرة إمكانية الوصول، من دون refs؛ للفحص فقط.
• --efficient ‏(أو --mode efficient): إعداد مسبق مضغوط للقطات الأدوار. اضبط browser.snapshotDefaults.mode: "efficient" لجعل هذا هو الافتراضي (راجع إعدادات Gateway).
• تؤدي --interactive و--compact و--depth و--selector إلى فرض لقطة أدوار مع refs من الشكل ref=e12. وتقيّد --frame "<iframe>" لقطات الأدوار داخل iframe.
• تضيف --labels لقطة شاشة داخل viewport مع وسوم refs متراكبة (وتطبع MEDIA:<path>).

​

اللقطات وrefs

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

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

​

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

• الانتظار لعنوان URL ‏(مع دعم globs بواسطة Playwright):
  • openclaw browser wait --url "**/dash"
• الانتظار لحالة التحميل:
  • openclaw browser wait --load networkidle
• الانتظار لشرط JS:
  • openclaw browser wait --fn "window.ready===true"
• الانتظار حتى يصبح selector مرئيًا:
  • 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> ‏(وفضّل refs الأدوار في الوضع التفاعلي)
3. إذا استمر الفشل: استخدم openclaw browser highlight <ref> لرؤية ما الذي تستهدفه Playwright
4. إذا تصرفت الصفحة بشكل غريب:
   • openclaw browser errors --clear
   • openclaw browser requests --filter api --clear
5. من أجل تصحيح أعمق: سجّل trace:
   • 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 وcookies set وcookies clear
• Storage: ‏storage local|session get|set|clear
• Offline: ‏set offline on|off
• Headers: ‏set headers --headers-json '{"X-Debug":"1"}' ‏(لا يزال الصياغة القديمة set headers --json '{"X-Debug":"1"}' مدعومة)
• مصادقة HTTP basic: ‏set credentials user pass ‏(أو --clear)
• Geolocation: ‏set geo <lat> <lon> --origin "https://example.com" ‏(أو --clear)
• Media: ‏set media dark|light|no-preference|none
• Timezone / locale: ‏set timezone ...، ‏set locale ...
• Device / viewport:
  • 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 host خاصًا (على loopback أو tailnet فقط).
• نقاط نهاية CDP البعيدة قوية؛ قم بإنشاء نفق لها واحمها.

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

​

ذو صلة

• المتصفح — نظرة عامة، والإعدادات، والملفات الشخصية، والأمان
• تسجيل الدخول في المتصفح — تسجيل الدخول إلى المواقع
• استكشاف أخطاء المتصفح على Linux وإصلاحها
• استكشاف أخطاء المتصفح على WSL2 وإصلاحها