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

openclaw onboard

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

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

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

زبان و منطقه

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

OPENCLAW_LOCALE=zh-CN openclaw onboardOPENCLAW_LOCALE=en openclaw onboard # جایگزینی صریح با انگلیسی

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

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

openclaw configureopenclaw agents add <name>

پیش‌فرض هدایت‌شده

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

1. اعلان امنیتی را بپذیرید.
2. مدل‌های پیکربندی‌شده، متغیرهای محیطی کلید API، CLIهای محلی هوش مصنوعیِ پشتیبانی‌شده و مدل‌های دارای قابلیت ابزار را که از قبل روی سرورهای در دسترس Ollama یا LM Studio در میزبان Gateway نصب شده‌اند، شناسایی کنید. این گذر فقط‌خواندنی هرگز مدلی را بارگیری نمی‌کند. نصب‌های Gemini CLI، Antigravity، Pi و OpenCode نیز هنگامی گزارش می‌شوند که نتوانند به‌عنوان مسیر استنتاج قابل‌استفادهٔ مجدد برای راه‌اندازی هدایت‌شده عمل کنند. Gemini و Antigravity نمی‌توانند کاوش بدون ابزار را اعمال کنند؛ Pi و OpenCode به‌جای مسیرهای استنتاج راه‌اندازی، چارچوب‌های کامل عامل هستند.
3. نخستین گزینهٔ شناسایی‌شده را با یک تکمیل واقعی آزمایش کنید. در صورت شکست، دلیل را نمایش دهید و به گزینهٔ قابل‌استفادهٔ بعدی ادامه دهید.
4. اگر همهٔ گزینه‌های شناسایی‌شده تمام شدند، OpenAI، Anthropic، xAI (Grok)، Google یا OpenRouter را انتخاب کنید، یا برای ارائه‌دهندگان باقی‌مانده بیشتر… را برگزینید. مناطق، طرح‌ها و روش‌های پشتیبانی‌شدهٔ مرورگر، دستگاه، کلید API یا توکن هر ارائه‌دهنده در منوی دومی نمایش داده می‌شوند و با همان تکمیل واقعی آزمایش می‌شوند. برای خروج بدون راه‌اندازی OpenClaw، فعلاً رد شود را انتخاب کنید.
5. فقط مسیر مدل تأییدشده و هرگونه وضعیت اعتبارنامه/Plugin موردنیاز آن را ماندگار کنید. تنظیمات فضای کاری و Gateway دست‌نخورده باقی می‌مانند.
6. OpenClaw را با مدل تأییدشده راه‌اندازی کنید تا بتواند فضای کاری، Gateway، کانال‌ها، عامل‌ها، Pluginها و باقی تنظیمات اختیاری را پیکربندی کند.

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

ویزارد کلاسیک: شروع سریع در برابر پیشرفته

برای باز کردن ویزارد کامل، openclaw onboard --classic را اجرا کنید. ویزارد با انتخابی میان شروع سریع (پیش‌فرض‌ها) و پیشرفته (کنترل کامل) آغاز می‌شود. برای انتخاب جریان کلاسیک و رد کردن آن پرسش، --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) اشاره کند و پیش از ذخیره‌سازی، یک بررسی مقدماتی سریع انجام می‌دهد. پس از راه‌اندازی مدل/احراز هویت، ویزارد یک آزمایش اختیاری تکمیل زنده پیشنهاد می‌دهد؛ در صورت شکست، می‌توان یک‌بار به راه‌اندازی مدل/احراز هویت بازگشت یا بدون مسدود کردن ادامهٔ ویزارد کلاسیک، آن را نادیده گرفت. نادیده گرفتن آن قفل OpenClaw را باز نمی‌کند؛ راه‌اندازی مکالمه‌ای همچنان به بررسی موفق استنتاج نیاز دارد.
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 - مهارت‌های توصیه‌شده و وابستگی‌های اختیاری آن‌ها را نصب می‌کند.

--flow import یک جریان مهاجرت شناسایی‌شده (برای نمونه Hermes) را به‌جای راه‌اندازی تازه در ویزارد کلاسیک اجرا می‌کند؛ به مهاجرت و راهنماهای مهاجرت در بخش نصب مراجعه کنید. openclaw onboard --modern یک نام مستعار سازگاری برای OpenClaw است. این فرمان از همان دروازهٔ استنتاجِ openclaw setup استفاده می‌کند: استنتاج تأییدشده دستیار را راه‌اندازی می‌کند، درحالی‌که شکست تعاملی به راه‌اندازی هدایت‌شدهٔ استنتاج بازمی‌گردد.

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

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

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

• agents.entries.*.name
• agents.entries.*.workspace
• agents.entries.*.agentDir

نکته‌ها:

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

مرجع کامل

برای رفتار گام‌به‌گام دقیق و خروجی‌های پیکربندی، به مرجع راه‌اندازی CLI مراجعه کنید. برای نمونه‌های غیرتعاملی، به خودکارسازی CLI مراجعه کنید. برای مرجع کامل پرچم‌ها، به openclaw onboard مراجعه کنید.

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

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