--- read_when: - اسکریپت‌نویسی یا اشکال‌زدایی مرورگر عامل از طریق API کنترل محلی - به‌دنبال مرجع CLI `openclaw browser` هستید - افزودن خودکارسازی سفارشی مرورگر با اسنپ‌شات‌ها و ارجاع‌ها summary: مرجع API کنترل مرورگر، CLI و کنش‌های اسکریپت‌نویسی OpenClaw title: API کنترل مرورگر x-i18n: generated_at: "2026-06-27T18:55:54Z" model: gpt-5.5 postprocess_version: locale-links-v1 provider: openai source_hash: ccfd1ec996b0fc211e2aefa0554e0fa5c7b0899ca981836134a3741b38bf7600 source_path: tools/browser-control.md workflow: 16 --- برای راه‌اندازی، پیکربندی و عیب‌یابی، [مرورگر](/fa/tools/browser) را ببینید. این صفحه مرجع API محلی کنترل HTTP، CLI مربوط به `openclaw browser` و الگوهای اسکریپت‌نویسی است (snapshots، refs، waits، جریان‌های اشکال‌زدایی). ## API کنترل (اختیاری) فقط برای یکپارچه‌سازی‌های محلی، Gateway یک API کوچک HTTP روی local loopback ارائه می‌کند. این سرور مستقل اختیاری است — متغیر محیطی `OPENCLAW_EAGER_BROWSER_CONTROL_SERVER=1` را در محیط سرویس gateway تنظیم کنید و پیش از در دسترس شدن endpointهای HTTP، gateway را بازراه‌اندازی کنید. بدون این متغیر، runtime کنترل مرورگر همچنان از طریق CLI و ابزارهای agent کار می‌کند، اما چیزی روی پورت کنترل loopback گوش نمی‌دهد. - وضعیت/شروع/توقف: `GET /`, `POST /start`, `POST /stop` - زبانه‌ها: `GET /tabs`, `POST /tabs/open`, `POST /tabs/focus`, `DELETE /tabs/:targetId` - Snapshot/اسکرین‌شات: `GET /snapshot`, `POST /screenshot` - کنش‌ها: `POST /navigate`, `POST /act` - Hookها: `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` همه endpointها `?profile=` را می‌پذیرند. `POST /start?headless=true` یک اجرای headless یک‌باره را برای پروفایل‌های محلی مدیریت‌شده درخواست می‌کند، بدون اینکه پیکربندی پایدار مرورگر را تغییر دهد؛ پروفایل‌های attach-only، CDP راه‌دور، و existing-session این override را رد می‌کنند، چون OpenClaw آن فرایندهای مرورگر را اجرا نمی‌کند. برای endpointهای زبانه، `targetId` نام فیلد سازگاری است. ترجیحاً `suggestedTargetId` را از `GET /tabs` یا `POST /tabs/open` ارسال کنید؛ برچسب‌ها و handleهای `tabId` مانند `t1` نیز پذیرفته می‌شوند. شناسه‌های خام target در CDP و پیشوندهای یکتای خام target-id همچنان کار می‌کنند، اما handleهای تشخیصی ناپایدار هستند. اگر احراز هویت gateway با راز مشترک پیکربندی شده باشد، مسیرهای HTTP مرورگر نیز به احراز هویت نیاز دارند: - `Authorization: Bearer ` - `x-openclaw-password: ` یا احراز هویت HTTP Basic با همان گذرواژه نکته‌ها: - این API مستقل loopback مرورگر، headerهای هویت trusted-proxy یا Tailscale Serve را مصرف **نمی‌کند**. - اگر `gateway.auth.mode` برابر `none` یا `trusted-proxy` باشد، این مسیرهای loopback مرورگر آن حالت‌های حامل هویت را به ارث نمی‌برند؛ آن‌ها را فقط روی loopback نگه دارید. ### قرارداد خطای `/act` `POST /act` برای اعتبارسنجی در سطح مسیر و شکست‌های policy از پاسخ خطای ساختاریافته استفاده می‌کند: ```json { "error": "", "code": "ACT_*" } ``` مقادیر فعلی `code`: - `ACT_KIND_REQUIRED` (HTTP 400): `kind` وجود ندارد یا شناخته‌شده نیست. - `ACT_INVALID_REQUEST` (HTTP 400): payload کنش در نرمال‌سازی یا اعتبارسنجی شکست خورد. - `ACT_SELECTOR_UNSUPPORTED` (HTTP 400): `selector` با نوع کنشی استفاده شد که پشتیبانی نمی‌شود. - `ACT_EVALUATE_DISABLED` (HTTP 403): `evaluate` (یا `wait --fn`) توسط config غیرفعال شده است. - `ACT_TARGET_ID_MISMATCH` (HTTP 403): `targetId` سطح بالا یا گروهی با target درخواست تعارض دارد. - `ACT_EXISTING_SESSION_UNSUPPORTED` (HTTP 501): کنش برای پروفایل‌های existing-session پشتیبانی نمی‌شود. شکست‌های دیگر runtime ممکن است همچنان `{ "error": "" }` را بدون فیلد `code` برگردانند. ### نیازمندی Playwright برخی قابلیت‌ها (navigate/act/AI snapshot/role snapshot، اسکرین‌شات‌های element، PDF) به Playwright نیاز دارند. اگر Playwright نصب نباشد، آن endpointها یک خطای روشن 501 برمی‌گردانند. چیزهایی که بدون Playwright همچنان کار می‌کنند: - snapshotهای ARIA - snapshotهای دسترس‌پذیری سبک role (`--interactive`, `--compact`, `--depth`, `--efficient`) وقتی WebSocket مربوط به CDP در سطح هر زبانه در دسترس باشد. این یک fallback برای بازرسی و کشف ref است؛ Playwright همچنان موتور اصلی کنش باقی می‌ماند. - اسکرین‌شات‌های صفحه برای مرورگر مدیریت‌شده `openclaw` وقتی WebSocket مربوط به CDP در سطح هر زبانه در دسترس باشد - اسکرین‌شات‌های صفحه برای پروفایل‌های `existing-session` / Chrome MCP - اسکرین‌شات‌های مبتنی بر ref در `existing-session` (`--ref`) از خروجی snapshot چیزهایی که همچنان به Playwright نیاز دارند: - `navigate` - `act` - snapshotهای AI که به قالب AI snapshot بومی Playwright وابسته‌اند - اسکرین‌شات‌های element با CSS-selector (`--element`) - خروجی PDF کامل مرورگر اسکرین‌شات‌های element همچنین `--full-page` را رد می‌کنند؛ route مقدار `fullPage is not supported for element screenshots` را برمی‌گرداند. اگر `Playwright is not available in this gateway build` را می‌بینید، Gateway بسته‌بندی‌شده وابستگی اصلی runtime مرورگر را ندارد. OpenClaw را دوباره نصب یا به‌روزرسانی کنید، سپس gateway را بازراه‌اندازی کنید. برای Docker، باینری‌های مرورگر Chromium را نیز طبق آنچه پایین آمده نصب کنید. #### نصب Docker Playwright اگر Gateway شما در Docker اجرا می‌شود، از `npx playwright` پرهیز کنید (تعارض‌های npm override). برای imageهای سفارشی، Chromium را داخل image قرار دهید: ```bash OPENCLAW_INSTALL_BROWSER=1 ./scripts/docker/setup.sh ``` برای یک image موجود، به‌جای آن از طریق 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 در Linux به‌صورت خودکار Chromium پایدارشده را شناسایی می‌کند. [Docker](/fa/install/docker) را ببینید. ## نحوه کارکرد (داخلی) یک سرور کوچک کنترل loopback درخواست‌های HTTP را می‌پذیرد و از طریق CDP به مرورگرهای مبتنی بر Chromium وصل می‌شود. کنش‌های پیشرفته (click/type/snapshot/PDF) روی CDP و از طریق Playwright انجام می‌شوند؛ وقتی Playwright موجود نباشد، فقط عملیات غیر Playwright در دسترس است. agent یک رابط پایدار می‌بیند، در حالی که مرورگرها و پروفایل‌های محلی/راه‌دور آزادانه در لایه زیرین جابه‌جا می‌شوند. ## مرجع سریع CLI همه دستورها `--browser-profile ` را برای هدف گرفتن یک پروفایل مشخص، و `--json` را برای خروجی قابل خواندن توسط ماشین می‌پذیرند. ```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 ``` ```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 ``` ```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 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 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/press که chooser/dialog را فعال می‌کند اجرا کنید. اگر یک کنش modal باز کند، پاسخ کنش شامل `blockedByDialog` و `browserState.dialogs.pending` است؛ همان `dialogId` را برای پاسخ مستقیم ارسال کنید. Dialogهایی که خارج از OpenClaw مدیریت شده‌اند زیر `browserState.dialogs.recent` ظاهر می‌شوند. - `click`/`type`/و غیره به یک `ref` از `snapshot` نیاز دارند (عدد `12`، ref نقش `e12`، یا ref قابل اقدام ARIA یعنی `ax12`). CSS selectorها عمداً برای کنش‌ها پشتیبانی نمی‌شوند. وقتی موقعیت قابل مشاهده در viewport تنها target قابل اتکا است، از `click-coords` استفاده کنید. - مسیرهای دانلود و trace به ریشه‌های موقت OpenClaw محدود هستند: `/tmp/openclaw{,/downloads}` (fallback: `${os.tmpdir()}/openclaw/...`). - `upload` فایل‌های موجود در ریشه موقت uploads متعلق به OpenClaw و رسانه ورودی مدیریت‌شده توسط OpenClaw را می‌پذیرد. رسانه ورودی مدیریت‌شده را می‌توان به‌صورت `media://inbound/`، مسیر sandbox-relative یعنی `media/inbound/`، یا یک مسیر resolve‌شده داخل دایرکتوری رسانه ورودی مدیریت‌شده ارجاع داد. refهای رسانه تودرتو، traversal، symlinkها، hardlinkها، و مسیرهای محلی دلخواه همچنان رد می‌شوند. - `upload` همچنین می‌تواند inputهای فایل را مستقیماً از طریق `--input-ref` یا `--element` تنظیم کند. شناسه‌ها و برچسب‌های پایدار زبانه پس از جایگزینی raw-target در Chromium باقی می‌مانند، وقتی OpenClaw بتواند زبانه جایگزین را اثبات کند، مانند همان URL یا تبدیل شدن یک زبانه قدیمی به یک زبانه جدید پس از ارسال فرم. شناسه‌های raw target همچنان ناپایدار هستند؛ در اسکریپت‌ها `suggestedTargetId` را از `tabs` ترجیح دهید. مرور سریع flagهای snapshot: - `--format ai` (پیش‌فرض با Playwright): اسنپ‌شات AI با ارجاع‌های عددی (`aria-ref=""`). - `--format aria`: درخت دسترس‌پذیری با ارجاع‌های `axN`. وقتی Playwright در دسترس باشد، OpenClaw ارجاع‌ها را با شناسه‌های backend DOM به صفحه زنده متصل می‌کند تا اقدام‌های بعدی بتوانند از آن‌ها استفاده کنند؛ در غیر این صورت خروجی را فقط برای بازرسی در نظر بگیرید. - `--efficient` (یا `--mode efficient`): پیش‌تنظیم اسنپ‌شات نقش فشرده. `browser.snapshotDefaults.mode: "efficient"` را تنظیم کنید تا این حالت پیش‌فرض شود (ببینید [پیکربندی Gateway](/fa/gateway/configuration-reference#browser)). - `--interactive`، `--compact`، `--depth`، `--selector` یک اسنپ‌شات نقش با ارجاع‌های `ref=e12` را اجباری می‌کنند. `--frame "