---
read_when:
    - اشکال‌زدایی نمای WebChat در مک یا پورت loopback
summary: برنامهٔ مک چگونه WebChat متعلق به Gateway را تعبیه می‌کند و چگونه می‌توان آن را اشکال‌زدایی کرد
title: وب‌چت (macOS)
x-i18n:
    generated_at: "2026-07-27T15:49:26Z"
    model: gpt-5.6
    postprocess_version: locale-links-v1
    prompt_version: 32
    provider: openai
    source_hash: b5e5983954e12d8546a01d089eda54e7eb0c60b4c92eff670f91797cd022c9fd
    source_path: platforms/mac/webchat.md
    workflow: 16
---

برنامه نوار منوی macOS رابط WebChat را به‌صورت یک نمای بومی SwiftUI در خود جای می‌دهد. این برنامه به Gateway متصل می‌شود و به‌طور پیش‌فرض از نشست اصلی عامل انتخاب‌شده استفاده می‌کند (`main`، یا هنگامی که `session.scope` برابر با `global` است، `global`).

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

- **نوار کناری نشست‌ها**: فهرست قابل‌جست‌وجوی نشست‌ها با بخش‌های سنجاق‌شده، گروه‌های پشتیبانی‌شده توسط Gateway و اخیر. نشست‌های فرزند ایجادشده در هر بخش زیر نشست والد خود قرار می‌گیرند؛ والدهای جمع‌شده خلاصه‌ای از فرزندان در حال اجرا، ناموفق و خوانده‌نشده را نشان می‌دهند. منوهای زمینه از نمایش اطلاعات نشست، تغییر نام، سنجاق‌کردن، انشعاب، خوانده‌شده/خوانده‌نشده، بایگانی/بازیابی، کپی کلید نشست و حذف پشتیبانی می‌کنند. کنش اصلی ایجاد نشست جدید (یا Shift-Cmd-N) بلافاصله از طریق `sessions.create` نشست را ایجاد می‌کند؛ پنجره بازشوی گزینه‌های کنار آن می‌تواند یک عامل را انتخاب کند و یک worktree مدیریت‌شده با base ref اختیاری درخواست دهد.
- **نوار ابزار پنجره**: حلقه مصرف زمینه (توکن‌ها و هزینه نشست، همراه با یک کنش فشرده)، کنترل‌های مدل و منوی کنش‌های نشست. مدل‌ها بر اساس ارائه‌دهنده گروه‌بندی می‌شوند و ارائه‌دهنده پیش‌فرض نخست قرار می‌گیرد، درحالی‌که مدل‌های سنجاق‌شده و اخیر در بالا باقی می‌مانند. کنترل‌ها می‌توانند سطح تفکر مدل را به ارث ببرند یا بازنویسی کنند، میزان جزئیات فراخوانی ابزار را انتخاب کنند و پاسخ‌های سریع را فعال یا غیرفعال کنند. منو می‌تواند نام نشست کنونی را تغییر دهد یا از آن انشعاب بگیرد و وضعیت سنجاق، خوانده‌شدن یا بایگانی آن را به‌روزرسانی کند. **نشست‌ها…** (Shift-Cmd-S) مدیر فعال/بایگانی‌شده را برای جست‌وجوی Gateway، مدیریت گروه، بررسی نشست، تغییر نام، سنجاق‌کردن، بایگانی و بازیابی باز می‌کند. حالت انتخاب، سنجاق‌کردن، برداشتن سنجاق، بایگانی یا حذف را روی چند نشست فعال اعمال می‌کند و درعین‌حال خطاهای منفرد را قابل‌مشاهده نگه می‌دارد. علامت‌های انتخاب جداگانه در منو استدلال دستیار و فعالیت ابزار را نشان می‌دهند یا پنهان می‌کنند؛ هر دو به‌طور پیش‌فرض فعال‌اند و در اجراهای بعدی به خاطر سپرده می‌شوند.
- **رونوشت و کادر نگارش**: پیام‌های دستیار به‌صورت متن ساده همراه با آواتار و پیام‌های کاربر به‌شکل حباب‌های رنگی نمایش داده می‌شوند. پرسش‌های در انتظار عامل به‌صورت کارت‌های بومی با گزینه‌های تک‌انتخابی یا چندانتخابی، پاسخ‌های متنی آزاد **سایر**، شمارش معکوس انقضا و وضعیت پایانی مشترک نمایش داده می‌شوند. گفت‌وگوهای خالی پیشنهادهای آغازین دسکتاپ را ارائه می‌کنند. تایپ `/` تکمیل خودکار دستورهای اسلش را که از `commands.list` پشتیبانی می‌شود باز می‌کند و امکان پیمایش با کلیدهای جهت‌نما/Tab/Return/Escape را فراهم می‌سازد. برای کپی Markdown قابل‌مشاهده یک پیام بدون استدلال پنهان، روی آن راست‌کلیک کنید. پیام‌های کوتاه‌شده دستیار همچنین گزینه **بازکردن پیام کامل** را ارائه می‌کنند که یک خوانشگر Markdown با قابلیت انتخاب متن بارگذاری می‌کند. برای TTS مبتنی بر Gateway همراه با گفتار محلی جایگزین، از **گوش‌دادن** استفاده کنید.
- **کنترل‌های صوتی**: کادر نگارش می‌تواند Talk Mode موجود macOS را بدون جایگزین‌کردن هم‌پوشانی نوار منوی آن آغاز یا متوقف کند. هنگامی که Talk Mode فعال است، کادر نگارش وضعیت گوش‌دادن/فکرکردن/صحبت‌کردن، فعالیت زنده صوتی و رونوشت چرخان قابل‌گسترش آن را نشان می‌دهد. برای انتخاب **System Default** یا یک میکروفون متصل، روی دکمه Talk راست‌کلیک کنید؛ Voice Wake و قابلیت فشردن برای صحبت نیز از همین انتخاب میکروفون استفاده می‌کنند. اگر میکروفون انتخاب‌شده قطع شود، نشست فعال Talk به پیش‌فرض سیستم برمی‌گردد و دفعه بعد که Talk Mode آغاز می‌شود دوباره انتخاب را امتحان می‌کند. هنگامی که Talk Mode ضبط صدا را در اختیار ندارد، یک کنش میکروفون جداگانه یادداشت صوتی ضبط می‌کند.

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

## چند پنجره Gateway

برای افزودن یا حذف نمایه‌های قابل‌استفاده مجدد Gateway، **Settings → Gateways** را باز کنید. هر
نمایه شامل یک نقطه پایانی شبکه خصوصی `ws://` یا امن `wss://` و
توکن یا گذرواژه اختیاری آن است؛ اعتبارنامه‌ها در macOS Keychain ذخیره می‌شوند.
نمایه‌های امن، پین گواهی نخستین استفاده مخصوص خود را که مشروط به اعتماد سیستم است نگه می‌دارند
و `gateway.remote.tlsFingerprint` را از Gateway اصلی به ارث نمی‌برند.
حذف یک نمایه همچنین پنجره‌های باز آن را می‌بندد و اتصال ثانویه آن را
خاموش می‌کند.

**File → New Gateway Window…** را انتخاب کنید یا Cmd-N را فشار دهید، سپس یکی از
نمایه‌های ذخیره‌شده را انتخاب کنید. انتخاب‌گر آخرین نمایه استفاده‌شده را به خاطر می‌سپارد. هر
انتخاب یک پنجره مستقل جدید ایجاد می‌کند؛ بنابراین یک Gateway می‌تواند در
چند پنجره با نشست‌های فعال و وضعیت پیمایش متفاوت ظاهر شود.

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

Gateway پیکربندی‌شده برنامه نوار منو همچنان مالک قابلیت‌های Node در Mac
و Talk Mode است. پنجره‌های اضافی Gateway فقط برای اپراتور هستند؛ بنابراین یک
Gateway دوم نمی‌تواند کنترل‌های سراسری میکروفون یا دستگاه را بی‌سروصدا به مقصد دیگری هدایت کند.
گوش‌دادن/TTS و کنش‌های عادی گفت‌وگو از اتصال Gateway همان پنجره استفاده می‌کنند.

## نوار گفت‌وگوی سریع

برای بازکردن یک کادر نگارش شناور برای نشست اصلی، Option-Space (⌥Space) را فشار دهید یا **گفت‌وگوی سریع** را از منوی نوار منو انتخاب کنید. میان‌بر سراسری را با ضبط‌کننده موجود در **Settings → General → Quick Chat shortcut** تغییر دهید.

گفت‌وگوی سریع عامل مقصد را نشان می‌دهد (آواتار یا ایموجی، با نام عامل به‌عنوان متن جای‌نگهدار) و پیام را به نشست اصلی آن عامل می‌فرستد. پس از آنکه Return ارسال را می‌پذیرد، نوار باز می‌ماند و با پاسخ Markdown جریانی و رونوشت اخیر به‌سمت پایین گسترش می‌یابد. ورودی نوار همچنان کادر نگارش باقی می‌ماند. برای ارسال و بازکردن همان مقصد در پنجره کامل گفت‌وگو Command-Return، برای خط جدید Shift-Return و برای بستن کل نوار و ناحیه پاسخ Escape را فشار دهید. کلیک بیرون نیز آن را می‌بندد. هنگامی که مجوزهای مرتبط macOS وجود ندارند، یک نوار پیوست‌شده کنش‌های **اعطای مجوز** و **اکنون نه** را ارائه می‌کند.

برای دیکته‌کردن در کادر نگارش از دکمه میکروفون استفاده کنید. نتایج جزئی گفتار، ضمن حفظ متنی که از قبل در کادر نگارش وجود داشت، بخش دیکته‌شده را به‌صورت زنده جایگزین می‌کنند. برای توقف، دوباره دکمه، Return یا Escape را فشار دهید؛ ارسال، پنهان‌کردن یا خارج‌کردن تمرکز از گفت‌وگوی سریع نیز میکروفون را آزاد می‌کند. نخستین استفاده، دسترسی به Microphone و Speech Recognition در macOS را درخواست می‌کند. گفت‌وگوی سریع از Apple Speech استفاده می‌کند و ممکن است از خدمات شبکه آن بهره ببرد؛ فقط Voice Wake غیرفعال به تشخیص روی دستگاه نیاز دارد.

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

برای انتخاب از میان پنج نشست با جدیدترین به‌روزرسانی یا بازگشت به **پیام جدید به &lt;agent&gt;**، روی دکمه تاریخچه کلیک کنید. انتخاب یک نشست اخیر، پیام را دقیقاً به همان نشست می‌فرستد و متن جای‌نگهدار را به **پاسخ در &lt;session&gt;** تغییر می‌دهد. پنهان‌کردن گفت‌وگوی سریع این مقصد موقت را به نشست اصلی عامل انتخاب‌شده بازنشانی می‌کند؛ تعویض عامل از منوی آواتار نیز آن را پاک می‌کند.

Command-Return گفت‌وگوی عاملی را که پیام را دریافت کرده است باز می‌کند، حتی هنگامی که محدوده نشست سراسری باشد.

دکمه دوربین منویی را برای **Capture Window…** یا **Capture Area…** باز می‌کند. ضبط پنجره به هر پنجره قابل‌مشاهده برچسب می‌زند؛ ضبط ناحیه هنگام کشیدن یک محدوده، هر نمایشگر را تیره می‌کند و اندازه زنده آن را نشان می‌دهد. تصویر صفحه انتخاب‌شده همراه با هر متن تایپ‌شده به‌عنوان زیرنویس آن، به عامل انتخاب‌شده ارسال می‌شود. نخستین استفاده، دسترسی Screen Recording در macOS را درخواست می‌کند. Escape، کلیک روی فضای خالی یا کلیک بدون کشیدن ناحیه‌ای معنادار عملیات را لغو می‌کند.

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

پس از پایان پاسخ، **چسباندن در &lt;app&gt;** را انتخاب کنید تا متن قابل‌مشاهده دستیار، به‌استثنای استدلال پنهان، در pasteboard عمومی کپی و در برنامه‌ای که در پیش‌زمینه بود جای‌گذاری شود. این قابلیت به مجوز Accessibility در macOS نیاز دارد. این کنش محتوای کنونی pasteboard را جایگزین و سپس گفت‌وگوی سریع را پنهان می‌کند.

این قابلیت را به‌طور کامل از طریق **Settings → General → Quick Chat** غیرفعال کنید؛ ضبط‌کننده میان‌بر نیز در همین بخش قرار دارد.

- **حالت محلی**: مستقیماً به WebSocket محلی Gateway متصل می‌شود.
- **حالت راه‌دور**: از مسیر مستقیم پیکربندی‌شده `ws://`/`wss://` یا تونل SSH مدیریت‌شده توسط برنامه به‌عنوان صفحه داده استفاده می‌کند.

## راه‌اندازی و اشکال‌زدایی

- دستی: منوی Lobster -> «بازکردن گفت‌وگو».
- بازشدن خودکار برای آزمایش:

  ```bash
  dist/OpenClaw.app/Contents/MacOS/OpenClaw --chat
  ```

  (`--webchat` به‌عنوان نام مستعار قدیمی پذیرفته می‌شود.)

- گزارش‌ها: `./scripts/clawlog.sh` (زیرسامانه `ai.openclaw`، دسته `WebChatSwiftUI`).

## نحوه اتصال اجزا

- صفحه داده: متدهای WS در Gateway شامل `chat.history`، `chat.message.get`، `chat.send`، `chat.abort`، `chat.inject`، به‌علاوه `question.list` و `question.resolve`، و رویدادهای `chat`، `agent`، `presence`، `tick`، `health` است؛ کارت‌های پرسش از رویدادهای `question.requested` و `question.resolved` پیروی می‌کنند و پس از اتصال مجدد از `question.list` تازه‌سازی می‌شوند.
- `chat.history` یک رونوشت عادی‌سازی‌شده برای نمایش برمی‌گرداند: تگ‌های دستور درون‌خطی از متن قابل‌مشاهده حذف می‌شوند، payloadهای XML فراخوانی ابزار در متن ساده (`<tool_call>`، `<function_call>`، `<tool_calls>`، `<function_calls>`، شامل بلوک‌های کوتاه‌شده) و توکن‌های کنترل مدل نشت‌کرده حذف می‌شوند، ردیف‌های دستیار که فقط شامل توکن سکوت‌اند، مانند `NO_REPLY`/`no_reply` دقیق، کنار گذاشته می‌شوند و ردیف‌های بیش‌ازحد بزرگ ممکن است با جای‌نگهدار کوتاه‌شده جایگزین شوند.
- نشست: همان‌طور که در بالا گفته شد، به‌طور پیش‌فرض نشست اصلی است؛ رابط کاربری می‌تواند بین نشست‌ها جابه‌جا شود.
- گروه‌های نشست: `sessions.groups.list`، `sessions.groups.put`، `sessions.groups.rename` و `sessions.groups.delete` مالک کاتالوگ گروه هستند. عضویت همان `category` نشست است که از طریق `sessions.patch` به‌روزرسانی می‌شود.
- وضعیت خوانده‌نشده: پس از فعال‌شدن یک نشست و بارگذاری موفق تاریخچه زنده آن، برنامه نشانگر خوانده‌نشده آن نشست را پاک می‌کند. بارگذاری‌های ناموفق تاریخچه آن را پاک نمی‌کنند؛ شکست موقت patch در فعال‌سازی بعدی دوباره امتحان می‌شود.
- فرایند آغاز به کار از یک نشست اختصاصی استفاده می‌کند تا راه‌اندازی اجرای نخست جدا باقی بماند.
- حافظه نهان آفلاین: برنامه برای هر Gateway یک حافظه نهان کوچک و فقط‌خواندنی از نشست‌ها و رونوشت‌های اخیر گفت‌وگو نگه می‌دارد (`~/Library/Application Support/OpenClaw/chat-cache.sqlite`): در بازشدن سرد، آخرین رونوشت شناخته‌شده بلافاصله نمایش داده می‌شود و پس از پاسخ Gateway تازه‌سازی می‌گردد، و گفت‌وگوهای اخیر هنگام قطع اتصال همچنان قابل‌مرور می‌مانند (ارسال تا بازگشت اتصال غیرفعال می‌ماند).

## سطح امنیتی

- حالت راه‌دور فقط پورت کنترل WebSocket در Gateway را از طریق SSH انتقال می‌دهد.

## محدودیت‌های شناخته‌شده

- رابط کاربری برای نشست‌های گفت‌وگو بهینه شده است، نه یک محیط ایزوله کامل مرورگر.

## مرتبط

- [WebChat](/fa/web/webchat)
- [برنامه macOS](/fa/platforms/macos)
