مرجع راه‌اندازی CLI

این صفحه مرجع کامل openclaw onboard است. برای راهنمای کوتاه، Onboarding (CLI) را ببینید.

# ویزارد چه کاری انجام می‌دهد

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

• راه‌اندازی مدل و احراز هویت (OAuth اشتراک OpenAI Code، Anthropic Claude CLI یا کلید API، به‌علاوه گزینه‌های MiniMax، GLM، Ollama، Moonshot، StepFun و AI Gateway)
• محل workspace و فایل‌های bootstrap
• تنظیمات Gateway (port، bind، auth، tailscale)
• کانال‌ها و ارائه‌دهندگان (Telegram، WhatsApp، Discord، Google Chat، Mattermost، Signal، BlueBubbles و دیگر Pluginهای کانال همراه)
• نصب daemon (LaunchAgent، واحد کاربر systemd، یا Windows Scheduled Task بومی با fallback پوشه Startup)
• بررسی سلامت
• راه‌اندازی Skills

حالت راه‌دور این دستگاه را برای اتصال به یک Gateway در جای دیگر پیکربندی می‌کند. این حالت چیزی را روی میزبان راه‌دور نصب یا تغییر نمی‌دهد.

# جزئیات جریان محلی

# جزئیات حالت راه‌دور

حالت راه‌دور این دستگاه را برای اتصال به یک Gateway در جای دیگر پیکربندی می‌کند.

آنچه تنظیم می‌کنید:

• URL Gateway راه‌دور (ws://...)
• token اگر auth Gateway راه‌دور لازم باشد (توصیه‌شده)

# گزینه‌های احراز هویت و مدل

رفتار model:

• model پیش‌فرض را از گزینه‌های تشخیص‌داده‌شده انتخاب کنید، یا provider و model را دستی وارد کنید.
• onboarding ارائه‌دهنده سفارشی، پشتیبانی image را برای IDهای رایج model استنباط می‌کند و فقط وقتی نام model ناشناخته باشد سؤال می‌پرسد.
• وقتی onboarding از یک انتخاب auth ارائه‌دهنده شروع شود، model picker به‌صورت خودکار همان ارائه‌دهنده را ترجیح می‌دهد. برای Volcengine و BytePlus، همان ترجیح با variantهای coding-plan آن‌ها نیز match می‌شود (volcengine-plan/*, byteplus-plan/*).
• اگر filter ارائه‌دهنده ترجیحی خالی باشد، picker به‌جای نمایش ندادن هیچ model، به catalog کامل fallback می‌کند.
• ویزارد یک بررسی model اجرا می‌کند و اگر model پیکربندی‌شده ناشناخته باشد یا auth آن موجود نباشد هشدار می‌دهد.

مسیرهای credential و profile:

• Auth profiles (کلیدهای API + OAuth): ~/.openclaw/agents/<agentId>/agent/auth-profiles.json
• وارد کردن OAuth قدیمی: ~/.openclaw/credentials/oauth.json

حالت ذخیره‌سازی credential:

• رفتار پیش‌فرض onboarding، کلیدهای API را به‌صورت مقادیر متنی ساده در auth profiles نگه می‌دارد.
• --secret-input-mode ref حالت reference را به‌جای ذخیره‌سازی key متنی ساده فعال می‌کند. در راه‌اندازی تعاملی، می‌توانید یکی از این‌ها را انتخاب کنید:
  • environment variable ref (برای مثال keyRef: { source: "env", provider: "default", id: "OPENAI_API_KEY" })
  • configured provider ref (file یا exec) با provider alias + id
• حالت reference تعاملی قبل از ذخیره یک preflight validation سریع اجرا می‌کند.
  • Env refs: نام variable + مقدار غیرخالی در محیط onboarding فعلی را اعتبارسنجی می‌کند.
  • Provider refs: پیکربندی provider را اعتبارسنجی می‌کند و id درخواست‌شده را resolve می‌کند.
  • اگر preflight شکست بخورد، onboarding خطا را نشان می‌دهد و اجازه retry می‌دهد.
• در حالت غیرتعاملی، --secret-input-mode ref فقط مبتنی بر env است.
  • env var ارائه‌دهنده را در محیط فرایند onboarding تنظیم کنید.
  • flagهای inline key (برای مثال --openai-api-key) نیاز دارند که آن env var تنظیم شده باشد؛ در غیر این صورت onboarding سریعاً fail می‌شود.
  • برای ارائه‌دهندگان سفارشی، حالت غیرتعاملی ref، models.providers.<id>.apiKey را به‌صورت { source: "env", provider: "default", id: "CUSTOM_API_KEY" } ذخیره می‌کند.
  • در آن مورد ارائه‌دهنده سفارشی، --custom-api-key نیاز دارد CUSTOM_API_KEY تنظیم شده باشد؛ در غیر این صورت onboarding سریعاً fail می‌شود.
• credentials احراز هویت Gateway در راه‌اندازی تعاملی از گزینه‌های متن ساده و SecretRef پشتیبانی می‌کنند:
  • حالت Token: تولید/ذخیره token متنی ساده (پیش‌فرض) یا استفاده از SecretRef.
  • حالت Password: متن ساده یا SecretRef.
• مسیر SecretRef غیرتعاملی برای token: --gateway-token-ref-env <ENV_VAR>.
• راه‌اندازی‌های متنی ساده موجود بدون تغییر به کار خود ادامه می‌دهند.

# خروجی‌ها و جزئیات داخلی

فیلدهای معمول در ~/.openclaw/openclaw.json:

• agents.defaults.workspace
• agents.defaults.skipBootstrap وقتی --skip-bootstrap پاس داده می‌شود
• agents.defaults.model / models.providers (اگر Minimax انتخاب شده باشد)
• tools.profile (راه‌اندازی اولیه محلی، وقتی تنظیم نشده باشد، به‌طور پیش‌فرض "coding" است؛ مقادیر صریح موجود حفظ می‌شوند)
• gateway.* (حالت، اتصال، احراز هویت، tailscale)
• session.dmScope (راه‌اندازی اولیه محلی، وقتی تنظیم نشده باشد، این مقدار را به‌طور پیش‌فرض روی per-channel-peer می‌گذارد؛ مقادیر صریح موجود حفظ می‌شوند)
• channels.telegram.botToken، channels.discord.token، channels.matrix.*، channels.signal.*، channels.imessage.*
• فهرست‌های مجاز کانال‌ها (Slack، Discord، Matrix، Microsoft Teams) وقتی هنگام اعلان‌ها آن را فعال می‌کنید (نام‌ها در صورت امکان به شناسه‌ها تبدیل می‌شوند)
• skills.install.nodeManager
  • پرچم setup --node-manager مقدارهای npm، pnpm یا bun را می‌پذیرد.
  • پیکربندی دستی همچنان می‌تواند بعداً skills.install.nodeManager: "yarn" را تنظیم کند.
• wizard.lastRunAt
• wizard.lastRunVersion
• wizard.lastRunCommit
• wizard.lastRunCommand
• wizard.lastRunMode

openclaw agents add مقدار agents.list[] و bindings اختیاری را می‌نویسد.

اعتبارنامه‌های WhatsApp زیر ~/.openclaw/credentials/whatsapp/<accountId>/ قرار می‌گیرند. نشست‌ها زیر ~/.openclaw/agents/<agentId>/sessions/ ذخیره می‌شوند.

RPC ویزارد Gateway:

• wizard.start
• wizard.next
• wizard.cancel
• wizard.status

کلاینت‌ها (برنامه macOS و Control UI) می‌توانند بدون پیاده‌سازی دوباره منطق راه‌اندازی اولیه، مراحل را نمایش دهند.

رفتار راه‌اندازی Signal:

• دارایی انتشار مناسب را دانلود می‌کند
• آن را زیر ~/.openclaw/tools/signal-cli/<version>/ ذخیره می‌کند
• channels.signal.cliPath را در پیکربندی می‌نویسد
• ساخت‌های JVM به Java 21 نیاز دارند
• وقتی ساخت‌های بومی موجود باشند، از آن‌ها استفاده می‌شود
• Windows از WSL2 استفاده می‌کند و جریان signal-cli در Linux را داخل WSL دنبال می‌کند

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

• مرکز راه‌اندازی اولیه: راه‌اندازی اولیه (CLI)
• خودکارسازی و اسکریپت‌ها: خودکارسازی CLI
• مرجع فرمان: openclaw onboard