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 معد ومتاح. في تثبيت معد، يمكنك الوصول إلى Crestodian باستخدام /crestodian داخل TUI أو openclaw crestodian.

يقبل نص ws:// العادي لعناوين local 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 لفرض بيانات وصفية للنص فقط. استخدم --custom-compatibility openai-responses لنقاط النهاية المتوافقة مع OpenAI التي تدعم /v1/responses لكنها لا تدعم /v1/chat/completions.

يدعم 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؛ وبالنسبة إلى المزودين المخصصين، يكتب models.providers.<id>.apiKey كمرجع بيئة (مثلا { source: "env", provider: "default", id: "CUSTOM_API_KEY" }).

عقد وضع ref غير التفاعلي:

• اضبط متغير بيئة المزود في بيئة عملية الإعداد (مثلا OPENAI_API_KEY).
• لا تمرر أعلام المفاتيح المضمنة (مثلا --openai-api-key) إلا إذا كان متغير البيئة ذاك مضبوطا أيضا.
• إذا مُرر علم مفتاح مضمن من دون متغير البيئة المطلوب، يفشل الإعداد بسرعة مع إرشادات.

خيارات رمز Gateway في الوضع غير التفاعلي:

• --gateway-auth token --gateway-token <token> يخزن رمزا بنص عادي.
• --gateway-auth token --gateway-token-ref-env <name> يخزن gateway.auth.token كـ SecretRef بيئي.
• --gateway-token و--gateway-token-ref-env متنافيان.
• يتطلب --gateway-token-ref-env متغير بيئة غير فارغ في بيئة عملية الإعداد.
• مع --install-daemon، عندما تتطلب مصادقة الرمز رمزا، يتم التحقق من رموز Gateway المدارة عبر SecretRef لكن لا تُحفظ كنص عادي محلول في بيانات وصفية لبيئة خدمة المشرف.
• مع --install-daemon، إذا كان وضع الرمز يتطلب رمزا وكان SecretRef الخاص بالرمز المعد غير محلول، يفشل الإعداد بإغلاق آمن مع إرشادات إصلاح.
• مع --install-daemon، إذا كان كل من gateway.auth.token وgateway.auth.password معدين وكان gateway.auth.mode غير مضبوط، يحظر الإعداد التثبيت حتى يُضبط الوضع صراحة.
• يكتب الإعداد المحلي gateway.mode="local" في الإعدادات. إذا افتقد ملف إعدادات لاحق gateway.mode، فتعامل مع ذلك كتلف في الإعدادات أو تعديل يدوي غير مكتمل، لا كاختصار صالح للوضع المحلي.
• يثبت الإعداد المحلي Plugins القابلة للتنزيل المحددة عندما يتطلبها مسار الإعداد المختار.
• لا يكتب الإعداد البعيد إلا معلومات الاتصال ب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.
• إذا كنت تريد فقط كتابة الإعدادات/مساحة العمل/التمهيد في الأتمتة، فاستخدم --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 استخدام المهام المجدولة أولا ثم يرجع إلى عنصر تسجيل دخول في مجلد بدء التشغيل لكل مستخدم إذا رُفض إنشاء المهمة.

سلوك الإعداد التفاعلي مع وضع المراجع:

• اختر استخدام مرجع سر عند المطالبة.
• ثم اختر إما:
  • متغير بيئة
  • مزود أسرار معد (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.

التحكم في إعداد الواجهة والخطافات:

• --skip-ui — تخطي مطالبات Control UI / TUI أثناء الإعداد.
• --skip-hooks — تخطي مطالبات إعداد Webhook / الخطاف أثناء الإعداد.

كتم المخرجات:

• --suppress-gateway-token-output — كتم مخرجات Gateway/الواجهة التي تحمل رموزا (تلميحات الرمز، ورابط تسجيل الدخول التلقائي الذي يحتوي على رمز مضمن، والتشغيل التلقائي لـControl UI). مفيد في الطرفيات المشتركة وبيئات CI.

ملاحظات التدفق

أوامر المتابعة الشائعة

openclaw channels addopenclaw configureopenclaw agents add <name>

استخدم openclaw setup كنقطة الدخول نفسها للإعداد الإرشادي الأولي. استخدم openclaw setup --baseline عندما تحتاج فقط إلى الإعدادات الأساسية/مساحة العمل الأساسية، وopenclaw configure لاحقًا للتغييرات المستهدفة، وopenclaw channels add لإعداد القناة فقط.