واجهة برمجة تطبيقات التحكم في المتصفح

لإعداد الأداة وتهيئتها واستكشاف أخطائها وإصلاحها، راجع Browser. هذه الصفحة هي مرجع واجهة HTTP API المحلية للتحكم، وCLI openclaw browser، وأنماط البرمجة النصية (اللقطات، والمراجع، والانتظارات، وتدفقات التصحيح).

واجهة التحكم API (اختيارية)

للتكاملات المحلية فقط، يوفّر Gateway واجهة HTTP API صغيرة عبر loopback:

• الحالة/البدء/الإيقاف: 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
• الأذونات: POST /permissions/grant
• التصحيح: 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

تقبل جميع نقاط النهاية ?profile=<name>. يطلب POST /start?headless=true تشغيلاً headless لمرة واحدة للملفات الشخصية المحلية المُدارة دون تغيير تهيئة المتصفح المحفوظة؛ وترفض ملفات التعريف attach-only وremote CDP والجلسات الموجودة هذا التجاوز لأن OpenClaw لا يشغّل عمليات المتصفح تلك.

إذا كانت مصادقة Gateway بالسر المشترك مهيأة، فإن مسارات HTTP للمتصفح تتطلب المصادقة أيضًا:

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

ملاحظات:

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

عقد أخطاء /act

يستخدم POST /act استجابة خطأ منظمة لفشل التحقق على مستوى المسار وفشل السياسات:

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

قيم code الحالية:

• 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): الإجراء غير مدعوم لملفات تعريف الجلسات الموجودة.

قد تعيد حالات فشل التشغيل الأخرى { "error": "<message>" } دون حقل code.

متطلب Playwright

تتطلب بعض الميزات (التنقل/الإجراء/لقطة AI/لقطة الدور، ولقطات شاشة العناصر، وPDF) وجود Playwright. إذا لم يكن Playwright مثبتًا، فتعيد نقاط النهاية هذه خطأ 501 واضحًا.

ما يزال يعمل دون Playwright:

• لقطات ARIA
• لقطات إمكانية الوصول بنمط الدور (--interactive, --compact, --depth, --efficient) عندما يكون WebSocket لكل علامة تبويب عبر CDP متاحًا. هذا بديل للفحص واكتشاف المراجع؛ ويبقى Playwright محرك الإجراءات الأساسي.
• لقطات شاشة الصفحة لمتصفح openclaw المُدار عندما يكون WebSocket لكل علامة تبويب عبر CDP متاحًا
• لقطات شاشة الصفحة لملفات تعريف existing-session / Chrome MCP
• لقطات شاشة existing-session القائمة على المرجع (--ref) من مخرجات اللقطة

ما يزال يحتاج إلى Playwright:

• navigate
• act
• لقطات AI التي تعتمد على تنسيق لقطة AI الأصلي في Playwright
• لقطات شاشة عناصر محدد CSS (--element)
• تصدير PDF كامل للمتصفح

ترفض لقطات شاشة العناصر أيضًا --full-page؛ يعيد المسار fullPage is not supported for element screenshots.

إذا رأيت Playwright is not available in this gateway build، فهذا يعني أن Gateway المعبأ يفتقد تبعية تشغيل المتصفح الأساسية. أعد تثبيت OpenClaw أو حدّثه، ثم أعد تشغيل Gateway. بالنسبة إلى Docker، ثبّت أيضًا ملفات Chromium الثنائية كما هو موضح أدناه.

تثبيت Playwright في Docker

إذا كان Gateway لديك يعمل في Docker، فتجنب npx playwright (تعارضات تجاوز npm). بالنسبة إلى الصور المخصصة، ضمّن Chromium داخل الصورة:

OPENCLAW_INSTALL_BROWSER=1 ./scripts/docker/setup.sh

بالنسبة إلى صورة موجودة، ثبّت عبر CLI المضمن بدلاً من ذلك:

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

لاستبقاء تنزيلات المتصفح، عيّن PLAYWRIGHT_BROWSERS_PATH (على سبيل المثال، /home/node/.cache/ms-playwright) وتأكد من استبقاء /home/node عبر OPENCLAW_HOME_VOLUME أو bind mount. يكتشف OpenClaw تلقائيًا Chromium المستبقى على Linux. راجع Docker.

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

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

مرجع سريع لـ CLI

تقبل جميع الأوامر --browser-profile <name> لاستهداف ملف تعريف محدد، و--json لإخراج قابل للقراءة آليًا.

openclaw browser statusopenclaw browser startopenclaw browser start --headless # one-shot local managed headless launchopenclaw browser stop            # also clears emulation on attach-only/remote CDPopenclaw browser tabsopenclaw browser tab             # shortcut for current tabopenclaw browser tab newopenclaw browser tab select 2openclaw browser tab close 2openclaw browser open https://example.comopenclaw browser focus abcd1234openclaw browser close abcd1234

openclaw browser screenshotopenclaw browser screenshot --full-pageopenclaw browser screenshot --ref 12        # or --ref e12openclaw browser screenshot --labelsopenclaw browser snapshotopenclaw browser snapshot --format aria --limit 200openclaw browser snapshot --interactive --compact --depth 6openclaw browser snapshot --efficientopenclaw browser snapshot --labelsopenclaw browser snapshot --urlsopenclaw browser snapshot --selector "#main" --interactiveopenclaw browser snapshot --frame "iframe#main" --interactiveopenclaw browser console --level erroropenclaw browser errors --clearopenclaw browser requests --filter api --clearopenclaw browser pdfopenclaw browser responsebody "**/api" --max-chars 5000

openclaw browser navigate https://example.comopenclaw browser resize 1280 720openclaw browser click 12 --double           # or e12 for role refsopenclaw browser click-coords 120 340        # viewport coordinatesopenclaw browser type 23 "hello" --submitopenclaw browser press Enteropenclaw browser hover 44openclaw browser scrollintoview e12openclaw browser drag 10 11openclaw browser select 9 OptionA OptionBopenclaw browser download e12 report.pdfopenclaw browser waitfordownload report.pdfopenclaw browser upload /tmp/openclaw/uploads/file.pdfopenclaw browser fill --fields '[{"ref":"1","type":"text","value":"Ada"}]'openclaw browser dialog --acceptopenclaw browser wait --text "Done"openclaw browser wait "#main" --url "**/dash" --load networkidle --fn "window.ready===true"openclaw browser evaluate --fn '(el) => el.textContent' --ref 7openclaw browser highlight e12openclaw browser trace startopenclaw browser trace stop

openclaw browser cookiesopenclaw browser cookies set session abc123 --url "https://example.com"openclaw browser cookies clearopenclaw browser storage local getopenclaw browser storage local set theme darkopenclaw browser storage session clearopenclaw browser set offline onopenclaw browser set headers --headers-json '{"X-Debug":"1"}'openclaw browser set credentials user pass            # --clear to removeopenclaw browser set geo 37.7749 -122.4194 --origin "https://example.com"openclaw browser set media darkopenclaw browser set timezone America/New_Yorkopenclaw browser set locale en-USopenclaw browser set device "iPhone 14"

ملاحظات:

• upload وdialog هما استدعاءا تسليح؛ شغّلهما قبل النقر/الضغط الذي يطلق منتقي الملفات/الحوار.
• تتطلب click/type/إلخ وجود ref من snapshot (رقمي 12، أو مرجع دور e12، أو مرجع ARIA قابل للتنفيذ ax12). محددات CSS غير مدعومة عمدًا للإجراءات. استخدم click-coords عندما يكون موضع منفذ العرض المرئي هو الهدف الموثوق الوحيد.
• تقيَّد مسارات التنزيل والتتبع والرفع بجذور OpenClaw المؤقتة: /tmp/openclaw{,/downloads,/uploads} (البديل: ${os.tmpdir()}/openclaw/...).
• يمكن لـ upload أيضًا تعيين مدخلات الملفات مباشرة عبر --input-ref أو --element.

تظل معرّفات علامات التبويب والتسميات المستقرة باقية بعد استبدال Chromium للهدف الخام عندما يستطيع OpenClaw إثبات علامة التبويب البديلة، مثل نفس URL أو تحوّل علامة تبويب قديمة واحدة إلى علامة تبويب جديدة واحدة بعد إرسال نموذج. تظل معرّفات الأهداف الخام متقلبة؛ فضّل suggestedTargetId من tabs في السكربتات.

نظرة سريعة على أعلام اللقطات:

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

اللقطات والمراجع

يدعم OpenClaw نمطين من "اللقطات":

• لقطة AI (مراجع رقمية): openclaw browser snapshot (افتراضي؛ --format ai)

  • الإخراج: لقطة نصية تتضمن مراجع رقمية.
  • الإجراءات: openclaw browser click 12, openclaw browser type 23 "hello".
  • داخليًا، يُحل المرجع عبر aria-ref في Playwright.

• لقطة الدور (مراجع دور مثل 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 متراكبة.
  • أضف --urls عندما يكون نص الرابط ملتبسًا ويحتاج الوكيل إلى أهداف تنقل ملموسة.

• لقطة ARIA (مراجع ARIA مثل ax12): openclaw browser snapshot --format aria

  • الناتج: شجرة إمكانية الوصول كعُقد منظمة.
  • الإجراءات: يعمل openclaw browser click ax12 عندما يستطيع مسار اللقطة ربط المرجع عبر Playwright ومعرفات DOM لخلفية Chrome.

• إذا لم يكن Playwright متاحًا، يمكن أن تظل لقطات ARIA مفيدة للفحص، لكن قد لا تكون المراجع قابلة للتنفيذ. أعد أخذ اللقطة باستخدام --format ai أو --interactive عندما تحتاج إلى مراجع إجراءات.

• إثبات Docker لمسار الرجوع الخام-CDP: يبدأ pnpm test:docker:browser-cdp-snapshot Chromium مع CDP، ويشغّل browser doctor --deep، ويتحقق من أن لقطات الأدوار تتضمن عناوين URL للروابط، والعناصر القابلة للنقر المرفوعة بالمؤشر، وبيانات iframe الوصفية.

سلوك المراجع:

• المراجع ليست ثابتة عبر عمليات التنقل؛ إذا فشل شيء ما، فأعد تشغيل snapshot واستخدم مرجعًا جديدًا.
• يعيد /act قيمة targetId الخام الحالية بعد الاستبدال الناتج عن الإجراء عندما يمكنه إثبات علامة التبويب البديلة. واصل استخدام معرفات/تسميات علامات التبويب الثابتة للأوامر اللاحقة.
• إذا أُخذت لقطة الدور باستخدام --frame، فإن مراجع الأدوار تكون محصورة بذلك iframe حتى لقطة الدور التالية.
• تفشل مراجع axN المجهولة أو القديمة بسرعة بدلًا من المتابعة إلى محدد aria-ref في Playwright. شغّل لقطة جديدة على علامة التبويب نفسها عندما يحدث ذلك.

تعزيزات الانتظار

يمكنك الانتظار على أكثر من مجرد الوقت/النص:

• انتظر عنوان URL (يدعم Playwright أنماط glob):
  • 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> (فضّل مراجع الأدوار في الوضع التفاعلي)
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

--json مخصص للبرمجة النصية والأدوات المنظمة.

أمثلة:

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

تتضمن لقطات الأدوار في JSON refs بالإضافة إلى كتلة stats صغيرة (lines/chars/refs/interactive) حتى تتمكن الأدوات من التفكير في حجم الحمولة وكثافتها.

مقابض الحالة والبيئة

هذه مفيدة لسير عمل "اجعل الموقع يتصرف مثل X":

• ملفات تعريف الارتباط: 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 الأساسية: 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 عشوائيًا في سياق الصفحة. يمكن لحقن المطالبات توجيه ذلك. عطّله باستخدام 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    },  },}

ذات صلة

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