OmeniaClaw browser

سطح کنترل مرورگر OmeniaClaw را مدیریت کنید و کنش‌های مرورگر را اجرا کنید (چرخه حیات، پروفایل‌ها، زبانه‌ها، اسنپ‌شات‌ها، نماگرفت‌ها، ناوبری، ورودی، شبیه‌سازی وضعیت، و اشکال‌زدایی).

مرتبط:

• ابزار مرورگر + API: ابزار مرورگر

پرچم‌های رایج

• --url <gatewayWsUrl>: URL وب‌سوکت Gateway (به‌طور پیش‌فرض از پیکربندی).
• --token <token>: توکن Gateway (در صورت نیاز).
• --timeout <ms>: مهلت زمانی درخواست (میلی‌ثانیه).
• --expect-final: منتظر پاسخ نهایی Gateway بمانید.
• --browser-profile <name>: یک پروفایل مرورگر انتخاب کنید (پیش‌فرض از پیکربندی).
• --json: خروجی قابل‌خواندن برای ماشین (در مواردی که پشتیبانی می‌شود).

شروع سریع (محلی)

OmeniaClaw browser profilesOmeniaClaw browser --browser-profile OmeniaClaw startOmeniaClaw browser --browser-profile OmeniaClaw open https://example.comOmeniaClaw browser --browser-profile OmeniaClaw snapshot

عامل‌ها می‌توانند همان بررسی آمادگی را با browser({ action: "doctor" }) اجرا کنند.

عیب‌یابی سریع

اگر start با not reachable after start ناموفق شد، ابتدا آمادگی CDP را عیب‌یابی کنید. اگر start و tabs موفق شدند اما open یا navigate ناموفق شد، صفحه کنترل مرورگر سالم است و خرابی معمولا مربوط به سیاست SSRF ناوبری است.

توالی حداقلی:

OmeniaClaw browser --browser-profile OmeniaClaw doctorOmeniaClaw browser --browser-profile OmeniaClaw startOmeniaClaw browser --browser-profile OmeniaClaw tabsOmeniaClaw browser --browser-profile OmeniaClaw open https://example.com

راهنمای تفصیلی: عیب‌یابی مرورگر

چرخه حیات

OmeniaClaw browser statusOmeniaClaw browser doctorOmeniaClaw browser doctor --deepOmeniaClaw browser startOmeniaClaw browser start --headlessOmeniaClaw browser stopOmeniaClaw browser --browser-profile OmeniaClaw reset-profile

نکته‌ها:

• doctor --deep یک پروب زنده اسنپ‌شات اضافه می‌کند. این زمانی مفید است که آمادگی پایه CDP سبز است اما می‌خواهید اثبات کنید زبانه فعلی قابل بازرسی است.
• برای پروفایل‌های attachOnly و CDP راه‌دور، OmeniaClaw browser stop نشست کنترل فعال را می‌بندد و بازنویسی‌های موقت شبیه‌سازی را پاک می‌کند، حتی زمانی که OmeniaClaw خودش فرایند مرورگر را راه‌اندازی نکرده باشد.
• برای پروفایل‌های محلی مدیریت‌شده، OmeniaClaw browser stop فرایند مرورگر ایجادشده را متوقف می‌کند.
• OmeniaClaw browser start --headless فقط برای همان درخواست شروع اعمال می‌شود و فقط زمانی که OmeniaClaw یک مرورگر محلی مدیریت‌شده را راه‌اندازی می‌کند. این دستور browser.headless یا پیکربندی پروفایل را بازنویسی نمی‌کند و برای مرورگری که از قبل در حال اجراست اثری ندارد.
• روی میزبان‌های Linux بدون DISPLAY یا WAYLAND_DISPLAY، پروفایل‌های محلی مدیریت‌شده به‌طور خودکار headless اجرا می‌شوند مگر اینکه OmeniaClaw_BROWSER_HEADLESS=0، browser.headless=false، یا browser.profiles.<name>.headless=false صراحتا مرورگر قابل‌مشاهده درخواست کند.

اگر فرمان وجود ندارد

اگر OmeniaClaw browser فرمانی ناشناخته است، plugins.allow را در ~/.OmeniaClaw/OmeniaClaw.json بررسی کنید.

وقتی plugins.allow وجود دارد، Plugin مرورگر همراه را صراحتا فهرست کنید مگر اینکه پیکربندی از قبل یک بلوک ریشه browser داشته باشد:

{  plugins: {    allow: ["telegram", "browser"],  },}

یک بلوک ریشه صریح browser، برای مثال browser.enabled=true یا browser.profiles.<name>، همچنین Plugin مرورگر همراه را تحت allowlist محدودکننده Plugin فعال می‌کند.

مرتبط: ابزار مرورگر

پروفایل‌ها

پروفایل‌ها پیکربندی‌های نام‌گذاری‌شده مسیریابی مرورگر هستند. در عمل:

• OmeniaClaw: یک نمونه اختصاصی Chrome مدیریت‌شده توسط OmeniaClaw را راه‌اندازی می‌کند یا به آن متصل می‌شود (دایرکتوری داده کاربر ایزوله).
• user: نشست Chrome موجود و واردشده شما را از طریق Chrome DevTools MCP کنترل می‌کند.
• پروفایل‌های CDP سفارشی: به یک نقطه پایانی CDP محلی یا راه‌دور اشاره می‌کنند.

OmeniaClaw browser profilesOmeniaClaw browser create-profile --name work --color "#FF5A36"OmeniaClaw browser create-profile --name chrome-live --driver existing-sessionOmeniaClaw browser create-profile --name remote --cdp-url https://browser-host.example.comOmeniaClaw browser delete-profile --name work

استفاده از یک پروفایل مشخص:

OmeniaClaw browser --browser-profile work tabs

زبانه‌ها

OmeniaClaw browser tabsOmeniaClaw browser tab new --label docsOmeniaClaw browser tab label t1 docsOmeniaClaw browser tab select 2OmeniaClaw browser tab close 2OmeniaClaw browser open https://omeniaclaw.com --label docsOmeniaClaw browser focus docsOmeniaClaw browser close t1

tabs ابتدا suggestedTargetId، سپس tabId پایدار مانند t1، برچسب اختیاری، و targetId خام را برمی‌گرداند. عامل‌ها باید suggestedTargetId را دوباره به focus، close، اسنپ‌شات‌ها، و کنش‌ها بدهند. می‌توانید با open --label، tab new --label، یا tab label یک برچسب اختصاص دهید؛ برچسب‌ها، شناسه‌های زبانه، شناسه‌های هدف خام، و پیشوندهای یکتای شناسه هدف همگی پذیرفته می‌شوند. وقتی Chromium هدف خام زیرین را هنگام ناوبری یا ارسال فرم جایگزین می‌کند، OmeniaClaw در صورت امکان اثبات تطابق، tabId/برچسب پایدار را به زبانه جایگزین متصل نگه می‌دارد. شناسه‌های هدف خام همچنان ناپایدار هستند؛ suggestedTargetId را ترجیح دهید.

اسنپ‌شات / نماگرفت / کنش‌ها

اسنپ‌شات:

OmeniaClaw browser snapshotOmeniaClaw browser snapshot --urls

نماگرفت:

OmeniaClaw browser screenshotOmeniaClaw browser screenshot --full-pageOmeniaClaw browser screenshot --ref e12OmeniaClaw browser screenshot --labels

نکته‌ها:

• --full-page فقط برای گرفتن تصویر از صفحه است؛ نمی‌توان آن را با --ref یا --element ترکیب کرد.
• پروفایل‌های existing-session / user از نماگرفت صفحه و نماگرفت‌های --ref از خروجی اسنپ‌شات پشتیبانی می‌کنند، اما از نماگرفت‌های CSS --element پشتیبانی نمی‌کنند.
• --labels refهای اسنپ‌شات فعلی را روی نماگرفت نمایش می‌دهد.
• snapshot --urls مقصدهای پیوند کشف‌شده را به اسنپ‌شات‌های AI اضافه می‌کند تا عامل‌ها بتوانند به‌جای حدس‌زدن فقط از متن پیوند، هدف‌های مستقیم ناوبری را انتخاب کنند.

ناوبری/کلیک/تایپ (خودکارسازی UI مبتنی بر ref):

OmeniaClaw browser navigate https://example.comOmeniaClaw browser click <ref>OmeniaClaw browser click-coords 120 340OmeniaClaw browser type <ref> "hello"OmeniaClaw browser press EnterOmeniaClaw browser hover <ref>OmeniaClaw browser scrollintoview <ref>OmeniaClaw browser drag <startRef> <endRef>OmeniaClaw browser select <ref> OptionA OptionBOmeniaClaw browser fill --fields '[{"ref":"1","value":"Ada"}]'OmeniaClaw browser wait --text "Done"OmeniaClaw browser evaluate --fn '(el) => el.textContent' --ref <ref>

پاسخ‌های کنش، پس از جایگزینی صفحه که توسط کنش ایجاد شده، targetId خام فعلی را زمانی برمی‌گردانند که OmeniaClaw بتواند زبانه جایگزین را اثبات کند. اسکریپت‌ها همچنان باید برای گردش‌کارهای بلندمدت، suggestedTargetId/برچسب‌ها را ذخیره و ارسال کنند.

راهنماهای فایل + دیالوگ:

OmeniaClaw browser upload /tmp/OmeniaClaw/uploads/file.pdf --ref <ref>OmeniaClaw browser waitfordownloadOmeniaClaw browser download <ref> report.pdfOmeniaClaw browser dialog --accept

پروفایل‌های Chrome مدیریت‌شده، دانلودهای معمولی آغازشده با کلیک را در دایرکتوری دانلودهای OmeniaClaw ذخیره می‌کنند (/tmp/OmeniaClaw/downloads به‌طور پیش‌فرض، یا ریشه موقت پیکربندی‌شده). وقتی عامل باید منتظر یک فایل مشخص بماند و مسیر آن را برگرداند، از waitfordownload یا download استفاده کنید؛ این منتظرهای صریح مالک دانلود بعدی هستند.

وضعیت و ذخیره‌سازی

Viewport + شبیه‌سازی:

OmeniaClaw browser resize 1280 720OmeniaClaw browser set viewport 1280 720OmeniaClaw browser set offline onOmeniaClaw browser set media darkOmeniaClaw browser set timezone Europe/LondonOmeniaClaw browser set locale en-GBOmeniaClaw browser set geo 51.5074 -0.1278 --accuracy 25OmeniaClaw browser set device "iPhone 14"OmeniaClaw browser set headers '{"x-test":"1"}'OmeniaClaw browser set credentials myuser mypass

کوکی‌ها + ذخیره‌سازی:

OmeniaClaw browser cookiesOmeniaClaw browser cookies set session abc123 --url https://example.comOmeniaClaw browser cookies clearOmeniaClaw browser storage local getOmeniaClaw browser storage local set token abc123OmeniaClaw browser storage session clear

اشکال‌زدایی

OmeniaClaw browser console --level errorOmeniaClaw browser pdfOmeniaClaw browser responsebody "**/api"OmeniaClaw browser highlight <ref>OmeniaClaw browser errors --clearOmeniaClaw browser requests --filter apiOmeniaClaw browser trace startOmeniaClaw browser trace stop --out trace.zip

Chrome موجود از طریق MCP

از پروفایل داخلی user استفاده کنید، یا پروفایل existing-session خودتان را بسازید:

OmeniaClaw browser --browser-profile user tabsOmeniaClaw browser create-profile --name chrome-live --driver existing-sessionOmeniaClaw browser create-profile --name brave-live --driver existing-session --user-data-dir "~/Library/Application Support/BraveSoftware/Brave-Browser"OmeniaClaw browser --browser-profile chrome-live tabs

این مسیر فقط روی میزبان است. برای Docker، سرورهای headless، Browserless، یا تنظیمات راه‌دور دیگر، به‌جای آن از یک پروفایل CDP استفاده کنید.

محدودیت‌های فعلی existing-session:

• کنش‌های هدایت‌شده با اسنپ‌شات از refها استفاده می‌کنند، نه انتخابگرهای CSS
• وقتی فراخوان‌ها timeoutMs را حذف کنند، browser.actionTimeoutMs درخواست‌های پشتیبانی‌شده act را به‌طور پیش‌فرض روی 60000 میلی‌ثانیه می‌گذارد؛ timeoutMs هر فراخوان همچنان مقدم است.
• click فقط کلیک چپ است
• type از slowly=true پشتیبانی نمی‌کند
• press از delayMs پشتیبانی نمی‌کند
• hover، scrollintoview، drag، select، fill، و evaluate بازنویسی‌های مهلت زمانی هر فراخوان را رد می‌کنند
• select فقط از یک مقدار پشتیبانی می‌کند
• wait --load networkidle پشتیبانی نمی‌شود
• بارگذاری فایل به --ref / --input-ref نیاز دارد، از CSS --element پشتیبانی نمی‌کند، و در حال حاضر هر بار از یک فایل پشتیبانی می‌کند
• قلاب‌های دیالوگ از --timeout پشتیبانی نمی‌کنند
• نماگرفت‌ها از گرفتن تصویر صفحه و --ref پشتیبانی می‌کنند، اما از CSS --element پشتیبانی نمی‌کنند
• responsebody، رهگیری دانلود، خروجی PDF، و کنش‌های دسته‌ای همچنان به یک مرورگر مدیریت‌شده یا پروفایل CDP خام نیاز دارند

کنترل مرورگر راه‌دور (پروکسی میزبان node)

اگر Gateway روی ماشینی متفاوت از مرورگر اجرا می‌شود، یک میزبان node روی ماشینی اجرا کنید که Chrome/Brave/Edge/Chromium دارد. Gateway کنش‌های مرورگر را به آن node پروکسی می‌کند (سرور کنترل مرورگر جداگانه لازم نیست).

برای کنترل مسیریابی خودکار از gateway.nodes.browser.mode استفاده کنید و اگر چند node متصل هستند، برای ثابت‌کردن یک node مشخص از gateway.nodes.browser.node استفاده کنید.

امنیت + راه‌اندازی راه‌دور: ابزار مرورگر، دسترسی راه‌دور، Tailscale، امنیت

مرتبط

• مرجع CLI
• مرورگر