openclaw browser

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

مرتبط:

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

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

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

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

openclaw browser profilesopenclaw browser --browser-profile openclaw startopenclaw browser --browser-profile openclaw open https://example.comopenclaw browser --browser-profile openclaw snapshot

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

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

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

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

openclaw browser --browser-profile openclaw doctoropenclaw browser --browser-profile openclaw startopenclaw browser --browser-profile openclaw tabsopenclaw browser --browser-profile openclaw open https://example.com

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

چرخه حیات

openclaw browser statusopenclaw browser doctoropenclaw browser doctor --deepopenclaw browser startopenclaw browser start --headlessopenclaw browser stopopenclaw browser --browser-profile openclaw reset-profile

نکته‌ها:

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

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

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

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

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

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

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

پروفایل‌ها

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

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

openclaw browser profilesopenclaw browser create-profile --name work --color "#FF5A36"openclaw browser create-profile --name chrome-live --driver existing-sessionopenclaw browser create-profile --name remote --cdp-url https://browser-host.example.comopenclaw browser delete-profile --name work

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

openclaw browser --browser-profile work tabs

زبانه‌ها

openclaw browser tabsopenclaw browser tab new --label docsopenclaw browser tab label t1 docsopenclaw browser tab select 2openclaw browser tab close 2openclaw browser open https://docs.openclaw.ai --label docsopenclaw browser focus docsopenclaw browser close t1

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

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

اسنپ‌شات:

openclaw browser snapshotopenclaw browser snapshot --urls

نماگرفت:

openclaw browser screenshotopenclaw browser screenshot --full-pageopenclaw browser screenshot --ref e12openclaw browser screenshot --labels

نکته‌ها:

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

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

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

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

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

openclaw browser upload /tmp/openclaw/uploads/file.pdf --ref <ref>openclaw browser waitfordownloadopenclaw browser download <ref> report.pdfopenclaw browser dialog --accept

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

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

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

openclaw browser resize 1280 720openclaw browser set viewport 1280 720openclaw browser set offline onopenclaw browser set media darkopenclaw browser set timezone Europe/Londonopenclaw browser set locale en-GBopenclaw browser set geo 51.5074 -0.1278 --accuracy 25openclaw browser set device "iPhone 14"openclaw browser set headers '{"x-test":"1"}'openclaw browser set credentials myuser mypass

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

openclaw browser cookiesopenclaw browser cookies set session abc123 --url https://example.comopenclaw browser cookies clearopenclaw browser storage local getopenclaw browser storage local set token abc123openclaw browser storage session clear

اشکال‌زدایی

openclaw browser console --level erroropenclaw browser pdfopenclaw browser responsebody "**/api"openclaw browser highlight <ref>openclaw browser errors --clearopenclaw browser requests --filter apiopenclaw browser trace startopenclaw browser trace stop --out trace.zip

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

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

openclaw browser --browser-profile user tabsopenclaw browser create-profile --name chrome-live --driver existing-sessionopenclaw browser create-profile --name brave-live --driver existing-session --user-data-dir "~/Library/Application Support/BraveSoftware/Brave-Browser"openclaw 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
• مرورگر