مرورگر (مدیریت‌شده توسط OpenClaw)

OpenClaw می‌تواند یک نمایهٔ اختصاصی Chrome/Brave/Edge/Chromium را اجرا کند که عامل آن را کنترل می‌کند. این نمایه از مرورگر شخصی شما جدا است و از طریق یک سرویس کنترل محلی کوچک درون Gateway مدیریت می‌شود (فقط loopback).

نمای مبتدی:

• آن را به‌صورت یک مرورگر جداگانه و فقط مخصوص عامل در نظر بگیرید.
• نمایهٔ openclaw به نمایهٔ مرورگر شخصی شما دست نمی‌زند.
• عامل می‌تواند در یک مسیر امن زبانه باز کند، صفحه‌ها را بخواند، کلیک کند و تایپ کند.
• نمایهٔ داخلی user از طریق Chrome MCP به نشست واقعی Chrome واردشدهٔ شما متصل می‌شود.

آنچه دریافت می‌کنید

• یک نمایهٔ مرورگر جداگانه با نام openclaw (به‌طور پیش‌فرض با تأکید نارنجی).
• کنترل قطعی زبانه‌ها (فهرست/باز کردن/تمرکز/بستن).
• کنش‌های عامل (کلیک/تایپ/کشیدن/انتخاب)، نماگرفت‌ها، تصاویر صفحه، PDFها.
• یک Skill همراه browser-automation که وقتی Plugin مرورگر فعال باشد، چرخهٔ بازیابی نماگرفت، زبانهٔ پایدار، ارجاع منقضی، و مانع دستی را به عامل‌ها آموزش می‌دهد.
• پشتیبانی اختیاری از چند نمایه (openclaw، work، remote، ...).

این مرورگر، مرورگر روزمرهٔ شما نیست. این یک سطح امن و جداگانه برای خودکارسازی و راستی‌آزمایی عامل است.

شروع سریع

openclaw browser --browser-profile openclaw doctoropenclaw browser --browser-profile openclaw doctor --deepopenclaw browser --browser-profile openclaw statusopenclaw browser --browser-profile openclaw startopenclaw browser --browser-profile openclaw open https://example.comopenclaw browser --browser-profile openclaw snapshot

اگر پیام «Browser disabled» دریافت کردید، آن را در پیکربندی فعال کنید (پایین را ببینید) و Gateway را دوباره راه‌اندازی کنید.

اگر openclaw browser به‌طور کامل وجود ندارد، یا عامل می‌گوید ابزار مرورگر در دسترس نیست، به فرمان یا ابزار مرورگر موجود نیست بروید.

کنترل Plugin

ابزار پیش‌فرض browser یک Plugin همراه است. برای جایگزین‌کردن آن با Plugin دیگری که همان نام ابزار browser را ثبت می‌کند، آن را غیرفعال کنید:

{  plugins: {    entries: {      browser: {        enabled: false,      },    },  },}

پیش‌فرض‌ها هم به plugins.entries.browser.enabled و هم به browser.enabled=true نیاز دارند. غیرفعال‌کردن فقط Plugin، openclaw browser CLI، متد Gateway با نام browser.request، ابزار عامل، و سرویس کنترل را به‌عنوان یک واحد حذف می‌کند؛ پیکربندی browser.* شما برای جایگزین دست‌نخورده می‌ماند.

تغییرات پیکربندی مرورگر به راه‌اندازی دوبارهٔ Gateway نیاز دارند تا Plugin بتواند سرویس خود را دوباره ثبت کند.

راهنمای عامل

نکتهٔ نمایهٔ ابزار: tools.profile: "coding" شامل web_search و web_fetch است، اما ابزار کامل browser را شامل نمی‌شود. اگر عامل یا یک زیرعامل ایجادشده باید از خودکارسازی مرورگر استفاده کند، مرورگر را در مرحلهٔ نمایه اضافه کنید:

{  tools: {    profile: "coding",    alsoAllow: ["browser"],  },}

برای یک عامل واحد، از agents.list[].tools.alsoAllow: ["browser"] استفاده کنید. tools.subagents.tools.allow: ["browser"] به‌تنهایی کافی نیست، چون سیاست زیرعامل پس از پالایش نمایه اعمال می‌شود.

Plugin مرورگر دو سطح راهنمای عامل ارائه می‌کند:

• توضیح ابزار browser قرارداد فشردهٔ همیشه‌فعال را حمل می‌کند: نمایهٔ درست را انتخاب کنید، ارجاع‌ها را روی همان زبانه نگه دارید، از tabId/برچسب‌ها برای هدف‌گیری زبانه استفاده کنید، و برای کار چندمرحله‌ای Skill مرورگر را بارگذاری کنید.
• Skill همراه browser-automation چرخهٔ عملیاتی طولانی‌تر را حمل می‌کند: ابتدا وضعیت/زبانه‌ها را بررسی کنید، زبانه‌های وظیفه را برچسب‌گذاری کنید، پیش از عمل نماگرفت بگیرید، پس از تغییرات UI دوباره نماگرفت بگیرید، ارجاع‌های منقضی را یک‌بار بازیابی کنید، و ورود/2FA/captcha یا موانع دوربین/میکروفون را به‌جای حدس‌زدن، به‌عنوان اقدام دستی گزارش کنید.

Skills همراه Plugin وقتی Plugin فعال باشد در Skills در دسترس عامل فهرست می‌شوند. دستورالعمل‌های کامل Skill بر حسب تقاضا بارگذاری می‌شوند، بنابراین نوبت‌های معمول هزینهٔ کامل توکن را پرداخت نمی‌کنند.

فرمان یا ابزار مرورگر موجود نیست

اگر پس از ارتقا openclaw browser ناشناخته است، browser.request موجود نیست، یا عامل ابزار مرورگر را ناموجود گزارش می‌کند، علت معمول یک فهرست plugins.allow است که browser را جا انداخته و هیچ بلوک پیکربندی ریشهٔ browser وجود ندارد. آن را اضافه کنید:

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

یک بلوک ریشهٔ صریح browser، برای مثال browser.enabled=true یا browser.profiles.<name>، حتی زیر یک plugins.allow محدودکننده نیز Plugin مرورگر همراه را فعال می‌کند و با رفتار پیکربندی کانال هم‌خوان است. plugins.entries.browser.enabled=true و tools.alsoAllow: ["browser"] به‌تنهایی جایگزین عضویت در فهرست مجاز نمی‌شوند. حذف کامل plugins.allow نیز پیش‌فرض را بازمی‌گرداند.

نمایه‌ها: openclaw در برابر user

• openclaw: مرورگر مدیریت‌شده و جداگانه (بدون نیاز به افزونه).
• user: نمایهٔ اتصال داخلی Chrome MCP برای نشست واقعی Chrome واردشدهٔ شما.

برای فراخوانی‌های ابزار مرورگر عامل:

• پیش‌فرض: از مرورگر جداگانهٔ openclaw استفاده کنید.
• وقتی نشست‌های واردشدهٔ موجود اهمیت دارند و کاربر پشت رایانه است تا هر اعلان اتصال را کلیک/تأیید کند، profile="user" را ترجیح دهید.
• وقتی یک حالت مرورگر مشخص می‌خواهید، profile بازنویسی صریح است.

اگر می‌خواهید حالت مدیریت‌شده به‌طور پیش‌فرض باشد، browser.defaultProfile: "openclaw" را تنظیم کنید.

پیکربندی

تنظیمات مرورگر در ~/.openclaw/openclaw.json قرار دارند.

{  browser: {    enabled: true, // default: true    ssrfPolicy: {      // dangerouslyAllowPrivateNetwork: true, // opt in only for trusted private-network access      // allowPrivateNetwork: true, // legacy alias      // hostnameAllowlist: ["*.example.com", "example.com"],      // allowedHostnames: ["localhost"],    },    // cdpUrl: "http://127.0.0.1:18792", // legacy single-profile override    remoteCdpTimeoutMs: 1500, // remote CDP HTTP timeout (ms)    remoteCdpHandshakeTimeoutMs: 3000, // remote CDP WebSocket handshake timeout (ms)    localLaunchTimeoutMs: 15000, // local managed Chrome discovery timeout (ms)    localCdpReadyTimeoutMs: 8000, // local managed post-launch CDP readiness timeout (ms)    actionTimeoutMs: 60000, // default browser act timeout (ms)    tabCleanup: {      enabled: true, // default: true      idleMinutes: 120, // set 0 to disable idle cleanup      maxTabsPerSession: 8, // set 0 to disable the per-session cap      sweepMinutes: 5,    },    defaultProfile: "openclaw",    color: "#FF4500",    headless: false,    noSandbox: false,    attachOnly: false,    executablePath: "/Applications/Brave Browser.app/Contents/MacOS/Brave Browser",    profiles: {      openclaw: { cdpPort: 18800, color: "#FF4500" },      work: {        cdpPort: 18801,        color: "#0066CC",        headless: true,        executablePath: "/Applications/Google Chrome.app/Contents/MacOS/Google Chrome",      },      user: {        driver: "existing-session",        attachOnly: true,        color: "#00AA00",      },      brave: {        driver: "existing-session",        attachOnly: true,        userDataDir: "~/Library/Application Support/BraveSoftware/Brave-Browser",        color: "#FB542B",      },      remote: { cdpUrl: "http://10.0.0.42:9222", color: "#00AA00" },    },  },}

استفاده از Brave یا مرورگر دیگری مبتنی بر Chromium

اگر مرورگر پیش‌فرض سیستم شما مبتنی بر Chromium باشد (Chrome/Brave/Edge/etc)، OpenClaw به‌طور خودکار از آن استفاده می‌کند. برای بازنویسی تشخیص خودکار، browser.executablePath را تنظیم کنید. مقدارهای executablePath در سطح بالا و برای هر پروفایل، ~ را برای پوشهٔ خانهٔ سیستم‌عامل شما می‌پذیرند:

openclaw config set browser.executablePath "/usr/bin/google-chrome"openclaw config set browser.profiles.work.executablePath "/Applications/Google Chrome.app/Contents/MacOS/Google Chrome"

یا آن را در پیکربندی، برای هر پلتفرم تنظیم کنید:

{browser: {executablePath: "/Applications/Brave Browser.app/Contents/MacOS/Brave Browser",},}

{browser: {executablePath: "C:\\Program Files\\BraveSoftware\\Brave-Browser\\Application\\brave.exe",},}

{browser: {executablePath: "/usr/bin/brave-browser",},}

executablePath مخصوص هر پروفایل فقط بر پروفایل‌های مدیریت‌شدهٔ محلی اثر می‌گذارد که OpenClaw آن‌ها را اجرا می‌کند. پروفایل‌های existing-session در عوض به مرورگری که از قبل در حال اجراست متصل می‌شوند، و پروفایل‌های CDP راه‌دور از مرورگر پشت cdpUrl استفاده می‌کنند.

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

• کنترل محلی (پیش‌فرض): Gateway سرویس کنترل local loopback را شروع می‌کند و می‌تواند یک مرورگر محلی اجرا کند.
• کنترل راه‌دور (میزبان Node): روی دستگاهی که مرورگر را دارد یک میزبان Node اجرا کنید؛ Gateway کنش‌های مرورگر را به آن proxy می‌کند.
• CDP راه‌دور: برای اتصال به یک مرورگر راه‌دور مبتنی بر Chromium، browser.profiles.<name>.cdpUrl (یا browser.cdpUrl) را تنظیم کنید. در این حالت، OpenClaw مرورگر محلی اجرا نخواهد کرد.
• برای سرویس‌های CDP مدیریت‌شدهٔ بیرونی روی loopback (برای مثال Browserless در Docker منتشرشده روی 127.0.0.1)، attachOnly: true را نیز تنظیم کنید. CDP روی loopback بدون attachOnly به‌عنوان پروفایل مرورگر محلی مدیریت‌شده توسط OpenClaw در نظر گرفته می‌شود.
• headless فقط بر پروفایل‌های مدیریت‌شدهٔ محلی اثر می‌گذارد که OpenClaw اجرا می‌کند. این گزینه مرورگرهای نشست موجود یا CDP راه‌دور را دوباره راه‌اندازی یا تغییر نمی‌دهد.
• executablePath از همان قاعدهٔ پروفایل مدیریت‌شدهٔ محلی پیروی می‌کند. تغییر آن روی یک پروفایل مدیریت‌شدهٔ محلی در حال اجرا، آن پروفایل را برای راه‌اندازی دوباره/همگام‌سازی علامت‌گذاری می‌کند تا اجرای بعدی از باینری جدید استفاده کند.

رفتار توقف بسته به حالت پروفایل متفاوت است:

• پروفایل‌های مدیریت‌شدهٔ محلی: openclaw browser stop فرایند مرورگری را متوقف می‌کند که OpenClaw اجرا کرده است
• پروفایل‌های فقط-اتصال و CDP راه‌دور: openclaw browser stop نشست کنترل فعال را می‌بندد و بازنویسی‌های شبیه‌سازی Playwright/CDP (viewport، scheme رنگ، locale، timezone، حالت offline، و وضعیت‌های مشابه) را آزاد می‌کند، حتی اگر هیچ فرایند مرورگری توسط OpenClaw اجرا نشده باشد

URLهای CDP راه‌دور می‌توانند شامل احراز هویت باشند:

• توکن‌های query (برای مثال، https://provider.example?token=<token>)
• احراز هویت HTTP Basic (برای مثال، https://user:pass@provider.example)

OpenClaw هنگام فراخوانی endpointهای /json/* و هنگام اتصال به WebSocket مربوط به CDP، احراز هویت را حفظ می‌کند. برای توکن‌ها، به‌جای commit کردن آن‌ها در فایل‌های پیکربندی، از متغیرهای محیطی یا مدیرهای secrets استفاده کنید.

proxy مرورگر Node (پیش‌فرض بدون پیکربندی)

اگر روی دستگاهی که مرورگر شما را دارد یک میزبان Node اجرا کنید، OpenClaw می‌تواند فراخوانی‌های ابزار مرورگر را بدون هیچ پیکربندی اضافی مرورگر، به‌طور خودکار به آن Node مسیردهی کند. این مسیر پیش‌فرض برای Gatewayهای راه‌دور است.

نکته‌ها:

• میزبان Node سرور کنترل مرورگر محلی خود را از طریق یک دستور proxy ارائه می‌کند.
• پروفایل‌ها از پیکربندی browser.profiles خود Node می‌آیند (همانند حالت محلی).
• nodeHost.browserProxy.allowProfiles اختیاری است. برای رفتار legacy/پیش‌فرض آن را خالی بگذارید: همهٔ پروفایل‌های پیکربندی‌شده از طریق proxy قابل دسترسی می‌مانند، از جمله مسیرهای ایجاد/حذف پروفایل.
• اگر nodeHost.browserProxy.allowProfiles را تنظیم کنید، OpenClaw آن را به‌عنوان مرز حداقل دسترسی در نظر می‌گیرد: فقط پروفایل‌های allowlist‌شده می‌توانند هدف قرار گیرند، و مسیرهای پایدار ایجاد/حذف پروفایل روی سطح proxy مسدود می‌شوند.
• اگر آن را نمی‌خواهید، غیرفعالش کنید:
  • روی Node: nodeHost.browserProxy.enabled=false
  • روی gateway: gateway.nodes.browser.mode="off"

Browserless (CDP راه‌دور میزبانی‌شده)

Browserless یک سرویس میزبانی‌شدهٔ Chromium است که URLهای اتصال CDP را روی HTTPS و WebSocket ارائه می‌کند. OpenClaw می‌تواند از هر دو فرم استفاده کند، اما برای یک پروفایل مرورگر راه‌دور، ساده‌ترین گزینه URL مستقیم WebSocket از مستندات اتصال Browserless است.

مثال:

{  browser: {    enabled: true,    defaultProfile: "browserless",    remoteCdpTimeoutMs: 2000,    remoteCdpHandshakeTimeoutMs: 4000,    profiles: {      browserless: {        cdpUrl: "wss://production-sfo.browserless.io?token=<BROWSERLESS_API_KEY>",        color: "#00AA00",      },    },  },}

نکته‌ها:

• <BROWSERLESS_API_KEY> را با توکن واقعی Browserless خود جایگزین کنید.
• endpoint منطقه‌ای را انتخاب کنید که با حساب Browserless شما مطابقت دارد (مستندات آن‌ها را ببینید).
• اگر Browserless یک URL پایهٔ HTTPS به شما بدهد، می‌توانید آن را برای اتصال مستقیم CDP به wss:// تبدیل کنید، یا URL مربوط به HTTPS را نگه دارید و اجازه دهید OpenClaw /json/version را کشف کند.

Browserless Docker روی همان میزبان

وقتی Browserless به‌صورت self-hosted در Docker اجرا می‌شود و OpenClaw روی میزبان اجرا می‌شود، با Browserless مانند یک سرویس CDP مدیریت‌شدهٔ بیرونی رفتار کنید:

{  browser: {    enabled: true,    defaultProfile: "browserless",    profiles: {      browserless: {        cdpUrl: "ws://127.0.0.1:3000",        attachOnly: true,        color: "#00AA00",      },    },  },}

نشانی موجود در browser.profiles.browserless.cdpUrl باید از فرایند OpenClaw قابل دسترسی باشد. Browserless همچنین باید endpoint قابل دسترسی متناظر را تبلیغ کند؛ مقدار Browserless EXTERNAL را به همان پایهٔ WebSocket عمومی-برای-OpenClaw تنظیم کنید، مانند ws://127.0.0.1:3000، ws://browserless:3000، یا یک نشانی شبکهٔ خصوصی پایدار Docker. اگر /json/version مقدار webSocketDebuggerUrl را برگرداند که به نشانی‌ای اشاره می‌کند که OpenClaw نمی‌تواند به آن برسد، HTTP مربوط به CDP ممکن است سالم به‌نظر برسد، در حالی که اتصال WebSocket همچنان شکست می‌خورد.

برای یک پروفایل Browserless روی loopback، attachOnly را تنظیم‌نشده رها نکنید. بدون attachOnly، OpenClaw پورت loopback را به‌عنوان یک پروفایل مرورگر مدیریت‌شدهٔ محلی در نظر می‌گیرد و ممکن است گزارش کند که پورت در حال استفاده است اما متعلق به OpenClaw نیست.

ارائه‌دهندگان CDP مستقیم WebSocket

برخی سرویس‌های مرورگر میزبانی‌شده، به‌جای کشف استاندارد CDP مبتنی بر HTTP (/json/version)، یک endpoint مستقیم WebSocket ارائه می‌کنند. OpenClaw سه شکل URL مربوط به CDP را می‌پذیرد و راهبرد اتصال درست را به‌طور خودکار انتخاب می‌کند:

• کشف HTTP(S) - http://host[:port] یا https://host[:port]. OpenClaw برای کشف URL اشکال‌زدای WebSocket، /json/version را فراخوانی می‌کند و سپس متصل می‌شود. هیچ fallback WebSocket وجود ندارد.
• endpointهای مستقیم WebSocket - ws://host[:port]/devtools/<kind>/<id> یا wss://... با یک مسیر /devtools/browser|page|worker|shared_worker|service_worker/<id>. OpenClaw مستقیماً از طریق handshake مربوط به WebSocket متصل می‌شود و /json/version را کاملاً رد می‌کند.
• ریشه‌های WebSocket خام - ws://host[:port] یا wss://host[:port] بدون مسیر /devtools/... (مثلاً Browserless، Browserbase). OpenClaw ابتدا کشف HTTP /json/version را امتحان می‌کند (با normalise کردن scheme به http/https)؛ اگر کشف مقدار webSocketDebuggerUrl برگرداند، از آن استفاده می‌شود، در غیر این صورت OpenClaw به handshake مستقیم WebSocket در ریشهٔ خام fallback می‌کند. اگر endpoint تبلیغ‌شدهٔ WebSocket handshake مربوط به CDP را رد کند اما ریشهٔ خام پیکربندی‌شده آن را بپذیرد، OpenClaw به همان ریشه نیز fallback می‌کند. این کار اجازه می‌دهد یک ws:// خام که به Chrome محلی اشاره می‌کند همچنان متصل شود، چون Chrome فقط upgradeهای WebSocket را روی مسیر خاص هر target از /json/version می‌پذیرد، در حالی که ارائه‌دهندگان میزبانی‌شده همچنان می‌توانند وقتی endpoint کشف آن‌ها URL کوتاه‌عمری تبلیغ می‌کند که برای Playwright CDP مناسب نیست، از endpoint ریشهٔ WebSocket خود استفاده کنند.

Browserbase

Browserbase یک پلتفرم ابری برای اجرای مرورگرهای headless با حل داخلی CAPTCHA، حالت stealth، و proxyهای residential است.

{  browser: {    enabled: true,    defaultProfile: "browserbase",    remoteCdpTimeoutMs: 3000,    remoteCdpHandshakeTimeoutMs: 5000,    profiles: {      browserbase: {        cdpUrl: "wss://connect.browserbase.com?apiKey=<BROWSERBASE_API_KEY>",        color: "#F97316",      },    },  },}

نکته‌ها:

• ثبت‌نام کنید و API Key خود را از داشبورد Overview کپی کنید.
• <BROWSERBASE_API_KEY> را با کلید API واقعی Browserbase خود جایگزین کنید.
• Browserbase هنگام اتصال WebSocket به‌طور خودکار یک نشست مرورگر ایجاد می‌کند، بنابراین مرحلهٔ دستی ایجاد نشست لازم نیست.
• tier رایگان اجازهٔ یک نشست همزمان و یک ساعت مرورگر در ماه را می‌دهد. برای محدودیت‌های طرح‌های پولی، pricing را ببینید.
• برای مرجع کامل API، راهنماهای SDK، و نمونه‌های یکپارچه‌سازی، مستندات Browserbase را ببینید.

امنیت

ایده‌های کلیدی:

• کنترل مرورگر فقط loopback است؛ جریان‌های دسترسی از طریق احراز هویت Gateway یا جفت‌سازی Node انجام می‌شوند.
• API HTTP مرورگر loopback مستقل فقط از احراز هویت با راز مشترک استفاده می‌کند: احراز هویت bearer با توکن gateway، x-openclaw-password، یا احراز هویت HTTP Basic با گذرواژه gateway پیکربندی‌شده.
• سرآیندهای هویت Tailscale Serve و gateway.auth.mode: "trusted-proxy" این API مرورگر loopback مستقل را احراز هویت نمی‌کنند.
• اگر کنترل مرورگر فعال باشد و هیچ احراز هویت با راز مشترکی پیکربندی نشده باشد، OpenClaw برای همان آغازبه‌کار یک توکن Gateway فقط زمان اجرا تولید می‌کند. اگر کلاینت‌ها به یک راز پایدار در میان راه‌اندازی‌های مجدد نیاز دارند، gateway.auth.token، gateway.auth.password، OPENCLAW_GATEWAY_TOKEN، یا OPENCLAW_GATEWAY_PASSWORD را به‌صراحت پیکربندی کنید.
• وقتی gateway.auth.mode از قبل password، none، یا trusted-proxy باشد، OpenClaw آن توکن را به‌صورت خودکار تولید نمی‌کند.
• Gateway و هر میزبان Node را روی یک شبکه خصوصی (Tailscale) نگه دارید؛ از در معرض عموم قرار دادن آن‌ها پرهیز کنید.
• با URLها/توکن‌های CDP راه دور مانند رازها رفتار کنید؛ env varها یا یک مدیر رازها را ترجیح دهید.

نکات CDP راه دور:

• در صورت امکان، endpointهای رمزنگاری‌شده (HTTPS یا WSS) و توکن‌های کوتاه‌عمر را ترجیح دهید.
• از قراردادن مستقیم توکن‌های بلندعمر در فایل‌های پیکربندی خودداری کنید.

پروفایل‌ها (چندمرورگری)

OpenClaw از چندین پروفایل نام‌دار (پیکربندی‌های مسیریابی) پشتیبانی می‌کند. پروفایل‌ها می‌توانند این‌ها باشند:

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

پیش‌فرض‌ها:

• اگر پروفایل openclaw وجود نداشته باشد، به‌صورت خودکار ساخته می‌شود.
• پروفایل user برای اتصال نشست موجود Chrome MCP به‌صورت داخلی وجود دارد.
• پروفایل‌های نشست موجود، فراتر از user، اختیاری هستند؛ آن‌ها را با --driver existing-session بسازید.
• پورت‌های CDP محلی به‌صورت پیش‌فرض از 18800-18899 تخصیص داده می‌شوند.
• حذف یک پروفایل، دایرکتوری داده محلی آن را به Trash منتقل می‌کند.

همه endpointهای کنترل ?profile=<name> را می‌پذیرند؛ CLI از --browser-profile استفاده می‌کند.

نشست موجود از طریق Chrome DevTools MCP

OpenClaw همچنین می‌تواند از طریق سرور رسمی Chrome DevTools MCP به یک پروفایل مرورگر مبتنی بر Chromium در حال اجرا متصل شود. این کار از تب‌ها و وضعیت ورود از قبل باز در آن پروفایل مرورگر دوباره استفاده می‌کند.

منابع رسمی پیش‌زمینه و راه‌اندازی:

• Chrome for Developers: استفاده از Chrome DevTools MCP با نشست مرورگر شما
• README مربوط به Chrome DevTools MCP

پروفایل داخلی:

• user

اختیاری: اگر نام، رنگ، یا دایرکتوری داده مرورگر متفاوتی می‌خواهید، پروفایل نشست موجود سفارشی خودتان را بسازید.

رفتار پیش‌فرض:

• پروفایل داخلی user از اتصال خودکار Chrome MCP استفاده می‌کند که پروفایل پیش‌فرض محلی Google Chrome را هدف می‌گیرد.

برای Brave، Edge، Chromium، یا یک پروفایل غیرپیش‌فرض Chrome از userDataDir استفاده کنید. ~ به دایرکتوری خانه سیستم‌عامل شما گسترش می‌یابد:

{  browser: {    profiles: {      brave: {        driver: "existing-session",        attachOnly: true,        userDataDir: "~/Library/Application Support/BraveSoftware/Brave-Browser",        color: "#FB542B",      },    },  },}

سپس در مرورگر متناظر:

1. صفحه inspect آن مرورگر را برای اشکال‌زدایی راه دور باز کنید.
2. اشکال‌زدایی راه دور را فعال کنید.
3. مرورگر را در حال اجرا نگه دارید و وقتی OpenClaw متصل می‌شود، prompt اتصال را تأیید کنید.

صفحه‌های inspect رایج:

• Chrome: chrome://inspect/#remote-debugging
• Brave: brave://inspect/#remote-debugging
• Edge: edge://inspect/#remote-debugging

آزمون smoke اتصال زنده:

openclaw browser --browser-profile user startopenclaw browser --browser-profile user statusopenclaw browser --browser-profile user tabsopenclaw browser --browser-profile user snapshot --format ai

موفقیت چه شکلی است:

• status مقدار driver: existing-session را نشان می‌دهد
• status مقدار transport: chrome-mcp را نشان می‌دهد
• status مقدار running: true را نشان می‌دهد
• tabs تب‌های مرورگر از قبل باز شما را فهرست می‌کند
• snapshot از تب زنده انتخاب‌شده ref برمی‌گرداند

اگر اتصال کار نکرد چه چیزهایی را بررسی کنید:

• مرورگر هدفِ مبتنی بر Chromium نسخه 144+ است
• اشکال‌زدایی راه دور در صفحه inspect آن مرورگر فعال است
• مرورگر prompt رضایت اتصال را نشان داده و شما آن را پذیرفته‌اید
• openclaw doctor پیکربندی قدیمی مرورگر مبتنی بر extension را migrate می‌کند و بررسی می‌کند که Chrome برای پروفایل‌های پیش‌فرض اتصال خودکار به‌صورت محلی نصب شده باشد، اما نمی‌تواند اشکال‌زدایی راه دور سمت مرورگر را برای شما فعال کند

استفاده عامل:

• وقتی به وضعیت مرورگر واردشده کاربر نیاز دارید، از profile="user" استفاده کنید.
• اگر از یک پروفایل نشست موجود سفارشی استفاده می‌کنید، همان نام پروفایل صریح را ارسال کنید.
• این حالت را فقط وقتی انتخاب کنید که کاربر پشت رایانه باشد تا prompt اتصال را تأیید کند.
• Gateway یا میزبان Node می‌تواند npx chrome-devtools-mcp@latest --autoConnect را spawn کند

یادداشت‌ها:

• این مسیر از پروفایل ایزوله openclaw پرریسک‌تر است، چون می‌تواند داخل نشست مرورگر واردشده شما عمل کند.
• OpenClaw مرورگر را برای این driver اجرا نمی‌کند؛ فقط متصل می‌شود.
• OpenClaw در اینجا از جریان رسمی --autoConnect مربوط به Chrome DevTools MCP استفاده می‌کند. اگر userDataDir تنظیم شده باشد، برای هدف‌گیری آن دایرکتوری داده کاربر عبور داده می‌شود.
• نشست موجود می‌تواند روی میزبان انتخاب‌شده یا از طریق یک Node مرورگر متصل، attach شود. اگر Chrome جای دیگری است و هیچ Node مرورگری متصل نیست، در عوض از CDP راه دور یا میزبان Node استفاده کنید.

اجرای سفارشی Chrome MCP

وقتی جریان پیش‌فرض npx chrome-devtools-mcp@latest چیزی نیست که می‌خواهید (میزبان‌های آفلاین، نسخه‌های pinشده، باینری‌های vendored)، سرور Chrome DevTools MCP ایجادشده را برای هر پروفایل override کنید:

وقتی cdpUrl روی یک پروفایل نشست موجود تنظیم شده باشد، OpenClaw --autoConnect را رد می‌کند و endpoint را به‌صورت خودکار به Chrome MCP forward می‌کند:

• http(s)://... → --browserUrl <url> (endpoint کشف HTTP مربوط به DevTools).
• ws(s)://... → --wsEndpoint <url> (WebSocket مستقیم CDP).

پرچم‌های endpoint و userDataDir را نمی‌توان با هم ترکیب کرد: وقتی cdpUrl تنظیم شده باشد، userDataDir برای اجرای Chrome MCP نادیده گرفته می‌شود، چون Chrome MCP به مرورگر در حال اجرای پشت endpoint attach می‌شود، نه اینکه یک دایرکتوری پروفایل را باز کند.

تضمین‌های ایزولاسیون

• دایرکتوری داده کاربر اختصاصی: هرگز به پروفایل مرورگر شخصی شما دست نمی‌زند.
• پورت‌های اختصاصی: از 9222 دوری می‌کند تا از برخورد با گردش‌کارهای توسعه جلوگیری شود.
• کنترل قطعی تب: tabs ابتدا suggestedTargetId را برمی‌گرداند، سپس handleهای پایدار tabId مانند t1، labelهای اختیاری، و targetId خام را. عامل‌ها باید از suggestedTargetId دوباره استفاده کنند؛ idهای خام برای اشکال‌زدایی و سازگاری در دسترس می‌مانند.

انتخاب مرورگر

هنگام اجرای محلی، OpenClaw اولین گزینه در دسترس را انتخاب می‌کند:

1. Chrome
2. Brave
3. Edge
4. Chromium
5. Chrome Canary

می‌توانید با browser.executablePath آن را override کنید.

پلتفرم‌ها:

• macOS: /Applications و ~/Applications را بررسی می‌کند.
• Linux: مکان‌های رایج Chrome/Brave/Edge/Chromium زیر /usr/bin، /snap/bin، /opt/google، /opt/brave.com، /usr/lib/chromium، و /usr/lib/chromium-browser، به‌علاوه Chromium مدیریت‌شده توسط Playwright زیر PLAYWRIGHT_BROWSERS_PATH یا ~/.cache/ms-playwright را بررسی می‌کند.
• Windows: مکان‌های نصب رایج را بررسی می‌کند.

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

برای اسکریپت‌نویسی و اشکال‌زدایی، Gateway یک API کنترل HTTP فقط loopback کوچک به‌همراه CLI متناظر openclaw browser ارائه می‌کند (snapshotها، refها، تقویت‌کننده‌های wait، خروجی JSON، گردش‌کارهای اشکال‌زدایی). برای مرجع کامل، API کنترل مرورگر را ببینید.

عیب‌یابی

برای مشکلات خاص Linux (به‌ویژه snap Chromium)، عیب‌یابی مرورگر را ببینید.

برای راه‌اندازی‌های split-host با WSL2 Gateway + Windows Chrome، عیب‌یابی WSL2 + Windows + CDP راه دور Chrome را ببینید.

شکست آغازبه‌کار CDP در برابر مسدودسازی SSRF ناوبری

این‌ها کلاس‌های شکست متفاوتی هستند و به مسیرهای کد متفاوتی اشاره می‌کنند.

• شکست آغازبه‌کار یا readiness مربوط به CDP یعنی OpenClaw نمی‌تواند تأیید کند که control plane مرورگر سالم است.
• مسدودسازی SSRF ناوبری یعنی control plane مرورگر سالم است، اما هدف ناوبری صفحه توسط policy رد شده است.

نمونه‌های رایج:

• شکست آغازبه‌کار یا readiness مربوط به CDP:
  • Chrome CDP websocket for profile "openclaw" is not reachable after start
  • Remote CDP for profile "<name>" is not reachable at <cdpUrl>
  • Port <port> is in use for profile "<name>" but not by openclaw وقتی یک سرویس CDP خارجی loopback بدون attachOnly: true پیکربندی شده باشد
• مسدودسازی SSRF ناوبری:
  • جریان‌های open، navigate، snapshot، یا بازکردن تب با خطای policy مرورگر/شبکه شکست می‌خورند، در حالی که start و tabs همچنان کار می‌کنند

برای جداکردن این دو، از این توالی حداقلی استفاده کنید:

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

نتایج را چگونه بخوانید:

• اگر start با not reachable after start شکست خورد، ابتدا readiness مربوط به CDP را عیب‌یابی کنید.
• اگر start موفق شد اما tabs شکست خورد، control plane همچنان ناسالم است. با این مورد به‌عنوان مشکل دسترسی‌پذیری CDP رفتار کنید، نه مشکل ناوبری صفحه.
• اگر start و tabs موفق شدند اما open یا navigate شکست خورد، control plane مرورگر بالا است و شکست در policy ناوبری یا صفحه هدف است.
• اگر start، tabs، و open همگی موفق شدند، مسیر پایه کنترل مرورگر مدیریت‌شده سالم است.

جزئیات مهم رفتار:

• پیکربندی مرورگر حتی وقتی browser.ssrfPolicy را پیکربندی نمی‌کنید، به‌صورت پیش‌فرض یک شیء policy SSRF fail-closed دارد.
• برای پروفایل مدیریت‌شده openclaw با local loopback، بررسی‌های سلامت CDP عمداً اعمال دسترسی‌پذیری SSRF مرورگر را برای control plane محلی خود OpenClaw رد می‌کنند.
• حفاظت ناوبری جداست. نتیجه موفق start یا tabs به این معنی نیست که هدف بعدی open یا navigate مجاز است.

راهنمایی امنیتی:

• به‌صورت پیش‌فرض، سیاست SSRF مرورگر را آسان‌گیر نکنید.
• استثناهای محدود برای میزبان مانند hostnameAllowlist یا allowedHostnames را به دسترسی گسترده به شبکه خصوصی ترجیح دهید.
• از dangerouslyAllowPrivateNetwork: true فقط در محیط‌های عمداً مورد اعتماد استفاده کنید که در آن‌ها دسترسی مرورگر به شبکه خصوصی لازم و بازبینی شده است.

ابزارهای عامل + نحوه کار کنترل

عامل برای خودکارسازی مرورگر یک ابزار دریافت می‌کند:

• browser - doctor/status/start/stop/tabs/open/focus/close/snapshot/screenshot/navigate/act

نگاشت آن به این شکل است:

• browser snapshot یک درخت UI پایدار (AI یا ARIA) برمی‌گرداند.
• browser act از شناسه‌های ref در snapshot برای کلیک/تایپ/کشیدن/انتخاب استفاده می‌کند.
• browser screenshot پیکسل‌ها را ثبت می‌کند (کل صفحه، عنصر، یا refهای برچسب‌خورده).
• browser doctor آمادگی Gateway، Plugin، پروفایل، مرورگر، و تب را بررسی می‌کند.
• browser این موارد را می‌پذیرد:
  • profile برای انتخاب یک پروفایل مرورگر نام‌گذاری‌شده (openclaw، chrome، یا CDP راه‌دور).
  • target (sandbox | host | node) برای انتخاب محل اجرای مرورگر.
  • در نشست‌های sandbox شده، target: "host" به agents.defaults.sandbox.browser.allowHostControl=true نیاز دارد.
  • اگر target حذف شود: نشست‌های sandbox شده به‌صورت پیش‌فرض از sandbox استفاده می‌کنند، و نشست‌های غیر sandbox به‌صورت پیش‌فرض از host.
  • اگر یک node با قابلیت مرورگر متصل باشد، ابزار ممکن است به‌صورت خودکار به آن مسیریابی کند، مگر اینکه target="host" یا target="node" را ثابت کنید.

این کار عامل را قطعی نگه می‌دارد و از selectorهای شکننده جلوگیری می‌کند.

مرتبط

• نمای کلی ابزارها - همه ابزارهای موجود عامل
• Sandboxing - کنترل مرورگر در محیط‌های sandbox شده
• امنیت - خطرات کنترل مرورگر و سخت‌سازی