افزونه Chrome

افزونه Chrome در OpenClaw به عامل اجازه می‌دهد بدون راه‌اندازی یک مرورگر مدیریت‌شده جداگانه و بدون نمایش پیام مسدودکننده Chrome با عنوان "Allow remote debugging?"، برگه‌های واردشده به حساب در Chrome را کنترل کند.

این قابلیت زمانی اهمیت دارد که OpenClaw را از طریق تلفن (Telegram، WhatsApp و غیره) هدایت می‌کنید: پروفایل user از طریق درگاه اشکال‌زدایی از راه دور Chrome متصل می‌شود و یک کادر رضایت روی دسکتاپ نمایش می‌دهد که وقتی حضور ندارید، کسی نمی‌تواند روی آن کلیک کند. افزونه در عوض از API ‏chrome.debugger استفاده می‌کند؛ بنابراین تنها نشانه داخل صفحه، نوار قابل‌بستن Chrome با متن "OpenClaw started debugging this browser" است.

این همان ساختاری است که افزونه‌های Chrome مربوط به Claude از Anthropic و Codex از OpenAI استفاده می‌کنند.

نحوه کار

سه بخش وجود دارد:

• سرویس کنترل مرورگر (میزبان Gateway یا Node):‏ API که ابزار browser آن را فراخوانی می‌کند.
• رله افزونه (WebSocket حلقه‌بازگشت): سرور کوچکی که سرویس کنترل روی 127.0.0.1 راه‌اندازی می‌کند. این سرور یک نقطه پایانی Chrome DevTools Protocol در اختیار OpenClaw قرار می‌دهد و با افزونه ارتباط برقرار می‌کند. هر دو طرف با یک توکن محلی میزبان احراز هویت می‌شوند (پایین را ببینید).
• افزونه Chrome در OpenClaw (MV3): با استفاده از chrome.debugger به برگه‌ها متصل می‌شود، ترافیک CDP را انتقال می‌دهد و گروه برگه OpenClaw را مدیریت می‌کند.

OpenClaw فقط برگه‌های موجود در گروه برگه OpenClaw را می‌بیند و کنترل می‌کند. این گروه مرز رضایت است: برای اشتراک‌گذاری، برگه‌ای را به داخل آن بکشید و برای لغو فوری دسترسی، برگه را از آن خارج کنید (یا روی دکمه نوار ابزار کلیک کنید).

نصب و جفت‌سازی

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

   openclaw browser extension path

2. ‏chrome://extensions را باز کنید، Developer mode را فعال کنید، روی Load unpacked کلیک کنید و پوشه چاپ‌شده را انتخاب کنید.

3. رشته جفت‌سازی را چاپ کنید:

   openclaw browser extension pair

4. روی نماد OpenClaw در نوار ابزار کلیک کنید و رشته جفت‌سازی را در پنجره بازشو جای‌گذاری کنید. وقتی افزونه به رله متصل شود، نشان به حالت ON درمی‌آید.

توکن جفت‌سازی یک راز محلی میزبان است که در نخستین استفاده ایجاد و زیر credentials/ در پوشه وضعیت (با حالت 0600) ذخیره می‌شود. هر دستگاهی که مرورگر را اجرا می‌کند — میزبان Gateway و هر میزبان Node مرورگر — توکن مخصوص خود را دارد؛ بنابراین هیچ اعتبارنامه‌ای لازم نیست میان دستگاه‌ها جابه‌جا شود. برای چرخش آن، فایل browser-extension-relay.secret را حذف و دوباره جفت‌سازی کنید.

استفاده

پروفایل داخلی chrome را در فراخوانی ابزار browser انتخاب کنید یا آن را پیش‌فرض قرار دهید:

openclaw config set browser.defaultProfile chrome

{  browser: {    profiles: {      chrome: { driver: "extension", color: "#FF4500" },    },  },}

• اشتراک‌گذاری یک برگه: در همان برگه روی دکمه OpenClaw در نوار ابزار کلیک کنید (برگه به گروه برگه OpenClaw می‌پیوندد) یا هر برگه‌ای را به داخل گروه بکشید.
• عامل همچنین می‌تواند برگه‌های جدیدی باز کند؛ این برگه‌ها به‌طور خودکار در گروه قرار می‌گیرند.
• لغو دسترسی: دوباره روی دکمه کلیک کنید، برگه را از گروه بیرون بکشید یا نوار اشکال‌زدایی Chrome را ببندید. عامل بلافاصله دسترسی به آن برگه را از دست می‌دهد.

پنل کناری دستیار برگه

پس از جفت‌سازی افزونه، در پنجره بازشوی نوار ابزار آن روی باز کردن دستیار برگه کلیک کنید. OpenClaw برای همان برگه مشخص Chrome، ‏sidepanel.html را پیکربندی می‌کند؛ مانیفست هیچ مسیر سراسری برای پنل کناری ندارد. بنابراین هر برگه یک سند پنل، نشست Gateway، اشتراک پیام و اتصال نوع‌دار ابزار مرورگر جداگانه دریافت می‌کند.

پنل، نشانی URL صفحه، عنوان، DOM یا متن قابل‌مشاهده را در پیام شما قرار نمی‌دهد. فقط متنی را ارسال می‌کند که تایپ می‌کنید. کنش‌های مرورگر یک اتصال جداگانه و احرازشده توسط Gateway را حمل می‌کنند که شامل برگه Chrome و هدف CDP است؛ ابزار مرورگر نیز تلاش برای جایگزینی آن هدف یا استفاده از کنش‌های سراسری مرورگر را رد می‌کند. پاسخ‌ها در پنل (deliver: false) باقی می‌مانند و مسیر Telegram، ‏Discord یا کانال دیگری را به ارث نمی‌برند.

دستیار یک دستگاه اختصاصی و جفت‌شده Gateway با دامنه‌های operator.read و operator.write است. در نخستین استفاده، درخواست آن را بررسی و تأیید کنید:

openclaw devices listopenclaw devices approve <requestId>

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

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

بستن یک برگه بلافاصله اشتراک فعال آن را حذف می‌کند، هر اجرای قابل‌مشاهده را لغو می‌کند و نشست آن برگه را بایگانی‌شده علامت می‌زند. اگر Gateway موقتاً آفلاین باشد، افزونه بایگانی در انتظار را به‌صورت پایدار نگه می‌دارد و فقط زمانی دوباره تلاش می‌کند که همان نقطه پایانی Gateway متصل شود؛ افزونه هرگز درخواست بایگانی را به Gateway دیگری ارسال نمی‌کند. پس از خرابی مرورگر، اجرای بعدی نشست‌های باقی‌مانده از نمونه قبلی مرورگر را بایگانی می‌کند. نشست‌های بایگانی‌شده کار جدید را رد می‌کنند، اما رونوشت‌هایشان در تاریخچه نشست در دسترس می‌ماند. کلیدهای دستیار مرورگر، نشست‌های رشته‌ای هستند؛ بنابراین نگه‌داری عادی بر اساس سن و تعداد ورودی، آن‌ها را حفظ می‌کند. بودجه دیسک نشست برای هر عامل همچنان اعمال می‌شود (پیش‌فرض 2gb) و ممکن است هنگام فشار، قدیمی‌ترین نشست‌ها را حذف کند؛ نگه‌داری نشست را ببینید.

پنل کناری در حال حاضر به رله افزونه میزبانی‌شده توسط Gateway یا رله مستقیم Gateway از راه دور نیاز دارد. رله حلقه‌بازگشت روی Node مرورگر هنوز نمی‌تواند مسیر Node موردنیاز اتصال نوع‌دار برگه را فراهم کند؛ بنابراین پنل به‌جای بازگشت به مسیریابی سراسری مرورگر، این توپولوژی را رد می‌کند.

ارسال صفحه به OpenClaw

برای اشتراک‌گذاری متن خوانای صفحه با نشست اصلی OpenClaw، در پنجره بازشوی نوار ابزار از ارسال صفحه به OpenClaw استفاده کنید. می‌توانید یک یادداشت اختیاری اضافه کنید، از منوی راست‌کلیک صفحه یا بخش انتخاب‌شده استفاده کنید، یا Alt+Shift+S را فشار دهید. اگر انتخاب فعالی وجود داشته باشد، OpenClaw آن را ترجیح می‌دهد، اشتراک‌گذاری را به‌عنوان یک رویداد سیستمی در صف قرار می‌دهد و نشست اصلی را بلافاصله بیدار می‌کند.

لازم نیست برگه در گروه برگه OpenClaw باشد. این یک اشتراک‌گذاری صریح و یک‌باره است: هیچ بخش دیگری از صفحه افشا نمی‌شود و هیچ دسترسی مداومی اعطا نمی‌کند. Google Docs با استفاده از نشست واردشده مرورگر شما و بدون راه‌اندازی Google API به‌صورت متن ساده صادر می‌شود. رشته‌های X و Twitter بدون اجزای پیرامونی رابط کاربری استخراج می‌شوند.

متن صفحه در مرز ایمنی محتوای خارجی OpenClaw قرار می‌گیرد. یادداشت اختیاری شما به‌عنوان دستور خودتان بیرون از آن مرز باقی می‌ماند. متن صفحه و بخش‌های انتخاب‌شده به حدود 120,000 نویسه محدود می‌شوند و در صورت کوتاه‌شدن، نشانگر برش را دربر می‌گیرند.

اشتراک‌گذاری صفحه زمانی کار می‌کند که رله افزونه توسط Gateway میزبانی شود و از جفت‌سازی روی همان میزبان یا جفت‌سازی مستقیم Gateway از طریق wss:// استفاده کند. رله‌های میزبانی‌شده روی Node فعلاً خطایی روشن برمی‌گردانند. برای تغییر نگاشت میان‌بر صفحه‌کلید، chrome://extensions/shortcuts را باز کنید.

راه دور / میان‌دستگاهی

لازم نیست Chrome روی میزبان Gateway اجرا شود. سه توپولوژی کار می‌کنند:

• همان میزبان (Gateway و Chrome روی یک دستگاه): با openclaw browser extension pair روی همان دستگاه جفت‌سازی کنید. رله فقط روی حلقه‌بازگشت در دسترس است. اگر Gateway محلی از TLS استفاده می‌کند، نام میزبان گواهی آن را صریحاً با --gateway-url wss://gateway-host.example ارائه کنید؛ جفت‌سازی هرگز یک IP حلقه‌بازگشت را جایگزین نمی‌کند.
• اتصال مستقیم به Gateway راه دور (Chrome روی لپ‌تاپ شما، Gateway روی VPS و هیچ‌چیز دیگری روی لپ‌تاپ نیست): روی Gateway، ‏openclaw browser extension pair --gateway-url wss://your-gateway.example.com را اجرا کنید. این فرمان یک رشته wss://…/browser/extension#<secret> چاپ می‌کند؛ افزونه را روی لپ‌تاپ بارگذاری و جفت‌سازی کنید. افزونه از طریق wss:// مستقیماً به Gateway متصل می‌شود — بدون نصب OpenClaw، ‏Node، ‏CLI یا بازکردن درگاه ورودی روی لپ‌تاپ. این مسیر میزبانی مدیریت‌شده است.
• از طریق میزبان Node مرورگر (Chrome روی دستگاهی که از قبل یک Node متعلق به OpenClaw را اجرا می‌کند): ‏pair را روی Node اجرا و به‌صورت محلی جفت‌سازی کنید؛ Gateway کنش‌های مرورگر را از طریق پیوند احرازشده موجود Node به آن هدایت می‌کند.

راز جفت‌سازی برای هر میزبان جداگانه است (در حالت مستقیم، متعلق به Gateway) و مسیر /browser/extension در Gateway آن را اعتبارسنجی می‌کند. برای مسیر مستقیم، Gateway را از طریق TLS ‏(wss://) ارائه کنید تا راز جفت‌سازی و ترافیک CDP رمزگذاری شوند. راز در قطعه URL رشته جفت‌سازی باقی می‌ماند و هنگام دست‌دهی WebSocket به‌عنوان اعتبارنامه زیرپروتکل ارائه می‌شود؛ بنابراین گزارش‌های دسترسی معمول پراکسی آن را در URL درخواست دریافت نمی‌کنند. مطمئن شوید هر پراکسی معکوس، سرآیند استاندارد Sec-WebSocket-Protocol را حفظ می‌کند.

عیب‌یابی

openclaw browser status --browser-profile chromeopenclaw browser doctor --browser-profile chrome

doctor بررسی رله افزونه Chrome را تا زمانی که پنجره بازشوی افزونه وضعیت Connected را نشان دهد، ناموفق گزارش می‌کند.

مدل امنیتی

• رله فقط به حلقه‌بازگشت متصل می‌شود؛ هر دو سمت WebSocket با توکن مشتق‌شده احراز هویت می‌شوند و مبدأ سمت افزونه با chrome-extension:// بررسی می‌شود.
• جفت‌سازی مستقیم Gateway توکن رله را در URL درخواست نمی‌پذیرد؛ افزونه همراه‌شده در عوض آن را در فهرست زیرپروتکل WebSocket حمل می‌کند.
• عامل فقط می‌تواند برگه‌های موجود در گروه برگه OpenClaw را ببیند و کنترل کند. سایر برگه‌های شما خصوصی باقی می‌مانند.
• اجرای پنل کناری از دو جهت محدود می‌شود: تحویل Gateway از فهرست مجاز مخصوص هر نشست استفاده می‌کند و ابزارهای مرورگر اتصال برگه/هدف Chrome را که بیرون از پرامپت حمل می‌شود، اعمال می‌کنند.
• در مقایسه با پروفایل user ‏(Chrome MCP) که پس از تأیید پیام اشکال‌زدایی از راه دور، کل مرورگر واردشده شما را در معرض دسترسی قرار می‌دهد، افزونه سطح اشتراک‌گذاری‌شده را به گروهی از برگه‌ها محدود نگه می‌دارد که می‌توانید در یک نگاه کنترل کنید.

همچنین برای مدل کامل پروفایل و پروفایل‌های مدیریت‌شده openclaw و Chrome MCP ‏user، بخش مرورگر را ببینید.