Guides
مرجع راهاندازی CLI
این صفحه مرجع کامل openclaw onboard است.
برای راهنمای کوتاه، Onboarding (CLI) را ببینید.
ویزارد چه میکند
حالت محلی (پیشفرض) شما را در این موارد راهنمایی میکند:
- راهاندازی مدل و احراز هویت (OAuth اشتراک OpenAI Code، Anthropic Claude CLI یا کلید API، بهعلاوه گزینههای MiniMax، GLM، Ollama، Moonshot، StepFun و AI Gateway)
- محل Workspace و فایلهای راهاندازی اولیه
- تنظیمات Gateway (پورت، bind، احراز هویت، Tailscale)
- کانالها و ارائهدهندگان (Telegram، WhatsApp، Discord، Google Chat، Mattermost، Signal، iMessage و دیگر Pluginهای کانال همراه)
- نصب Daemon (LaunchAgent، واحد کاربر systemd، یا Windows Scheduled Task بومی با fallback پوشه Startup)
- بررسی سلامت
- راهاندازی Skills
حالت راه دور این ماشین را برای اتصال به یک gateway در جای دیگر پیکربندی میکند. این حالت چیزی را روی میزبان راه دور نصب یا تغییر نمیدهد.
جزئیات جریان محلی
تشخیص پیکربندی موجود
- اگر
~/.openclaw/openclaw.jsonوجود داشته باشد، Keep، Modify یا Reset را انتخاب کنید. - اجرای دوباره ویزارد چیزی را پاک نمیکند مگر اینکه صراحتاً Reset را انتخاب کنید (یا
--resetرا پاس دهید). - CLI
--resetبهطور پیشفرضconfig+creds+sessionsاست؛ برای حذف Workspace هم از--reset-scope fullاستفاده کنید. - اگر پیکربندی نامعتبر باشد یا کلیدهای قدیمی داشته باشد، ویزارد متوقف میشود و از شما میخواهد پیش از ادامه
openclaw doctorرا اجرا کنید. - Reset از
trashاستفاده میکند و این محدودهها را پیشنهاد میدهد:- فقط پیکربندی
- پیکربندی + اعتبارنامهها + نشستها
- بازنشانی کامل (Workspace را هم حذف میکند)
مدل و احراز هویت
- ماتریس کامل گزینهها در گزینههای احراز هویت و مدل آمده است.
Workspace
- پیشفرض
~/.openclaw/workspace(قابل پیکربندی). - فایلهای Workspace موردنیاز برای آیین راهاندازی اولیه در اولین اجرا را seed میکند.
- چیدمان Workspace: Agent workspace.
Gateway
- برای پورت، bind، حالت احراز هویت و در معرض قرار دادن از طریق Tailscale سؤال میکند.
- توصیهشده: حتی برای loopback نیز احراز هویت توکنی را فعال نگه دارید تا کلاینتهای WS محلی مجبور به احراز هویت باشند.
- در حالت توکن، راهاندازی تعاملی این گزینهها را ارائه میدهد:
- ایجاد/ذخیره توکن متن ساده (پیشفرض)
- استفاده از SecretRef (اختیاری)
- در حالت گذرواژه، راهاندازی تعاملی از ذخیرهسازی متن ساده یا SecretRef نیز پشتیبانی میکند.
- مسیر SecretRef توکن غیرتعاملی:
--gateway-token-ref-env <ENV_VAR>.- به یک متغیر محیطی غیرخالی در محیط فرایند onboarding نیاز دارد.
- نمیتواند با
--gateway-tokenترکیب شود.
- احراز هویت را فقط زمانی غیرفعال کنید که به تمام فرایندهای محلی کاملاً اعتماد دارید.
- bindهای غیر loopback همچنان به احراز هویت نیاز دارند.
کانالها
- WhatsApp: ورود اختیاری با QR
- Telegram: توکن بات
- Discord: توکن بات
- Google Chat: JSON حساب سرویس + مخاطب Webhook
- Mattermost: توکن بات + URL پایه
- Signal: نصب اختیاری
signal-cli+ پیکربندی حساب - iMessage: مسیر CLI
imsg+ دسترسی به پایگاه داده Messages؛ وقتی Gateway خارج از Mac اجرا میشود از wrapper SSH استفاده کنید - امنیت DM: پیشفرض pairing است. اولین DM یک کد ارسال میکند؛ با
openclaw pairing approve <channel> <code>تأیید کنید یا از allowlistها استفاده کنید.
نصب Daemon
- macOS: LaunchAgent
- به نشست کاربر واردشده نیاز دارد؛ برای حالت headless از LaunchDaemon سفارشی استفاده کنید (همراه محصول ارائه نمیشود).
- Linux و Windows از طریق WSL2: واحد کاربر systemd
- ویزارد تلاش میکند
loginctl enable-linger <user>را اجرا کند تا gateway پس از خروج از حساب نیز فعال بماند. - ممکن است sudo بخواهد (
/var/lib/systemd/lingerرا مینویسد)؛ ابتدا بدون sudo امتحان میکند.
- ویزارد تلاش میکند
- Windows بومی: ابتدا Scheduled Task
- اگر ایجاد task رد شود، OpenClaw به یک مورد ورود پوشه Startup برای هر کاربر fallback میکند و gateway را فوراً شروع میکند.
- Scheduled Taskها همچنان ترجیح داده میشوند چون وضعیت supervisor بهتری فراهم میکنند.
- انتخاب runtime: Node (توصیهشده؛ برای WhatsApp و Telegram لازم است). Bun توصیه نمیشود.
بررسی سلامت
- Gateway را شروع میکند (در صورت نیاز) و
openclaw healthرا اجرا میکند. openclaw status --deepپروب سلامت gateway زنده را به خروجی status اضافه میکند، از جمله پروبهای کانال وقتی پشتیبانی شوند.
Skills
- Skills موجود را میخواند و نیازمندیها را بررسی میکند.
- به شما اجازه میدهد مدیر node را انتخاب کنید: npm، pnpm یا bun.
- وابستگیهای اختیاری Skills همراه و مورداعتماد را وقتی installer لازم در دسترس باشد نصب میکند.
- installerهای Homebrew، uv و Go ناموجود را رد میکند، سپس Skills متأثر را با راهنمای راهاندازی دستی گروهبندی میکند. پس از نصب پیشنیازهای جاافتاده
openclaw doctorرا اجرا کنید.
پایان
- خلاصه و گامهای بعدی، از جمله گزینههای برنامه iOS، Android و macOS.
جزئیات حالت راه دور
حالت راه دور این ماشین را برای اتصال به یک gateway در جای دیگر پیکربندی میکند.
چیزهایی که تنظیم میکنید:
- URL Gateway راه دور (
ws://...) - توکن، اگر احراز هویت gateway راه دور لازم باشد (توصیهشده)
گزینههای احراز هویت و مدل
کلید API Anthropic
اگر ANTHROPIC_API_KEY موجود باشد از آن استفاده میکند، یا کلید را درخواست میکند و سپس آن را برای استفاده Daemon ذخیره میکند.
اشتراک OpenAI Code (OAuth)
جریان مرورگر؛ code#state را paste کنید.
وقتی مدل تنظیم نشده باشد یا از قبل عضو خانواده OpenAI باشد، agents.defaults.model را از طریق runtime مربوط به Codex روی openai/gpt-5.5 تنظیم میکند.
اشتراک OpenAI Code (device pairing)
جریان pairing مرورگر با یک device code کوتاهعمر.
وقتی مدل تنظیم نشده باشد یا از قبل عضو خانواده OpenAI باشد، agents.defaults.model را از طریق runtime مربوط به Codex روی openai/gpt-5.5 تنظیم میکند.
کلید API OpenAI
اگر OPENAI_API_KEY موجود باشد از آن استفاده میکند، یا کلید را درخواست میکند و سپس اعتبارنامه را در پروفایلهای احراز هویت ذخیره میکند.
وقتی مدل تنظیم نشده باشد، openai/* باشد، یا refهای مدل Codex قدیمی باشند، agents.defaults.model را روی openai/gpt-5.5 تنظیم میکند.
xAI (Grok) OAuth
ورود با مرورگر برای حسابهای واجد شرایط SuperGrok یا X Premium. این مسیر
xAI توصیهشده برای بیشتر کاربران است. OpenClaw پروفایل احراز هویت حاصل را
برای مدلهای Grok، Grok web_search، x_search و code_execution ذخیره میکند.
کد دستگاه xAI (Grok)
ورود با مرورگر مناسب راه دور، با یک کد کوتاه بهجای callback به localhost. از این گزینه روی میزبانهای SSH، Docker یا VPS استفاده کنید.
کلید API xAI (Grok)
XAI_API_KEY را درخواست میکند و xAI را بهعنوان ارائهدهنده مدل پیکربندی میکند. وقتی
بهجای OAuth اشتراکی یک کلید API مربوط به xAI Console میخواهید از این گزینه استفاده کنید.
OpenCode
OPENCODE_API_KEY (یا OPENCODE_ZEN_API_KEY) را درخواست میکند و به شما اجازه میدهد کاتالوگ Zen یا Go را انتخاب کنید.
URL راهاندازی: opencode.ai/auth.
کلید API (عمومی)
کلید را برای شما ذخیره میکند.
Vercel AI Gateway
AI_GATEWAY_API_KEY را درخواست میکند.
جزئیات بیشتر: Vercel AI Gateway.
Cloudflare AI Gateway
شناسه حساب، شناسه gateway و CLOUDFLARE_AI_GATEWAY_API_KEY را درخواست میکند.
جزئیات بیشتر: Cloudflare AI Gateway.
MiniMax
پیکربندی بهطور خودکار نوشته میشود. پیشفرض میزبانیشده MiniMax-M3 است؛ راهاندازی با کلید API از
minimax/... و راهاندازی OAuth از minimax-portal/... استفاده میکند.
جزئیات بیشتر: MiniMax.
StepFun
پیکربندی برای StepFun standard یا Step Plan روی endpointهای چین یا جهانی بهطور خودکار نوشته میشود.
Standard در حال حاضر شامل step-3.5-flash است و Step Plan همچنین شامل step-3.5-flash-2603 میشود.
جزئیات بیشتر: StepFun.
Synthetic (سازگار با Anthropic)
SYNTHETIC_API_KEY را درخواست میکند.
جزئیات بیشتر: Synthetic.
Ollama (مدلهای باز Cloud و محلی)
ابتدا برای Cloud + Local، Cloud only یا Local only سؤال میکند.
Cloud only از OLLAMA_API_KEY همراه با https://ollama.com استفاده میکند.
حالتهای متکی به میزبان URL پایه را درخواست میکنند (پیشفرض http://127.0.0.1:11434)، مدلهای موجود را کشف میکنند و پیشفرضها را پیشنهاد میدهند.
Cloud + Local همچنین بررسی میکند که آیا آن میزبان Ollama برای دسترسی ابری وارد شده است یا نه.
جزئیات بیشتر: Ollama.
Moonshot و Kimi Coding
پیکربندیهای Moonshot (Kimi K2) و Kimi Coding بهطور خودکار نوشته میشوند. جزئیات بیشتر: Moonshot AI (Kimi + Kimi Coding).
ارائهدهنده سفارشی
با endpointهای سازگار با OpenAI و سازگار با Anthropic کار میکند.
Onboarding تعاملی از همان گزینههای ذخیرهسازی کلید API پشتیبانی میکند که جریانهای کلید API دیگر ارائهدهندهها دارند:
- همین حالا کلید API را paste کنید (متن ساده)
- استفاده از reference محرمانه (env ref یا provider ref پیکربندیشده، همراه با اعتبارسنجی preflight)
پرچمهای غیرتعاملی:
--auth-choice custom-api-key--custom-base-url--custom-model-id--custom-api-key(اختیاری؛ بهCUSTOM_API_KEYfallback میکند)--custom-provider-id(اختیاری)--custom-compatibility <openai|openai-responses|anthropic>(اختیاری؛ پیشفرضopenai)--custom-image-input/--custom-text-input(اختیاری؛ قابلیت ورودی مدل استنباطشده را override میکند)
رد کردن
احراز هویت را پیکربندینشده باقی میگذارد.
رفتار مدل:
- مدل پیشفرض را از گزینههای تشخیصدادهشده انتخاب کنید، یا ارائهدهنده و مدل را دستی وارد کنید.
- Onboarding ارائهدهنده سفارشی پشتیبانی تصویر را برای شناسههای رایج مدل استنباط میکند و فقط وقتی نام مدل ناشناخته باشد سؤال میکند.
- وقتی onboarding از یک گزینه احراز هویت ارائهدهنده شروع شود، انتخابگر مدل
آن ارائهدهنده را بهطور خودکار ترجیح میدهد. برای Volcengine و BytePlus، همین ترجیح
با variantهای coding-plan آنها نیز مطابقت دارد (
volcengine-plan/*،byteplus-plan/*). - اگر فیلتر ارائهدهنده ترجیحی خالی شود، انتخابگر بهجای نمایش ندادن مدلها به کاتالوگ کامل fallback میکند.
- ویزارد بررسی مدل را اجرا میکند و اگر مدل پیکربندیشده ناشناخته باشد یا احراز هویت نداشته باشد هشدار میدهد.
مسیرهای اعتبارنامه و پروفایل:
- پروفایلهای احراز هویت (کلیدهای API + OAuth):
~/.openclaw/agents/<agentId>/agent/auth-profiles.json - وارد کردن OAuth قدیمی:
~/.openclaw/credentials/oauth.json
حالت ذخیرهسازی اعتبارنامه:
- رفتار پیشفرض راهاندازی اولیه، کلیدهای API را بهصورت مقادیر متن ساده در پروفایلهای احراز هویت ذخیره میکند.
--secret-input-mode refبهجای ذخیرهسازی کلید بهصورت متن ساده، حالت ارجاع را فعال میکند. در راهاندازی تعاملی، میتوانید یکی از این دو را انتخاب کنید:- ارجاع متغیر محیطی (برای مثال
keyRef: { source: "env", provider: "default", id: "OPENAI_API_KEY" }) - ارجاع ارائهدهنده پیکربندیشده (
fileیاexec) با نام مستعار ارائهدهنده + شناسه
- ارجاع متغیر محیطی (برای مثال
- حالت ارجاع تعاملی، پیش از ذخیرهسازی یک اعتبارسنجی پیشپرواز سریع اجرا میکند.
- ارجاعهای محیطی: نام متغیر + مقدار غیرخالی را در محیط راهاندازی فعلی اعتبارسنجی میکند.
- ارجاعهای ارائهدهنده: پیکربندی ارائهدهنده را اعتبارسنجی میکند و شناسه درخواستی را resolve میکند.
- اگر پیشپرواز ناموفق باشد، راهاندازی خطا را نشان میدهد و به شما اجازه تلاش دوباره میدهد.
- در حالت غیرتعاملی،
--secret-input-mode refفقط با env پشتیبانی میشود.- متغیر محیطی ارائهدهنده را در محیط فرایند راهاندازی تنظیم کنید.
- فلگهای کلید درونخطی (برای مثال
--openai-api-key) نیاز دارند آن متغیر محیطی تنظیم شده باشد؛ در غیر این صورت راهاندازی سریعاً شکست میخورد. - برای ارائهدهندههای سفارشی، حالت غیرتعاملی
refمقدارmodels.providers.<id>.apiKeyرا بهصورت{ source: "env", provider: "default", id: "CUSTOM_API_KEY" }ذخیره میکند. - در آن حالت ارائهدهنده سفارشی،
--custom-api-keyنیاز داردCUSTOM_API_KEYتنظیم شده باشد؛ در غیر این صورت راهاندازی سریعاً شکست میخورد.
- اعتبارنامههای احراز هویت Gateway در راهاندازی تعاملی از انتخابهای متن ساده و SecretRef پشتیبانی میکنند:
- حالت توکن: تولید/ذخیره توکن متن ساده (پیشفرض) یا استفاده از SecretRef.
- حالت گذرواژه: متن ساده یا SecretRef.
- مسیر SecretRef توکن غیرتعاملی:
--gateway-token-ref-env <ENV_VAR>. - راهاندازیهای متن ساده موجود بدون تغییر به کار ادامه میدهند.
خروجیها و اجزای داخلی
فیلدهای معمول در ~/.openclaw/openclaw.json:
agents.defaults.workspaceagents.defaults.skipBootstrapوقتی--skip-bootstrapپاس داده شودagents.defaults.model/models.providers(اگر Minimax انتخاب شده باشد)tools.profile(راهاندازی محلی وقتی تنظیم نشده باشد بهصورت پیشفرض"coding"است؛ مقادیر صریح موجود حفظ میشوند)gateway.*(حالت، bind، احراز هویت، tailscale)session.dmScope(راهاندازی محلی وقتی تنظیم نشده باشد این را بهصورت پیشفرضper-channel-peerقرار میدهد؛ مقادیر صریح موجود حفظ میشوند)channels.telegram.botToken،channels.discord.token،channels.matrix.*،channels.signal.*،channels.imessage.*- allowlistهای کانال (Slack، Discord، Matrix، Microsoft Teams) وقتی هنگام promptها انتخاب میکنید (نامها در صورت امکان به شناسهها resolve میشوند)
skills.install.nodeManager- فلگ
setup --node-managerمقدارهایnpm،pnpm، یاbunرا میپذیرد. - پیکربندی دستی همچنان میتواند بعداً
skills.install.nodeManager: "yarn"را تنظیم کند.
- فلگ
wizard.lastRunAtwizard.lastRunVersionwizard.lastRunCommitwizard.lastRunCommandwizard.lastRunModewizard.securityAcknowledgedAt
openclaw agents add مقدار agents.list[] و bindings اختیاری را مینویسد.
اعتبارنامههای WhatsApp زیر ~/.openclaw/credentials/whatsapp/<accountId>/ قرار میگیرند.
جلسهها زیر ~/.openclaw/agents/<agentId>/sessions/ ذخیره میشوند.
RPC ویزارد Gateway:
wizard.startwizard.nextwizard.cancelwizard.status
کلاینتها (اپ macOS و Control UI) میتوانند مرحلهها را بدون پیادهسازی دوباره منطق راهاندازی نمایش دهند.
رفتار راهاندازی Signal:
- asset انتشار مناسب را دانلود میکند
- آن را زیر
~/.openclaw/tools/signal-cli/<version>/ذخیره میکند - مقدار
channels.signal.cliPathرا در پیکربندی مینویسد - buildهای JVM به Java 21 نیاز دارند
- وقتی buildهای native موجود باشند، از آنها استفاده میشود
- Windows از WSL2 استفاده میکند و جریان signal-cli لینوکس را داخل WSL دنبال میکند
مستندات مرتبط
- مرکز راهاندازی اولیه: راهاندازی اولیه (CLI)
- اتوماسیون و اسکریپتها: اتوماسیون CLI
- مرجع دستور:
openclaw onboard
