> ## 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. # واجهة برمجة تطبيقات التحكم في المتصفح للإعداد والتهيئة واستكشاف الأخطاء وإصلاحها، راجع [المتصفح](/ar/tools/browser). هذه الصفحة هي المرجع لواجهة HTTP API للتحكم المحلي، وCLI ‏`openclaw browser`، وأنماط البرمجة النصية (اللقطات، والمراجع، والانتظار، وتدفقات التصحيح). ## واجهة API للتحكم (اختيارية) للتكاملات المحلية فقط، يوفّر Gateway واجهة HTTP API صغيرة عبر local loopback. هذا الخادم المستقل اختياري — اضبط متغير البيئة `OPENCLAW_EAGER_BROWSER_CONTROL_SERVER=1` في بيئة خدمة Gateway وأعد تشغيل Gateway قبل أن تصبح نقاط نهاية HTTP متاحة. من دون هذا المتغير، يظل تشغيل التحكم في المتصفح يعمل عبر CLI وأدوات الوكيل، لكن لا شيء يستمع على منفذ تحكم 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=`. يطلب `POST /start?headless=true` تشغيلاً لمرة واحدة بلا واجهة رسومية للملفات الشخصية المحلية المُدارة من دون تغيير تهيئة المتصفح المحفوظة؛ وترفض ملفات التعريف من نوع الإرفاق فقط وCDP البعيد والجلسات القائمة هذا التجاوز لأن OpenClaw لا يشغّل عمليات تلك المتصفحات. بالنسبة إلى نقاط نهاية علامات التبويب، `targetId` هو اسم حقل التوافق. يُفضّل تمرير `suggestedTargetId` من `GET /tabs` أو `POST /tabs/open`؛ كما تُقبل التسميات ومقابض `tabId` مثل `t1`. ما تزال معرفات أهداف CDP الخام وبادئات معرف الهدف الخام الفريدة تعمل، لكنها مقابض تشخيصية متقلبة. إذا كانت مصادقة Gateway بالسر المشترك مهيأة، فإن مسارات HTTP للمتصفح تتطلب المصادقة أيضاً: * `Authorization: Bearer ` * `x-openclaw-password: ` أو مصادقة HTTP Basic باستخدام كلمة المرور تلك ملاحظات: * لا تستهلك واجهة API المستقلة هذه لمتصفح loopback ترويسات هوية الوكيل الموثوق أو Tailscale Serve. * إذا كان `gateway.auth.mode` هو `none` أو `trusted-proxy`، فإن مسارات متصفح loopback هذه لا ترث تلك الأوضاع الحاملة للهوية؛ أبقها مقتصرة على loopback فقط. ### عقد أخطاء `/act` يستخدم `POST /act` استجابة خطأ منظمة لإخفاقات التحقق على مستوى المسار والسياسة: ```json theme={"theme":{"light":"min-light","dark":"min-dark"}} { "error": "", "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": "" }` من دون حقل `code`. ### متطلب Playwright تتطلب بعض الميزات (التنقل/الإجراء/لقطة الذكاء الاصطناعي/لقطة الدور، ولقطات شاشة العناصر، و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` * لقطات الذكاء الاصطناعي التي تعتمد على تنسيق لقطة الذكاء الاصطناعي الأصلي في 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 كما هو موضح أدناه. #### تثبيت Docker Playwright إذا كان Gateway لديك يعمل في Docker، فتجنب `npx playwright` (تعارضات تجاوز npm). بالنسبة إلى الصور المخصصة، ادمج Chromium داخل الصورة: ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}} OPENCLAW_INSTALL_BROWSER=1 ./scripts/docker/setup.sh ``` بالنسبة إلى صورة موجودة، ثبّت عبر CLI المضمن بدلاً من ذلك: ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}} 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` أو ربط تحميل. يكتشف OpenClaw تلقائياً Chromium المحفوظ على Linux. راجع [Docker](/ar/install/docker). ## كيف يعمل (داخلي) يقبل خادم تحكم loopback صغير طلبات HTTP ويتصل بالمتصفحات المستندة إلى Chromium عبر CDP. تمر الإجراءات المتقدمة (النقر/الكتابة/اللقطة/PDF) عبر Playwright فوق CDP؛ وعند غياب Playwright، لا تتوفر إلا العمليات غير المعتمدة على Playwright. يرى الوكيل واجهة مستقرة واحدة بينما تتبدل المتصفحات والملفات الشخصية المحلية/البعيدة بحرية تحتها. ## مرجع CLI السريع تقبل كل الأوامر `--browser-profile ` لاستهداف ملف تعريف محدد، و`--json` للحصول على إخراج قابل للقراءة آلياً. ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}} openclaw browser status openclaw browser start openclaw browser start --headless # تشغيل محلي مُدار بلا واجهة رسومية لمرة واحدة openclaw browser stop # يمسح أيضاً المحاكاة في الإرفاق فقط/CDP البعيد 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 ``` ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}} openclaw browser screenshot openclaw browser screenshot --full-page openclaw browser screenshot --ref 12 # أو --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 ``` ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}} openclaw browser navigate https://example.com openclaw browser resize 1280 720 openclaw browser click 12 --double # أو e12 لمراجع الدور openclaw browser click-coords 120 340 # إحداثيات إطار العرض 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 upload media://inbound/file.pdf openclaw browser fill --fields '[{"ref":"1","type":"text","value":"Ada"}]' openclaw browser dialog --accept openclaw browser dialog --dismiss --dialog-id d1 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 evaluate --fn 'const title = document.title; return title;' openclaw browser evaluate --timeout-ms 30000 --fn 'async () => { await window.ready; return true; }' openclaw browser highlight e12 openclaw browser trace start openclaw browser trace stop ``` ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}} 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 للإزالة 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` هما استدعاءان **للتهيئة**؛ شغّلهما قبل النقرة/الضغط الذي يفعّل منتقي الملفات/مربع الحوار. إذا فتح إجراء نافذة مشروطة، تتضمن استجابة الإجراء `blockedByDialog` و`browserState.dialogs.pending`؛ مرّر ذلك `dialogId` للرد مباشرة. تظهر مربعات الحوار التي عولجت خارج OpenClaw تحت `browserState.dialogs.recent`. * تتطلب `click`/`type`/إلخ وجود `ref` من `snapshot` (رقمي `12`، أو مرجع دور `e12`، أو مرجع ARIA قابل للإجراء `ax12`). محددات CSS غير مدعومة عمداً للإجراءات. استخدم `click-coords` عندما يكون موضع إطار العرض المرئي هو الهدف الموثوق الوحيد. * مسارات التنزيل والتتبع مقيدة بجذور OpenClaw المؤقتة: `/tmp/openclaw{,/downloads}` (البديل: `${os.tmpdir()}/openclaw/...`). * يقبل `upload` الملفات من جذر التحميلات المؤقت في OpenClaw والوسائط الواردة المُدارة من OpenClaw. يمكن الإشارة إلى الوسائط الواردة المُدارة بصيغة `media://inbound/`، أو `media/inbound/` نسبةً إلى صندوق العزل، أو مسار محلول داخل دليل الوسائط الواردة المُدار. ما تزال مراجع الوسائط المتداخلة، والتنقل عبر المسارات، والروابط الرمزية، والروابط الصلبة، والمسارات المحلية العشوائية مرفوضة. * يمكن لـ`upload` أيضاً ضبط مدخلات الملفات مباشرة عبر `--input-ref` أو `--element`. تظل معرفات علامات التبويب والتسميات المستقرة صالحة بعد استبدال هدف Chromium الخام عندما يستطيع OpenClaw إثبات علامة التبويب البديلة، مثل عنوان URL نفسه أو تحول علامة تبويب قديمة واحدة إلى علامة تبويب جديدة واحدة بعد إرسال نموذج. ما تزال معرفات الأهداف الخام متقلبة؛ ويفضل استخدام `suggestedTargetId` من `tabs` في النصوص البرمجية. نظرة سريعة على أعلام اللقطات: * `--format ai` (الافتراضي مع Playwright): لقطة ذكاء اصطناعي بمراجع رقمية (`aria-ref=""`). * `--format aria`: شجرة إمكانية الوصول بمراجع `axN`. عند توفر Playwright، يربط OpenClaw المراجع بمعرفات DOM الخلفية في الصفحة الحية حتى تتمكن الإجراءات اللاحقة من استخدامها؛ وإلا فتعامل مع المخرجات على أنها للفحص فقط. * `--efficient` (أو `--mode efficient`): إعداد مسبق مدمج للقطة الأدوار. عيّن `browser.snapshotDefaults.mode: "efficient"` لجعل هذا هو الإعداد الافتراضي (انظر [تكوين Gateway](/ar/gateway/configuration-reference#browser)). * تفرض `--interactive` و`--compact` و`--depth` و`--selector` لقطة أدوار بمراجع `ref=e12`. يقيّد `--frame "