---
read_when:
    - افزودن خودکارسازی مرورگر تحت کنترل عامل
    - اشکال‌زدایی علت تداخل openclaw با Chrome شخصی شما
    - پیاده‌سازی تنظیمات مرورگر و چرخهٔ حیات در برنامهٔ macOS
summary: سرویس یکپارچه کنترل مرورگر + فرمان‌های عملیاتی
title: مرورگر (مدیریت‌شده توسط OpenClaw)
x-i18n:
    generated_at: "2026-07-16T17:27:42Z"
    model: gpt-5.6
    postprocess_version: locale-links-v1
    prompt_version: 32
    provider: openai
    source_hash: cf43bd54994d29d48cfc1e16889ec34af83e885c1dd1b63c287f0df116c7f0bf
    source_path: tools/browser.md
    workflow: 16
---

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

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

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

- یک پروفایل مرورگر جداگانه با نام **openclaw** (به‌طور پیش‌فرض با رنگ تأکیدی نارنجی).
- کنترل قطعی زبانه‌ها (فهرست‌کردن/بازکردن/تمرکز/بستن).
- کنش‌های عامل (کلیک/تایپ/کشیدن/انتخاب)، عکس‌های فوری، اسکرین‌شات‌ها و PDFها.
- پروفایل‌های مبتنی بر Playwright پیمایش مستقیم به پیوست‌ها را در پوشه دانلودهای مدیریت‌شده ذخیره می‌کنند و پس از اعتبارسنجی خط‌مشی URL نهایی، فراداده `{ url, suggestedFilename, path }` را برمی‌گردانند.
- کنش‌های عامل مبتنی بر Playwright، هنگامی که کنش بلافاصله یک یا چند دانلود را آغاز کند، آرایه‌ای از `downloads` را با همان فراداده مدیریت‌شده برمی‌گردانند.
- یک Skill همراه `browser-automation` که هنگام فعال‌بودن Plugin مرورگر، چرخه بازیابی عکس فوری،
  زبانه پایدار، ارجاع منقضی و مانع نیازمند اقدام دستی را به عامل‌ها
  آموزش می‌دهد.
- پشتیبانی اختیاری از چند پروفایل (`openclaw`، `work`، `remote` و ...).

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

در macOS می‌توانید به‌صراحت کوکی‌ها را از یک پروفایل سیستمی خانواده Chrome به یک پروفایل مدیریت‌شده جداگانه کپی کنید. مرورگر مدیریت‌شده همچنان از پوشه داده کاربری خودش استفاده می‌کند؛ فقط کوکی‌های انتخاب‌شده کپی می‌شوند و فضای ذخیره‌سازی محلی و IndexedDB منتقل نمی‌شوند. برای فرمان‌های درون‌ریزی و محدودیت‌ها، [پروفایل‌ها](#profiles-multi-browser) یا [مرجع CLI ‏`openclaw browser`](/fa/cli/browser) را ببینید.

## شروع سریع

```bash
openclaw browser --browser-profile openclaw doctor
openclaw browser --browser-profile openclaw doctor --deep
openclaw browser --browser-profile openclaw status
openclaw browser --browser-profile openclaw start
openclaw browser --browser-profile openclaw open https://example.com
openclaw browser --browser-profile openclaw snapshot
```

«مرورگر غیرفعال است» یعنی Plugin یا `browser.enabled` خاموش است؛
[پیکربندی](#configuration) و [کنترل Plugin](#plugin-control) را ببینید.

اگر `openclaw browser` به‌طور کامل وجود ندارد یا عامل اعلام می‌کند که ابزار مرورگر
در دسترس نیست، مستقیماً به [نبودن فرمان یا ابزار مرورگر](#missing-browser-command-or-tool) بروید.

## کنترل Plugin

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

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

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

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

## راهنمای عامل

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

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

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

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

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

هنگامی که Plugin فعال است، Skillهای همراه آن در فهرست Skillهای دردسترس عامل
نمایش داده می‌شوند. دستورالعمل‌های کامل Skill هنگام نیاز بارگذاری می‌شوند؛ بنابراین نوبت‌های
عادی هزینه کامل توکن را متحمل نمی‌شوند.

## نبودن فرمان یا ابزار مرورگر

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

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

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

## پروفایل‌ها: `openclaw`، `user`، `chrome`

- `openclaw`: مرورگر مدیریت‌شده و جداشده (بدون نیاز به افزونه).
- `user`: پروفایل اتصال داخلی Chrome DevTools MCP برای نشست **واقعی
  و واردشده Chrome** شما. نخستین بار که OpenClaw متصل می‌شود، Chrome پیام مسدودکننده «Allow remote debugging?»
  را نمایش می‌دهد؛ بنابراین باید شخصی پشت رایانه حضور داشته باشد.
- `chrome`: پروفایل داخلی [افزونه Chrome](/fa/tools/chrome-extension) برای
  نشست **واقعی و واردشده Chrome** شما. حتی وقتی کسی پشت میز نیست، از طریق تلفن کار می‌کند،
  زیرا به‌جای درگاه اشکال‌زدایی از راه دور، زبانه‌ها را از طریق افزونه مرورگر OpenClaw کنترل می‌کند؛
  بنابراین پیام «Allow remote debugging?» نمایش داده نمی‌شود.

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

- پیش‌فرض: از مرورگر جداشده `openclaw` استفاده کنید.
- هنگامی که نشست‌های واردشده موجود اهمیت دارند و کاربر **از رایانه دور است**
  (Telegram،‏ WhatsApp و غیره)، `profile="chrome"` (افزونه) را ترجیح دهید.
- هنگامی که نشست‌های واردشده موجود اهمیت دارند و کاربر **پشت رایانه است**
  تا پیام اتصال را تأیید کند، `profile="user"` (Chrome MCP) را ترجیح دهید.
- هنگامی که حالت مرورگر مشخصی می‌خواهید، `profile` بازنویسی صریح است.

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

## پیکربندی

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

```json5
{
  browser: {
    enabled: true, // پیش‌فرض: true
    evaluateEnabled: true, // پیش‌فرض: true؛ false،‏ act:evaluate (JS دلخواه) را غیرفعال می‌کند
    ssrfPolicy: {
      // dangerouslyAllowPrivateNetwork: true, // فقط برای دسترسی قابل‌اعتماد به شبکه خصوصی، داوطلبانه فعال کنید
      // hostnameAllowlist: ["*.example.com", "example.com"],
      // allowedHostnames: ["localhost"],
    },
    // cdpUrl: "http://127.0.0.1:18792", // بازنویسی قدیمی تک‌پروفایلی
    remoteCdpTimeoutMs: 1500, // مهلت زمانی HTTP برای CDP راه دور (میلی‌ثانیه)
    remoteCdpHandshakeTimeoutMs: 3000, // مهلت زمانی دست‌دهی WebSocket برای CDP راه دور (میلی‌ثانیه)
    localLaunchTimeoutMs: 15000, // مهلت زمانی کشف Chrome مدیریت‌شده محلی (میلی‌ثانیه)
    localCdpReadyTimeoutMs: 8000, // مهلت زمانی آماده‌شدن CDP محلی پس از اجرا (میلی‌ثانیه)
    actionTimeoutMs: 60000, // مهلت زمانی پیش‌فرض کنش مرورگر (میلی‌ثانیه)
    tabCleanup: {
      enabled: true, // پیش‌فرض: true
      idleMinutes: 120, // برای غیرفعال‌کردن پاک‌سازی زبانه‌های بیکار، روی 0 تنظیم کنید
      maxTabsPerSession: 8, // برای غیرفعال‌کردن سقف هر نشست، روی 0 تنظیم کنید
      sweepMinutes: 5,
    },
    // snapshotDefaults: { mode: "efficient" }, // حالت پیش‌فرض عکس فوری هنگامی که فراخواننده حالتی را مشخص نمی‌کند
    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" },
    },
  },
}
```

هنگامی که فراخواننده `snapshotFormat` یا
`mode` صریحی ارسال نمی‌کند، `browser.snapshotDefaults.mode: "efficient"` حالت پیش‌فرض استخراج `snapshot`
را تغییر می‌دهد؛ برای گزینه‌های عکس فوری در هر فراخوانی، [API کنترل مرورگر](/fa/tools/browser-control) را ببینید.

### بینایی اسکرین‌شات (پشتیبانی از مدل‌های فقط‌متنی)

هنگامی که مدل اصلی فقط‌متنی است (بدون پشتیبانی بینایی/چندوجهی)، اسکرین‌شات‌های
مرورگر بلوک‌های تصویری را برمی‌گردانند که مدل نمی‌تواند آن‌ها را بخواند. اسکرین‌شات‌های مرورگر
از پیکربندی موجود درک تصویر استفاده می‌کنند؛ بنابراین یک مدل تصویری
پیکربندی‌شده برای درک رسانه می‌تواند بدون هیچ تنظیم مدل مختص مرورگر،
اسکرین‌شات‌ها را به‌صورت متن توصیف کند.

```json5
{
  tools: {
    media: {
      image: {
        models: [
          { provider: "bytedance", model: "doubao-seed-2.0-pro" },
          // گزینه‌های جایگزین را اضافه کنید؛ نخستین موفقیت برنده است
          { provider: "openai", model: "gpt-4o" },
        ],
      },
      // مدل‌های رسانه مشترک نیز در صورت برچسب‌گذاری برای پشتیبانی از تصویر کار می‌کنند.
      // models: [{ provider: "openai", model: "gpt-4o", capabilities: ["image"] }],
    },
  },
  agents: {
    defaults: {
      // پیش‌فرض‌های موجود مدل تصویر نیز رعایت می‌شوند.
      // imageModel: { primary: "openai/gpt-4o" },
    },
  },
}
```

**نحوه کار:**

1. عامل `browser screenshot` را فراخوانی می‌کند و تصویر طبق معمول روی دیسک ذخیره می‌شود.
2. ابزار مرورگر از زمان‌اجرای موجود درک تصویر می‌پرسد آیا می‌تواند
   با استفاده از مدل‌های تصویری رسانه پیکربندی‌شده، مدل‌های رسانه مشترک،
   پیش‌فرض‌های مدل تصویر یا یک ارائه‌دهنده تصویر مبتنی بر احراز هویت، اسکرین‌شات را توصیف کند.
3. مدل بینایی یک توصیف متنی برمی‌گرداند که با
   `wrapExternalContent` (محافظ تزریق اعلان) بسته‌بندی می‌شود و به‌جای بلوک تصویر،
   به‌صورت بلوک متن به عامل بازگردانده می‌شود.
4. اگر درک تصویر دردسترس نباشد، نادیده گرفته شود یا شکست بخورد، مرورگر
   به بازگرداندن بلوک تصویر اصلی برمی‌گردد.

بلوک‌های تصویر اسکرین‌شات نتایج خصوصی ابزار هستند: عامل می‌تواند آن‌ها را بررسی کند،
اما OpenClaw آن‌ها را به‌طور خودکار به پاسخ‌های کانال پیوست نمی‌کند. برای اشتراک‌گذاری
اسکرین‌شات، از عامل بخواهید آن را صریحاً با ابزار پیام ارسال کند.

برای گزینه‌های جایگزین مدل، مهلت‌های زمانی، محدودیت‌های بایت، پروفایل‌ها و تنظیمات
درخواست ارائه‌دهنده، از فیلدهای موجود `tools.media.image` / `tools.media.models` استفاده کنید.

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

<AccordionGroup>

<Accordion title="درگاه‌ها و دسترسی‌پذیری">

- سرویس کنترل روی loopback و پورتی مشتق‌شده از `gateway.port` متصل می‌شود (پیش‌فرض `18791` = gateway + 2). `OPENCLAW_GATEWAY_PORT` بر `gateway.port` اولویت دارد؛ هرکدام پورت‌های مشتق‌شده در همان خانواده را جابه‌جا می‌کند.
- پروفایل‌های محلی `openclaw`، `cdpPort`/`cdpUrl` را به‌طور خودکار از بازه‌ای که 9 پورت بالاتر از پورت کنترل آغاز می‌شود تخصیص می‌دهند (پیش‌فرض `18800`-`18899`)؛ این موارد را فقط برای
  پروفایل‌های CDP راه‌دور یا اتصال به endpoint نشست موجود تنظیم کنید. اگر `cdpUrl` تنظیم نشده باشد، مقدار پیش‌فرض آن
  پورت CDP محلی مدیریت‌شده است.
- `remoteCdpTimeoutMs` برای بررسی‌های دسترسی‌پذیری HTTP مربوط به CDP راه‌دور و `attachOnly`
  و درخواست‌های HTTP بازکردن زبانه اعمال می‌شود؛ `remoteCdpHandshakeTimeoutMs` برای
  دست‌دهی‌های WebSocket مربوط به CDP آن‌ها اعمال می‌شود. شمارش ماندگار زبانه‌های Playwright راه‌دور،
  مقدار بزرگ‌تر این دو را به‌عنوان مهلت عملیات خود استفاده می‌کند.
- `localLaunchTimeoutMs` مهلتی است که یک فرایند Chrome مدیریت‌شده و اجراشده به‌صورت محلی
  برای در دسترس قراردادن endpoint مربوط به HTTP در CDP دارد. `localCdpReadyTimeoutMs`
  مهلت بعدی برای آماده‌شدن websocket مربوط به CDP پس از شناسایی فرایند است.
  در Raspberry Pi، VPS ضعیف یا سخت‌افزار قدیمی که Chromium
  روی آن آهسته راه‌اندازی می‌شود، این مقادیر را افزایش دهید. مقادیر باید اعداد صحیح مثبت تا `120000` ms باشند؛
  مقادیر نامعتبر پیکربندی رد می‌شوند.
- خرابی‌های مکرر در اجرا یا آماده‌شدن Chrome مدیریت‌شده، به‌ازای هر
  پروفایل با قطع‌کننده مدار مهار می‌شوند. پس از چند خرابی پیاپی، OpenClaw به‌جای ایجاد Chromium
  در هر فراخوانی ابزار مرورگر، تلاش‌های جدید برای اجرا را برای مدت کوتاهی متوقف می‌کند. مشکل
  راه‌اندازی را برطرف کنید، اگر مرورگر لازم نیست آن را غیرفعال کنید، یا پس از تعمیر
  Gateway را دوباره راه‌اندازی کنید.
- `actionTimeoutMs` مهلت پیش‌فرض درخواست‌های `act` مرورگر است، زمانی که فراخواننده `timeoutMs` را ارسال نمی‌کند. انتقال کلاینت یک بازه ارفاقی کوچک اضافه می‌کند تا انتظارهای طولانی به‌جای پایان‌یافتن مهلت در مرز HTTP، کامل شوند.
- `tabCleanup` پاک‌سازی با حداکثر تلاش برای زبانه‌هایی است که نشست‌های مرورگر عامل اصلی باز کرده‌اند. پاک‌سازی چرخه حیات عامل فرعی، cron و ACP همچنان زبانه‌های صریحاً ردیابی‌شده آن‌ها را در پایان نشست می‌بندد؛ نشست‌های اصلی زبانه‌های فعال را برای استفاده مجدد نگه می‌دارند، سپس زبانه‌های ردیابی‌شده بیکار یا اضافی را در پس‌زمینه می‌بندند.

</Accordion>

<Accordion title="سیاست SSRF">

- درخواست‌های پیمایش مرورگر و بازکردن زبانه پیشاپیش بررسی می‌شوند. هنگام انجام کنش و در بازه ارفاقی محدود پس از آن، تعاملات محافظت‌شده Playwright (کلیک، کلیک مختصاتی، نگه‌داشتن نشانگر، کشیدن، پیمایش، انتخاب، فشردن، تایپ، پرکردن فرم و ارزیابی) بارگذاری اسناد سطح‌بالا و زیرفریم را که سیاست رد کرده است، پیش از ارسال بایت‌های درخواست HTTP رهگیری می‌کنند و سپس با حداکثر تلاش URL نهایی `http(s)` را دوباره بررسی می‌کنند.
- پیش از هر اجرای تازه Chrome تحت مدیریت OpenClaw، این سامانه با حداکثر تلاش پیش‌بینی شبکه را غیرفعال می‌کند و preconnect گمانه‌زنانه مشاهده‌شده Chromium برای آن بارگذاری‌های ردشده را متوقف می‌سازد. این دفاع در عمق است، نه مرز سیاست: مرورگری که پس از راه‌اندازی مجدد سرویس کنترل دوباره استفاده می‌شود و دیگر backendهای مرورگر ممکن است این سخت‌سازی را نداشته باشند. مسیریابی Playwright همچنان دیوار آتش شبکه نیست و پرش‌های تغییرمسیر، نخستین درخواست یک پنجره بازشو، ترافیک Service Worker، کد صفحه‌ای که پس از بازه محافظتی محدود اجرا می‌شود یا همه مسیرهای پس‌زمینه/زیرمنبع را رهگیری نمی‌کند. جداسازی کامل خروجی شبکه به جداسازی در سمت مالک یا پراکسی اعمال‌کننده سیاست نیاز دارد.
- در حالت سخت‌گیرانه SSRF، شناسایی endpoint مربوط به CDP راه‌دور و بررسی‌های `/json/version` (`cdpUrl`) نیز کنترل می‌شوند.
- متغیرهای محیطی `HTTP_PROXY`، `HTTPS_PROXY`، `ALL_PROXY` و `NO_PROXY` مربوط به Gateway/ارائه‌دهنده، مرورگر مدیریت‌شده OpenClaw را به‌طور خودکار از پراکسی عبور نمی‌دهند. Chrome مدیریت‌شده به‌طور پیش‌فرض مستقیماً اجرا می‌شود تا تنظیمات پراکسی ارائه‌دهنده بررسی‌های SSRF مرورگر را تضعیف نکنند.
- بررسی‌های آمادگی CDP محلی مدیریت‌شده OpenClaw و اتصال‌های DevTools WebSocket، برای endpoint دقیق loopback که اجرا شده است پراکسی شبکه مدیریت‌شده را دور می‌زنند؛ بنابراین وقتی پراکسی اپراتور خروجی loopback را مسدود می‌کند نیز `openclaw browser start` کار می‌کند.
- برای عبوردادن خود مرورگر مدیریت‌شده از پراکسی، فلگ‌های صریح پراکسی Chrome را از طریق `browser.extraArgs` ارسال کنید؛ مانند `--proxy-server=...` یا `--proxy-pac-url=...`. حالت سخت‌گیرانه SSRF، مسیریابی صریح پراکسی مرورگر را مسدود می‌کند، مگر اینکه دسترسی مرورگر به شبکه خصوصی عمداً فعال شده باشد.
- `browser.ssrfPolicy.dangerouslyAllowPrivateNetwork` به‌طور پیش‌فرض خاموش است؛ فقط زمانی آن را فعال کنید که دسترسی مرورگر به شبکه خصوصی عمداً مورد اعتماد است.
- `browser.ssrfPolicy.allowPrivateNetwork` همچنان به‌عنوان نام مستعار قدیمی پشتیبانی می‌شود.

</Accordion>

<Accordion title="رفتار پروفایل">

- `attachOnly: true` یعنی هرگز مرورگر محلی را اجرا نکن؛ فقط اگر مرورگری از قبل در حال اجراست به آن متصل شو.
- `headless` را می‌توان سراسری یا برای هر پروفایل محلی مدیریت‌شده تنظیم کرد. مقادیر هر پروفایل بر `browser.headless` تقدم دارند؛ بنابراین یک پروفایل اجراشده به‌صورت محلی می‌تواند headless بماند و پروفایل دیگر قابل‌مشاهده باشد.
- `POST /start?headless=true` و `openclaw browser start --headless` برای پروفایل‌های محلی مدیریت‌شده،
  بدون بازنویسی `browser.headless` یا پیکربندی پروفایل، اجرای یک‌باره headless را
  درخواست می‌کنند. پروفایل‌های نشست موجود، فقط‌اتصال و
  CDP راه‌دور این override را رد می‌کنند، زیرا OpenClaw آن
  فرایندهای مرورگر را اجرا نمی‌کند.
- در میزبان‌های Linux فاقد `DISPLAY` یا `WAYLAND_DISPLAY`، اگر نه محیط و نه پیکربندی
  پروفایل/سراسری به‌صراحت حالت دارای رابط را انتخاب نکرده باشند، پروفایل‌های محلی مدیریت‌شده
  به‌طور خودکار به‌صورت headless اجرا می‌شوند. از فرم صریح سطح مرورگر
  `openclaw browser --json status` استفاده کنید؛ `openclaw browser status --json` انتهایی
  نیز کار می‌کند، زیرا `status`، `--json` مخصوص خود را تعریف نمی‌کند. فرمان، مقدار
  `headlessSource` را به‌صورت `env`، `profile`، `config`،
  `request`، `linux-display-fallback` یا `default` گزارش می‌کند.
- `OPENCLAW_BROWSER_HEADLESS=1` اجرای محلی مدیریت‌شده را برای
  فرایند جاری به‌اجبار headless می‌کند. `OPENCLAW_BROWSER_HEADLESS=0` برای شروع‌های معمولی
  حالت دارای رابط را اجباری می‌کند و در میزبان‌های Linux فاقد سرور نمایش، خطایی با راهکار عملی برمی‌گرداند؛
  درخواست صریح `start --headless` همچنان برای همان اجرای واحد اولویت دارد.
- مسیر کنترل مرورگر و کلاینت برنامه‌نویسی‌شده، `error`
  خوانا برای انسانِ خطای نبود نمایشگر را حفظ می‌کنند و دلیل پایدار
  `no_display_for_headed_profile` را در دسترس قرار می‌دهند. `details` آن فقط شامل `profile`،
  `requestedHeadless`، `headlessSource` و `displayPresent` است تا کلاینت‌های API بتوانند
  بدون تطبیق متن پیام، راهکار اصلاحی درست را انتخاب کنند.
- برای یک پروفایل محلی مدیریت‌شده در حال اجرا، وضعیت و doctor از endpoint سطح مرورگر CDP در Chrome
  درباره renderer، backend، دستگاه/درایور، وضعیت قابلیت،
  راهکارهای موقت درایور و قابلیت‌های ویدیویی شتاب‌یافته پرس‌وجو می‌کنند. نتیجه
  برای همان فرایند مرورگر در cache نگه‌داری می‌شود و به‌طور کامل از طریق
  `openclaw browser --json status` ارائه می‌شود. فراخوانی غیرفعال وضعیت، Chrome را اجرا نمی‌کند.
  مرورگرهای نشست موجود، افزونه، CDP راه‌دور و sandbox جدا باقی می‌مانند
  و از طریق این مسیر میزبان مدیریت‌شده بازرسی نمی‌شوند.
- Chrome مدیریت‌شده headless همچنان از پیش‌فرض محافظه‌کارانه `--disable-gpu` استفاده می‌کند.
  عیب‌یابی، شتاب‌دهی را فعال نمی‌کند، تنظیم سراسری شتاب‌دهی اضافه نمی‌کند
  و دسترسی مرورگر sandbox به دستگاه را اعطا نمی‌کند.
- `executablePath` را می‌توان سراسری یا برای هر پروفایل محلی مدیریت‌شده تنظیم کرد. مقادیر هر پروفایل بر `browser.executablePath` تقدم دارند؛ بنابراین پروفایل‌های مدیریت‌شده مختلف می‌توانند مرورگرهای مبتنی بر Chromium متفاوتی را اجرا کنند. هر دو فرم، `~` را برای پوشه خانگی سیستم‌عامل می‌پذیرند.
- `color` (در سطح بالا و برای هر پروفایل) رابط کاربری مرورگر را رنگی می‌کند تا بتوانید تشخیص دهید کدام پروفایل فعال است.
- پروفایل پیش‌فرض `openclaw` است (مستقل مدیریت‌شده). برای انتخاب مرورگر کاربر واردشده از `defaultProfile: "user"` استفاده کنید.
- ترتیب تشخیص خودکار: مرورگر پیش‌فرض سیستم، اگر مبتنی بر Chromium باشد؛ در غیر این صورت Chrome، Brave، Edge، Chromium، Chrome Canary.
- `driver: "existing-session"` به‌جای CDP خام از Chrome DevTools MCP استفاده می‌کند. می‌تواند از طریق اتصال خودکار Chrome MCP یا، زمانی که از قبل endpoint مربوط به DevTools برای مرورگر در حال اجرا دارید، از طریق `cdpUrl` متصل شود.
- `driver: "extension"`، Chrome واردشده شما را از طریق [افزونه Chrome متعلق به OpenClaw](/fa/tools/chrome-extension) کنترل می‌کند. relay مالک endpoint مربوط به loopback خود است؛ بنابراین این پروفایل‌ها `cdpUrl` را نمی‌پذیرند. این تنها حالت مرورگر واردشده‌ای است که بدون حضور کسی پشت رایانه کار می‌کند.
- زمانی `browser.profiles.<name>.userDataDir` را تنظیم کنید که پروفایل نشست موجود باید به یک پروفایل کاربری غیراستاندارد Chromium (Brave، Edge و غیره) متصل شود. این مسیر همچنین `~` را برای پوشه خانگی سیستم‌عامل می‌پذیرد.

</Accordion>

</AccordionGroup>

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

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

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

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

<Tabs>
  <Tab title="macOS">
```json5
{
  browser: {
    executablePath: "/Applications/Brave Browser.app/Contents/MacOS/Brave Browser",
  },
}
```
  </Tab>
  <Tab title="Windows">
```json5
{
  browser: {
    executablePath: "C:\\Program Files\\BraveSoftware\\Brave-Browser\\Application\\brave.exe",
  },
}
```
  </Tab>
  <Tab title="Linux">
```json5
{
  browser: {
    executablePath: "/usr/bin/brave-browser",
  },
}
```
  </Tab>
</Tabs>

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

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

- **کنترل محلی (پیش‌فرض):** Gateway سرویس کنترل loopback را راه‌اندازی می‌کند و می‌تواند یک مرورگر محلی را اجرا کند.
- **کنترل راه‌دور (میزبان node):** یک میزبان node را روی دستگاهی که مرورگر دارد اجرا کنید؛ Gateway کنش‌های مرورگر را از طریق پراکسی به آن می‌فرستد.
- **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` نشست کنترل فعال را می‌بندد
  و overrideهای شبیه‌سازی Playwright/CDP (viewport،
  طرح رنگ، locale، منطقه زمانی، حالت آفلاین و وضعیت‌های مشابه) را آزاد می‌کند،
  با اینکه هیچ فرایند مرورگری توسط OpenClaw اجرا نشده است

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

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

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

## پراکسی مرورگر Node (پیش‌فرض بدون نیاز به پیکربندی)

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

نکات:

- میزبان Node، سرور محلی کنترل مرورگر خود را از طریق یک **فرمان پروکسی** در دسترس قرار می‌دهد.
- پروفایل‌ها از پیکربندی `browser.profiles` خود Node می‌آیند (همانند حالت محلی).
- فرمان پروکسی، صرف‌نظر از `allowProfiles`، هرگز تغییرات پایدار پروفایل (`create-profile`، `delete-profile`، `reset-profile`) را مجاز نمی‌کند؛ این تغییرات را مستقیماً روی Node انجام دهید.
- `nodeHost.browserProxy.allowProfiles` اختیاری است. برای رفتار قدیمی/پیش‌فرض آن را خالی بگذارید: همه پروفایل‌های پیکربندی‌شده از طریق پروکسی در دسترس باقی می‌مانند.
- اگر `nodeHost.browserProxy.allowProfiles` را تنظیم کنید، OpenClaw آن را مرز حداقل دسترسی در نظر می‌گیرد که نام پروفایل‌هایی را که پروکسی هدف قرار می‌دهد محدود می‌کند.
- اگر آن را نمی‌خواهید، غیرفعالش کنید:
  - روی Node: `nodeHost.browserProxy.enabled=false`
  - روی Gateway: `gateway.nodes.browser.mode="off"` (همچنین `"auto"` را برای انتخاب یک Node مرورگر متصل یا `"manual"` را برای الزام پارامتر صریح Node می‌پذیرد)

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

[Browserless](https://browserless.io) یک سرویس میزبانی‌شده Chromium است که URLهای اتصال
CDP را از طریق HTTPS و WebSocket ارائه می‌کند. OpenClaw می‌تواند از هر دو شکل استفاده کند، اما
برای یک پروفایل مرورگر راه‌دور، ساده‌ترین گزینه URL مستقیم WebSocket
از مستندات اتصال Browserless است.

مثال:

```json5
{
  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 خود جایگزین کنید.
- نقطه پایانی منطقه‌ای متناسب با حساب Browserless خود را انتخاب کنید (مستندات آن‌ها را ببینید).
- اگر Browserless یک URL پایه HTTPS به شما می‌دهد، می‌توانید آن را برای اتصال مستقیم CDP به
  `wss://` تبدیل کنید یا URL HTTPS را نگه دارید و اجازه دهید OpenClaw
  `/json/version` را کشف کند.

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

وقتی Browserless به‌صورت خودمیزبان در Docker اجرا می‌شود و OpenClaw روی میزبان اجرا می‌شود،
Browserless را به‌عنوان یک سرویس CDP با مدیریت خارجی در نظر بگیرید:

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

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

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

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

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

- **کشف HTTP(S)** - `http://host[:port]` یا `https://host[:port]`.
  OpenClaw برای کشف URL اشکال‌زدای WebSocket، ‏`/json/version` را فراخوانی می‌کند و سپس
  متصل می‌شود. هیچ بازگشتی به WebSocket وجود ندارد.
- **نقاط پایانی WebSocket مستقیم** - `ws://host[:port]/devtools/<kind>/<id>` یا
  `wss://...` با مسیر `/devtools/browser|page|worker|shared_worker|service_worker/<id>`.
  OpenClaw مستقیماً از طریق دست‌دهی WebSocket متصل می‌شود و
  `/json/version` را به‌طور کامل نادیده می‌گیرد.
- **ریشه‌های WebSocket بدون مسیر** - `ws://host[:port]` یا `wss://host[:port]` بدون
  مسیر `/devtools/...` (برای مثال [Browserless](https://browserless.io)،
  [Browserbase](https://www.browserbase.com)). OpenClaw ابتدا کشف HTTP
  از طریق `/json/version` را امتحان می‌کند (با نرمال‌سازی طرح به `http`/`https`)؛
  اگر کشف یک `webSocketDebuggerUrl` برگرداند، از آن استفاده می‌شود، وگرنه OpenClaw
  به دست‌دهی مستقیم WebSocket در ریشه بدون مسیر بازمی‌گردد. اگر نقطه پایانی
  WebSocket اعلام‌شده دست‌دهی CDP را رد کند اما ریشه بدون مسیر پیکربندی‌شده
  آن را بپذیرد، OpenClaw به آن ریشه نیز بازمی‌گردد. این کار اجازه می‌دهد یک `ws://`
  بدون مسیر که به Chrome محلی اشاره می‌کند همچنان متصل شود، زیرا Chrome فقط ارتقاهای WebSocket
  را در مسیر ویژه هر هدف از `/json/version` می‌پذیرد، درحالی‌که ارائه‌دهندگان
  میزبانی‌شده همچنان می‌توانند از نقطه پایانی ریشه WebSocket خود استفاده کنند، زمانی که نقطه پایانی کشف آن‌ها
  یک URL کوتاه‌عمر را اعلام می‌کند که برای CDP در Playwright مناسب نیست.

`openclaw browser doctor` از همان منطق ابتدا کشف و سپس بازگشت به WebSocket
مانند اتصال زمان اجرا استفاده می‌کند، بنابراین URL ریشه بدون مسیری که با موفقیت متصل می‌شود،
در عیب‌یابی به‌عنوان غیرقابل دسترسی گزارش نمی‌شود.

### Browserbase

[Browserbase](https://www.browserbase.com) یک پلتفرم ابری برای اجرای
مرورگرهای بدون رابط با حل داخلی CAPTCHA، حالت مخفی و
پروکسی‌های مسکونی است.

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

نکات:

- [ثبت‌نام کنید](https://www.browserbase.com/sign-up) و **API Key** خود را
  از [داشبورد Overview](https://www.browserbase.com/overview) کپی کنید.
- `<BROWSERBASE_API_KEY>` را با کلید API واقعی Browserbase خود جایگزین کنید.
- Browserbase هنگام اتصال WebSocket به‌طور خودکار یک نشست مرورگر ایجاد می‌کند، بنابراین
  به مرحله ایجاد دستی نشست نیازی نیست.
- برای محدودیت‌های کنونی سطح رایگان و طرح‌های پولی، [قیمت‌گذاری](https://www.browserbase.com/pricing) را ببینید.
- برای مرجع کامل API، راهنماهای SDK و نمونه‌های یکپارچه‌سازی،
  [مستندات Browserbase](https://docs.browserbase.com) را ببینید.

### Notte

[Notte](https://www.notte.cc) یک پلتفرم ابری برای اجرای مرورگرهای
بدون رابط با قابلیت مخفی‌سازی داخلی، پروکسی‌های مسکونی و یک Gateway
بومی CDP مبتنی بر WebSocket است.

```json5
{
  browser: {
    enabled: true,
    defaultProfile: "notte",
    remoteCdpTimeoutMs: 3000,
    remoteCdpHandshakeTimeoutMs: 5000,
    profiles: {
      notte: {
        cdpUrl: "wss://us-prod.notte.cc/sessions/connect?token=<NOTTE_API_KEY>",
        color: "#7C3AED",
      },
    },
  },
}
```

نکات:

- [ثبت‌نام کنید](https://console.notte.cc) و **API Key** خود را از
  صفحه تنظیمات کنسول کپی کنید.
- `<NOTTE_API_KEY>` را با کلید API واقعی Notte خود جایگزین کنید.
- Notte هنگام اتصال WebSocket به‌طور خودکار یک نشست مرورگر ایجاد می‌کند، بنابراین
  به مرحله ایجاد دستی نشست نیازی نیست. با قطع اتصال
  WebSocket، نشست نابود می‌شود.
- برای محدودیت‌های کنونی سطح رایگان و طرح‌های پولی، [قیمت‌گذاری](https://www.notte.cc/#pricing) را ببینید.
- برای مرجع کامل API، راهنماهای SDK و نمونه‌های یکپارچه‌سازی،
  [مستندات Notte](https://docs.notte.cc) را ببینید.

## امنیت

نکات کلیدی:

- کنترل مرورگر فقط روی 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.auth.mode` برابر `none` باشد یک توکن، و اگر برابر
  `trusted-proxy` باشد یک گذرواژه (که از طریق `gateway.auth.password` ذخیره می‌شود تا کلاینت‌های
  loopback خارج از فرایند بتوانند آن را بازیابی کنند). اگر از قبل یک
  اعتبارنامه رشته‌ای صریح برای آن حالت پیکربندی شده باشد، یا
  `gateway.auth.mode` برابر `password` باشد، تولید خودکار انجام نمی‌شود.
- اگر به‌جای مقدار تولیدشده، یک راز پایدار تحت کنترل خود می‌خواهید،
  `gateway.auth.token`، `gateway.auth.password`، `OPENCLAW_GATEWAY_TOKEN` یا
  `OPENCLAW_GATEWAY_PASSWORD` را صریحاً پیکربندی کنید.

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

- در صورت امکان، نقاط پایانی رمزگذاری‌شده (HTTPS یا WSS) و توکن‌های کوتاه‌عمر را ترجیح دهید.
- از قراردادن مستقیم توکن‌های بلندمدت در فایل‌های پیکربندی خودداری کنید.
- Gateway و همه میزبان‌های Node را در یک شبکه خصوصی (Tailscale) نگه دارید؛ از قرارگیری عمومی اجتناب کنید.
- URLها/توکن‌های CDP راه‌دور را مانند رازها در نظر بگیرید؛ متغیرهای محیطی یا مدیر رازها را ترجیح دهید.

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

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

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

پیش‌فرض‌ها:

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

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

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

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

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

- [Chrome for Developers: استفاده از Chrome DevTools MCP با نشست مرورگر خود](https://developer.chrome.com/blog/chrome-devtools-mcp-debug-your-browser-session)
- [README مربوط به Chrome DevTools MCP](https://github.com/ChromeDevTools/chrome-devtools-mcp)

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

به‌طور پیش‌فرض، پروفایل داخلی `user` از اتصال خودکار Chrome MCP استفاده می‌کند که
پروفایل محلی پیش‌فرض Google Chrome را هدف قرار می‌دهد. برای Brave،
Edge، Chromium یا یک پروفایل غیراصلی Chrome از `userDataDir` استفاده کنید. `~` به پوشه خانه سیستم‌عامل شما
بسط می‌یابد:

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

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

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

صفحه‌های بازرسی رایج:

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

آزمون سریع اتصال زنده:

```bash
openclaw browser --browser-profile user start
openclaw browser --browser-profile user status
openclaw browser --browser-profile user tabs
openclaw browser --browser-profile user snapshot --format ai
```

نشانه‌های موفقیت:

- `status`، `driver: existing-session` را نشان می‌دهد
- `status`، `transport: chrome-mcp` را نشان می‌دهد
- `status`، `running: true` را نشان می‌دهد
- `tabs` زبانه‌های مرورگرِ ازپیش‌بازشده را فهرست می‌کند
- `snapshot` ارجاع‌ها را از زبانهٔ فعال انتخاب‌شده برمی‌گرداند

اگر اتصال کار نمی‌کند، موارد زیر را بررسی کنید:

- نسخهٔ مرورگر هدفِ مبتنی بر Chromium برابر با `144+` است
- اشکال‌زدایی راه‌دور در صفحهٔ بازرسی آن مرورگر فعال است
- مرورگر درخواست رضایت برای اتصال را نمایش داده و آن را پذیرفته‌اید
- اگر Chrome با یک `--remote-debugging-port` صریح راه‌اندازی شده است،
  `browser.profiles.<name>.cdpUrl` را به‌جای اتکا به اتصال خودکار Chrome MCP، روی همان
  نقطهٔ پایانی DevTools تنظیم کنید
- `openclaw doctor` پیکربندی قدیمی مرورگر مبتنی بر افزونه را مهاجرت می‌دهد و بررسی می‌کند که
  Chrome برای پروفایل‌های پیش‌فرض اتصال خودکار به‌صورت محلی نصب شده باشد، اما نمی‌تواند
  اشکال‌زدایی راه‌دور سمت مرورگر را برای شما فعال کند

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

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

نکات:

- این مسیر از پروفایل ایزولهٔ `openclaw` پرخطرتر است، زیرا می‌تواند
  درون نشست مرورگری که وارد آن شده‌اید عمل کند.
- OpenClaw مرورگر را برای این درایور راه‌اندازی نمی‌کند؛ فقط به آن متصل می‌شود.
- OpenClaw در اینجا از جریان رسمی `--autoConnect` در Chrome DevTools MCP استفاده می‌کند. اگر
  `userDataDir` تنظیم شده باشد، برای هدف‌گیری آن پوشهٔ دادهٔ کاربر منتقل می‌شود.
- نشست موجود می‌تواند روی میزبان انتخاب‌شده یا از طریق یک
  Node مرورگر متصل، وصل شود. اگر Chrome در جای دیگری قرار دارد و هیچ Node مرورگری متصل نیست، به‌جای آن از
  CDP راه‌دور یا یک میزبان Node استفاده کنید.
- هدف‌های Chrome MCP و ارجاع‌های اسنپ‌شات به یک زیرفرایند MCP محدود هستند. پس از
  راه‌اندازی مجدد آن فرایند، دوباره `browser tabs` را اجرا کنید، پیش از کار مختص هدف
  یک هدف تازه را صریحاً انتخاب کنید و پیش از استفاده از ارجاع‌ها اسنپ‌شات جدیدی بگیرید.
  هر ارجاع فقط برای هدف و آخرین اسنپ‌شات خود معتبر است. نام‌های مستعار قدیمی
  حتی اگر URL زبانهٔ جایگزین یکسان باشد، به آن منتقل نمی‌شوند.
- Chrome DevTools MCP درحال‌حاضر ابزارهای صفحه را بر اساس شناسهٔ عددی صفحه و محلیِ فرایند
  مسیریابی می‌کند. دستگیره‌های محدود به فرایند از استفادهٔ مجدد در زیرفرایند جایگزین جلوگیری می‌کنند، اما
  جایگزینی بافت مرورگر درون همان فرایند بین دو فراخوانی مجاور ابزار همچنان می‌تواند
  هدف یک عمل را تغییر دهد. مسیریابی کاملاً اتمی به پشتیبانی بالادستی ابزار صفحه
  از شناسه‌های پایدار هدف نیاز دارد.

### راه‌اندازی سفارشی Chrome MCP

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

| فیلد        | کاری که انجام می‌دهد                                                                                                               |
| ------------ | -------------------------------------------------------------------------------------------------------------------------- |
| `mcpCommand` | فایل اجرایی که به‌جای `npx` ایجاد می‌شود. همان‌گونه که هست تفکیک می‌شود؛ مسیرهای مطلق رعایت می‌شوند.                                          |
| `mcpArgs`    | آرایهٔ آرگومان که بدون تغییر به `mcpCommand` ارسال می‌شود. جایگزین آرگومان‌های پیش‌فرض `chrome-devtools-mcp@latest --autoConnect` می‌شود. |

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

- `http(s)://...` ← `--browserUrl <url>` (نقطهٔ پایانی کشف HTTP در DevTools).
- `ws(s)://...` ← `--wsEndpoint <url>` (WebSocket مستقیم CDP).

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

<Accordion title="محدودیت‌های قابلیت نشست موجود">

در مقایسه با پروفایل مدیریت‌شدهٔ `openclaw`، درایورهای نشست موجود محدودتر هستند:

- **نماگرفت‌ها** - ثبت کل صفحه و ثبت عناصر `--ref` کار می‌کنند؛ انتخابگرهای CSS ‏`--element` کار نمی‌کنند. برای نماگرفت از صفحه یا عنصر مبتنی بر ارجاع، Playwright لازم نیست. (`--full-page` را در هیچ پروفایلی، نه‌فقط نشست موجود، نمی‌توان با `--ref` یا `--element` ترکیب کرد.)
- **عمل‌ها** - `click`، `type`، `hover`، `scrollIntoView`، `drag` و `select` به ارجاع‌های اسنپ‌شات نیاز دارند (بدون انتخابگر CSS). ‏`click-coords` روی مختصات قابل‌مشاهدهٔ نمای دید کلیک می‌کند و به ارجاع اسنپ‌شات نیاز ندارد. ‏`click` فقط از دکمهٔ چپ پشتیبانی می‌کند (بدون بازنویسی دکمه یا کلیدهای اصلاح‌گر). ‏`type` از `slowly=true` پشتیبانی نمی‌کند؛ از `fill` یا `press` استفاده کنید. ‏`press` از `delayMs` پشتیبانی نمی‌کند. ‏`type`، `hover`، `scrollIntoView`، `drag`، `select` و `fill` از بازنویسی‌های `timeoutMs` برای هر فراخوانی پشتیبانی نمی‌کنند؛ `evaluate` پشتیبانی می‌کند. ‏`select` یک مقدار واحد می‌پذیرد. ‏`batch` پشتیبانی نمی‌شود؛ عمل‌ها را جداگانه ارسال کنید.
- **انتظار / بارگذاری / کادر محاوره‌ای** - `wait --url` از الگوهای دقیق، زیررشته و glob پشتیبانی می‌کند (همانند حالت مدیریت‌شده)؛ `wait --load networkidle` در پروفایل‌های نشست موجود پشتیبانی نمی‌شود (در پروفایل‌های مدیریت‌شده و CDP خام/راه‌دور کار می‌کند). قلاب‌های بارگذاری به `ref` یا `inputRef`، هر بار یک فایل و بدون `element` در CSS نیاز دارند. قلاب‌های کادر محاوره‌ای از بازنویسی مهلت زمانی یا `dialogId` پشتیبانی نمی‌کنند.
- **نمایان‌بودن کادر محاوره‌ای** - پاسخ‌های عمل مرورگر مدیریت‌شده، هنگامی که عملی یک کادر محاوره‌ای مودال باز می‌کند، شامل `blockedByDialog` و `browserState.dialogs.pending` هستند؛ اسنپ‌شات‌ها نیز وضعیت کادر محاوره‌ای در انتظار را شامل می‌شوند. تا زمانی که کادر محاوره‌ای در انتظار است، با `browser dialog --accept/--dismiss --dialog-id <id>` پاسخ دهید. کادرهای محاوره‌ای مدیریت‌شده خارج از OpenClaw زیر `browserState.dialogs.recent` ظاهر می‌شوند.
- **قابلیت‌های مختص حالت مدیریت‌شده** - صدور PDF، رهگیری دانلود و `responsebody` همچنان به مسیر مرورگر مدیریت‌شده نیاز دارند.

</Accordion>

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

- **پوشهٔ اختصاصی دادهٔ کاربر**: هرگز به پروفایل شخصی مرورگر شما دست نمی‌زند.
- **درگاه‌های اختصاصی**: برای جلوگیری از تداخل با جریان‌های کاری توسعه، از `9222` اجتناب می‌کند.
- **کنترل قطعی زبانه**: `tabs` ابتدا `suggestedTargetId` و سپس
  دستگیره‌های پایدار `tabId` مانند `t1`، برچسب‌های اختیاری و `targetId` خام را برمی‌گرداند.
  عامل‌ها باید از `suggestedTargetId` دوباره استفاده کنند؛ شناسه‌های خام برای
  اشکال‌زدایی و سازگاری همچنان در دسترس‌اند.

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

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

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

می‌توانید با `browser.executablePath` آن را بازنویسی کنید.

پلتفرم‌ها:

- 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` ارائه می‌کند (اسنپ‌شات‌ها، ارجاع‌ها، قابلیت‌های تقویت‌شدهٔ انتظار،
خروجی JSON، جریان‌های کاری اشکال‌زدایی). برای مرجع کامل به
[API کنترل مرورگر](/fa/tools/browser-control) مراجعه کنید.

## عیب‌یابی

برای مشکلات ویژهٔ Linux (به‌خصوص Chromium نسخهٔ snap)، به
[عیب‌یابی مرورگر](/fa/tools/browser-linux-troubleshooting) مراجعه کنید.

برای راه‌اندازی‌های دومیزبانهٔ WSL2 Gateway و Windows Chrome، به
[عیب‌یابی WSL2 + Windows + CDP راه‌دور Chrome](/fa/tools/browser-wsl2-windows-remote-cdp-troubleshooting) مراجعه کنید.

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

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

- **شکست راه‌اندازی یا آمادگی CDP** یعنی OpenClaw نمی‌تواند سالم‌بودن صفحهٔ کنترل مرورگر را تأیید کند.
- **مسدودسازی SSRF پیمایش** یعنی صفحهٔ کنترل مرورگر سالم است، اما هدف پیمایش صفحه طبق خط‌مشی رد می‌شود.

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

- شکست راه‌اندازی یا آمادگی 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`، اسنپ‌شات یا بازکردن زبانه با خطای خط‌مشی مرورگر/شبکه شکست می‌خورند، درحالی‌که `start` و `tabs` همچنان کار می‌کنند

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

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

نحوهٔ تفسیر نتایج:

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

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

- پیکربندی مرورگر، حتی وقتی `browser.ssrfPolicy` را پیکربندی نمی‌کنید، به‌طور پیش‌فرض یک شیء خط‌مشی SSRF با حالت بسته در صورت شکست دارد.
- برای پروفایل مدیریت‌شدهٔ loopback محلی `openclaw`، بررسی‌های سلامت CDP عمداً اعمال دسترسی‌پذیری SSRF مرورگر را برای صفحهٔ کنترل محلی خود 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` یک درخت رابط کاربری پایدار (AI یا ARIA) برمی‌گرداند.
- `browser act` از شناسه‌های snapshot یعنی `ref` برای کلیک‌کردن/تایپ‌کردن/کشیدن/انتخاب‌کردن استفاده می‌کند.
- `browser screenshot` پیکسل‌ها را ثبت می‌کند (کل صفحه، عنصر یا ارجاع‌های برچسب‌گذاری‌شده).
- `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"` را ثابت کنید.

این کار رفتار عامل را قطعی نگه می‌دارد و از انتخابگرهای شکننده جلوگیری می‌کند.

## مرتبط

- [نمای کلی ابزارها](/fa/tools) - همه ابزارهای عامل موجود
- [Sandboxing](/fa/gateway/sandboxing) - کنترل مرورگر در محیط‌های sandbox‌شده
- [امنیت](/fa/gateway/security) - خطرات کنترل مرورگر و مقاوم‌سازی