openclaw onboard

راه‌اندازی هدایت‌شده‌ای که ابتدا استنتاج را برقرار می‌کند: دسترسی موجود به هوش مصنوعی را تشخیص می‌دهد، انجام موفق یک تکمیل زنده را الزامی می‌کند، فقط مسیر عملیاتی را ذخیره می‌کند و سپس Crestodian را برای پیکربندی باقی موارد اجرا می‌کند. openclaw setup همان نقطه ورود است؛ openclaw setup --baseline فقط پیکربندی پایه/فضای کاری را می‌نویسد.

مثال‌ها

openclaw onboardopenclaw onboard --classicopenclaw onboard --modernopenclaw onboard --flow quickstartopenclaw onboard --flow manualopenclaw onboard --flow importopenclaw onboard --import-from hermes --import-source ~/.hermesopenclaw onboard --skip-bootstrapopenclaw onboard --mode remote --remote-url wss://gateway-host:18789

• --classic: جادوگر کامل و گام‌به‌گام را باز می‌کند. نمی‌توان آن را با --non-interactive ترکیب کرد؛ برای راه‌اندازی خودکار، --classic را حذف کنید.
• --flow quickstart: جادوگر کلاسیک را با حداقل پرسش‌ها باز می‌کند و یک توکن Gateway را به‌طور خودکار ایجاد می‌کند.
• --flow manual (نام مستعار advanced): جادوگر کلاسیک را با همه پرسش‌های مربوط به درگاه، اتصال و احراز هویت باز می‌کند.
• --flow import: یک ارائه‌دهنده مهاجرت شناسایی‌شده را اجرا می‌کند (برای مثال Hermes با --import-from hermes)، طرح را پیش‌نمایش می‌کند و سپس پس از تأیید آن را اعمال می‌کند. واردسازی فقط روی یک راه‌اندازی تازه OpenClaw اجرا می‌شود؛ اگر پیکربندی، اعتبارنامه‌ها، نشست‌ها یا وضعیت فضای کاری وجود دارند، ابتدا آن‌ها را بازنشانی کنید. برای طرح‌های اجرای آزمایشی، حالت بازنویسی، گزارش‌ها و نگاشت‌های دقیق از openclaw migrate استفاده کنید.
• --modern یک نام مستعار سازگاری برای دستیار راه‌اندازی محاوره‌ای Crestodian است. این گزینه از همان دروازه استنتاج زنده openclaw crestodian استفاده می‌کند و فقط --workspace،‏ --accept-risk، --non-interactive و --json را می‌پذیرد. سایر پرچم‌های راه‌اندازی به‌جای نادیده گرفته‌شدن بی‌سروصدا، رد می‌شوند.

جریان هدایت‌شده

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

اگر تشخیص خودکار همه گزینه‌ها را بررسی کند، گزینه شناسایی‌شده دیگری را انتخاب کنید یا کلید API یک ارائه‌دهنده را در اعلان ورودی پوشیده وارد کنید. کلید دستی از طریق همان مسیر تکمیل زنده آزمایش می‌شود. آشنایی اولیه هدایت‌شده پیش از موفقیت یک گزینه، Crestodian یا خروج بدون هوش مصنوعی را ارائه نمی‌کند. OpenClaw فقط پس از موفقیت آزمایش، مسیر مدل تأییدشده و اعتبارنامه آن را ذخیره می‌کند؛ گزینه ناموفق مدل پیکربندی‌شده را جایگزین نمی‌کند و اعتبارنامه امتحان‌شده را ذخیره نمی‌کند. راه‌اندازی فضای کاری و Gateway تا زمان آغاز Crestodian بدون تغییر باقی می‌ماند.

در حالت هدایت‌شده، --workspace <dir> فضای کاری پیشنهادی Crestodian و زمینه استنتاج ایزوله را مشخص می‌کند. تا زمانی که پیشنهاد راه‌اندازی Crestodian را تأیید نکنید، ذخیره نمی‌شود. آشنایی اولیه کلاسیک و غیرتعاملی، فضای کاری خود را از طریق جریان راه‌اندازی معمولشان ذخیره می‌کنند.

پس از موفقیت استنتاج، آشنایی اولیه هدایت‌شده فوراً Crestodian را با مدل تأییدشده اجرا می‌کند. سپس Crestodian می‌تواند فضای کاری، Gateway، کانال‌ها، عامل‌ها، Pluginها و سایر قابلیت‌های اختیاری را پیکربندی کند. درون Crestodian، از open channel wizard for <channel> استفاده کنید تا جمع‌آوری اعتبارنامه کانال به یک جادوگر ترمینال با ورودی پوشیده سپرده شود. برای تغییر ارائه‌دهنده مدل یا احراز هویت آن، از Crestodian خارج شوید و openclaw onboard را اجرا کنید؛ Crestodian جریان‌های ارائه‌دهنده هدایت‌شده یا کلاسیک را باز نمی‌کند.

در یک نصب پیکربندی‌شده، اجرای دوباره openclaw onboard ابتدا مدل پیش‌فرض فعلی را تأیید می‌کند؛ بنابراین همان جریان به‌عنوان مرحله تأیید و تعمیر نیز عمل می‌کند. اگر این بررسی شکست بخورد، مدل پیکربندی‌شده هرگز به‌طور خودکار جایگزین نمی‌شود — آشنایی اولیه متوقف می‌شود و درباره نحوه ادامه می‌پرسد. بررسی خارج از فضای کاری شما اجرا می‌شود؛ بنابراین مدلی که Plugin فضای کاری فراهم می‌کند ممکن است در اینجا شکست بخورد، درحالی‌که همچنان در عامل کار می‌کند. برای احراز هویت مختص ارائه‌دهنده، کانال‌ها، Skills، راه‌اندازی Gateway راه‌دور، واردسازی‌ها یا کنترل‌های کامل Gateway از openclaw onboard --classic استفاده کنید. برای راه‌اندازی و تعمیر محاوره‌ایِ غیرمرتبط با استنتاج، openclaw crestodian را اجرا کنید؛ openclaw onboard --modern یک نام مستعار سازگاری است که از همان دروازه استنتاج عبور می‌کند. جادوگر کلاسیک می‌تواند در صورت تمایل مدل پیش‌فرض را با یک تکمیل زنده تأیید کند، اما Crestodian تا زمانی که بررسی استنتاج زنده خودش موفق نشود، آغاز نخواهد شد.

در یک ترمینال تعاملی، اجرای ساده openclaw (بدون زیرفرمان) بر اساس وضعیت پیکربندی مسیریابی می‌شود:

• اگر فایل پیکربندی فعال وجود نداشته باشد یا هیچ تنظیم تألیف‌شده‌ای نداشته باشد (خالی یا فقط شامل فراداده باشد)، آشنایی اولیه هدایت‌شده را آغاز می‌کند.
• اگر فایل پیکربندی وجود داشته باشد اما اعتبارسنجی ناموفق باشد، مسیر کلاسیک آشنایی اولیه را با راهنمایی openclaw doctor آغاز می‌کند. Crestodian به استنتاج عملیاتی نیاز دارد و برای تعمیر این وضعیت پیش از استنتاج استفاده نمی‌شود.
• اگر فایل پیکربندی معتبر باشد، TUI عادی عامل را باز می‌کند. یک Gateway پیکربندی‌شده و در دسترس که عامل و مدل دارد، مستقیماً و بدون آشنایی اولیه یا Crestodian به آن رابط کاربری می‌رود. در یک نصب پیکربندی‌شده، از طریق /crestodian درون TUI یا openclaw crestodian به Crestodian دسترسی پیدا کنید.

نشانی‌های Gateway با ws:// متن ساده برای local loopback، مقادیر صریح IP خصوصی، .local و Tailnet با الگوی *.ts.net پذیرفته می‌شوند. برای سایر نام‌های DNS خصوصی مورداعتماد، OPENCLAW_ALLOW_INSECURE_PRIVATE_WS=1 را در محیط فرایند آشنایی اولیه تنظیم کنید.

بازنشانی

openclaw onboard --resetopenclaw onboard --reset --reset-scope full

--reset پیش از اجرای راه‌اندازی، وضعیت را پاک می‌کند. --reset-scope میزان پاک‌سازی را کنترل می‌کند: config (فقط پیکربندی)، config+creds+sessions (حالت پیش‌فرض وقتی --reset بدون محدوده ارسال شود)، یا full (فضای کاری را نیز بازنشانی می‌کند). بازنشانی فضای کاری فقط با --reset-scope full انجام می‌شود.

زبان و منطقه

آشنایی اولیه تعاملی برای متن‌های ثابت راه‌اندازی از زبان و منطقه جادوگر CLI استفاده می‌کند. ترتیب تشخیص:

1. OPENCLAW_LOCALE
2. LC_ALL
3. LC_MESSAGES
4. LANG
5. استفاده از انگلیسی به‌عنوان جایگزین

زبان‌ها و مناطق پشتیبانی‌شده جادوگر عبارت‌اند از en،‏ zh-CN و zh-TW. مقادیر زبان و منطقه می‌توانند از قالب‌های دارای زیرخط یا پسوند POSIX مانند zh_CN.UTF-8 استفاده کنند. نام محصولات، نام فرمان‌ها، کلیدهای پیکربندی، نشانی‌های اینترنتی، شناسه‌های ارائه‌دهنده، شناسه‌های مدل و برچسب‌های Plugin/کانال بدون تغییر باقی می‌مانند.

OPENCLAW_LOCALE=zh-CN openclaw onboard

راه‌اندازی غیرتعاملی

--non-interactive به --accept-risk نیاز دارد (تأیید می‌کند که عامل‌ها قدرتمند هستند و دسترسی کامل به سامانه خطرناک است). مقدار پیش‌فرض --mode برابر local است.

openclaw onboard --non-interactive \  --auth-choice custom-api-key \  --custom-base-url "https://llm.example.com/v1" \  --custom-model-id "foo-large" \  --custom-api-key "$CUSTOM_API_KEY" \  --secret-input-mode plaintext \  --custom-compatibility openai \  --custom-image-input

--custom-api-key اختیاری است؛ اگر حذف شود، آشنایی اولیه CUSTOM_API_KEY را در محیط بررسی می‌کند. OpenClaw شناسه‌های رایج مدل‌های بینایی (GPT-4o/4.1/5.x، Claude 3/4، Gemini، Qwen-VL، LLaVA، Pixtral و موارد مشابه) را به‌طور خودکار دارای قابلیت تصویر علامت‌گذاری می‌کند. برای شناسه‌های سفارشی و ناشناخته مدل‌های بینایی، --custom-image-input را ارسال کنید، یا برای اجبار فراداده فقط‌متنی از --custom-text-input استفاده کنید. برای نقاط پایانی سازگار با OpenAI که از /v1/responses پشتیبانی می‌کنند اما از /v1/chat/completions پشتیبانی نمی‌کنند، از --custom-compatibility openai-responses استفاده کنید؛ مقادیر معتبر عبارت‌اند از openai (پیش‌فرض)، openai-responses و anthropic.

LM Studio نیز یک پرچم کلید مختص ارائه‌دهنده دارد:

openclaw onboard --non-interactive \  --auth-choice lmstudio \  --custom-base-url "http://localhost:1234/v1" \  --custom-model-id "qwen/qwen3.5-9b" \  --lmstudio-api-key "$LM_API_TOKEN" \  --accept-risk

Ollama غیرتعاملی:

openclaw onboard --non-interactive \  --auth-choice ollama \  --custom-base-url "http://ollama-host:11434" \  --custom-model-id "qwen3.5:27b" \  --accept-risk

مقدار پیش‌فرض --custom-base-url برابر http://127.0.0.1:11434 است. --custom-model-id اختیاری است؛ اگر حذف شود، آشنایی اولیه از مقادیر پیش‌فرض پیشنهادی Ollama استفاده می‌کند. شناسه‌های مدل ابری مانند kimi-k2.5:cloud نیز در اینجا کار می‌کنند.

کلیدهای ارائه‌دهنده را به‌جای متن ساده به‌صورت ارجاع ذخیره کنید:

openclaw onboard --non-interactive \  --auth-choice openai-api-key \  --secret-input-mode ref \  --accept-risk

با --secret-input-mode ref، آشنایی اولیه به‌جای مقادیر کلید متن ساده، ارجاع‌های مبتنی بر محیط را می‌نویسد: برای ارائه‌دهندگان مبتنی بر نمایه احراز هویت، این مقدار keyRef: { source: "env", provider: "default", id: <envVar> } را می‌نویسد؛ برای ارائه‌دهندگان سفارشی نیز models.providers.<id>.apiKey را به همین روش می‌نویسد (برای مثال { source: "env", provider: "default", id: "CUSTOM_API_KEY" }). قرارداد: متغیر محیطی ارائه‌دهنده را در محیط فرایند آشنایی اولیه تنظیم کنید (برای مثال OPENAI_API_KEY) و مگر اینکه آن متغیر محیطی تنظیم شده باشد، هم‌زمان یک پرچم کلید درون‌خطی ارسال نکنید؛ مقدار پرچم بدون متغیر محیطی منطبق، به‌سرعت و همراه با راهنمایی شکست می‌خورد.

احراز هویت Gateway (غیرتعاملی)

• --gateway-auth token --gateway-token <token> یک توکن متن ساده ذخیره می‌کند. token حالت پیش‌فرض احراز هویت است.
• --gateway-auth token --gateway-token-ref-env <name> مقدار gateway.auth.token را به‌صورت SecretRef محیطی ذخیره می‌کند. به یک متغیر محیطی غیرخالی با همان نام در محیط فرایند آشنایی اولیه نیاز دارد.
• --gateway-token و --gateway-token-ref-env با یکدیگر ناسازگارند.
• هنگام استفاده از --install-daemon: مقدار gateway.auth.token تحت مدیریت SecretRef اعتبارسنجی می‌شود، اما متن ساده حل‌شده آن در فراداده محیط سرویس ناظر ذخیره نمی‌شود؛ اگر ارجاع حل‌نشده باشد، نصب به‌صورت ایمن متوقف می‌شود و راهنمای رفع مشکل را نمایش می‌دهد. اگر هر دو gateway.auth.token و gateway.auth.password پیکربندی شده باشند و gateway.auth.mode تنظیم نشده باشد، نصب تا زمان تنظیم صریح حالت مسدود می‌شود.
• آشنایی اولیه محلی مقدار gateway.mode="local" را در پیکربندی می‌نویسد. اگر فایل پیکربندی بعدی فاقد gateway.mode باشد، این وضعیت نشان‌دهنده خرابی پیکربندی یا ویرایش دستی ناقص است، نه یک میان‌بر معتبر برای حالت محلی.
• آشنایی اولیه محلی Pluginهای قابل‌بارگیری موردنیاز مسیر راه‌اندازی انتخاب‌شده را نصب می‌کند (برای مثال Plugin زمان اجرای Codex یا Copilot برای گزینه‌های احراز هویت مربوطه). آشنایی اولیه راه‌دور فقط اطلاعات اتصال Gateway راه‌دور را می‌نویسد و هرگز بسته‌های Plugin محلی را نصب نمی‌کند.
• --allow-unconfigured یک راه گریز جداگانه برای openclaw gateway run است؛ این گزینه به آشنایی اولیه اجازه نمی‌دهد gateway.mode را نادیده بگیرد.

export OPENAI_API_KEY="your-provider-key"export OPENCLAW_GATEWAY_TOKEN="your-token"openclaw onboard --non-interactive \  --mode local \  --auth-choice openai-api-key \  --secret-input-mode ref \  --gateway-auth token \  --gateway-token-ref-env OPENCLAW_GATEWAY_TOKEN \  --accept-risk

سلامت Gateway محلی

• مگر اینکه --skip-health را ارسال کنید، آشنایی اولیه پیش از خروج موفقیت‌آمیز منتظر در دسترس‌شدن Gateway محلی می‌ماند.
• --install-daemon ابتدا مسیر نصب Gateway مدیریت‌شده را آغاز می‌کند. بدون آن، یک Gateway محلی باید از قبل در حال اجرا باشد (برای مثال openclaw gateway run).
• اگر در خودکارسازی فقط نوشتن پیکربندی/فضای کاری/بوت‌استرپ را می‌خواهید، --skip-health انتظار را نادیده می‌گیرد.
• --skip-bootstrap مقدار agents.defaults.skipBootstrap: true را تنظیم می‌کند و ایجاد AGENTS.md،‏ SOUL.md،‏ TOOLS.md،‏ IDENTITY.md،‏ USER.md،‏ HEARTBEAT.md و BOOTSTRAP.md را نادیده می‌گیرد.
• در Windows بومی، --install-daemon ابتدا Scheduled Tasks را امتحان می‌کند و اگر ایجاد وظیفه رد شود، به یک مورد ورود به سیستم در پوشه Startup مختص کاربر برمی‌گردد.

حالت ارجاع تعاملی

• هنگام درخواست، استفاده از ارجاع راز را انتخاب کنید و سپس متغیر محیطی یا یک ارائه‌دهنده راز پیکربندی‌شده (file یا exec) را برگزینید.
• آشنایی اولیه پیش از ذخیره ارجاع، یک اعتبارسنجی سریع مقدماتی اجرا می‌کند و در صورت شکست به شما اجازه تلاش دوباره می‌دهد.

گزینه‌های نقطه پایانی Z.AI

# انتخاب نقطهٔ پایانی بدون اعلان تعاملیopenclaw onboard --non-interactive \  --auth-choice zai-coding-global \  --zai-api-key "$ZAI_API_KEY" # دیگر گزینه‌های نقطهٔ پایانی Z.AI: zai-coding-cn، zai-global، zai-cn

Mistral:

openclaw onboard --non-interactive \  --auth-choice mistral-api-key \  --mistral-api-key "$MISTRAL_API_KEY"

پرچم‌های غیرتعاملی بیشتر

احراز هویت مدل مبتنی بر توکن (همراه با --auth-choice token استفاده می‌شود):

Cloudflare AI Gateway: ‏--cloudflare-ai-gateway-account-id <id>، ‏--cloudflare-ai-gateway-gateway-id <id>.

کنترل نصب دیمون: --no-install-daemon / --skip-daemon (نام‌های مستعار؛ نصب سرویس Gateway را رد می‌کنند)، --daemon-runtime <node|bun>.

Skills: ‏--node-manager <npm|pnpm|bun> (پیش‌فرض npm)، ‏--skip-skills.

راه‌اندازی رابط کاربری و هوک: --skip-ui (رد کردن اعلان‌های Control UI/TUI)، --skip-hooks (رد کردن راه‌اندازی Webhook/هوک)، --skip-channels، --skip-search.

خروجی: --suppress-gateway-token-output خروجی‌های Gateway/رابط کاربریِ حاوی توکن را پنهان می‌کند (راهنمایی‌های توکن، نشانی ورود خودکار با توکن تعبیه‌شده و اجرای خودکار Control UI) — برای پایانه‌های مشترک و CI مفید است.

پیش‌فیلتر کردن ارائه‌دهندگان

وقتی یک گزینهٔ احراز هویت به ارائه‌دهنده‌ای ترجیحی اشاره دارد، فرایند راه‌اندازی، انتخاب‌گرهای مدل پیش‌فرض و فهرست مجاز را از پیش به مدل‌های همان ارائه‌دهنده محدود می‌کند. این فیلتر ارائه‌دهندگان دیگری را نیز که متعلق به همان Plugin هستند تطبیق می‌دهد؛ در نتیجه گونه‌های Coding Plan مانند volcengine/volcengine-plan و byteplus/byteplus-plan را پوشش می‌دهد. اگر فیلتر ارائه‌دهندهٔ ترجیحی هیچ مدل بارگذاری‌شده‌ای پیدا نکند، فرایند راه‌اندازی به‌جای خالی گذاشتن انتخاب‌گر، به فهرست بدون فیلتر برمی‌گردد.

پیگیری‌های جست‌وجوی وب

برخی ارائه‌دهندگان جست‌وجوی وب در جریان راه‌اندازی، اعلان‌های پیگیری مختص ارائه‌دهنده را فعال می‌کنند:

• Grok می‌تواند راه‌اندازی اختیاری x_search را با همان احراز هویت xAI و یک انتخاب مدل x_search ارائه دهد.
• Kimi می‌تواند دربارهٔ منطقهٔ API مربوط به Moonshot (api.moonshot.ai در برابر api.moonshot.cn) و مدل پیش‌فرض جست‌وجوی وب Kimi سؤال کند.

رفتارهای دیگر

• رفتار دامنهٔ پیام مستقیم در راه‌اندازی محلی: مرجع راه‌اندازی CLI.
• سریع‌ترین راه برای نخستین گفت‌وگو: openclaw dashboard (Control UI، بدون راه‌اندازی کانال).
• ارائه‌دهندهٔ سفارشی: هر نقطهٔ پایانی سازگار با OpenAI یا Anthropic، از جمله ارائه‌دهندگان میزبانی‌شده‌ای را که فهرست نشده‌اند، متصل کنید. برای تشخیص خودکار از طریق یک کاوش زنده، از سازگاری ناشناخته استفاده کنید.
• اگر وضعیت Hermes تشخیص داده شود، فرایند راه‌اندازی یک جریان مهاجرت پیشنهاد می‌دهد (--flow import را در بالا ببینید).

فرمان‌های متداول پس از راه‌اندازی

بعداً برای تغییرات هدفمندِ بدون استنتاج از openclaw configure و برای راه‌اندازی صرفاً کانال از openclaw channels add استفاده کنید. برای تغییر ارائه‌دهندهٔ مدل یا مسیر احراز هویت، به‌جای آن openclaw onboard را اجرا کنید.

openclaw channels addopenclaw configureopenclaw agents add <name>