---
read_when:
    - اجرا یا پیکربندی فرایند راه‌اندازی اولیه CLI
    - راه‌اندازی یک دستگاه جدید
sidebarTitle: 'Onboarding: CLI'
summary: 'راه‌اندازی اولیه CLI: استنتاج را تأیید کنید، سپس ادامهٔ پیکربندی را به Crestodian بسپارید'
title: راه‌اندازی اولیه (CLI)
x-i18n:
    generated_at: "2026-07-12T10:57:32Z"
    model: gpt-5.6
    postprocess_version: locale-links-v1
    provider: openai
    source_hash: 62dd8fc2780940f738fc99f04ef0c765f5582161c55d11100fae3b4bbbb0ea15
    source_path: start/wizard.md
    workflow: 16
---

```bash
openclaw onboard
```

راه‌اندازی اولیه از طریق CLI، روش پیشنهادی پیکربندی در ترمینال برای macOS، Linux و
Windows (به‌صورت بومی یا WSL2) است. این فرایند به‌طور پیش‌فرض دسترسی هوش مصنوعی موجود
روی دستگاه را شناسایی می‌کند، آن را با یک تکمیل واقعی می‌آزماید و سپس Crestodian را
برای پیکربندی فضای کاری، Gateway و قابلیت‌های اختیاری اجرا می‌کند. `openclaw setup` نیز همین فرایند را اجرا می‌کند ([پیکربندی](/fa/cli/setup) گونهٔ صرفاً پیکربندیِ
`--baseline` را پوشش می‌دهد). کاربران نسخهٔ دسکتاپ Windows همچنین می‌توانند
از [مرکز Windows](/fa/platforms/windows) شروع کنند.

راه‌اندازی هدایت‌شده ابتدا استنتاج را برقرار می‌کند. این فرایند دسترسی هوش مصنوعی موجود را
شناسایی می‌کند، به یک تکمیل واقعی نیاز دارد و تنها پس از آن [Crestodian](/fa/cli/crestodian)
را برای پیکربندی سایر بخش‌های OpenClaw اجرا می‌کند. در فرایند هدایت‌شده، هیچ مسیر
Crestodian پیش از استنتاج یا مسیری برای رد کردن هوش مصنوعی وجود ندارد.

جادوگر کلاسیک همچنان برای ورود به ارائه‌دهنده، پیکربندی Gateway راه‌دور،
جفت‌سازی کانال، کنترل‌های سرویس پس‌زمینه، Skills و درون‌ریزی‌ها در دسترس است. آن را صریحاً
با `openclaw onboard --classic` اجرا کنید؛ صفحهٔ نامزدهای استنتاج هدایت‌شده
کار را به آن واگذار نمی‌کند. پس از موفقیت استنتاج، Crestodian می‌تواند با استفاده از
`open channel wizard for <channel>` پیکربندی کانال‌هایی را که به اسرار نیاز دارند به یک
جادوگر ترمینالی با ورودی پوشیده بسپارد. برای تغییر ارائه‌دهندهٔ مدل یا احراز هویت آن،
از Crestodian خارج شوید و `openclaw onboard` را اجرا کنید؛ Crestodian فرایندهای
هدایت‌شده یا کلاسیک ارائه‌دهنده را باز نمی‌کند.

<Info>
سریع‌ترین راه برای نخستین گفت‌وگو: پیکربندی هدایت‌شده را کامل کنید، `openclaw dashboard` را اجرا کنید و از طریق
رابط کنترل در مرورگر گفت‌وگو کنید. مستندات: [داشبورد](/fa/web/dashboard).
</Info>

## زبان و منطقه

جادوگر، متن‌های ثابت راه‌اندازی اولیه را بومی‌سازی می‌کند. ترتیب تشخیص: `OPENCLAW_LOCALE`،
`LC_ALL`، `LC_MESSAGES`، `LANG` و سپس انگلیسی. زبان‌های پشتیبانی‌شده: `en`،
`zh-CN`، `zh-TW`.

```bash
OPENCLAW_LOCALE=zh-CN openclaw onboard
```

نام محصولات، فرمان‌ها، کلیدهای پیکربندی، نشانی‌های اینترنتی، شناسه‌های ارائه‌دهنده، شناسه‌های مدل و
برچسب‌های Plugin/کانال، صرف‌نظر از زبان انتخابی، به انگلیسی باقی می‌مانند.

برای پیکربندی دوبارهٔ تنظیمات غیرمرتبط با استنتاج در آینده:

```bash
openclaw configure
openclaw agents add <name>
```

<Note>
`--json` به‌معنای حالت غیرتعاملی نیست. برای اسکریپت‌ها از `--non-interactive` استفاده کنید (نگاه کنید به [خودکارسازی CLI](/fa/start/wizard-cli-automation)).
</Note>

<Tip>
جادوگر کلاسیک یک مرحلهٔ جست‌وجوی وب دارد که در آن می‌توانید ارائه‌دهنده‌ای را انتخاب کنید: Brave،
DuckDuckGo، Exa، Firecrawl، Gemini، Grok، Kimi، MiniMax Search، Ollama Web
Search، Perplexity، SearXNG یا Tavily. برخی به کلید API نیاز دارند و برخی
بدون کلید کار می‌کنند. بعداً می‌توانید این مورد را با `openclaw configure --section web` پیکربندی کنید. مستندات:
[ابزارهای وب](/fa/tools/web).
</Tip>

## حالت هدایت‌شدهٔ پیش‌فرض

اجرای سادهٔ `openclaw onboard` این مسیر را دنبال می‌کند:

1. اعلان امنیتی را بپذیرید.
2. مدل‌های پیکربندی‌شده، متغیرهای محیطی کلید API و CLIهای محلی هوش مصنوعی
   پشتیبانی‌شده را شناسایی کنید.
3. نخستین نامزد شناسایی‌شده را با یک تکمیل واقعی آزمایش کنید. در صورت شکست، دلیل را
   نمایش دهید و به نامزد قابل‌استفادهٔ بعدی بروید.
4. اگر همهٔ گزینه‌های شناسایی‌شده تمام شدند، یکی از نامزدهای شناسایی‌شده را دوباره امتحان کنید یا کلید API ارائه‌دهنده را
   در یک اعلان با ورودی پوشیده وارد کنید. راه‌اندازی هدایت‌شده
   پیش از کار کردن استنتاج، Crestodian یا خروج با رد کردن هوش مصنوعی را ارائه نمی‌کند.
5. فقط مسیر مدل تأییدشده و هر وضعیت اعتبارنامه/Plugin موردنیاز آن را
   ذخیره کنید. تنظیمات فضای کاری و Gateway بدون تغییر باقی می‌مانند.
6. Crestodian را با مدل تأییدشده اجرا کنید تا بتواند فضای کاری،
   Gateway، کانال‌ها، عامل‌ها، Pluginها و سایر پیکربندی‌های اختیاری را تنظیم کند.

اجرای دوبارهٔ فرمان روی یک نصب پیکربندی‌شده، ابتدا مدل پیش‌فرض فعلی را
آزمایش می‌کند و فرایند هدایت‌شده را به مرحله‌ای برای تأیید و تعمیر تبدیل می‌کند. شکست
بررسی هرگز مدل پیکربندی‌شده را به‌طور خودکار جایگزین نمی‌کند؛ راه‌اندازی اولیه متوقف می‌شود و
نحوهٔ ادامه را می‌پرسد. برای افزودن موارد غیرمرتبط با استنتاج در آینده، `openclaw channels add` یا `openclaw configure` را
اجرا کنید؛ برای تغییر مسیر ارائه‌دهنده یا احراز هویت از `openclaw onboard` استفاده کنید.

## جادوگر کلاسیک: QuickStart در برابر Advanced

برای باز کردن جادوگر کامل، `openclaw onboard --classic` را اجرا کنید. این جادوگر با
انتخاب بین **QuickStart** (پیش‌فرض‌ها) و **Advanced** (کنترل کامل) آغاز می‌شود. برای انتخاب
فرایند کلاسیک و رد کردن این اعلان، `--flow quickstart` یا `--flow advanced` (نام مستعار `manual`) را وارد کنید.

<Tabs>
  <Tab title="QuickStart (defaults)">
    - Gateway محلی، اتصال به local loopback
    - فضای کاری پیش‌فرض (یا فضای کاری موجود)
    - درگاه Gateway برابر با **18789**
    - احراز هویت Gateway به‌صورت **Token** (تولید خودکار، حتی روی local loopback)
    - سیاست ابزار: `tools.profile: "coding"` برای پیکربندی‌های جدید (پروفایل صریح موجود حفظ می‌شود)
    - جداسازی پیام مستقیم: `session.dmScope: "per-channel-peer"` برای پیکربندی‌های جدید. جزئیات: [مرجع پیکربندی CLI](/fa/start/wizard-cli-reference#outputs-and-internals)
    - دسترسی از طریق Tailscale روی **Off**
    - پیام‌های مستقیم Telegram و WhatsApp به‌طور پیش‌فرض روی **allowlist** هستند: Telegram شناسهٔ عددی کاربر Telegram را درخواست می‌کند و WhatsApp شمارهٔ تلفن را می‌پرسد

  </Tab>
  <Tab title="Advanced (full control)">
    - همهٔ مراحل را در دسترس قرار می‌دهد: حالت، فضای کاری، Gateway، کانال‌ها، سرویس پس‌زمینه، Skills

  </Tab>
</Tabs>

حالت راه‌دور (`--mode remote`) همیشه از فرایند پیشرفته استفاده می‌کند؛ این حالت فقط
این دستگاه را برای اتصال به Gateway در مکانی دیگر پیکربندی می‌کند و هرگز چیزی را
روی میزبان راه‌دور نصب یا تغییر نمی‌دهد.

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

حالت محلی (پیش‌فرض) این مراحل را طی می‌کند:

1. **مدل/احراز هویت** - یک فرایند احراز هویت ارائه‌دهنده را انتخاب کنید (کلید API، OAuth یا
   احراز هویت دستی مخصوص ارائه‌دهنده)، از جمله ارائه‌دهندهٔ سفارشی
   (سازگار با OpenAI، سازگار با OpenAI Responses، سازگار با Anthropic یا
   شناسایی خودکار ناشناخته). یک مدل پیش‌فرض انتخاب کنید.
   پیکربندی جدید کلید API در OpenAI به‌طور پیش‌فرض از `openai/gpt-5.6` استفاده می‌کند (شناسهٔ بدون پیشوند API مستقیم
   به Sol حل می‌شود)؛ پیکربندی جدید ChatGPT/Codex به‌طور پیش‌فرض از
   `openai/gpt-5.6-sol` استفاده می‌کند. اجرای دوبارهٔ پیکربندی، مدل صریح موجود را حفظ می‌کند،
   از جمله `openai/gpt-5.5`. اگر حساب به GPT-5.6 دسترسی ندارد،
   `openai/gpt-5.5` را صریحاً انتخاب کنید.
   نکتهٔ امنیتی: اگر این عامل قرار است ابزارها را اجرا کند یا محتوای Webhook/قلاب را
   پردازش کند، قوی‌ترین مدل نسل جدید موجود را ترجیح دهید و سیاست
   ابزار را سخت‌گیرانه نگه دارید؛ رده‌های ضعیف‌تر یا قدیمی‌تر در برابر تزریق پرامپت آسیب‌پذیرترند.
   در اجراهای غیرتعاملی، `--secret-input-mode ref` به‌جای مقادیر متنی سادهٔ کلید API،
   ارجاع‌های متکی بر متغیر محیطی را ذخیره می‌کند؛ متغیر محیطی مورد ارجاع باید از قبل
   تنظیم شده باشد، وگرنه راه‌اندازی اولیه فوراً شکست می‌خورد. حالت تعاملی ارجاع به اسرار می‌تواند
   به یک متغیر محیطی یا ارجاع پیکربندی‌شدهٔ ارائه‌دهنده (`file` یا
   `exec`) اشاره کند و پیش از ذخیره، بررسی اولیهٔ سریعی انجام می‌دهد. پس از پیکربندی مدل/احراز هویت،
   جادوگر یک آزمایش اختیاری تکمیل زنده ارائه می‌دهد؛ در صورت شکست می‌توان یک بار به
   پیکربندی مدل/احراز هویت بازگشت یا بدون مسدود شدن ادامهٔ
   جادوگر کلاسیک آن را نادیده گرفت. نادیده گرفتن آن Crestodian را فعال نمی‌کند؛ پیکربندی مکالمه‌ای
   همچنان به بررسی موفق استنتاج نیاز دارد.
2. **فضای کاری** - پوشهٔ فایل‌های عامل (پیش‌فرض `~/.openclaw/workspace`). فایل‌های راه‌انداز اولیه را ایجاد می‌کند.
3. **Gateway** - درگاه، نشانی اتصال، حالت احراز هویت، دسترسی از طریق Tailscale. در
   حالت تعاملی توکن، ذخیره‌سازی توکن به‌صورت متن ساده (پیش‌فرض) را انتخاب کنید یا
   استفاده از SecretRef را فعال کنید. مسیر غیرتعاملی SecretRef: `--gateway-token-ref-env <ENV_VAR>`.
4. **کانال‌ها** - کانال‌های گفت‌وگوی داخلی و Pluginهای رسمی، از جمله
   Discord، Feishu، Google Chat، iMessage، Mattermost، Microsoft Teams،
   QQ Bot، Signal، Slack، Telegram، WhatsApp و موارد دیگر.
5. **سرویس پس‌زمینه** - یک LaunchAgent در macOS، واحد کاربری systemd در
   Linux/WSL2 یا یک Scheduled Task بومی Windows را با مسیر جایگزین پوشهٔ
   Startup مخصوص هر کاربر نصب می‌کند.
   اگر احراز هویت توکنی لازم باشد و `gateway.auth.token` با SecretRef مدیریت شود،
   نصب سرویس پس‌زمینه آن را اعتبارسنجی می‌کند، اما توکن حل‌شده را در
   فرادادهٔ محیط سرویس ناظر ذخیره نمی‌کند؛ SecretRef حل‌نشده
   همراه با راهنمایی، نصب را مسدود می‌کند. اگر در حالی که `gateway.auth.mode` تنظیم نشده، هر دو
   `gateway.auth.token` و `gateway.auth.password` تنظیم شده باشند، نصب
   تا زمانی که حالت را صریحاً تعیین کنید مسدود می‌شود.
6. **بررسی سلامت** - Gateway را اجرا می‌کند و دردسترس‌بودن آن را تأیید می‌کند.
7. **Skills** - Skills پیشنهادی و وابستگی‌های اختیاری آن‌ها را نصب می‌کند.

<Note>
اجرای دوبارهٔ راه‌اندازی اولیه هیچ چیزی را پاک **نمی‌کند**، مگر اینکه صریحاً
**Reset** را انتخاب کنید (یا `--reset` را وارد کنید). گزینهٔ `--reset` در CLI به‌طور پیش‌فرض پیکربندی، اعتبارنامه‌ها
و نشست‌ها را بازنشانی می‌کند؛ برای حذف فضای کاری نیز از `--reset-scope full` استفاده کنید. اگر
پیکربندی نامعتبر باشد یا کلیدهای قدیمی داشته باشد، راه‌اندازی اولیه از شما می‌خواهد ابتدا
`openclaw doctor` را اجرا کنید.
</Note>

`--flow import` به‌جای پیکربندی جدید، یک فرایند مهاجرت شناسایی‌شده (برای مثال Hermes) را در
جادوگر کلاسیک اجرا می‌کند؛ نگاه کنید به [مهاجرت](/fa/cli/migrate) و راهنماهای مهاجرت در بخش
[نصب](/fa/install/migrating-hermes). `openclaw onboard --modern` نام مستعار سازگاری برای
[Crestodian](/fa/cli/crestodian) است. این فرمان از همان مانع استنتاج `openclaw crestodian` استفاده می‌کند:
استنتاج تأییدشده دستیار را اجرا می‌کند، در حالی که شکست تعاملی کاربر را به پیکربندی
هدایت‌شدهٔ استنتاج بازمی‌گرداند.

## افزودن عامل دیگر

برای ایجاد عاملی جداگانه با فضای کاری، نشست‌ها و پروفایل‌های احراز هویت مخصوص خود، از
`openclaw agents add <name>` استفاده کنید. اجرای آن بدون `--workspace` یک
فرایند تعاملی برای نام، فضای کاری، احراز هویت، کانال‌ها و اتصال‌ها آغاز می‌کند؛ این
جادوگر کامل `openclaw onboard` نیست.

مواردی که تنظیم می‌کند:

- `agents.list[].name`
- `agents.list[].workspace`
- `agents.list[].agentDir`

نکات:

- فضای کاری پیش‌فرض: `~/.openclaw/workspace-<agentId>` (یا در مسیر
  `agents.defaults.workspace`، اگر تنظیم شده باشد).
- برای هدایت پیام‌های ورودی به این عامل، `bindings` را اضافه کنید (راه‌اندازی اولیه می‌تواند این کار را برای شما انجام دهد).
- پرچم‌های غیرتعاملی: `--model`، `--agent-dir`، `--bind`، `--non-interactive`.

## مرجع کامل

برای رفتار گام‌به‌گام و خروجی‌های پیکربندی با جزئیات، به
[مرجع پیکربندی CLI](/fa/start/wizard-cli-reference) مراجعه کنید.
برای نمونه‌های غیرتعاملی، به [خودکارسازی CLI](/fa/start/wizard-cli-automation) مراجعه کنید.
برای مرجع کامل پرچم‌ها، به [`openclaw onboard`](/fa/cli/onboard) مراجعه کنید.

## مستندات مرتبط

- مرجع فرمان CLI: [`openclaw onboard`](/fa/cli/onboard)
- نمای کلی راه‌اندازی اولیه: [نمای کلی راه‌اندازی اولیه](/fa/start/onboarding-overview)
- راه‌اندازی اولیهٔ برنامهٔ macOS: [راه‌اندازی اولیه](/fa/start/onboarding)
- آیین نخستین اجرای عامل: [راه‌اندازی آغازین عامل](/fa/start/bootstrapping)