openclaw browser

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

مرتبط:

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

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

• --url <gatewayWsUrl>: نشانی WebSocket مربوط به 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، پروفایل‌های مدیریت‌شده محلی به‌طور خودکار بی‌سر اجرا می‌شوند، مگر اینکه 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 مرورگر بسته‌بندی‌شده را نیز زیر یک فهرست مجاز محدودکننده 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 یک برچسب اختصاص دهید؛ برچسب‌ها، شناسه‌های زبانه، شناسه‌های خام هدف، و پیشوندهای یکتای شناسه هدف همگی پذیرفته می‌شوند. فیلد درخواست برای سازگاری همچنان targetId نام دارد، اما این ارجاع‌های زبانه را می‌پذیرد. شناسه‌های خام هدف را به‌عنوان دسته‌های تشخیصی در نظر بگیرید، نه حافظه پایدار عامل. وقتی 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 ارجاع‌های اسنپ‌شات فعلی را روی اسکرین‌شات قرار می‌دهد. روی پروفایل‌های مبتنی بر Playwright، با --full-page (هم‌پوشانی برچسب کل صفحه)، --ref (هم‌پوشانی برچسب برش عنصر بر اساس ارجاع ARIA)، و --element (هم‌پوشانی برچسب برش عنصر بر اساس انتخابگر CSS) کار می‌کند؛ در حالت‌های برش عنصر، برچسب‌ها نسبت به عنصر تصویر می‌شوند. پاسخ همچنین یک آرایه annotations با کادر محدودکننده هر ارجاع دارد. هر مورد دارای ref، number، role، name اختیاری، و box: {x, y, width, height} است؛ مختصات در فضای تصویر گرفته‌شده هستند (نما / کل صفحه / نسبی به عنصر). وقتی خالی باشد، فیلد حذف می‌شود. پروفایل‌های existing-session یک هم‌پوشانی chrome-mcp را روی اسکرین‌شات‌های صفحه رندر می‌کنند، اما از کمک‌گر تصویرسازی Playwright استفاده نمی‌کنند و annotations را شامل نمی‌شوند؛ اسکرین‌شات‌های CSS --element در آنجا پشتیبانی نمی‌شوند. بدون Playwright یا chrome-mcp، اسکرین‌شات‌های برچسب‌دار در دسترس نیستند. نسخه‌های قبلی --full-page، --ref، و --element را روی اسکرین‌شات‌های برچسب‌دار Playwright نادیده می‌گرفتند و همیشه یک تصویر نما برمی‌گرداندند؛ اسکرین‌شات‌های برچسب‌دار اکنون به آن دامنه‌ها احترام می‌گذارند.
• snapshot --urls مقصدهای پیوند کشف‌شده را به اسنپ‌شات‌های هوش مصنوعی اضافه می‌کند تا عامل‌ها بتوانند به‌جای حدس زدن فقط از متن پیوند، مقصدهای ناوبری مستقیم را انتخاب کنند.

ناوبری/کلیک/تایپ (اتوماسیون رابط کاربری مبتنی بر ارجاع):

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>openclaw browser evaluate --fn 'const title = document.title; return title;'openclaw browser evaluate --timeout-ms 30000 --fn 'async () => { await window.ready; return true; }'

evaluate --fn منبع یک تابع، یک عبارت، یا بدنه یک دستور را می‌پذیرد. بدنه‌های دستور به‌صورت تابع‌های async پیچیده می‌شوند، بنابراین برای مقداری که می‌خواهید برگردد از return استفاده کنید. وقتی تابع سمت صفحه ممکن است بیشتر از مهلت زمانی پیش‌فرض evaluate زمان نیاز داشته باشد، از evaluate --timeout-ms <ms> استفاده کنید.

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

کمک‌گرهای فایل + گفت‌وگو:

openclaw browser upload /tmp/openclaw/uploads/file.pdf --ref <ref>openclaw browser upload media://inbound/file.pdf --ref <ref>openclaw browser waitfordownloadopenclaw browser download <ref> report.pdfopenclaw browser dialog --acceptopenclaw browser dialog --dismiss --dialog-id d1

پروفایل‌های Chrome مدیریت‌شده دانلودهای عادی آغازشده با کلیک را در دایرکتوری دانلودهای OpenClaw ذخیره می‌کنند (/tmp/openclaw/downloads به‌صورت پیش‌فرض، یا ریشه موقت پیکربندی‌شده). وقتی عامل باید منتظر یک فایل مشخص بماند و مسیر آن را برگرداند، از waitfordownload یا download استفاده کنید؛ این انتظارگرهای صریح مالک دانلود بعدی هستند. آپلودها فایل‌ها را از ریشه آپلودهای موقت OpenClaw و رسانه ورودی مدیریت‌شده توسط OpenClaw می‌پذیرند، از جمله ارجاع‌های media://inbound/<id> و media/inbound/<id> نسبی به سندباکس. ارجاع‌های رسانه تودرتو، پیمایش مسیر، و مسیرهای محلی دلخواه همچنان رد می‌شوند. وقتی یک کنش یک گفت‌وگوی مودال باز می‌کند، پاسخ کنش blockedByDialog را همراه با browserState.dialogs.pending برمی‌گرداند؛ برای پاسخ مستقیم به آن، --dialog-id را بدهید. گفت‌وگوهایی که بیرون از OpenClaw رسیدگی شده‌اند زیر browserState.dialogs.recent ظاهر می‌شوند.

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

نما + شبیه‌سازی:

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 create-profile --name chrome-port --driver existing-session --cdp-url http://127.0.0.1:9222openclaw browser --browser-profile chrome-live tabs

مسیر پیش‌فرض existing-session، اتصال خودکار Chrome MCP فقط روی میزبان است. اگر مرورگر از قبل با یک نقطه پایانی DevTools در حال اجراست، --cdp-url را بدهید تا Chrome MCP به‌جای آن به همان نقطه پایانی متصل شود. برای Docker، Browserless، یا راه‌اندازی‌های راه‌دور دیگری که معناشناسی Chrome MCP لازم نیست، از یک پروفایل CDP استفاده کنید.

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

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

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

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

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

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

مرتبط

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