openclaw onboard

راه‌اندازی اولیهٔ هدایت‌شدهٔ کامل برای تنظیم Gateway محلی یا راه دور. زمانی از این استفاده کنید که می‌خواهید OpenClaw احراز هویت مدل، فضای کاری، Gateway، کانال‌ها، Skills و سلامت را در یک جریان مرور کند.

راهنماهای مرتبط

نمونه‌ها

openclaw onboardopenclaw 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

--flow import از ارائه‌دهنده‌های مهاجرتِ متعلق به Plugin مانند Hermes استفاده می‌کند. این گزینه فقط روی یک تنظیم تازهٔ OpenClaw اجرا می‌شود؛ اگر پیکربندی، اعتبارنامه‌ها، نشست‌ها، یا فایل‌های حافظه/هویت فضای کاری موجود باشند، پیش از وارد کردن، بازنشانی کنید یا یک تنظیم تازه انتخاب کنید.

--modern پیش‌نمایش راه‌اندازی اولیهٔ گفت‌وگویی Crestodian را شروع می‌کند. بدون --modern، openclaw onboard جریان کلاسیک راه‌اندازی اولیه را نگه می‌دارد.

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

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

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

زبان

راه‌اندازی اولیهٔ تعاملی از زبان جادوگر CLI برای متن ثابت تنظیم استفاده می‌کند. ترتیب حل‌وفصل چنین است:

1. OPENCLAW_LOCALE
2. LC_ALL
3. LC_MESSAGES
4. LANG
5. بازگشت به انگلیسی

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

نمونه:

OPENCLAW_LOCALE=zh-CN openclaw onboard

ارائه‌دهندهٔ سفارشی غیرتعاملی:

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 شناسه‌های رایج مدل‌های بینایی را به‌طور خودکار دارای قابلیت تصویر علامت‌گذاری می‌کند. برای شناسه‌های سفارشی بینایی ناشناخته --custom-image-input را پاس کنید، یا برای اجبار فرادادهٔ فقط‌متنی از --custom-text-input استفاده کنید. برای نقاط پایانی سازگار با OpenAI که از /v1/responses پشتیبانی می‌کنند اما از /v1/chat/completions نه، از --custom-compatibility openai-responses استفاده کنید.

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، راه‌اندازی اولیه به‌جای مقدارهای کلیدِ متن ساده، ارجاع‌های مبتنی بر env می‌نویسد. برای ارائه‌دهنده‌های مبتنی بر نمایهٔ احراز هویت، این کار ورودی‌های keyRef می‌نویسد؛ برای ارائه‌دهنده‌های سفارشی، models.providers.<id>.apiKey را به‌عنوان یک ارجاع env می‌نویسد (برای مثال { source: "env", provider: "default", id: "CUSTOM_API_KEY" }).

قرارداد حالت ref غیرتعاملی:

• متغیر env ارائه‌دهنده را در محیط فرایند راه‌اندازی اولیه تنظیم کنید (برای مثال OPENAI_API_KEY).
• پرچم‌های کلید درون‌خطی (برای مثال --openai-api-key) را پاس نکنید مگر اینکه آن متغیر env نیز تنظیم شده باشد.
• اگر یک پرچم کلید درون‌خطی بدون متغیر env لازم پاس شود، راه‌اندازی اولیه سریع و همراه با راهنمایی شکست می‌خورد.

گزینه‌های توکن Gateway در حالت غیرتعاملی:

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

نمونه:

export OPENCLAW_GATEWAY_TOKEN="your-token"openclaw onboard --non-interactive \  --mode local \  --auth-choice skip \  --gateway-auth token \  --gateway-token-ref-env OPENCLAW_GATEWAY_TOKEN \  --accept-risk

سلامت Gateway محلی غیرتعاملی:

• مگر اینکه --skip-health را پاس کنید، راه‌اندازی اولیه پیش از خروج موفق، منتظر یک Gateway محلی در دسترس می‌ماند.
• --install-daemon ابتدا مسیر نصب Gateway مدیریت‌شده را شروع می‌کند. بدون آن، باید از قبل یک Gateway محلی در حال اجرا داشته باشید، برای مثال openclaw gateway run.
• اگر در اتوماسیون فقط نوشتن پیکربندی/فضای کاری/bootstrap را می‌خواهید، از --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 را امتحان می‌کند و اگر ایجاد task رد شود، به یک مورد ورود پوشهٔ Startup برای هر کاربر بازمی‌گردد.

رفتار راه‌اندازی اولیهٔ تعاملی با حالت ارجاع:

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

انتخاب‌های نقطهٔ پایانی Z.AI غیرتعاملی

# Promptless endpoint selectionopenclaw onboard --non-interactive \  --auth-choice zai-coding-global \  --zai-api-key "$ZAI_API_KEY" # Other Z.AI endpoint choices:# --auth-choice zai-coding-cn# --auth-choice zai-global# --auth-choice zai-cn

نمونهٔ Mistral غیرتعاملی:

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

پرچم‌های غیرتعاملی اضافی

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

• --token-provider <id> — شناسهٔ ارائه‌دهندهٔ توکن. مشخص می‌کند کدام ارائه‌دهنده توکن را صادر می‌کند.
• --token <token> — مقدار توکن برای احراز هویت مدل.
• --token-profile-id <id> — شناسهٔ نمایهٔ احراز هویت. ذخیره‌سازی توکن عمومی به‌طور پیش‌فرض <provider>:manual است؛ جریان‌های تنظیم متعلق به ارائه‌دهنده ممکن است از پیش‌فرض خود استفاده کنند، مانند anthropic:default.
• --token-expires-in <duration> — مدت انقضای اختیاری توکن (مثلاً 365d، 12h).

Cloudflare AI Gateway (غیرتعاملی):

• --cloudflare-ai-gateway-account-id <id> — شناسهٔ حساب Cloudflare برای مسیریابی از طریق Cloudflare AI Gateway.
• --cloudflare-ai-gateway-gateway-id <id> — شناسهٔ Cloudflare AI Gateway.

کنترل نصب daemon:

• --no-install-daemon — نصب سرویس Gateway را به‌صراحت رد می‌کند.
• --skip-daemon — نام مستعار برای --no-install-daemon.

کنترل تنظیم UI و hook:

• --skip-ui — درخواست‌های Control UI / TUI را در طول راه‌اندازی اولیه رد می‌کند.
• --skip-hooks — درخواست‌های تنظیم webhook / hook را در طول راه‌اندازی اولیه رد می‌کند.

سرکوب خروجی:

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

نکات جریان

فرمان‌های پیگیری رایج

openclaw channels addopenclaw configureopenclaw agents add <name>

از openclaw setup به‌عنوان همان نقطهٔ ورود راه‌اندازی هدایت‌شده استفاده کنید. وقتی فقط به پیکربندی/فضای کاری پایه نیاز دارید از openclaw setup --baseline استفاده کنید، برای تغییرات هدفمند بعدی از openclaw configure، و برای راه‌اندازی فقط کانال از openclaw channels add استفاده کنید.