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

Documentation Index

Fetch the complete documentation index at: https://docs2.openclaw.ai/llms.txt

Use this file to discover all available pages before exploring further.

​

واجهة التحكم 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
• الأذونات: 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

• 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

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

​

متطلب Playwright

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

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

​

تثبيت Playwright في Docker

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

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 start --headless # one-shot local managed headless launch
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 screenshot --labels
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 --urls
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 click-coords 120 340        # viewport coordinates
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 هما استدعاءا تسليح؛ شغّلهما قبل النقر/الضغط الذي يطلق منتقي الملفات/الحوار.
• تتطلب click/type/إلخ وجود ref من snapshot (رقمي 12، أو مرجع دور e12، أو مرجع ARIA قابل للتنفيذ ax12). محددات CSS غير مدعومة عمدًا للإجراءات. استخدم click-coords عندما يكون موضع منفذ العرض المرئي هو الهدف الموثوق الوحيد.
• تقيَّد مسارات التنزيل والتتبع والرفع بجذور OpenClaw المؤقتة: /tmp/openclaw{,/downloads,/uploads} (البديل: ${os.tmpdir()}/openclaw/...).
• يمكن لـ upload أيضًا تعيين مدخلات الملفات مباشرة عبر --input-ref أو --element.

• --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.

​

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

• لقطة 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

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 الأساسية: 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 وإصلاحها