راه‌اندازی اولیه (CLI)

openclaw onboard

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

راه‌اندازی هدایت‌شده ابتدا استنتاج را برقرار می‌کند. این فرایند دسترسی هوش مصنوعی موجود را شناسایی می‌کند، به یک تکمیل واقعی نیاز دارد و تنها پس از آن Crestodian را برای پیکربندی سایر بخش‌های OpenClaw اجرا می‌کند. در فرایند هدایت‌شده، هیچ مسیر Crestodian پیش از استنتاج یا مسیری برای رد کردن هوش مصنوعی وجود ندارد.

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

زبان و منطقه

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

OPENCLAW_LOCALE=zh-CN openclaw onboard

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

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

openclaw configureopenclaw agents add <name>

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

اجرای سادهٔ 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) را وارد کنید.

حالت راه‌دور (--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 پیشنهادی و وابستگی‌های اختیاری آن‌ها را نصب می‌کند.

--flow import به‌جای پیکربندی جدید، یک فرایند مهاجرت شناسایی‌شده (برای مثال Hermes) را در جادوگر کلاسیک اجرا می‌کند؛ نگاه کنید به مهاجرت و راهنماهای مهاجرت در بخش نصب. openclaw onboard --modern نام مستعار سازگاری برای 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 مراجعه کنید. برای نمونه‌های غیرتعاملی، به خودکارسازی CLI مراجعه کنید. برای مرجع کامل پرچم‌ها، به openclaw onboard مراجعه کنید.

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

• مرجع فرمان CLI: openclaw onboard
• نمای کلی راه‌اندازی اولیه: نمای کلی راه‌اندازی اولیه
• راه‌اندازی اولیهٔ برنامهٔ macOS: راه‌اندازی اولیه
• آیین نخستین اجرای عامل: راه‌اندازی آغازین عامل