---
title: "Playwright MCP چیست؟ نصب و تنظیمات پروکسی"
description: "Playwright MCP یک سرور MCP است که به عامل هوش مصنوعی امکان می‌دهد با مرورگر واقعی کار کند. نصب، پرچم‌های پروکسی و محدودسازی مبدأها را با نمونه توضیح می‌دهیم."
url: https://proxynet.io/fa/blog/playwright-mcp
date: 2026-09-19
author: "Acar Diveroli"
category: "هوش مصنوعی, یکپارچه‌سازی"
lang: fa
---

# Playwright MCP چیست؟ نصب و تنظیمات پروکسی

وقتی به Claude Code یا Cursor می‌گویید «این صفحه را باز کن و قیمت سه محصول اول را بخوان»، دستیار بیشتر وقت‌ها HTML خام صفحه را می‌آورد. اگر قیمت با JavaScript بارگذاری شود، فقط یک اسکلت خالی در دستش می‌ماند. Playwright MCP این خلأ را پر می‌کند: یک مرورگر واقعی پشت دستیار می‌گذارد و کلیک و تایپ را به شکل فراخوانی ابزار در اختیارش قرار می‌دهد. نصب آن یک خط است. پرسش‌ها بعد از آن می‌آیند: مرورگر از کدام IP خارج می‌شود، نام کاربری و رمز عبور پروکسی کجا نوشته می‌شود و آیا عامل می‌تواند به هر سایتی که خواست برود؟

در این نوشته توضیح می‌دهیم Playwright MCP چیست و چگونه کار می‌کند، درخت دسترس‌پذیری چه تفاوتی با تصویر صفحه دارد، نصب در چهار کلاینت رایج چگونه است، کدام پرچم‌ها به کار می‌آیند، پروکسی چگونه تنظیم می‌شود (از جمله پروکسی دارای احراز هویت)، چگونه با `--allowed-origins` مبدأها محدود می‌شوند و چرا این محدودیت مرز امنیتی به شمار نمی‌آید. پرچم‌ها را در روز نگارش با README رسمی و خروجی `--help` تطبیق داده‌ایم. نمونه‌ها را با `@playwright/mcp` نسخه 0.0.82 و از طریق یک پروکسی آزمایشی محلی اجرا کرده‌ایم.

> **نکته: پاسخ کوتاه**
>
> Playwright MCP یک سرور MCP است که Microsoft منتشر کرده و به برنامه‌های هوش مصنوعی امکان استفاده از مرورگر می‌دهد. با فرمان `npx @playwright/mcp@latest` اجرا می‌شود و صفحه را نه به شکل تصویر صفحه، بلکه به شکل متن درخت دسترس‌پذیری به مدل می‌دهد. پروکسی با پرچم `--proxy-server` تعریف می‌شود، اما نام کاربری و رمز عبور درون نشانی نوشته نمی‌شوند و جای آنها شیء `proxy` در فایل پیکربندی است. `--allowed-origins` و `--blocked-origins` مبدأهایی را که عامل می‌تواند ببیند محدود می‌کنند، ولی همان‌طور که README آشکارا نوشته است مرز امنیتی نیستند.

## Playwright MCP چیست؟

Playwright MCP بنا به تعریف [مخزن رسمی آن](https://github.com/microsoft/playwright-mcp) یک سرور Model Context Protocol است که با استفاده از Playwright خودکارسازی مرورگر ارائه می‌دهد. دو بخش دارد. Playwright کتابخانه‌ای است که Chromium، Firefox و WebKit را از درون کد کنترل می‌کند و جزئیات آن را در نوشته [Playwright چیست و چگونه با پروکسی استفاده می‌شود؟](/fa/blog/playwright-proxy) آورده‌ایم. MCP هم پروتکلی است که برنامه‌های هوش مصنوعی را به شیوه‌ای استاندارد به ابزارهای بیرونی وصل می‌کند.

خود پروتکل را اینجا دوباره توضیح نمی‌دهیم. همین اندازه کافی است: برنامه دستیار (host) سرور MCP را به شکل یک فرایند محلی اجرا می‌کند، سرور فهرست ابزارهایش را همراه با شِمای آنها اعلام می‌کند و مدل هر وقت لازم باشد این ابزارها را فرا می‌خواند. تفکیک host، client و server، روش‌های انتقال و خطرهای سطح پروتکل در نوشته [پروتکل MCP چیست و چگونه کار می‌کند؟](/fa/blog/what-is-mcp) آمده است.

ابزارهایی که Playwright MCP ارائه می‌دهد کنش‌های مرورگرند: `browser_navigate`، `browser_click`، `browser_type`، `browser_fill_form`، `browser_snapshot`، `browser_take_screenshot`، `browser_tabs` و مانند اینها. در نسخه 0.0.82 نصب پیش‌فرض 25 ابزار اعلام کرد. وقتی `--caps=vision,pdf` را افزودیم، کلیک با مختصات و تولید PDF هم آمد و شمار ابزارها به 32 رسید. تفاوتش با نوشتن یک اسکریپت مرورگر به دست خودتان این است که درباره گام‌ها مدل تصمیم می‌گیرد: شما هدف را می‌گویید و مدل با نگاه به صفحه انتخاب می‌کند روی کدام پیوند کلیک شود. سازوکار کلی حلقه عامل در نوشته [عامل‌های هوش مصنوعی چگونه کار می‌کنند؟](/fa/blog/how-ai-agents-work) آمده است.

## Playwright MCP چگونه کار می‌کند؟

یک درخواست از آغاز تا پایان این گام‌ها را طی می‌کند:

1. برنامه host فرمان درون پیکربندی را اجرا می‌کند: `npx @playwright/mcp@latest`. سرور از طریق stdio وصل می‌شود و فهرست ابزارها را اعلام می‌کند.
2. شما کاری را به زبان طبیعی می‌نویسید. مدل ابزار `browser_navigate` را همراه با نشانی فرا می‌خواند.
3. سرور در نخستین فراخوانی ابزار مرورگر را اجرا می‌کند. وقتی `--browser` داده نشد، در آزمون ما Google Chrome نصب‌شده روی سیستم باز شد؛ پنجره به طور پیش‌فرض دیده می‌شود و با `--headless` پنهان می‌شود.
4. پس از بارگذاری صفحه، سرور نشانی صفحه، عنوان و یک snapshot از درخت دسترس‌پذیری تولید می‌کند. در 0.0.82 پاسخ `browser_navigate` این snapshot را به شکل فایل YAML در پوشه `.playwright-mcp` درون پوشه کاری ذخیره کرد و مسیر آن را برگرداند، ولی `browser_snapshot` درخت را مستقیم درون پاسخ برگرداند.
5. هر عنصر درخت یک ارجاع دارد: `link "Travel" [ref=e21]`. مدل عنصری را که می‌خواهد رویش کلیک کند با همین ارجاع اعلام می‌کند: `browser_click`، `target: e21`.
6. سرور کنش را با Playwright اجرا می‌کند و کدی را که اجرا کرده هم در پاسخ نشان می‌دهد: `await page.getByRole('link', { name: 'Travel' }).click();`. سپس snapshot صفحه تازه برمی‌گردد و حلقه ادامه می‌یابد.

به لطف همین خط کد می‌توانید کاوش عامل را بعدها به یک اسکریپت معمولی Playwright تبدیل کنید. پرچم `--codegen` زبان این خروجی را تعیین می‌کند (`typescript`، `python`، `java`، `csharp` یا `none`).

## چرا درخت دسترس‌پذیری از تصویر صفحه کارآمدتر است؟

درخت دسترس‌پذیری ساختاری است که مرورگر برای صفحه‌خوان‌ها تولید می‌کند. [بنا به تعریف MDN](https://developer.mozilla.org/en-US/docs/Glossary/Accessibility_tree) برای هر عنصر چهار داده دارد: نام، توضیح، نقش و وضعیت. Playwright این درخت را به شکل YAML بیرون می‌دهد؛ جزئیات قالب در [مستندات aria snapshot](https://playwright.dev/docs/aria-snapshots) آمده است. snapshot صفحه آزمایشی ما (`books.toscrape.com`) این‌گونه آغاز شد:

```yaml
- generic [active] [ref=e1]:
  - banner [ref=e2]:
    - generic [ref=e5]:
      - link "Books to Scrape" [ref=e6] [cursor=pointer]:
        - /url: index.html
      - text: We love being scraped!
  # ... (truncated)
            - list [ref=e19]:
              - listitem [ref=e20]:
                - link "Travel" [ref=e21] [cursor=pointer]:
                  - /url: catalogue/category/books/travel_2/index.html
```

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

| | درخت دسترس‌پذیری (`browser_snapshot`) | تصویر صفحه (`browser_take_screenshot`) |
|---|---|---|
| داده‌ای که به مدل می‌رود | متن (YAML) | تصویر (PNG یا JPEG) |
| مدل با توان درک تصویر لازم است؟ | خیر | بله |
| عنصر چگونه هدف گرفته می‌شود؟ | با مقدار `ref` و به طور دقیق | با مختصات، اگر `--caps=vision` فعال باشد |
| جزئیاتی که دیده نمی‌شود | رنگ، چیدمان، محتوای تصویر | کارکرد عنصرهایی که نام دسترس‌پذیر ندارند |
| کار مناسب | پیمایش، فرم، خواندن داده | راستی‌آزمایی بصری، بازبینی طراحی |

توضیح خود ابزار هم همین را می‌گوید: بر پایه تصویر صفحه نمی‌توان کنشی انجام داد و برای کنش از snapshot استفاده می‌شود. با این حال گمان نکنید متن رایگان است. در آزمون ما صفحه اصلی فهرست کتاب‌ها درختی نزدیک به 32 هزار نویسه تولید کرد و شِمای 25 ابزار هم به حدود 20 هزار نویسه رسید. اینها شمار نویسه‌اند؛ معادل توکن آنها به مدل بستگی دارد و ما آن را اندازه نگرفته‌ایم. README در همین باره روراست است: برای عامل‌های کدنویسی که با پایگاه کد بزرگ کار می‌کنند مسیر [Playwright CLI](https://github.com/microsoft/playwright-cli) را پیشنهاد می‌کند که شِمای ابزارها و درخت را در بافت مدل بار نمی‌کند، و MCP را برای کارهایی می‌داند که به وضعیت ماندگار مرورگر و استدلال گام‌به‌گام روی صفحه نیاز دارند. `--snapshot-mode=none` افزوده شدن خودکار snapshot به پاسخ‌ها را خاموش می‌کند و `--mobile` صفحه‌های سبک‌تر موبایل را باز می‌کند.

## Playwright MCP چگونه نصب می‌شود؟

تنها چیزی که لازم دارید ⁦Node.js 18⁩ یا نسخه‌ای تازه‌تر و کلاینتی است که از MCP پشتیبانی کند. بسته را دستی نصب نمی‌کنید؛ کلاینت در هر بار اجرا آن را با `npx` راه می‌اندازد. مدخلی که README آن را «پیکربندی استاندارد» می‌نامد در بیشتر کلاینت‌ها یکسان است:

```json
{
  "mcpServers": {
    "playwright": {
      "command": "npx",
      "args": ["@playwright/mcp@latest"]
    }
  }
}
```

جایی که این مدخل نوشته می‌شود به کلاینت بستگی دارد:

| کلاینت | نصب |
|---|---|
| Claude Code | `claude mcp add playwright npx @playwright/mcp@latest` |
| Claude Desktop | مدخل استاندارد به فایل `claude_desktop_config.json` افزوده می‌شود که از مسیر `Settings` ← `Developer` ← `Edit Config` باز می‌شود |
| Cursor | `Cursor Settings` ← `MCP` ← `Add new MCP Server`، نوع `command`، فرمان `npx @playwright/mcp@latest` |
| VS Code | فرمان `code --add-mcp` یا فایل `.vscode/mcp.json`؛ در این فایل کلید بالایی `servers` است، نه `mcpServers` |

اگر در Claude Code می‌خواهید به سرور پرچم بدهید، میان آنها `--` بگذارید. بنا به [مستندات MCP در Claude Code](https://code.claude.com/docs/en/mcp) هر چه پس از دو خط تیره بیاید دست‌نخورده به فرمان سرور داده می‌شود:

```bash
claude mcp add --scope project playwright -- npx @playwright/mcp@latest --headless --isolated
```

`--scope project` مدخل را در فایل `.mcp.json` در ریشه پروژه می‌نویسد؛ اگر این فایل را به مخزن بیفزایید، همه اعضای تیم همان تنظیم را به کار می‌برند. وقتی فرمان را آزمودیم، در فایل همان مدخل استاندارد بالا همراه با پرچم‌ها ساخته شد. اتصال را می‌توانید با `claude mcp list` یا درون نشست با `/mcp` بررسی کنید. جزئیات مربوط به VS Code در [مستندات MCP در VS Code](https://code.visualstudio.com/docs/agent-customization/mcp-servers) آمده است.

برچسب `@latest` در هر بار اجرا نسخه روز را می‌گیرد. این بسته تند تغییر می‌کند: نام پرچم‌ها در این نوشته متعلق به 0.0.82 است. اگر می‌خواهید رفتار در کل تیم یکسان باشد، نسخه را ثابت کنید (`@playwright/mcp@0.0.82`) و پیش از ارتقا خروجی `npx @playwright/mcp@latest --help` را ببینید.

## کدام پرچم‌ها بیشتر به کار می‌آیند؟

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

| پرچم | کارکرد |
|---|---|
| `--headless` | مرورگر را بدون پنجره اجرا می‌کند. پیش‌فرض با پنجره است |
| `--browser <name>` | `chrome`، `firefox`، `webkit` یا `msedge` |
| `--isolated` | پروفایل را در حافظه نگه می‌دارد و روی دیسک نمی‌نویسد؛ با بسته شدن نشست کوکی‌ها پاک می‌شوند |
| `--user-data-dir <path>` | پوشه پروفایل ماندگار |
| `--storage-state <path>` | کوکی‌های آغازین و حافظه محلی را در نشست ایزوله بار می‌کند |
| `--proxy-server <address>` | سرور پروکسی: `http://server:3128` یا `socks5://server:8080` |
| `--proxy-bypass <domains>` | دامنه‌هایی که از پروکسی عبور نمی‌کنند و با ویرگول جدا می‌شوند |
| `--allowed-origins <list>` | مبدأهایی که مرورگر اجازه دارد به آنها درخواست بفرستد و با نقطه‌ویرگول جدا می‌شوند |
| `--blocked-origins <list>` | مبدأهایی که مسدود می‌شوند؛ پیش از فهرست مجاز ارزیابی می‌شود |
| `--caps <list>` | قابلیت‌های افزوده: `vision`، `pdf`، `devtools` |
| `--config <path>` | فایل پیکربندی JSON |
| `--timeout-navigation <ms>` | مهلت پیمایش، پیش‌فرض 60000 |

هر پرچم یک متغیر محیطی متناظر دارد (مانند `PLAYWRIGHT_MCP_PROXY_SERVER` و `PLAYWRIGHT_MCP_ALLOWED_ORIGINS`). متغیر پروکسی را آزمودیم و همان نتیجه پرچم را داد.

## در Playwright MCP پروکسی چگونه تنظیم می‌شود؟

برای پروکسی‌ای که اطلاعات ورود نمی‌خواهد، یعنی وقتی IP خروجی شما در پنل به لیست سفید IP افزوده شده است، یک پرچم کافی است:

```json
{
  "mcpServers": {
    "playwright": {
      "command": "npx",
      "args": [
        "@playwright/mcp@latest",
        "--headless",
        "--isolated",
        "--proxy-server=http://pr.proxynet.io:8000",
        "--proxy-bypass=localhost,127.0.0.1"
      ]
    }
  }
}
```

این پیکربندی را با پروکسی آزمایشی محلی خودمان اجرا کردیم: هر صفحه‌ای که عامل باز کرد به شکل یک سطر `CONNECT` در گزارش پروکسی ثبت شد. دامنه‌ای که به فهرست `--proxy-bypass` افزودیم هرگز در گزارش دیده نشد، یعنی مستقیم وصل شد. اگر سرور توسعه محلی خودتان را می‌آزمایید، مدخل `localhost` را فراموش نکنید؛ وگرنه عامل می‌کوشد از طریق پروکسی به صفحه‌ای روی دستگاه خود شما برسد.

SOCKS5 هم کار می‌کند: `--proxy-server=socks5://pr.proxynet.io:1080`. در آزمون ما صفحه باز شد و نام دامنه به سرور SOCKS5 رسید، یعنی ترجمه DNS در سمت پروکسی ماند. در SOCKS5 نام کاربری و رمز عبور پشتیبانی نمی‌شود؛ علتش Chromium است و جزئیات در همان نوشته پروکسی در Playwright آمده که بالاتر به آن اشاره کردیم. بخش مربوط به محصول در صفحه [پروکسی SOCKS5](https://proxynet.io/fa/socks5-proxy) است.

برای اطمینان از اینکه پروکسی واقعاً فعال است می‌توانید از خود عامل بپرسید: «نشانی https://httpbin.org/ip را باز کن و نشانی IP نمایش‌داده‌شده را بنویس.» اگر نشانی برگشتی IP خود شما نباشد، ترافیک از پروکسی می‌گذرد.

## پروکسی دارای نام کاربری و رمز عبور چگونه تعریف می‌شود؟

نخستین راهی که به ذهن می‌رسد گنجاندن اطلاعات ورود در خود نشانی است: `--proxy-server=http://user:pass@pr.proxynet.io:8000`. این راه کار نمی‌کند. وقتی آن را آزمودیم سرور اجرا شد، ولی نخستین پیمایش با این خطا برگشت:

```text
Error: browserBackend.callTool: net::ERR_INVALID_AUTH_CREDENTIALS at https://httpbin.org/ip
```

در گزارش پروکسی دیدیم که درخواست بدون اطلاعات ورود رسیده و پاسخ `407` گرفته است. وقتی هیچ اطلاعات ورودی هم ننوشتیم خطا همین بود. یعنی این پرچم فقط طرح، سرور و پورت را حمل می‌کند.

راه‌حل فایل پیکربندی است. فیلد `browser.launchOptions` در فایل JSON که با `--config` داده می‌شود به گزینه‌های اجرای خود Playwright منتقل می‌شود و شیء `proxy` هم همان‌جاست:

```json
{
  "browser": {
    "isolated": true,
    "launchOptions": {
      "headless": true,
      "proxy": {
        "server": "http://pr.proxynet.io:8000",
        "username": "user",
        "password": "pass"
      }
    }
  },
  "network": {
    "allowedOrigins": ["https://books.toscrape.com", "https://httpbin.org"]
  }
}
```

مدخل سمت کلاینت فقط به فایل اشاره می‌کند:

```json
{
  "mcpServers": {
    "playwright": {
      "command": "npx",
      "args": ["@playwright/mcp@latest", "--config=playwright-mcp.json"]
    }
  }
}
```

این جفت را با پروکسی محلی خودمان که نام کاربری و رمز عبور می‌خواهد آزمودیم: مرورگر نخست `407` گرفت، اطلاعات ورود را فرستاد و صفحه باز شد. نوشتن مسیر فایل به شکل مسیر مطلق مطمئن‌تر است، چون پوشه‌ای که کلاینت سرور را در آن اجرا می‌کند از برنامه‌ای به برنامه دیگر فرق دارد.

چون رمز عبور به شکل متن ساده در یک فایل می‌ماند، دو احتیاط را رعایت کنید: فایل را به مخزن نیفزایید و اگر ممکن است برای این کار یک کاربر پروکسی جداگانه بسازید. اگر اصلاً نمی‌خواهید رمز عبور را جایی بنویسید، با لیست سفید IP به همان نصب تک‌پرچمی بخش پیشین برمی‌گردید. مقایسه این دو روش در نوشته [احراز هویت پروکسی: نام کاربری و رمز یا لیست سفید IP](/fa/blog/proxy-authentication-methods) آمده است.

## مبدأهایی که عامل می‌تواند ببیند چگونه محدود می‌شوند؟

دادن مرورگر به مدل یعنی هر صفحه‌ای که می‌خواند می‌تواند در گوشش دستور زمزمه کند. سازوکار prompt injection غیرمستقیم و اینکه چرا فهرست مجاز از فهرست مسدود محکم‌تر است را در نوشته [دسترسی امن LLM به وب: محدودیت نرخ و مجوزها](/fa/blog/llm-safe-web-access) توضیح داده‌ایم. Playwright MCP یک پیاده‌سازی آماده از همان فکر ارائه می‌دهد:

```json
"args": [
  "@playwright/mcp@latest",
  "--allowed-origins=https://books.toscrape.com;https://httpbin.org"
]
```

مبدأ (origin) از طرح، دامنه و پورت ساخته می‌شود؛ فهرست با نقطه‌ویرگول جدا می‌شود. معادل آن در فایل پیکربندی آرایه `network.allowedOrigins` است که نویسه عام پورت را به شکل `http://localhost:*` می‌پذیرد. `--blocked-origins` برعکس عمل می‌کند و زودتر ارزیابی می‌شود؛ وقتی بدون فهرست مجاز به کار رود، هر نشانی که در فهرست نباشد باز می‌ماند.

در آزمون ما عاملی که کوشید به نشانی بیرون از فهرست برود این پاسخ را گرفت: `net::ERR_BLOCKED_BY_CLIENT`. تصویری بیرون از فهرست که درون یک صفحه مجاز گذاشته بودیم هم بار نشد، یعنی قاعده افزون بر پیمایش، منابع فرعی را هم در بر می‌گیرد.

> **هشدار: مرز امنیتی نیست**
>
> خروجی راهنما برای هر دو پرچم همین یادداشت را آورده است: `*does not* serve as a security boundary and *does not* affect redirects`. بخش Security در README کلی‌تر است: می‌گوید `Playwright MCP is **not** a security boundary` و به [سند توصیه‌های امنیتی MCP](https://modelcontextprotocol.io/docs/tutorials/security/security_best_practices) ارجاع می‌دهد.

معنای عملی این هشدار را با سه مشاهده می‌توان نشان داد:

- **تغییر مسیرها از فهرست می‌گذرند.** وقتی یک نشانی محلی درون فهرست مجاز با `302` به سایتی بیرون از فهرست تغییر مسیر داد، صفحه باز شد و عامل محتوایش را خواند.
- **به نشانی مسدودشده هم ممکن است اتصال باز شود.** برای دامنه مسدودشده در گزارش پروکسی یک سطر `CONNECT` دیدیم. صفحه بار نشد، ولی مرورگر با آن سرور اتصال برقرار کرد.
- **ترافیک پس‌زمینه خود مرورگر تابع این قاعده نیست.** درخواست‌های Chrome به سرویس‌های به‌روزرسانی و حساب کاربری، مستقل از فهرست، از پروکسی گذشتند. اگر ترافیک را بر پایه GB می‌پردازید، این درخواست‌ها هم در شمارنده حساب می‌شوند.

در میان ابزارهای پیش‌فرض `browser_evaluate` و `browser_run_code_unsafe` هم هست. توضیح دومی روشن است: JavaScript دلخواه را در فرایند سرور اجرا می‌کند و هم‌ارز اجرای کد از راه دور است. دسترسی به سیستم فایل به طور پیش‌فرض به پوشه کاری محدود است و نشانی‌های `file://` مسدودند؛ `--allow-unrestricted-file-access` این محدودیت را برمی‌دارد، پس تا لازم نشده آن را به کار نبرید.

مرز واقعی را بیرون می‌سازید: عامل را در یک حساب کاربری جداگانه یا در کانتینر اجرا کنید، با `--isolated` آن را از نشست‌های شخصی خود جدا نگه دارید، گام تأیید در فراخوانی ابزارها را خاموش نکنید و اگر ممکن است در پروکسی خروجی یک بازبینی دوم روی دامنه‌ها انجام دهید. پرچم‌ها جای این لایه‌ها را نمی‌گیرند، بلکه به آنها افزوده می‌شوند.

## پروفایل و نشست: ماندگار یا ایزوله؟

حالت پیش‌فرض پروفایل ماندگار است: کوکی‌ها و داده‌های ورود روی دیسک می‌مانند و عامل در نشست بعدی از همان‌جا ادامه می‌دهد. پوشه پروفایل بر پایه پوشه کاری کلاینت ساخته می‌شود، پس پروژه‌های گوناگون پروفایل جدا می‌گیرند. README یک هشدار دارد: پروفایل ماندگار را در هر لحظه فقط یک مرورگر می‌تواند به کار ببرد. اگر می‌خواهید در یک پروژه دو کلاینت باز کنید، به دومی `--isolated` یا یک `--user-data-dir` جداگانه بدهید.

`--isolated` هر نشست را پاک آغاز می‌کند و با بسته شدن مرورگر همه چیز را پاک می‌کند. در کارهای خواندن داده پیش‌فرض درست همین است. اگر باید برنامه خودتان را در حالت واردشده بیازمایید، کوکی‌ها را یک بار برون‌بری می‌کنید و با `--storage-state` بار می‌کنید؛ قالب آن در [مستندات احراز هویت](https://playwright.dev/docs/auth) در Playwright آمده است. این فایل کلیدهای نشست شما را در خود دارد، مانند رمز عبور از آن نگهداری کنید. حالت سوم وصل شدن به Chrome باز خودتان با `--extension` است. در این حالت عامل به همه زبانه‌هایی که در آنها وارد شده‌اید دسترسی پیدا می‌کند، پس این راه را فقط وقتی برگزینید که می‌دانید چه می‌کنید.

## کاربردها

- **بازبینی بومی‌سازی:** اینکه عامل بگردد و ببیند سایت شما از یک کشور مشخص چگونه دیده می‌شود. پروکسی را روی نقطه خروج همان کشور می‌گذارید و از عامل می‌خواهید مواردی مانند زبان، واحد پول و اعلان کوکی را گزارش کند. جزئیات در صفحه [بومی‌سازی](/fa/localization) آمده است؛ در بازبینی‌هایی که ظاهر یک اتصال خانگی واقعی لازم است از [پروکسی مسکونی](https://proxynet.io/fa/residential-proxy) استفاده می‌شود.
- **آزمون اکتشافی:** اینکه عامل یک روند را در برنامه خودتان طی کند و کد Playwright تولیدشده را به آزمون ماندگار تبدیل کنید. چیدمان آزمون از کشورهای گوناگون در صفحه [آزمون برنامه](/fa/app-testing) آمده است.
- **خواندن یک‌باره داده از صفحه پویا:** گرفتن چند مقدار از صفحه‌ای عمومی که با JavaScript بارگذاری می‌شود. برای کار منظم و پرحجم، عامل گران تمام می‌شود؛ چیدمان ماندگار در صفحه [راه‌حل استخراج داده](/fa/data-scraping) و اینکه اصلاً مرورگر لازم است یا نه در نوشته [صفحه‌های ایستا و پویا در وب اسکرپینگ](/fa/blog/static-vs-dynamic-pages) آمده است.
- **اشکال‌زدایی:** عامل با ابزارهای `browser_console_messages` و `browser_network_requests` خطاهای کنسول و درخواست‌های شبکه صفحه را می‌خواند و برایتان خلاصه می‌کند.

حتی وقتی عامل در کار است، آنچه وب را می‌گردد یک مرورگر است و همان قاعده‌ها برقرارند: به فایل `robots.txt` و شرایط استفاده سایت پایبند باشید، اگر API رسمی هست آن را ترجیح دهید و نرخ درخواست را پایین نگه دارید. افزونه‌های گریز از تشخیص را توصیه نمی‌کنیم. اینکه چرا سایت‌ها می‌کوشند بازدیدکننده خودکار را تشخیص دهند در نوشته [چرا سایت‌ها عامل‌های خرید هوش مصنوعی را مسدود می‌کنند؟](/fa/blog/ai-shopping-agents-blocked) آمده است.

## خطاهای رایج

| آنچه می‌بینید | علت | چه باید کرد |
|---|---|---|
| `net::ERR_INVALID_AUTH_CREDENTIALS` | پروکسی اطلاعات ورود می‌خواهد؛ یا اصلاً داده نشده یا درون نشانی گنجانده شده است | `username` و `password` را در فیلد `launchOptions.proxy` فایل `--config` بنویسید |
| `net::ERR_PROXY_CONNECTION_FAILED` | نشانی یا پورت پروکسی نادرست است یا اتصال خروجی به دیوار آتش می‌خورد | همان نشانی را با cURL بیازمایید |
| `net::ERR_BLOCKED_BY_CLIENT` | نشانی بیرون از `--allowed-origins` یا درون `--blocked-origins` است | مبدأ را با طرح و پورتش به فهرست بیفزایید |
| در کلاینت دوم مرورگر باز نمی‌شود | پروفایل ماندگار در مرورگر دیگری قفل است | `--isolated` یا یک `--user-data-dir` جداگانه |
| عامل به سرور محلی شما نمی‌رسد | ترافیک `localhost` هم به پروکسی می‌رود | `--proxy-bypass=localhost,127.0.0.1` |

خطاهایی هم هست که از عادت می‌آیند و در جدول نمی‌گنجند:

- **فهرست مجاز را اقدام امنیتی دانستن.** تغییر مسیر از فهرست می‌گذرد؛ جداسازی را در سطح فرایند و شبکه بسازید.
- **باز کردن پروفایل شخصی Chrome برای عامل.** پروفایلی که نشست‌های ایمیل و بانک شما در آن است نباید در دست مدلی باشد که محتوای بیرونی می‌خواند.
- **خواستن تصویر صفحه برای هر کار.** کنش‌ها همین حالا هم روی snapshot انجام می‌شوند؛ تصویر فقط برای راستی‌آزمایی بصری است.
- **کار تیمی با `@latest`.** نام پرچم‌ها ممکن است از نسخه‌ای به نسخه دیگر عوض شود؛ نسخه را ثابت کنید.
- **سپردن خزش منظم به عامل.** هر گام یک فراخوانی مدل هزینه دارد. با عامل کاوش کنید، کد تولیدشده را به اسکریپت تبدیل کنید و همان را اجرا کنید.

## راهنمای انتخاب

| نیاز | پیشنهاد |
|---|---|
| دستیار باید صفحه‌ای را بخواند که با JavaScript بارگذاری می‌شود | Playwright MCP با `--headless --isolated` |
| عامل باید از کشوری مشخص خارج شود | نقطه خروج همان کشور با `--proxy-server` |
| پروکسی با نام کاربری و رمز عبور | `launchOptions.proxy` در فایل `--config` |
| نمی‌خواهید رمز عبور در فایل نوشته شود | لیست سفید IP و `--proxy-server` به تنهایی |
| محدود کردن عامل به چند سایت | `--allowed-origins` به همراه جداسازی فرایند و شبکه |
| عامل کدنویسی در پایگاه کد بزرگ | Playwright CLI که README پیشنهاد می‌کند |
| خزش روزانه صدها صفحه | نه عامل، بلکه اسکریپتی که با کتابخانه Playwright نوشته شده است |
| آشنایی با پروتکل و خطرهای آن | راهنمای MCP ما |

## پرسش‌های متداول

### آیا Playwright MCP رایگان است؟

بله. بسته با مجوز ⁦Apache 2.0⁩ منتشر می‌شود و با `npx` بدون هزینه اجرا می‌شود. هزینه از دو جا می‌آید: شِمای ابزارها و snapshot صفحه‌ها که مدل پردازش می‌کند، و ترافیک پروکسی که مصرف می‌کنید.

### تفاوت Playwright MCP با کتابخانه Playwright چیست؟

در کتابخانه گام‌ها را خودتان کدنویسی می‌کنید و اسکریپت در هر اجرا همان مسیر را می‌رود. در سرور MCP درباره گام‌ها مدل تصمیم می‌گیرد و شما فقط هدف را می‌گویید. اولی برای کارهای تکراری ارزان و پیش‌بینی‌پذیر است و دومی برای کاوش و کارهای یک‌باره سریع. جزئیات پروکسی در سمت کتابخانه (پروکسی برای هر context، چرخش، جدول خطاها) در نوشته ما درباره پروکسی در Playwright آمده است.

### از کدام مرورگر استفاده می‌کند و آیا باید Chrome نصب باشد؟

وقتی `--browser` داده نشد، در آزمون ما Google Chrome سیستم باز شد. می‌توانید آن را با `--browser firefox`، `webkit` یا `msedge` عوض کنید یا با `--executable-path` یک فایل اجرایی مشخص مرورگر را نشان دهید.

### آیا همان Browser Use است؟

هدف یکی است: واداشتن مدل به استفاده از مرورگر. Browser Use یک کتابخانه مستقل عامل در Python است و حلقه را خودش اجرا می‌کند. Playwright MCP فقط ابزارها را ارائه می‌دهد و حلقه را همان دستیاری اجرا می‌کند که از پیش به کار می‌برید (Claude Code، Cursor، VS Code).

### آیا می‌توان آن را با پروکسی چرخشی به کار برد؟

می‌توان، ولی مرورگر برای یک صفحه اتصال‌های بسیاری باز می‌کند و در دروازه‌ای که در هر اتصال IP را عوض می‌کند این اتصال‌ها ممکن است از نشانی‌های گوناگون خارج شوند. هنگام خواندن صفحه‌های مستقل مشکلی پیش نمی‌آید. اگر نمی‌خواهید IP در میانه یک روند چندگامی عوض شود، [پروکسی با نشست ثابت](https://proxynet.io/fa/sticky-proxy) را برگزینید. سازوکار چرخش در [نوشته ما درباره چرخش IP](/fa/blog/ip-rotation-explained) آمده است.

### آیا استفاده از پروکسی صفحه‌های راستی‌آزمایی را از میان برمی‌دارد؟

خیر. پروکسی فقط تعیین می‌کند درخواست از کدام IP خارج شود. نشانه‌هایی که مرورگر زیر کنترل خودکارسازی به جا می‌گذارد و نرخ درخواست همان می‌ماند. راه ماندگار نرخ معقول، صفحه‌های مجاز و در صورت وجود API رسمی است.

## خلاصه

Playwright MCP به دستیار شما یک مرورگر واقعی می‌دهد و صفحه را به شکل درخت دسترس‌پذیری برایش خوانا می‌کند. نصب یک خط است: `npx @playwright/mcp@latest`. برای پروکسی `--proxy-server` کافی است؛ اگر نام کاربری و رمز عبور لازم باشد، گنجاندن آنها در نشانی به `ERR_INVALID_AUTH_CREDENTIALS` می‌انجامد و جای درست شیء `launchOptions.proxy` در فایل پیکربندی است. `--allowed-origins` قلمرو عامل را تنگ‌تر می‌کند، ولی تغییر مسیرها را در بر نمی‌گیرد و به گفته خود مستندات مرز امنیتی نیست؛ جداسازی را در سطح فرایند و شبکه بسازید. نسخه را ثابت کنید، کاوش را با عامل انجام دهید و کار تکراری را به اسکریپت بسپارید. انواع پروکسی مناسب برای نقطه خروج عامل خود را می‌توانید در [خدمات پروکسی ما](/fa/proxy) ببینید.