رابط برنامه‌نویسی کاربردی کنترل مرورگر

برای راه‌اندازی، پیکربندی، و عیب‌یابی، Browser را ببینید. این صفحه مرجع API محلی کنترل HTTP، CLI مربوط به OmeniaClaw browser، و الگوهای اسکریپت‌نویسی (snapshotها، refها، waitها، جریان‌های debug) است.

API کنترل (اختیاری)

فقط برای یکپارچه‌سازی‌های محلی، Gateway یک API کوچک HTTP روی loopback ارائه می‌کند:

• وضعیت/شروع/توقف: GET /, POST /start, POST /stop
• تب‌ها: GET /tabs, POST /tabs/open, POST /tabs/focus, DELETE /tabs/:targetId
• Snapshot/screenshot: GET /snapshot, POST /screenshot
• کنش‌ها: POST /navigate, POST /act
• Hookها: POST /hooks/file-chooser, POST /hooks/dialog
• دانلودها: POST /download, POST /wait/download
• مجوزها: POST /permissions/grant
• Debugging: GET /console, POST /pdf
• Debugging: 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=<name> را می‌پذیرند. POST /start?headless=true برای profileهای محلی مدیریت‌شده، یک اجرای headless یک‌باره درخواست می‌کند، بدون اینکه پیکربندی ماندگار مرورگر را تغییر دهد؛ profileهای attach-only، remote CDP، و existing-session این override را رد می‌کنند، چون OmeniaClaw آن فرایندهای مرورگر را اجرا نمی‌کند.

اگر احراز هویت Gateway با shared-secret پیکربندی شده باشد، routeهای HTTP مرورگر نیز به احراز هویت نیاز دارند:

• Authorization: Bearer <gateway token>
• x-OmeniaClaw-password: <gateway password> یا احراز هویت HTTP Basic با همان گذرواژه

نکته‌ها:

• این API مستقل loopback مرورگر، headerهای هویت trusted-proxy یا Tailscale Serve را مصرف نمی‌کند.
• اگر gateway.auth.mode برابر none یا trusted-proxy باشد، این routeهای loopback مرورگر آن modeهای دارای هویت را به ارث نمی‌برند؛ آن‌ها را فقط loopback نگه دارید.

قرارداد خطای /act

POST /act برای اعتبارسنجی در سطح route و شکست‌های policy از پاسخ خطای ساختاریافته استفاده می‌کند:

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

مقادیر فعلی code:

• ACT_KIND_REQUIRED (HTTP 400): kind وجود ندارد یا شناسایی نشده است.
• ACT_INVALID_REQUEST (HTTP 400): payload کنش در normalizing یا اعتبارسنجی شکست خورد.
• ACT_SELECTOR_UNSUPPORTED (HTTP 400): selector با نوع کنش پشتیبانی‌نشده استفاده شده است.
• ACT_EVALUATE_DISABLED (HTTP 403): evaluate (یا wait --fn) توسط config غیرفعال شده است.
• ACT_TARGET_ID_MISMATCH (HTTP 403): targetId سطح‌بالا یا batched با target درخواست تعارض دارد.
• ACT_EXISTING_SESSION_UNSUPPORTED (HTTP 501): کنش برای profileهای existing-session پشتیبانی نمی‌شود.

شکست‌های runtime دیگر ممکن است همچنان بدون فیلد code مقدار { "error": "<message>" } را برگردانند.

نیازمندی Playwright

برخی قابلیت‌ها (navigate/act/snapshot هوش مصنوعی/snapshot نقش، screenshotهای element، PDF) به Playwright نیاز دارند. اگر Playwright نصب نباشد، آن endpointها یک خطای 501 روشن برمی‌گردانند.

چیزهایی که بدون Playwright همچنان کار می‌کنند:

• snapshotهای ARIA
• snapshotهای دسترس‌پذیری سبک نقش (--interactive, --compact, --depth, --efficient) وقتی WebSocket مربوط به CDP هر تب در دسترس باشد. این یک fallback برای بازرسی و کشف ref است؛ Playwright همچنان موتور اصلی کنش است.
• screenshotهای صفحه برای مرورگر مدیریت‌شده OmeniaClaw وقتی CDP WebSocket هر تب در دسترس باشد
• screenshotهای صفحه برای profileهای existing-session / Chrome MCP
• screenshotهای مبتنی بر ref مربوط به existing-session (--ref) از خروجی snapshot

چیزهایی که همچنان به Playwright نیاز دارند:

• navigate
• act
• snapshotهای هوش مصنوعی که به قالب snapshot هوش مصنوعی بومی Playwright وابسته‌اند
• screenshotهای element با CSS-selector (--element)
• خروجی PDF کامل مرورگر

screenshotهای element همچنین --full-page را رد می‌کنند؛ route مقدار fullPage is not supported for element screenshots را برمی‌گرداند.

اگر Playwright is not available in this gateway build را دیدید، Gateway بسته‌بندی‌شده وابستگی runtime اصلی مرورگر را ندارد. OmeniaClaw را دوباره نصب یا به‌روزرسانی کنید، سپس gateway را restart کنید. برای Docker، binaryهای مرورگر Chromium را نیز طبق پایین نصب کنید.

نصب Docker Playwright

اگر Gateway شما در Docker اجرا می‌شود، از npx playwright پرهیز کنید (تعارض‌های npm override). برای imageهای سفارشی، Chromium را داخل image bake کنید:

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

برای یک image موجود، به‌جای آن از طریق CLI همراه نصب کنید:

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

برای ماندگار کردن دانلودهای مرورگر، PLAYWRIGHT_BROWSERS_PATH را تنظیم کنید (برای نمونه، /home/node/.cache/ms-playwright) و مطمئن شوید /home/node از طریق OmeniaClaw_HOME_VOLUME یا یک bind mount ماندگار شده است. OmeniaClaw روی Linux، Chromium ماندگارشده را به‌طور خودکار تشخیص می‌دهد. Docker را ببینید.

نحوه کارکرد (داخلی)

یک سرور کنترل کوچک loopback درخواست‌های HTTP را می‌پذیرد و از طریق CDP به مرورگرهای مبتنی بر Chromium وصل می‌شود. کنش‌های پیشرفته (click/type/snapshot/PDF) روی CDP از طریق Playwright انجام می‌شوند؛ وقتی Playwright وجود ندارد، فقط عملیات غیر Playwright در دسترس‌اند. عامل یک رابط پایدار می‌بیند، در حالی که مرورگرها و profileهای محلی/remote در لایه زیرین آزادانه جابه‌جا می‌شوند.

مرجع سریع CLI

همه commandها برای هدف‌گیری یک profile مشخص، --browser-profile <name> را می‌پذیرند، و برای خروجی قابل خواندن توسط ماشین، --json را می‌پذیرند.

OmeniaClaw browser statusOmeniaClaw browser startOmeniaClaw browser start --headless # one-shot local managed headless launchOmeniaClaw browser stop            # also clears emulation on attach-only/remote CDPOmeniaClaw browser tabsOmeniaClaw browser tab             # shortcut for current tabOmeniaClaw browser tab newOmeniaClaw browser tab select 2OmeniaClaw browser tab close 2OmeniaClaw browser open https://example.comOmeniaClaw browser focus abcd1234OmeniaClaw browser close abcd1234

OmeniaClaw browser screenshotOmeniaClaw browser screenshot --full-pageOmeniaClaw browser screenshot --ref 12        # or --ref e12OmeniaClaw browser screenshot --labelsOmeniaClaw browser snapshotOmeniaClaw browser snapshot --format aria --limit 200OmeniaClaw browser snapshot --interactive --compact --depth 6OmeniaClaw browser snapshot --efficientOmeniaClaw browser snapshot --labelsOmeniaClaw browser snapshot --urlsOmeniaClaw browser snapshot --selector "#main" --interactiveOmeniaClaw browser snapshot --frame "iframe#main" --interactiveOmeniaClaw browser console --level errorOmeniaClaw browser errors --clearOmeniaClaw browser requests --filter api --clearOmeniaClaw browser pdfOmeniaClaw browser responsebody "**/api" --max-chars 5000

OmeniaClaw browser navigate https://example.comOmeniaClaw browser resize 1280 720OmeniaClaw browser click 12 --double           # or e12 for role refsOmeniaClaw browser click-coords 120 340        # viewport coordinatesOmeniaClaw browser type 23 "hello" --submitOmeniaClaw browser press EnterOmeniaClaw browser hover 44OmeniaClaw browser scrollintoview e12OmeniaClaw browser drag 10 11OmeniaClaw browser select 9 OptionA OptionBOmeniaClaw browser download e12 report.pdfOmeniaClaw browser waitfordownload report.pdfOmeniaClaw browser upload /tmp/OmeniaClaw/uploads/file.pdfOmeniaClaw browser fill --fields '[{"ref":"1","type":"text","value":"Ada"}]'OmeniaClaw browser dialog --acceptOmeniaClaw browser wait --text "Done"OmeniaClaw browser wait "#main" --url "**/dash" --load networkidle --fn "window.ready===true"OmeniaClaw browser evaluate --fn '(el) => el.textContent' --ref 7OmeniaClaw browser highlight e12OmeniaClaw browser trace startOmeniaClaw browser trace stop

OmeniaClaw browser cookiesOmeniaClaw browser cookies set session abc123 --url "https://example.com"OmeniaClaw browser cookies clearOmeniaClaw browser storage local getOmeniaClaw browser storage local set theme darkOmeniaClaw browser storage session clearOmeniaClaw browser set offline onOmeniaClaw browser set headers --headers-json '{"X-Debug":"1"}'OmeniaClaw browser set credentials user pass            # --clear to removeOmeniaClaw browser set geo 37.7749 -122.4194 --origin "https://example.com"OmeniaClaw browser set media darkOmeniaClaw browser set timezone America/New_YorkOmeniaClaw browser set locale en-USOmeniaClaw browser set device "iPhone 14"

نکته‌ها:

• upload و dialog فراخوانی‌های arming هستند؛ آن‌ها را پیش از click/pressای اجرا کنید که chooser/dialog را trigger می‌کند.
• click/type/etc به یک ref از snapshot نیاز دارند (12 عددی، role ref به شکل e12، یا ARIA ref قابل اقدام به شکل ax12). CSS selectorها عمدا برای کنش‌ها پشتیبانی نمی‌شوند. وقتی موقعیت قابل مشاهده viewport تنها target قابل اتکاست، از click-coords استفاده کنید.
• مسیرهای دانلود، trace، و upload به ریشه‌های temp مربوط به OmeniaClaw محدودند: /tmp/OmeniaClaw{,/downloads,/uploads} (fallback: ${os.tmpdir()}/OmeniaClaw/...).
• upload همچنین می‌تواند از طریق --input-ref یا --element، file inputها را مستقیم تنظیم کند.

شناسه‌ها و برچسب‌های پایدار تب‌ها پس از جایگزینی raw-target در Chromium باقی می‌مانند، وقتی OmeniaClaw بتواند تب جایگزین را اثبات کند؛ مثل URL یکسان یا تبدیل یک تب قدیمی به یک تب جدید پس از ارسال فرم. شناسه‌های raw target همچنان ناپایدارند؛ در اسکریپت‌ها suggestedTargetId از tabs را ترجیح دهید.

نگاهی سریع به flagهای snapshot:

• --format ai (پیش‌فرض همراه Playwright): snapshot هوش مصنوعی با refهای عددی (aria-ref="<n>").
• --format aria: درخت دسترس‌پذیری با refهای axN. وقتی Playwright در دسترس باشد، OmeniaClaw refها را با backend DOM idها به صفحه زنده bind می‌کند تا کنش‌های بعدی بتوانند از آن‌ها استفاده کنند؛ در غیر این صورت خروجی را فقط برای بازرسی در نظر بگیرید.
• --efficient (یا --mode efficient): preset فشرده role snapshot. برای اینکه این حالت پیش‌فرض شود، browser.snapshotDefaults.mode: "efficient" را تنظیم کنید (پیکربندی Gateway را ببینید).
• --interactive, --compact, --depth, --selector یک role snapshot با refهای ref=e12 را اجبار می‌کنند. --frame "<iframe>" role snapshotها را به یک iframe محدود می‌کند.
• --labels یک screenshot فقط viewport با برچسب‌های ref روی آن اضافه می‌کند (MEDIA:<path> را چاپ می‌کند).
• --urls مقصدهای link کشف‌شده را به snapshotهای هوش مصنوعی اضافه می‌کند.

Snapshotها و refها

OmeniaClaw از دو سبک «snapshot» پشتیبانی می‌کند:

• snapshot هوش مصنوعی (refهای عددی): OmeniaClaw browser snapshot (پیش‌فرض؛ --format ai)

  • خروجی: یک snapshot متنی که شامل refهای عددی است.
  • کنش‌ها: OmeniaClaw browser click 12, OmeniaClaw browser type 23 "hello".
  • در داخل، ref از طریق aria-ref مربوط به Playwright resolve می‌شود.

• Role snapshot (role refهایی مثل e12): OmeniaClaw browser snapshot --interactive (یا --compact, --depth, --selector, --frame)

  • خروجی: یک فهرست/درخت مبتنی بر نقش با [ref=e12] (و [nth=1] اختیاری).
  • کنش‌ها: OmeniaClaw browser click e12, OmeniaClaw browser highlight e12.
  • در داخل، ref از طریق getByRole(...) (به‌علاوه nth() برای تکراری‌ها) resolve می‌شود.
  • برای افزودن یک screenshot از viewport با برچسب‌های e12 روی آن، --labels را اضافه کنید.
  • وقتی متن link مبهم است و عامل به targetهای مشخص ناوبری نیاز دارد، --urls را اضافه کنید.

• تصویر لحظه‌ای ARIA (ارجاع‌های ARIA مانند ax12): OmeniaClaw browser snapshot --format aria

  • خروجی: درخت دسترس‌پذیری به‌صورت گره‌های ساختاریافته.
  • کنش‌ها: OmeniaClaw browser click ax12 زمانی کار می‌کند که مسیر تصویر لحظه‌ای بتواند ارجاع را از طریق شناسه‌های DOM در backend مربوط به Playwright و 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 به‌جای افتادن به selector مربوط به aria-ref در Playwright، سریع شکست می‌خورند. وقتی این اتفاق افتاد، روی همان زبانه یک تصویر لحظه‌ای تازه بگیرید.

قابلیت‌های پیشرفته انتظار

می‌توانید فقط برای زمان/متن منتظر نمانید:

• انتظار برای URL (globهای پشتیبانی‌شده توسط Playwright):
  • OmeniaClaw browser wait --url "**/dash"
• انتظار برای وضعیت بارگذاری:
  • OmeniaClaw browser wait --load networkidle
• انتظار برای یک predicate جاوااسکریپت:
  • OmeniaClaw browser wait --fn "window.ready===true"
• انتظار برای اینکه یک selector قابل مشاهده شود:
  • OmeniaClaw browser wait "#main"

این‌ها را می‌توان با هم ترکیب کرد:

OmeniaClaw browser wait "#main" \  --url "**/dash" \  --load networkidle \  --fn "window.ready===true" \  --timeout-ms 15000

گردش‌کارهای اشکال‌زدایی

وقتی یک کنش شکست می‌خورد (مثلاً «قابل مشاهده نیست»، «نقض حالت سخت‌گیرانه»، «پوشانده شده»):

1. OmeniaClaw browser snapshot --interactive
2. از click <ref> / type <ref> استفاده کنید (در حالت تعاملی، ارجاع‌های نقش را ترجیح دهید)
3. اگر همچنان شکست خورد: OmeniaClaw browser highlight <ref> تا ببینید Playwright چه چیزی را هدف گرفته است
4. اگر صفحه رفتار عجیبی داشت:
   • OmeniaClaw browser errors --clear
   • OmeniaClaw browser requests --filter api --clear
5. برای اشکال‌زدایی عمیق: یک trace ضبط کنید:
   • OmeniaClaw browser trace start
   • مشکل را بازتولید کنید
   • OmeniaClaw browser trace stop (TRACE:<path> را چاپ می‌کند)

خروجی JSON

--json برای اسکریپت‌نویسی و ابزارهای ساختاریافته است.

نمونه‌ها:

OmeniaClaw browser status --jsonOmeniaClaw browser snapshot --interactive --jsonOmeniaClaw browser requests --filter api --jsonOmeniaClaw browser cookies --json

تصویرهای لحظه‌ای نقش در JSON شامل refs به‌همراه یک بلوک کوچک stats هستند (lines/chars/refs/interactive)، تا ابزارها بتوانند درباره اندازه و تراکم payload استدلال کنند.

کنترل‌های وضعیت و محیط

این‌ها برای گردش‌کارهای «سایت را مثل 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
• منطقه زمانی / locale: set timezone ..., set locale ...
• دستگاه / viewport:
  • set device "iPhone 14" (presetهای دستگاه در Playwright)
  • set viewport 1280 720

امنیت و حریم خصوصی

• پروفایل مرورگر OmeniaClaw ممکن است شامل نشست‌های واردشده باشد؛ آن را حساس تلقی کنید.
• browser act kind=evaluate / OmeniaClaw browser evaluate و wait --fn جاوااسکریپت دلخواه را در context صفحه اجرا می‌کنند. تزریق prompt می‌تواند این را هدایت کند. اگر به آن نیاز ندارید، با browser.evaluateEnabled=false غیرفعالش کنید.
• برای نکات ورود و ضدربات (X/Twitter و غیره)، ورود مرورگر + ارسال در X/Twitter را ببینید.
• میزبان Gateway/Node را خصوصی نگه دارید (local loopback یا فقط tailnet).
• endpointهای CDP راه دور قدرتمند هستند؛ آن‌ها را تونل و محافظت کنید.

نمونه حالت سخت‌گیرانه (مقصدهای خصوصی/داخلی را به‌طور پیش‌فرض مسدود کنید):

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

مرتبط

• مرورگر - نمای کلی، پیکربندی، پروفایل‌ها، امنیت
• ورود مرورگر - ورود به سایت‌ها
• عیب‌یابی Browser در Linux
• عیب‌یابی Browser در WSL2