# openclaw browser

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

مرتبط:

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

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

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

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

openclaw browser profiles
openclaw browser --browser-profile openclaw start
openclaw browser --browser-profile openclaw open https://example.com
openclaw browser --browser-profile openclaw snapshot

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

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

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

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

openclaw browser --browser-profile openclaw doctor
openclaw browser --browser-profile openclaw start
openclaw browser --browser-profile openclaw tabs
openclaw browser --browser-profile openclaw open https://example.com

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

# چرخه حیات

openclaw browser status
openclaw browser doctor
openclaw browser doctor --deep
openclaw browser start
openclaw browser start --headless
openclaw browser stop
openclaw 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 profiles
openclaw browser create-profile --name work --color "#FF5A36"
openclaw browser create-profile --name chrome-live --driver existing-session
openclaw browser create-profile --name remote --cdp-url https://browser-host.example.com
openclaw browser delete-profile --name work

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

openclaw browser --browser-profile work tabs

# زبانه‌ها

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

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

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

اسنپ‌شات:

openclaw browser snapshot
openclaw browser snapshot --urls

نماگرفت:

openclaw browser screenshot
openclaw browser screenshot --full-page
openclaw browser screenshot --ref e12
openclaw 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.com
openclaw browser click <ref>
openclaw browser click-coords 120 340
openclaw browser type <ref> "hello"
openclaw browser press Enter
openclaw browser hover <ref>
openclaw browser scrollintoview <ref>
openclaw browser drag <startRef> <endRef>
openclaw browser select <ref> OptionA OptionB
openclaw 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 waitfordownload
openclaw browser download <ref> report.pdf
openclaw browser dialog --accept

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

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

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

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

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

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 token abc123
openclaw browser storage session clear

# اشکال‌زدایی

openclaw browser console --level error
openclaw browser pdf
openclaw browser responsebody "**/api"
openclaw browser highlight <ref>
openclaw browser errors --clear
openclaw browser requests --filter api
openclaw browser trace start
openclaw browser trace stop --out trace.zip

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

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

openclaw browser --browser-profile user tabs
openclaw browser create-profile --name chrome-live --driver existing-session
openclaw 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
• مرورگر