---
read_when:
    - كتابة نصوص برمجية أو تصحيح أخطاء متصفح الوكيل عبر واجهة برمجة تطبيقات التحكم المحلية
    - تبحث عن مرجع CLI الخاص بـ `openclaw browser`
    - إضافة أتمتة متصفح مخصصة باستخدام اللقطات والمراجع
summary: واجهة برمجة تطبيقات التحكم في المتصفح في OpenClaw، ومرجع CLI، وإجراءات البرمجة النصية
title: واجهة برمجة تطبيقات التحكم في المتصفح
x-i18n:
    generated_at: "2026-05-11T20:41:29Z"
    model: gpt-5.5
    provider: openai
    source_hash: 317ac82cb9060ae1f9495a992dcbb25356ef23b98a5802cf0ed65d1720c2a57d
    source_path: tools/browser-control.md
    workflow: 16
---

لإعداد الأداة وتهيئتها واستكشاف أخطائها وإصلاحها، راجع [Browser](/ar/tools/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` استجابة خطأ منظمة لفشل التحقق على مستوى المسار
وفشل السياسات:

```json
{ "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 داخل الصورة:

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

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

```bash
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](/ar/install/docker).

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

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

## مرجع سريع لـ CLI

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

<AccordionGroup>

<Accordion title="الأساسيات: الحالة، علامات التبويب، الفتح/التركيز/الإغلاق">

```bash
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
```

</Accordion>

<Accordion title="الفحص: لقطة الشاشة، اللقطة، وحدة التحكم، الأخطاء، الطلبات">

```bash
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
```

</Accordion>

<Accordion title="الإجراءات: التنقل، النقر، الكتابة، السحب، الانتظار، التقييم">

```bash
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
```

</Accordion>

<Accordion title="الحالة: ملفات تعريف الارتباط، التخزين، دون اتصال، الترويسات، الموقع الجغرافي، الجهاز">

```bash
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"
```

</Accordion>

</AccordionGroup>

ملاحظات:

- `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](/ar/gateway/configuration-reference#browser)).
- تفرض `--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"`

يمكن دمج هذه الخيارات:

```bash
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` مخصص للبرمجة النصية والأدوات المنظمة.

أمثلة:

```bash
openclaw browser status --json
openclaw browser snapshot --interactive --json
openclaw browser requests --filter api --json
openclaw 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](/ar/tools/browser-login).
- أبقِ مضيف Gateway/Node خاصًا (local loopback أو tailnet فقط).
- نقاط نهاية CDP البعيدة قوية؛ أنشئ نفقًا إليها واحمها.

مثال الوضع الصارم (حظر الوجهات الخاصة/الداخلية افتراضيًا):

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

## ذات صلة

- [المتصفح](/ar/tools/browser) - نظرة عامة، التكوين، الملفات الشخصية، الأمان
- [تسجيل دخول المتصفح](/ar/tools/browser-login) - تسجيل الدخول إلى المواقع
- [استكشاف أخطاء متصفح Linux وإصلاحها](/ar/tools/browser-linux-troubleshooting)
- [استكشاف أخطاء متصفح WSL2 وإصلاحها](/ar/tools/browser-wsl2-windows-remote-cdp-troubleshooting)