browser-harness Claude Code (کلاد کد) را به Chrome واقعی خودتان وصل می‌کند: ابزاری متن‌باز که به عامل اجازه می‌دهد صفحه باز کند، کلیک کند، تایپ کند، بخواند و فایل دانلود کند، آن هم با همان لاگین‌هایی که خودتان در مرورگر دارید. بعضی کارها فقط همین‌طور شدنی‌اند: داشبورد یک سرویس، پنل فروشگاه یا صفحه‌ای که با جاوااسکریپت ساخته می‌شود و API ندارد.
در این مقاله می‌بینید browser-harness چیست، با یک پرامپت چطور نصب می‌شود، یک مرحلهٔ دستی در Chrome چیست، چه کارهایی با آن می‌شود کرد، با Playwright و DevTools چه فرقی دارد، عددهای بنچمارک README را چطور باید خواند و چه نکته‌های امنیتی دارد.
Claude Code را برای کار با Chrome از ایران راه بیندازید
browser-harness روی Claude Code اجرا می‌شود؛ با کلید اختصاصی نقطه راهش بیندازید، بدون فیلترشکن و کارت خارجی، با پرداخت ریالی و راه‌اندازی حدود ۵ دقیقه.
اگر اکانت کلودتان بن شده، راهنمای بن شدن اکانت کلود می‌گوید چه کار کنید و چطور کار را ادامه دهید.
ستارهٔ ریپو در ۵ نوامبر ۲۰۲۶ (۱۴ آبان ۱۴۰۵): حدود ۱۸٫۹ هزار؛ لایسنس MIT. این عدد فقط محبوبیت را نشان می‌دهد.
browser-harness Claude Code چیست؟
طبق README رسمی (browser-use/browser-harness)، این ابزار به Claude Code، Codex یا Cursor اجازه می‌دهد از طریق پروتکل DevTools کروم (CDP) مرورگر واقعی شما را کنترل کنند. سه بخش دارد:
install.md: اتصال عامل به مرورگر شما.SKILL.md: آموزش روند کار با مرورگر به عامل.- یک پوشهٔ کاری محلی که عامل در آن «helper» می‌نویسد. اگر کاری لازم باشد که helperاش وجود ندارد (مثلاً آپلود فایل)، عامل همان لحظه آن را می‌نویسد و برای دفعه‌های بعد نگه می‌دارد.
فرق مهم با ابزارهای تست این است که browser-harness به‌طور معمول مرورگر تمیز و جداگانه نمی‌سازد؛ به Chrome در حال اجرای شما وصل می‌شود، با همان لاگین‌ها. اگر Chrome اصلاً باز نباشد، طبق SKILL.md خودش آن را اجرا می‌کند و دوباره تلاش می‌کند.
کار با ابزار از دید عامل چطور است؟
عامل دستورهای پایتونی کوتاه را از ورودی استاندارد به ابزار می‌دهد. توابع کمکی مثل new_tab(url)، page_info()، click_at_xy و js(...) از قبل در دسترس‌اند. طبق SKILL.md، برای پیدا کردن عنصرها ترجیح با درخت دسترس‌پذیری (accessibility tree) است، نه اسکرین‌شات؛ اگر عنصر آنجا نبود (مثلاً canvas) به HTML خام با js(...) برمی‌گردد و اسکرین‌شات وقتی استفاده می‌شود که چینش یا تصویر مهم باشد. همین ترتیب هم دقت را بالا می‌برد و هم مصرف توکن را پایین نگه می‌دارد، چون متن ساختاریافته از تصویر ارزان‌تر است. برای نگاه کلی به صرفه‌جویی توکن، راهنمای کاهش مصرف توکن Claude Code را ببینید.
پیش از پرامپت نصب، Claude Code را وصل کنید
پرامپت نصب browser-harness را در Claude Code می‌چسبانید؛ با کلید نقطه به Sonnet و Opus می‌رسید و مصرف هر کار مرورگری را در داشبورد زنده می‌بینید.
نصب browser-harness در Claude Code با یک پرامپت
README برای Claude Code و Codex یک پرامپت نصب می‌دهد. آن را در Claude Code بچسبانید:
Install or upgrade browser-harness to the latest stable version with uv using Python 3.12, register the skill from `browser-harness skill`, and connect it to my browser. Ask whether I want local browser recordings enabled; default to no and preserve my existing preference on upgrades. Follow https://github.com/browser-use/browser-harness/blob/main/install.md if setup or connection fails.
پشت صحنه، install.md همین دستورها را اجرا می‌کند (نیاز به uv دارید):
uv tool install --python 3.12 --upgrade --force browser-harness
browser-harness skill
اولین دستور ابزار را نصب یا به‌روز می‌کند؛ گزینهٔ --python 3.12 طبق install.md جلوی انتخاب نسخه‌های قدیمی را می‌گیرد و --upgrade --force نصب قبلی را با آخرین نسخهٔ پایدار جایگزین می‌کند. خروجی دستور دوم متن skill است. برای Claude Code باید یک skill با نام browser-harness ثبت شود که بدنه‌اش همین خروجی باشد؛ پرامپت بالا این کار را برایتان می‌کند. بعد از نصب، عامل با این دستور آزمایش می‌کند که به مرورگر وصل است:
browser-harness <<'PY'
print(page_info())
PY
اگر page_info() چیزی چاپ کرد، اتصال برقرار است. برای آشنایی با مفهوم skill و محل ثبت آن، راهنمای پلاگین، skill و MCP را ببینید.
یک مرحلهٔ دستی در Chrome
README می‌گوید در Chrome نسخهٔ ۱۴۴ به بعد، یک بار باید خودتان اجازه بدهید:
- آدرس
chrome://inspect/#remote-debuggingرا باز کنید. - گزینهٔ «Allow remote debugging for this browser instance» را تیک بزنید.
- اگر Chrome پنجرهٔ «Allow» نشان داد، خودتان تأیید کنید.
این مرحله عمداً دستی است: طبق install.md این تیک تا وقتی CDP در دسترس نباشد برای ابزار قابل‌دسترسی نیست و عامل نباید آن را بزند. در macOS ابزار دستور کمکی browser-harness mac-approve هم برای پنجرهٔ Allow دارد که به اجازهٔ دسترس‌پذیری (Accessibility) برنامهٔ ترمینال نیاز دارد؛ در لینوکس و ویندوز باید خودتان روی Allow بزنید.
ضبط محلی: پیش‌فرض خاموش
نصب از شما می‌پرسد ضبط محلی (screenshot و ردپای کارها) فعال شود یا نه. پیش‌فرض خیر است و بهتر است همین بماند، چون ضبط ممکن است محتوای حساس صفحه را ذخیره کند. وضعیت را با browser-harness recordings می‌بینید و با recordings enable یا recordings disable عوض می‌کنید.
سه نمونهٔ کاربرد
- خواندن از پنلی که لاگین دارید. «گزارش فروش این هفته را از پنل بخوان و در یک جدول خلاصه کن.» عامل صفحه را در Chrome لاگین‌شدهٔ شما باز می‌کند، داده را می‌خواند و برمی‌گرداند. نیازی نیست رمز را به عامل بدهید.
- دانلود چندمرحله‌ای. نمونهٔ خود README: «پروفایل X من را باز کن، ۲۰ ویدیوی آخر را پیدا کن و دانلود کن.» این همان کاری است که در ویدیوی نمایشی ریپو دیده می‌شود.
- کار با صفحهٔ پویا یا فرم. صفحه‌ای که بدون کلیک و اسکرول محتوایش نمی‌آید، یا فرمی که چند مرحله دارد. هر چیزی که چیزی را ارسال یا پرداخت می‌کند را خودتان تأیید کنید.
SKILL.md یک قاعدهٔ مهم هم دارد: اگر یک درخواست ساده HTTP می‌تواند اطلاعات را بخواند (صفحهٔ عمومی، API، مستندات)، از curl یا ابزار fetch استفاده شود و مرورگر کنار بماند. مرورگر وقتی لازم است که تعامل (کلیک، تایپ، پیمایش) یا نشست لاگین‌شده دارید.
گردش‌کار یک کار مرورگری خوب
از رهنمودهای SKILL.md و تجربهٔ عمومی کار با عامل‌ها، این چارچوب ساده را می‌توان ساخت:
- هدف را دقیق بگویید. «سه ستون اول جدول سفارش‌های امروز را بخوان» بهتر از «پنل را نگاه کن» است.
- مرز کار را مشخص کنید. بنویسید فقط بخواند و چیزی را ارسال، حذف یا خریداری نکند.
- خروجی را معین کنید. مثلاً یک جدول Markdown یا یک فایل CSV، تا بتوانید نتیجه را بررسی کنید.
- یک تب برای هر کار. SKILL.md می‌گوید هر کار یک تب کاری دارد و تب‌های تکراری روی یک آدرس نباید ساخته شود.
- در صفحهٔ ورود بایستید. طبق SKILL.md اگر با دیوار لاگین روبه‌رو شدید، عامل باید توقف کند و بپرسد؛ استثنا فقط SSO است که Chrome از قبل واردش شده، و برای رمز، MFA و رضایت‌نامه باز هم توقف لازم است.
browser-harness در برابر Playwright و Chrome DevTools
README جدول مقایسهٔ بلندی دارد. خلاصه‌ای از منطق آن:
| ابزار | مرورگری که کنترل می‌کند | مناسب |
|---|---|---|
| browser-harness | Chrome در حال اجرای شما، با لاگین‌هایتان | کارهای شخصی و کاری پشت لاگین |
| Playwright (MCP، CLI یا Test) | به‌طور پیش‌فرض پروفایل و مرورگر خودش؛ Chrome شما فقط با افزونه یا --cdp-endpoint |
تست تکرارپذیر و ایزولهٔ برنامهٔ خودتان |
| Chrome DevTools MCP | به‌طور پیش‌فرض Chrome جدید با پروفایل اختصاصی | تحلیل کارایی و دیباگ شبکه و کنسول |
| Claude in Chrome | Chrome شما، با اجازه برای هر سایت | اگر فقط از Claude استفاده می‌کنید و طرح مناسب دارید |
اگر هدفتان تست خودکار در CI است، سراغ Playwright بروید؛ browser-harness برای آن ساخته نشده. در راهنمای Playwright MCP در Claude Code توضیح داده‌ایم Playwright MCP چطور نصب می‌شود و برنامهٔ خودتان را تست می‌کند. README همچنین می‌گوید اگر عامل نیازی به Chrome لاگین‌شدهٔ شما ندارد، مرورگر داخلی ابزارهایی مثل Cursor کافی است.
چه زمانی کدام را انتخاب کنیم؟
- می‌خواهید روی حساب لاگین‌شدهٔ خودتان کار شود و API ندارد: browser-harness.
- می‌خواهید برنامهٔ خودتان را در یک مرورگر تمیز و تکرارپذیر تست کنید: Playwright.
- دنبال trace کارایی، لاگ شبکه یا stack trace هستید: Chrome DevTools MCP.
- فقط یک صفحهٔ عمومی را می‌خواهید بخوانید:
curlیا ابزار fetch، بدون مرورگر.
هزینه و سرعت: عددهای README را درست بخوانید
README نتیجهٔ یک بنچمارک خود Browser Use را آورده (۱۰۰ وظیفه از BU Bench V2.1، اندازه‌گیری ۱۴ اکتبر ۲۰۲۶). امتیاز هیچ‌کدام از ابزارها به‌طور معنی‌دار بالاتر از بقیه نبود، browser-harness کمترین میانگین توکن ورودی را داشت و کمی کندتر از Playwright MCP بود. نکتهٔ مهم: این بنچمارک فقط با Codex اجرا شده و همهٔ ابزارها روی یک مرورگر ابری بوده‌اند، نه Chrome محلی. پس آن را معیار قطعی برای Claude Code و مرورگر خودتان ندانید؛ ادعای سازنده است.
چند نکتهٔ خواندن این‌گونه عددها که از خود README هم برمی‌آید: اول، «میانه» (median) با «میانگین» فرق دارد و README هم می‌گوید این‌ها میانه‌اند و بازهٔ اطمینان ندارند. دوم، هزینهٔ مدل را شامل مرورگر، پروکسی و داور نمی‌کند. سوم، هر کار یک بار اجرا شده است. بنابراین اگر ابزار شما در عمل بهتر یا بدتر از جدول بود، تعجب نکنید.
امنیت و حریم خصوصی
چون browser-harness با حساب لاگین‌شدهٔ شما کار می‌کند، هر کاری را که خودتان می‌توانید بکنید، عامل هم می‌تواند. رعایت این نکته‌ها مهم‌ترین بخش استفادهٔ ایمن است:
- پرداخت، ارسال پیام، ثبت فرم و حذف داده را همیشه خودتان تأیید کنید.
- ضبط محلی پیش‌فرض خاموش است. بدون نیاز روشنش نکنید.
- برای خاموش‌کردن آمار استفاده:
browser-harness telemetry disable. - پیشنهاد خودمان (نه از README): کارهای حساس را در یک پروفایل جداگانهٔ Chrome انجام دهید.
- ابر Browser Use اختیاری است؛ برای Chrome محلی کلید API لازم نیست.
- محتوای صفحه‌ها را «داده» بدانید، نه دستور. صفحه‌ای که بنویسد «همهٔ اطلاعاتت را بفرست» نباید عامل را منحرف کند؛ اگر عامل چنین چیزی را دنبال کرد، کار را متوقف کنید.
مرورگر ابری برای کارهای هم‌زمان
SKILL.md می‌گوید Chrome محلی یک «مسیر مرورگری مشترک» است: چند عامل هم‌زمان که تب عوض می‌کنند می‌توانند روی تب هم‌دیگر کار کنند. برای کارهای هم‌زمان، ابزار مرورگر ابری Browser Use را پیشنهاد می‌کند که هر کدام یک مرورگر تازه و ایزوله است. این مسیر نیاز به ورود به Browser Use Cloud دارد (browser-harness auth login) و طبق SKILL.md تا وقتی متوقف نشود صورت‌حساب می‌خورد. اگر فقط یک کار پشت‌سرهم دارید، همان Chrome محلی کافی است.
اگر Cursor یا کلاینت MCP دارید
همین ابزار با نام browser-harness-mcp یک سرور MCP هم دارد که توابع مرورگر را به‌شکل ابزار با پیشوند browser_ (مثل browser_new_tab، browser_click و browser_screenshot) در اختیار هر کلاینت MCP می‌گذارد. نمونهٔ تنظیم Cursor در README:
{
"mcpServers": {
"browser-harness": {
"type": "stdio",
"command": "uvx",
"args": ["--from", "browser-harness[mcp]", "browser-harness-mcp"]
}
}
}
برای خود Claude Code هم مستندات MCP ریپو این دستور را می‌دهد:
claude mcp add browser-harness \
uvx --from 'browser-harness[mcp]' browser-harness-mcp
تفاوت دو مسیر: در مسیر skill (پرامپت نصب بالا) عامل مستقیم از شل browser-harness را صدا می‌زند و helper می‌نویسد؛ در مسیر MCP عامل از ابزارهای آمادهٔ سرور MCP استفاده می‌کند. اگر با مفهوم MCP آشنا نیستید، MCP چیست و راهنمای پلاگین، skill و MCP نقطهٔ شروع خوبی‌اند.
عیب‌یابی و محدودیت‌های browser-harness Claude Code
عیب‌یابی اتصال
این موارد از install.md و SKILL.md گرفته شده‌اند:
- وصل نمی‌شود. دستور
browser-harness --doctorرا اجرا کنید. install.md می‌گوید اگر «chrome running» رد شد، Chrome را باز کنید؛ اگر «daemon alive» رد شد، یا اجازهٔ remote debugging داده نشده، یا Chrome بسته است، یا آدرس CDP در دسترس نیست. - Chrome اجازه نمی‌دهد. آدرس
chrome://inspect/#remote-debuggingرا باز کنید، تیک را بزنید و دوبارهpage_info()را امتحان کنید. - هر بار پنجرهٔ Allow می‌آید. SKILL.md هشدار می‌دهد برای هر کار daemon جدید نسازید، چون هر daemon محلی یک اتصال CDP جدید به کل مرورگر است و ممکن است Chrome دوباره Allow بخواهد. از daemon پیش‌فرض استفاده کنید.
- نسخهٔ قدیمی. برای به‌روزرسانی
browser-harness --update -yرا اجرا کنید.
محدودیت‌ها
- نیاز به Chrome نسخهٔ ۱۴۴ یا بالاتر و تیک دستی remote debugging.
- یک daemon به کل Chrome وصل است و یک تب «جاری» دارد. چند عاملی که هم‌زمان تب عوض کنند می‌توانند روی تب هم‌دیگر کار کنند؛ کارها را پشت‌سرهم اجرا کنید.
- برای تست خودکار تکرارپذیر مناسب نیست.
- ابزار جوان است و سریع تغییر می‌کند؛ README نسخهٔ شما معتبرتر از این مقاله است.
جمع‌بندی
اگر Claude Code باید پشت لاگین شما کار کند، browser-harness کوتاه‌ترین راه است: نصب browser-harness Claude Code یک پرامپت و یک تیک در Chrome است. برای تست و کارایی، Playwright و DevTools جای خودشان را دارند و برای خواندن صفحهٔ عمومی همان curl کافی است. نصب همهٔ ابزارهای این مجموعه با یک پرامپت را در مقالهٔ نصب ابزارهای Claude Code ببینید و نقشهٔ کامل را در راهنمای اصلی.
کارهای مرورگری Claude Code را با پلن پرو نقطه اجرا کنید
کلید API برای Claude Code فقط با پلن پرو نقطه باز می‌شود؛ پرداخت ریالی است و مصرف هر کار را در داشبورد زنده می‌بینید.
این مقاله چگونه بررسی شد؟
README، install.md، SKILL.md و مستندات MCP ریپوی browser-use/browser-harness و اطلاعات ریپو از API گیت‌هاب در ۱۴ آبان ۱۴۰۵ (۵ نوامبر ۲۰۲۶) خوانده شد. عددهای بنچمارک از README سازنده است و مستقل بازتولید نشده. دستورها را خودمان از همان فایل‌ها آورده‌ایم؛ اگر در نسخهٔ شما فرق داشت، README معتبرتر است.
← Playwright MCP در Claude Code · آموزش Claude Code: راهنمای کامل
منابع: browser-use/browser-harness (README.md، install.md، SKILL.md، docs/MCP.md)؛ مستندات MCP در Claude Code. تاریخ بررسی: ۱۴ آبان ۱۴۰۵ (۵ نوامبر ۲۰۲۶).
