---
read_when:
    - در حال پیاده‌سازی یا بازبینی مرحله‌ای از بازطراحی فرایند آغاز به کار هستید
summary: طرح پیاده‌سازی بازطراحی فرایند ورود به کار متولی (سند زنده)
title: بازطراحی فرایند راه‌اندازی اولیه
x-i18n:
    generated_at: "2026-07-27T16:17:42Z"
    model: gpt-5.6
    postprocess_version: locale-links-v1
    prompt_version: 32
    provider: openai
    source_hash: f892991583d0b77a670e9bf7aa5a0c74af3b3eac9e7b0448706486254eb7e2a0
    source_path: start/onboarding-redesign.md
    workflow: 16
---

# برنامه پیاده‌سازی بازطراحی راه‌اندازی اولیه

> **سند زنده.** این صفحه بازطراحی راه‌اندازی اولیه متولی را در سطح
> پیاده‌سازی دنبال می‌کند و با نهایی‌شدن هر مرحله به‌روزرسانی می‌شود. وقتی آخرین مرحله
> ادغام شود، این صفحه به‌عنوان راهنمای کاربرمحور راه‌اندازی اولیه بازنویسی می‌شود و به
> پیمایش مستندات می‌پیوندد. تا آن زمان، عمداً در `docs.json` قرار ندارد.

## هدف نهایی

یک کاربر غیرفنی `openclaw onboard` را وارد می‌کند (یا برنامه را باز می‌کند) و با
یک حضور مکالمه‌ای واحد روبه‌رو می‌شود — OpenClaw، متولی سیستم («متولی» فقط
نام داخلی است؛ کاربر همیشه «OpenClaw» را می‌بیند) — که هوش مصنوعی او را پیدا می‌کند،
همه‌چیز را با پیش‌فرض‌های اعلام‌شده به‌جای پرسش تنظیم می‌کند، عامل او را در قالب لحظه‌ای
مشهود برای شکل‌گیری هویت متولد می‌کند و از آن پس برای همیشه به‌عنوان
مراقب سیستم در دسترس می‌ماند. به‌طور پیش‌فرض جادویی، با یک مرز رضایت و بدون بن‌بست.

اصول طراحی (تصمیم‌گیری شده‌اند؛ بی‌دلیل دوباره به بحث گذاشته نشوند):

- **پیش‌فرض‌های اعلام‌شده با امکان بازگردانی آسان** جایگزین پرسش‌های مسدودکننده می‌شوند. تنها
  الزام قطعی، استنتاجِ کارآمد است؛ هر چیز دیگر یک پیشنهاد است.
- **پرسش صفر مرز رضایت است**: «دسترسی کامل» (توصیه‌شده) یعنی
  کشف بی‌صدا و خودکار انجام می‌شود؛ «ابتدا بپرس» همه انواع کشف — اسکن
  هوش مصنوعی، اسکن برنامه‌ها و اسکن منابع حافظه — را به یک
  تأیید صریح وابسته می‌کند و مسیری کاملاً دستی نیز فراهم است که هرگز اسکن نمی‌کند.
- **مکالمه به‌عنوان رابط کاربری با هوشمندی تدریجی**: سطح متولی
  پیش از کارکردن هرگونه هوش مصنوعی وجود دارد (گفت‌وگوی اسکریپت‌شده)، به‌محض
  تأیید یک مسیر از مدل پشتیبانی می‌گیرد و این موضوع را آشکارا اعلام می‌کند. هرگز تظاهر به هوشمندی نمی‌کند:
  ورودی متنی آزاد پیش از تأیید مسیر، با پیام محترمانه «بگذارید ابتدا مغزم را
  راه بیندازم» پاسخ داده می‌شود.
- **تولد یک آیین است**: همان رشته، تعویض آواتار، عامل خودش را نام‌گذاری
  می‌کند و چهره‌اش را خودش برمی‌گزیند. متولی سلسله‌مراتب را یک‌بار آموزش می‌دهد: «درباره
  سیستم از من بپرسید، یا فقط از عامل خود بپرسید — او منتقل می‌کند.»
- **اعتماد بر اساس منبع سطح‌بندی می‌شود**: ورودی‌های کاتالوگ رسمی ممکن است از پیش انتخاب شوند؛
  Skills شخص ثالث ClawHub صرف‌نظر از رتبه‌بندی مدل هرگز از پیش انتخاب
  نمی‌شوند و برچسب آن‌ها اعلام می‌کند که کد ناشر را نصب می‌کنند.
- **نصب‌های پیکربندی‌شده مقدس‌اند**: اجرای دوباره راه‌اندازی اولیه یک مرحله
  تأیید است. هرگز تنظیمات را دوباره اعمال نمی‌کند و سرویس Gateway را هرگز بازراه‌اندازی نمی‌کند.
- **ترمینال مسیر جایگزین است، نه یک پرسش**: وقتی Gateway در دسترس است،
  داشبورد مرورگر ترجیح داده می‌شود؛ هرگز پرسیده نمی‌شود «ترمینال یا مرورگر؟».
- **مدل‌های ضعیف سطحی مختصرشده دریافت می‌کنند** (`localModelLean` خودکار)، که با
  واژه‌های ساده توضیح داده می‌شود — هرگز با اصطلاحات ابزارها، حالت کد یا پنجره‌های زمینه بیان نمی‌شود.

## جریان منتشرشده فعلی (پس از مراحل 1 تا 3)

`openclaw onboard` در یک نصب تازه macOS، در مسیر موفق — در مجموع چهار بار Enter:

1. یادداشت امنیتی ← یک Enter برای تأیید (ذخیره می‌شود؛ دیگر هرگز پرسیده نمی‌شود).
2. **پرسش صفر**: «چگونه همه‌چیز را تنظیم کنم؟» — دسترسی کامل (توصیه‌شده)
   یا ابتدا بپرس. انتخاب در `wizard.accessMode` ذخیره می‌شود؛ در اجرای مجدد، انتخاب
   ذخیره‌شده پیش‌فرض است. حالت محافظت‌شده + «پیکربندی دستی» بدون
   هیچ‌گونه اسکن به انتخاب‌گر ارائه‌دهنده می‌رسد و اسکن منابع حافظه را نیز رد می‌کند.
3. **نمایش کشف**: CLIهای کدنویسی، کلیدهای محیطی و زمان‌های اجرای محلی را شناسایی می‌کند؛
   هنگام یافتن عامل‌های کدنویسی توضیحی کوتاه می‌دهد؛ نامزدها را به‌ترتیب به‌صورت زنده
   آزمایش می‌کند و شکست‌ها را بی‌سروصدا در یک خط خلاصه گردآوری می‌کند (جزئیات پشت
   «مشاهده گزینه‌های دیگر»). نخستین مسیر کارآمد به‌عنوان پیش‌فرض اعلام می‌شود و
   مسیری تک‌کلیدی به انتخاب‌گر کامل وجود دارد؛ کاوش و ردکردن، مسیر
   کارآمد را حفظ می‌کند.
4. پیشنهاد واردکردن حافظه (Claude Code / Codex / Hermes)، که در صورت ردشدن کشف
   از آن صرف‌نظر می‌شود.
5. فقط نصب‌های تازه: برنامه استاندارد تنظیمات به‌طور خودکار اعمال می‌شود
   (فضای کاری، سرویس Gateway، نشست‌ها — همان برنامه‌ای که «بله» مکالمه‌ای
   اجرا می‌کند). نصب‌های پیکربندی‌شده پیام «از قبل تنظیم شده است» را نمایش می‌دهند و هرگز
   به سرویس دست نمی‌زنند.
6. **توصیه‌های برنامه**: برنامه‌های نصب‌شده که مدل تأییدشده
   با کاتالوگ‌های رسمی + ClawHub تطبیق داده است؛ Pluginهای رسمی کانال
   از پیش علامت‌خورده‌اند و Skills شخص ثالث با برچسب هشدار نیازمند انتخاب‌اند. قابل ردکردن؛
   کلید قطع `wizard.appRecommendations`.
7. **تولد**: وقتی Gateway در دسترس باشد، تحویل به مرورگر باز می‌شود (GUI) یا
   نشانی URL داشبورد نمایش داده می‌شود (بدون رابط گرافیکی/SSH) و تا اتصال Control UI
   منتظر می‌ماند — «داشبورد متصل شد — ادامه در مرورگر.» در غیر این صورت، یا
   با `--tui`، TUI ترمینال با پیام تولد آغازین اولیه
   باز می‌شود و عامل خودش را معرفی می‌کند.

راه‌اندازی اولیه Gateway راه‌دور، تحویل مکالمه‌ای قدیمی خود را حفظ می‌کند
(`handoffMode: "chat"`)؛ تنظیمات باید روی Gateway راه‌دور اعمال شوند.

## مراحل

| #   | مرحله                                                                                                                                                     | سطح                 | وضعیت                                                                                                                            |
| --- | --------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------- | -------------------------------------------------------------------------------------------------------------------------------- |
| 1   | توصیه‌های Plugin بر اساس برنامه‌های نصب‌شده (اسکن، نامزدها، تطبیق‌دهنده هوش مصنوعی، مرحله جادوگر، فرمان Node ‏`device.apps`)                              | CLI کلاسیک + هدایت‌شده | ادغام‌شده ([#109668](https://github.com/openclaw/openclaw/pull/109668))                                                          |
| 2   | ستون فقرات متولی CLI (پرسش صفر، نمایش کشف، اعمال خودکار + تولد)                                                                                           | CLI هدایت‌شده       | ادغام‌شده ([`a83ed13204f1`](https://github.com/openclaw/openclaw/commit/a83ed13204f118adf1009e5ac88d5afe1905b86c))               |
| 3   | تحویل با اولویت مرورگر (تشخیص نشست GUI، انتظار برای اتصال داشبورد، TUI به‌عنوان مسیر جایگزین)                                                             | CLI ← وب             | ادغام‌شده ([#110054](https://github.com/openclaw/openclaw/pull/110054))                                                          |
| 4   | سطح وب متولی (کارت‌های گزینه، فیلد نوع‌دار `question` در `openclaw.chat`، بازتاب مراحل جادوگر، تحویل اجرای نخست)                                   | Control UI          | ادغام‌شده ([#110141](https://github.com/openclaw/openclaw/pull/110141)، [#110242](https://github.com/openclaw/openclaw/pull/110242)) |
| 5   | تولد و راه‌اندازی اولیه (ذخیره توصیه‌ها با معنای یک‌بار اجرا، توالی تولد با نام‌گذاری خودکار، تحویل خودکار تولد پس از تنظیم تازه؛ نردبان آواتار به تعویق افتاده) | راه‌اندازی عامل     | ادغام‌شده ([#110173](https://github.com/openclaw/openclaw/pull/110173)، [#110331](https://github.com/openclaw/openclaw/pull/110331)) |
| 6   | حضور متولی PR1 (ورودی سنجاق‌شده نوار کناری، «از OpenClaw بپرسید» در تنظیمات، خوشامدگویی مراقب با ظاهر عادی؛ توضیح رویداد و فراخوانی کانال در PR2)             | وب + کانال‌ها       | ادغام‌شده ([#110269](https://github.com/openclaw/openclaw/pull/110269))                                                          |
| 7   | تاب‌آوری (دسترسی به متولی هنگام خرابی پیکربندی، بازیابی سطح جزئی، پزشک خودکار)                                                                             | Gateway             | پیگیری                                                                                                                           |

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

### مرحله 1 — توصیه‌های برنامه (PR #109668)

- اسکنر: `src/infra/installed-apps.ts` (شمارش macOS بدون نیاز به TCC؛ بسته‌های
  پیوند نمادین `.app` را دنبال می‌کند).
- نامزدها: کاتالوگ‌های رسمی + جست‌وجوی ClawHub، بودجه کلی 20s، کاهش کارکرد
  آفلاین به‌صورت تدریجی تا نامزدهای صرفاً کاتالوگی. ورودی‌های کاتالوگ، مانیفست‌های بسته
  بدون `id` در سطح بالا هستند — نامزدها با شناسه Plugin حل‌شده
  کلیدگذاری می‌شوند (در برابر کاتالوگ‌های بسته‌بندی‌شده واقعی آزمون رگرسیون شده است؛ کلیدگذاری با
  `entry.id` زمانی کل کاتالوگ را به یک مورد فروکاست و همه توصیه‌های
  رسمی را حذف کرد).
- تطبیق‌دهنده هوش مصنوعی: یک تکمیل در مسیر تأییدشده
  (`src/system-agent/setup-app-recommendations.ts`)؛ بدون نگاشت دست‌چین‌شده شناسه بسته —
  مدل هم‌پوشانی‌های تصادفی نام را رد می‌کند. خروجی به بودجه
  `maxTokens` خود مدل حل‌شده محدود می‌شود (لایه جریان وقتی سقف
  صریحی ارسال نشده باشد آن را اعمال می‌کند).
- **محافظ زنجیره تأمین**: متن فهرست ClawHub تحت کنترل ناشر است و
  به اعلان تطبیق‌دهنده می‌رسد، بنابراین یک فهرست می‌تواند خود را
  «توصیه‌شده» معرفی کند. فقط ورودی‌های کاتالوگ رسمی ممکن است از پیش انتخاب شوند؛ Skills
  متعلق به ClawHub همیشه به علامت‌زدن صریح نیاز دارند و با عبارت «Skill شخص ثالث ClawHub؛
  کد ناشر خود را نصب می‌کند» برچسب‌گذاری می‌شوند.
- فرمان Node ‏`device.apps` (میزبان Node مبتنی بر TS، هم‌ترازی پاکت Android)، اشتراک‌گذاری
  به‌طور پیش‌فرض خاموش است؛ کلید قطع Gateway ‏`wizard.appRecommendations`.
- ارائه در جادوگر کلاسیک و جریان متولی هدایت‌شده انجام می‌شود
  (`src/wizard/setup.app-recommendations.ts`)؛ انتقال هدف به انتهای راه‌اندازی اولیه
  همچنان برای مرحله 5 باقی می‌ماند (سرویس از قبل یک منبع موجودی تزریق‌پذیر
  می‌پذیرد). معنای یک‌بار اجرا (پیشنهاد فقط تا زمان پذیرش، اسکن ذخیره‌شده) نیز
  همراه با مخزن مرحله 5 ارائه می‌شود؛ در حال حاضر اجرای مجدد دوباره پیشنهاد می‌دهد.
- همچنین اصلاح شد: اعلان‌های سفارشی `completeSetupInference` دیگر سقف خروجی
  32 توکنیِ کاوشگر تأیید را به ارث نمی‌برند (`SETUP_INFERENCE_TEST_MAX_TOKENS`
  فقط برای کاوشگر «با OK پاسخ بده» اعمال می‌شود).

### مرحله 2 — ستون فقرات متولی CLI (PR #109841)

- بازطراحی جریان در `src/commands/onboard-guided.ts`؛ راه‌اندازی اولیه Gateway راه‌دور
  تحویل گفت‌وگوی قدیمی خود را از طریق `handoffMode: "chat"` حفظ می‌کند.
- پرسش صفر `wizard.accessMode` ("full" | "guarded") را ذخیره می‌کند؛ اجرای مجدد
  به‌طور پیش‌فرض از انتخاب ذخیره‌شده استفاده می‌کند (پذیرش پیش‌فرض هرگز نمی‌تواند حالت محافظت‌شده را بی‌صدا
  به دسترسی کامل تنزل دهد). حالت محافظت‌شده + دستی از
  `listManualSetupInferenceOptions` استفاده می‌کند (فقط پیکربندی/مانیفست‌ها، بدون کاوش) و
  اسکن منابع حافظه را رد می‌کند.
- کشف: گردآوری بی‌صدای شکست‌ها (یک خط خلاصه؛ جزئیات پشت
  «مشاهده گزینه‌های دیگر»)، توضیح کوتاه عامل کدنویسی، پیش‌فرض مسیر اعلام‌شده. شمار
  نشست‌ها در این توضیح تا زمان وجود یک درز کم‌هزینه
  برای شمارش نشست به تعویق افتاده است (فعلاً فقط کیفی).
- نصب‌های تازه: `applySystemAgentSetup` («بله» مکالمه‌ای قطعی)، سپس تولد
  از طریق `launchTuiCli` که با پیام راه‌اندازی اولیه مقداردهی شده است.
  نصب‌های پیکربندی‌شده (پیکربندی از پیش موجود مدل یا Gateway — مُهرهای زمانی
  جادوگر چیزی را ثابت نمی‌کنند، زیرا با configure/doctor مشترک‌اند):
  فقط تأیید — بدون اعمال و بدون بازراه‌اندازی سرویس Gateway. شکست در اعمال
  به گفت‌وگوی مکالمه‌ای بازمی‌گردد.

### مرحله 3 — تحویل با اولویت مرورگر (PR #110054، ادغام‌شده)

- `src/commands/onboard-browser-handoff.ts` مسئول تشخیص صرفِ نشست گرافیکی
  است (`SSH_CONNECTION`/`SSH_TTY`؛ `DISPLAY`/`WAYLAND_DISPLAY` در Linux)
  و انتظار 60ثانیه‌ای GUI / 300ثانیه‌ای SSH را مدیریت می‌کند. راه‌اندازی هدایت‌شده درحال‌حاضر
  واگذاری را فقط در macOS فعال می‌کند؛ `--tui` و سایر پلتفرم‌ها مسیر خروجی
  ترمینال را حفظ می‌کنند. فعال‌سازی Linux/Windows در پیگیری بعدی انجام می‌شود.
- پیوندهای داشبورد از همان تابع‌های کمکی `resolveAdvertisedControlUiLinks`،
  `resolveLocalControlUiProbeLinks` و `buildOnboardingControlUiUrl`
  نهایی‌سازی کلاسیک استفاده می‌کنند. راه‌اندازی مرورگر از تابع کمکی مشترک `openUrl` استفاده می‌کند.
- آمادگی، RPC موجود `system-presence` را به‌صورت یک **کلاینت loopback در حالت CLI
  که راز مشترک پیکربندی‌شده را ارائه می‌کند** پایش می‌کند — همان مسیر مورداعتمادی که همهٔ
  فرمان‌های `openclaw` استفاده می‌کنند. یک کلاینت Control UI با احراز هویت مشترک خام
  در Gatewayهای SecretRef با پیام «هویت دستگاه الزامی است» رد می‌شود. پیش‌بررسی
  دسترس‌پذیری همان مقصد (و راز) حلقهٔ انتظار را برطرف می‌کند، بنابراین
  دروازه و انتظار هرگز نمی‌توانند دربارهٔ احراز هویت اختلاف داشته باشند. واگذاری تنها
  زمانی کامل می‌شود که یک ردیف حضور متصل `openclaw-control-ui`/`webchat` نسبت
  به خط مبنای پیش از راه‌اندازی جدید باشد (داشبوردی که از قبل باز است نمی‌تواند
  آن را کامل کند).
- `gateway.controlUi.enabled: false` پیش از نمایش هر URL مسیر را کوتاه می‌کند.
- به‌صورت سرتاسری در برابر یک Gateway ایزوله با همان پیکربندی اثبات شد: چاپ URL ← اتصال واقعی
  مرورگر ← «داشبورد متصل شد — در مرورگر خود ادامه دهید» ← بدون
  مسیر خروجی ترمینال. توقف پیشین بر اثر «عدم تطابق توکن» یک مصنوع
  مهار آزمون بود — راهنمای آزمون زیر را ببینید.

### فاز 4 — سطح متولی وب (ادغام‌شده: #110141، #110242)

- صفحهٔ `/custodian` روی `openclaw.chat` با مؤلفهٔ کارت گزینه
  (2-4 کارت، حداکثر یک مورد پیشنهادی، همیشه قابل رد کردن)؛ پوستهٔ راه‌اندازی از طریق
  `?onboarding=1`؛ تکمیل اجرای نخست تنظیم مدل، کار را به آن واگذار می‌کند.
- پرسش‌های ساختاریافته یک فیلد افزایشی نوع‌دار `question` روی
  `SystemAgentChatResult` هستند (متن `reply` برای هر گزینه؛ نثر برای
  برنامهٔ macOS/TUI همیشه مستقل می‌ماند). تولیدکنندگان: هر دو گونهٔ خوشامدگویی راه‌اندازی و
  مراحل انتخاب/تأیید ویزارد میزبانی‌شده با 2-4 گزینهٔ بسته — ویزاردهای واقعی کانال
  به‌شکل کارت رندر می‌شوند. راه‌حل موقت نشانگر رشته‌ای PR1 حذف شد.
- مالکیت نشست به URL دروازه + تمام اعتبارنامه‌های ارائه‌شده محدود می‌شود
  (توکن، گذرواژه، توکن bootstrap، توکن ذخیره‌شدهٔ دستگاه — در افت‌های
  گذرای hello پایدار می‌ماند)؛ نوبت‌های ناموفق کاربر هرگز قابل بازپخش نیستند؛ ورودی
  حساس عیناً ارسال و در رونوشت پوشانده می‌شود.

### فاز 5 — خروج و bootstrap (ادغام‌شده: #110173، #110331)

- متولی یک عامل بی‌نام ایجاد می‌کند (فراخوانی ابزار)؛ bootstrap عامل با
  نام‌گذاری خود آغاز می‌شود. PR1 این آیین را به سه ضرب محدود می‌کند (نام ← خط
  روح ← پرسش Skills) و نردبان آواتار خودترسیم‌شده/تولید تصویر
  (نامزدهای تولیدشده توسط مدل ← نشان‌های ازپیش‌تنظیم‌شده ← حفظ لوگو) را به پیگیری بعدی
  موکول می‌کند. همان رشته، تعویض آواتار؛ نشان چنگال برای متولی محفوظ می‌ماند. هویت
  موردتوافق دو بار ماندگار می‌شود: در `IDENTITY.md`/`SOUL.md` (آنچه عامل
  می‌خواند) و از طریق `openclaw agents set-identity` (آنچه کانال‌ها و UI
  نمایش می‌دهند).
- پیشنهادها (سرویس فاز 1، پویش ذخیره‌شده با معنای یک‌بار اجرا) به‌عنوان
  آخرین گام bootstrap پیش از حذف فایل bootstrap ارائه می‌شوند: «مجموعهٔ حداقلی
  یا حداکثر راحتی؟» bootstrap پیشنهاد ذخیره‌شده را از طریق
  `openclaw onboard recommendations --json` می‌خواند (فقط شناسه‌های نصب مات) و
  پس از رسیدگی به انتخاب، دریافت آن را تأیید می‌کند تا هرگز دوباره نپرسد. دکمه‌های
  اتصال کانال برای هر کانال راهنمای تنظیم دارند؛ عامل اعتبارنامه‌ها را
  محاوره‌ای جمع‌آوری می‌کند و نوشتن پیکربندی را به متولی می‌سپارد
  («در حال پرسیدن از OpenClaw…» عبارت معیار است).
- خودآموزی پرسیده می‌شود، نه اعلام، و هم‌زمان رضایت برای کارگاه Skills
  نیز محسوب می‌شود؛ اعتماد انتشار، پویش، راستی‌آزمایی و بررسی‌های یکپارچگی
  ClawHub را همراه با هشدار کد ناشر توضیح دهید — هرگز القا نکنید که همهٔ انتشارها امضا شده‌اند.
- خروج خودکار عرضه شد: اعمال تنظیمات نصب تازه، خروج را اعلام می‌کند و
  واگذار می‌کند (TUI ترمینال / `open-agent` برای کلاینت‌های Gateway)؛ صفحهٔ وب
  با پیش‌نویس ازپیش‌پرشدهٔ «بیدار شو، دوست من!» وارد گفت‌وگوی عامل می‌شود.
  واگذاری فقط پس از راستی‌آزمایی پاکِ پس از نوشتن فعال می‌شود. ارائهٔ پیشنهاد
  در صورت صفر بودن عامل‌ها پس از حذف (به‌جای خودکارسازی) همچنان پرداخت نهایی پیگیری بعدی است.

### فاز 6 — حضور متولی (PR1 ادغام‌شده: #110269؛ توضیحات/فراخوانی در PR2 هستند)

- عرضه‌شده در PR1: ورودی نوار کناری «OpenClaw» که به‌طور پیش‌فرض سنجاق شده است (پروفایل‌های تازه؛
  کاربران موجود سنجاق‌های ذخیره‌شده را نگه می‌دارند و از طریق سفارشی‌سازی/More به آن دسترسی دارند)، «از
  OpenClaw بپرسید» به‌عنوان نخستین ورودی تنظیمات، و بازدیدهای `/custodian` با
  پوستهٔ عادی که درخواست خوشامدگویی سرپرست را می‌دهند (بدون گونهٔ خوشامدگویی راه‌اندازی)، و
  «خروج از تنظیمات» فقط در حالت راه‌اندازی رندر می‌شود. یک پنل درون‌خطی و متصل تنظیمات
  به استخراج مشترک نمای مکالمه نیاز دارد (پیگیری بعدی).
- توضیحات واکنشی به رویداد با حفاظ‌های ضد Clippy: فقط تغییرات مهم یا
  ناموفق، حداکثر یک‌بار در هر بازدید تنظیمات مگر اینکه درخواست شود. همان
  درز رویداد، متولی را بعداً به صدای احراز هویت تنزل‌یافته یا کانال‌های
  خراب تبدیل می‌کند.
- کانال‌ها: در استفادهٔ روزمره نامرئی (عامل واسطه می‌شود)؛ با فراخوانی صریح
  و در رویدادهای ازکارافتادن عامل در همان رشته قابل دسترسی است، با نام و
  آواتار چنگال خود در جاهایی که پلتفرم اجازه می‌دهد.
- مدل ضعیف هنگام تنظیم شناسایی شد: `localModelLean` به‌طور خودکار تنظیم می‌شود و متولی
  آن را با کلمات ساده همراه با پیشنهاد ارتقا بیان می‌کند.
- متولی نام مستعار داخلی خود را می‌داند («بعضی‌ها من را متولی صدا می‌زنند —
  OpenClaw هم خوب است») و همیشه عامل را با نام خطاب می‌کند.

### فاز 7 — تاب‌آوری (پیش از ساخت به تصمیم مالک نیاز دارد)

طرح اولیه — «متولی باید فارغ از میزان خرابی
پیکربندی قابل دسترسی باشد» — با خط‌مشی امنیتی مخزن در تضاد است: راهنمای ریشه
بیان می‌کند که Gateway وقتی پیکربندی از نظر ساختاری نامعتبر باشد **از راه‌اندازی خودداری می‌کند**
و فقط خرابی‌های مالک SecretRef به قابلیت‌های پیکربندی‌شده اما دردسترس‌نبودنی
تنزل می‌یابند. ارائهٔ هر سطحی از یک پیکربندی نامعتبر یک تغییر خط‌مشی است،
نه جزئیات پیاده‌سازی. دو دامنه وجود دارد، یکی را انتخاب کنید:

- **گزینهٔ A (پیشنهادی، منطبق با خط‌مشی): doctor خودکار در سمت CLI.** وقتی
  راه‌اندازی Gateway یا CLI به‌دلیل یک پیکربندی نامعتبر با شکل شناخته‌شده شکست می‌خورد، CLI اجرای
  `openclaw doctor --fix` را پیشنهاد می‌دهد (یا با رضایت اجرا می‌کند)، سپس یک‌بار دوباره تلاش
  می‌کند و به‌روشنی گزارش می‌دهد. رفتار Gateway تغییر نمی‌کند؛ متولی از طریق
  مسیر موجود SecretRef تنزل‌یافته و ترمینال قابل دسترسی می‌ماند.
- **گزینهٔ B (نیازمند تأیید صریح مالک + بازبینی امنیتی): حالت
  سطح حداقلی Gateway.** در پیکربندی از نظر ساختاری نامعتبر، سطحی قفل‌شده
  راه‌اندازی کنید که فقط مکالمهٔ متولی و کنش‌های doctor را ارائه دهد. این کار
  قرارداد راه‌اندازی شکست‌بسته را بازنویسی می‌کند و باید پیش از هرگونه کدنویسی،
  سازوکار محافظت ورودی خود را تعریف کند.

پیگیری‌های باقی‌مانده از فازهای 4-6 (ردیابی‌شده، بدون زمان‌بندی): نردبان آواتار/تولید تصویر
برای خروج؛ رندر فیلد نوع‌دار `question` در برنامهٔ macOS؛ یک
پنل درون‌خطی و متصل تنظیمات برای متولی (نیازمند استخراج مشترک نمای مکالمه)؛
توضیحات واکنشی به رویداد و فراخوانی کانال/بازیابی هنگام ازکارافتادن عامل
(PR2 فاز 6)؛ `localModelLean` خودکار برای مدل‌های ضعیف؛ اینکه آیا
سنجاق‌های ذخیره‌شدهٔ نوار کناری کاربران موجود باید ورودی OpenClaw را بپذیرند.

## راهنمای آزمون و ادغام (به‌سختی به‌دست‌آمده؛ پیش از فازهای 4-6 بخوانید)

- **`OPENCLAW_STATE_DIR` سرویس Gateway را ایزوله نمی‌کند.** برچسب
  LaunchAgent (`ai.openclaw.gateway`) در سطح ماشین سراسری است: آزمون راه‌اندازی
  نصب تازه با دایرکتوری وضعیت ایزوله، سرویس واقعی ماشین را بازنویسی و بازراه‌اندازی
  خواهد کرد (اسکریپت‌های پوششی درون دایرکتوری ایزوله قرار می‌گیرند؛ راه‌اندازی بعدی
  سرویس پس از پاک‌سازی آن دایرکتوری خراب می‌شود). پس از هر آزمون نصب تازه،
  با `openclaw gateway install --force && openclaw gateway
restart` از محیط واقعی بازیابی کنید و plist را راستی‌آزمایی کنید. پیگیری محصول:
  برچسب‌های سرویس محدود به دایرکتوری وضعیت، یا تشخیص سرویس بیگانه توسط راه‌اندازی.
- **مهار سرتاسری ایمن**: پیکربندی ایزوله را از قبل با یک بخش `gateway`
  پر کنید (تا راه‌اندازی مسیر نصب پیکربندی‌شده را طی کند و هرگز سرویس را لمس نکند)
  و `openclaw gateway run` را به‌صورت فرایند سادهٔ پیش‌زمینه روی
  یک درگاه آزاد با توکن ساده اجرا کنید. آن مهار، حلقهٔ فاز 3 را
  از جمله اتصال واقعی مرورگر اثبات کرد.
- **مسیرهای احراز هویت بر اساس هویت کلاینت متفاوت‌اند، نه فقط اعتبارنامه‌ها.** حضور و
  سایر خواندن‌های اپراتور از یک کلاینت loopback در حالت CLI با اعتبارنامه‌های همان
  پیکربندی استفاده می‌کنند. Gatewayهای دارای احراز هویت توکنی به راز مشترک نیاز دارند؛ Gatewayهای
  SecretRef/none می‌توانند بدون توکن به احراز هویت loopback مورداعتماد برگردند. یک کلاینت
  مرورگر با هویت Control UI به هویت دستگاه یا مجوز loopback در زمینهٔ امن
  نیاز دارد. کاوشگری که در برابر Gateway ارائه‌دهندهٔ یک
  پیکربندی متفاوت احراز هویت می‌کند (دام LaunchAgent را ببینید) با «عدم تطابق توکن» شکست می‌خورد — آن
  مصنوع برای مدتی فاز 3 را متوقف کرد.
- **کاوشگرهای تکمیل**: `runSetupInferenceTest` کاوشگر راستی‌آزمایی را به
  32 توکن خروجی محدود می‌کند؛ promptهای سفارشی این محدودیت را دور می‌زنند و با
  `maxTokens` خود مدل محدود می‌شوند. مدل‌های استدلالی ابتدا آن بودجه را با استدلال
  پنهان مصرف می‌کنند — نوبت با متن خالی معمولاً یعنی بودجه همان‌جا تمام شده است.
- **ادغام عامل به CI میزبانی‌شدهٔ exact-head نیاز دارد.** گردش‌کار سنگین `CI` ممکن است
  هنگام بار سازمان روی pushها در صف قرار نگیرد؛ راه‌حل جایگزین نگه‌دارنده،
  dispatch دروازهٔ انتشار روی شاخهٔ PR است:

  ```bash
  gh workflow run ci.yml --ref <branch> -f target_ref=<head-sha> -f release_gate=true -f pull_request_number=<pr>
  ```

  اجرا باید روی
  مرجع شاخه باشد تا `head_sha` تطابق داشته باشد، و عنوان به
  `CI release gate <sha>` تبدیل شود که `scripts/verify-pr-hosted-gates.mjs`
  آن را می‌پذیرد. سپس `scripts/pr` را طبق معمول آماده/ادغام کنید.

- **دروازه‌هایی که CI فراتر از آزمون‌های متمرکز اعمال می‌کند**: نگاشت مستندات
  (`pnpm docs:map:gen` پس از افزودن هر صفحهٔ مستندات)، oxlint (`no-map-spread`،
  `max-lines` — فایل‌ها را تقسیم کنید، هرگز سرکوب نکنید)، `check:test-types`، کد مردهٔ
  knip (فقط آنچه تولید مصرف می‌کند صادر کنید؛ آزمون‌ها را از APIهای عمومی عبور دهید)،
  و طبقه‌بند شارد آزمون زنده
  (`test/scripts/test-live-shard.test.ts` باید هر `*.live.test.ts` جدید را فهرست کند).

## گزارش تصمیم‌ها

- اسکن جادویی با کلید توقف، نه با رویکرد اول‌رضایت (مرحله 1؛ خروجی پایدار
  پیش از اسکن، استفاده از مدل و ClawHub را افشا می‌کند و یادداشت نتایج نیز آن را تکرار می‌کند).
- مسیر عمودی کامل شامل فرمان Node ‏`device.apps` (مرحله 1).
- Skills شخص ثالث ClawHub هرگز از پیش انتخاب نمی‌شوند و با برچسب
  نصب کد ناشر مشخص می‌شوند؛ ورودی‌های رسمی ممکن است از پیش علامت‌خورده باشند
  (مرحله 1، وضعیت امنیتی عرضه‌شده).
- دو کارت دسترسی، نه سه کارت؛ رضایت از ابتدا در انتخاب گنجانده شده است (مرحله 2).
- بازشدن خودکار همراه با اعلان، نه یک دکمه مسدودکننده (مراحل 2/5).
- اول مرورگر: بازشدن در ترمینال گزینه جایگزین است و هرگز پرسش «ترمینال یا
  مرورگر؟» مطرح نمی‌شود (مرحله 3).
- متولی در کانال حضور دارد (فراخوانی + بازیابی)، نه اینکه فقط در وب/CLI
  در دسترس باشد (مرحله 6).
- بازشدن در همان رشته و با تعویض آواتار رخ می‌دهد؛ پس از تکمیل،
  برنامه به رابط کاربری معمول منتقل می‌شود (مرحله 5).
- بخش تنظیمات نام «تنظیمات» را حفظ می‌کند؛ متولی به‌جای جایگزین‌کردن آن،
  در همان‌جا (و در نوار کناری) قرار می‌گیرد (مرحله 6).
- کارت‌های گزینه محدودند: 2-4 گزینه، دقیقاً یکی توصیه‌شده و همواره
  قابل ردکردن؛ همان مؤلفه هم برای راه‌اندازی اولیه و هم برای ابزار پرسش عامل به‌کار می‌رود
  (مرحله 4).
- «در حال پرسیدن از OpenClaw…» اصطلاح متعارف واگذاری است؛ شخصیت‌ها می‌توانند رنگ‌وبویی بیفزایند،
  اما روایت ابزار ساده می‌ماند (مرحله 5).
- متن روبه‌کاربر هنگام توضیح کوتاه‌سازی برای مدل ضعیف، هرگز از عبارت‌های
  «حالت کد»، «ابزارها» یا «پنجره زمینه» استفاده نمی‌کند (مرحله 6).

## شکاف‌های شناخته‌شده و پیگیری‌ها

- برچسب LaunchAgent به دایرکتوری وضعیت محدود نیست (مشکل آزمایشی بالا؛ همچنین یک
  شکاف واقعی محصول در حالت چندنمونه‌ای).
- اجرای فقط‌یک‌باره توصیه‌ها و اسکن ذخیره‌شده (مرحله 5)؛ اجرای مجدد
  در حال حاضر آن‌ها را دوباره پیشنهاد می‌کند.
- واگذاری به مرورگر فقط در macOS انجام می‌شود؛ فعال‌سازی Linux/Windows در انتظار است.
- شوخی مربوط به تعداد نشست‌ها کیفی است؛ شمارش‌ها به یک رابط کم‌هزینه برای شمارش نشست نیاز دارند.
- واگذاری به مرورگر به داشبورد معمولی می‌رسد؛ پیوند عمیق متولی در حالت راه‌اندازی اولیه
  با مرحله 4 ارائه می‌شود.