English简体中文繁體中文日本語EspañolPortuguês (BR)한국어DeutschFrançaisहिन्दीالعربيةItalianoTiếng ViệtNederlandsTürkçeУкраїнськаBahasa IndonesiaPolskiРусскийفارسیไทย
View as MarkdownView this page as plain textOpen in ChatGPTAsk questions about this pageOpen in ClaudeAsk questions about this pageOpen in PerplexityAsk questions about this page

Technical reference

مرجع الإعداد الأولي

هذا هو المرجع الكامل للأمر openclaw onboard. للاطلاع على نظرة عامة عالية المستوى، راجع الإعداد الأولي (CLI).

تفاصيل التدفق (الوضع المحلي)

  • Existing config detection

    • إذا كان ~/.openclaw/openclaw.json موجودًا، فاختر الاحتفاظ بالقيم الحالية، أو المراجعة والتحديث، أو إعادة الضبط قبل الإعداد.
    • لا تؤدي إعادة تشغيل الإعداد الأولي إلى مسح أي شيء إلا إذا اخترت إعادة الضبط صراحةً (أو مررت --reset).
    • الخيار --reset في CLI يستخدم config+creds+sessions افتراضيًا؛ استخدم --reset-scope full لإزالة مساحة العمل أيضًا.
    • إذا كان التكوين غير صالح أو يحتوي على مفاتيح قديمة، يتوقف المعالج ويطلب منك تشغيل openclaw doctor قبل المتابعة.
    • تستخدم إعادة الضبط trash (وليس rm مطلقًا) وتعرض نطاقات:
      • التكوين فقط
      • التكوين + بيانات الاعتماد + الجلسات
      • إعادة ضبط كاملة (تزيل مساحة العمل أيضًا)

  • Model/Auth

    • مفتاح Anthropic API: يستخدم ANTHROPIC_API_KEY إذا كان موجودًا أو يطلب مفتاحًا، ثم يحفظه لاستخدام الخدمة الخلفية.
    • مفتاح Anthropic API: خيار مساعد Anthropic المفضل في الإعداد الأولي/التكوين.
    • رمز إعداد Anthropic: لا يزال متاحًا في الإعداد الأولي/التكوين، مع أن OpenClaw يفضل الآن إعادة استخدام Claude CLI عند توفره.
    • اشتراك OpenAI Code (Codex) (OAuth): تدفق عبر المتصفح؛ الصق code#state.
      • يضبط agents.defaults.model على openai/gpt-5.5 عبر وقت تشغيل Codex عندما لا يكون النموذج مضبوطًا أو يكون بالفعل من عائلة OpenAI.
    • اشتراك OpenAI Code (Codex) (إقران الجهاز): تدفق إقران عبر المتصفح باستخدام رمز جهاز قصير العمر.
      • يضبط agents.defaults.model على openai/gpt-5.5 عبر وقت تشغيل Codex عندما لا يكون النموذج مضبوطًا أو يكون بالفعل من عائلة OpenAI.
    • مفتاح OpenAI API: يستخدم OPENAI_API_KEY إذا كان موجودًا أو يطلب مفتاحًا، ثم يخزنه في ملفات تعريف المصادقة.
      • يضبط agents.defaults.model على openai/gpt-5.5 عندما لا يكون النموذج مضبوطًا، أو يكون openai/*، أو مراجع نماذج Codex قديمة.
    • xAI (Grok) OAuth / مفتاح API: يسجل الدخول باستخدام xAI OAuth عند اختياره، أو يطلب XAI_API_KEY في مسار مفتاح API، ويكوّن xAI كموفر نماذج.
    • OpenCode: يطلب OPENCODE_API_KEY (أو OPENCODE_ZEN_API_KEY، احصل عليه من https://opencode.ai/auth) ويتيح لك اختيار كتالوج Zen أو Go.
    • Ollama: يعرض أولًا السحابة + المحلي، أو السحابة فقط، أو المحلي فقط. يطلب Cloud only قيمة OLLAMA_API_KEY ويستخدم https://ollama.com؛ أما الأوضاع المدعومة بالمضيف فتطلب عنوان URL الأساسي لـ Ollama، وتكتشف النماذج المتاحة، وتسحب النموذج المحلي المحدد تلقائيًا عند الحاجة؛ كما يتحقق Cloud + Local مما إذا كان مضيف Ollama ذلك مسجل الدخول للوصول السحابي.
    • مزيد من التفاصيل: Ollama
    • مفتاح 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 القياسي أو Step Plan على نقاط النهاية الصينية أو العالمية.
    • يتضمن القياسي حاليًا step-3.5-flash، كما يتضمن Step Plan أيضًا step-3.5-flash-2603.
    • مزيد من التفاصيل: StepFun
    • Synthetic (متوافق مع Anthropic): يطلب SYNTHETIC_API_KEY.
    • مزيد من التفاصيل: Synthetic
    • Moonshot (Kimi K2): تتم كتابة التكوين تلقائيًا.
    • Kimi Coding: تتم كتابة التكوين تلقائيًا.
    • مزيد من التفاصيل: Moonshot AI (Kimi + Kimi Coding)
    • تخطي: لم يتم تكوين أي مصادقة بعد.
    • اختر نموذجًا افتراضيًا من الخيارات المكتشفة (أو أدخل الموفر/النموذج يدويًا). للحصول على أفضل جودة وتقليل خطر حقن الموجهات، اختر أقوى نموذج من أحدث جيل متاح في مجموعة موفريك.
    • يجري الإعداد الأولي فحصًا للنموذج ويحذر إذا كان النموذج المكوّن غير معروف أو تنقصه المصادقة.
    • الوضع الافتراضي لتخزين مفاتيح API هو قيم ملف تعريف مصادقة بنص عادي. استخدم --secret-input-mode ref لتخزين مراجع مدعومة بمتغيرات البيئة بدلًا من ذلك (مثل keyRef: { source: "env", provider: "default", id: "OPENAI_API_KEY" }).
    • توجد ملفات تعريف المصادقة في ~/.openclaw/agents/<agentId>/agent/auth-profiles.json (مفاتيح API + OAuth). الملف ~/.openclaw/credentials/oauth.json قديم ومخصص للاستيراد فقط.
    • مزيد من التفاصيل: /concepts/oauth

  • Workspace

    • الافتراضي ~/.openclaw/workspace (قابل للتكوين).
    • يزرع ملفات مساحة العمل اللازمة لطقس تمهيد العميل.
    • تخطيط مساحة العمل الكامل + دليل النسخ الاحتياطي: مساحة عمل العميل

  • Gateway

    • المنفذ، والربط، ووضع المصادقة، والتعرض عبر Tailscale.
    • توصية المصادقة: أبقِ الرمز المميز حتى مع loopback بحيث يجب على عملاء WS المحليين المصادقة.
    • في وضع الرمز المميز، يعرض الإعداد التفاعلي:
      • إنشاء/تخزين رمز مميز بنص عادي (افتراضي)
      • استخدام SecretRef (اختياري)
      • يعيد البدء السريع استخدام SecretRefs الحالية في gateway.auth.token عبر موفري env وfile وexec لتمهيد مسبار الإعداد الأولي/لوحة التحكم.
      • إذا كان SecretRef ذلك مكوّنًا ولكن لا يمكن حله، يفشل الإعداد الأولي مبكرًا برسالة إصلاح واضحة بدلًا من خفض مصادقة وقت التشغيل بصمت.
    • في وضع كلمة المرور، يدعم الإعداد التفاعلي أيضًا التخزين بنص عادي أو SecretRef.
    • مسار SecretRef غير التفاعلي للرمز المميز: --gateway-token-ref-env &lt;ENV_VAR&gt;.
      • يتطلب متغير بيئة غير فارغ في بيئة عملية الإعداد الأولي.
      • لا يمكن دمجه مع --gateway-token.
    • عطّل المصادقة فقط إذا كنت تثق تمامًا بكل عملية محلية.
    • لا تزال روابط غير loopback تتطلب المصادقة.

  • Channels

    • WhatsApp: تسجيل دخول QR اختياري.
    • Telegram: رمز البوت.
    • Discord: رمز البوت.
    • Google Chat: JSON لحساب خدمة + جمهور Webhook.
    • Mattermost (Plugin): رمز البوت + عنوان URL الأساسي.
    • Signal: تثبيت اختياري لـ signal-cli + تكوين الحساب.
    • iMessage: مسار imsg في CLI + الوصول إلى قاعدة بيانات Messages؛ استخدم مغلف SSH عندما يعمل Gateway خارج Mac.
    • أمان الرسائل المباشرة: الافتراضي هو الإقران. ترسل أول رسالة مباشرة رمزًا؛ وافق عبر openclaw pairing approve <channel> <code> أو استخدم قوائم السماح.

  • Web search

    • اختر موفرًا مدعومًا مثل Brave أو DuckDuckGo أو Exa أو Firecrawl أو Gemini أو Grok أو Kimi أو MiniMax Search أو Ollama Web Search أو Perplexity أو SearXNG أو Tavily (أو تخطَّ).
    • يمكن للموفرين المدعومين بـ API استخدام متغيرات البيئة أو التكوين الحالي للإعداد السريع؛ أما الموفرون بلا مفاتيح فيستخدمون متطلباتهم الخاصة بدلًا من ذلك.
    • تخطَّ باستخدام --skip-search.
    • كوّن لاحقًا: openclaw configure --section web.

  • Daemon install

    • macOS: LaunchAgent
      • يتطلب جلسة مستخدم مسجل الدخول؛ للبيئات بلا واجهة، استخدم LaunchDaemon مخصصًا (غير مشحون).
    • Linux (وWindows عبر WSL2): وحدة systemd للمستخدم
      • يحاول الإعداد الأولي تمكين البقاء عبر loginctl enable-linger <user> بحيث يبقى Gateway عاملًا بعد تسجيل الخروج.
      • قد يطلب sudo (يكتب إلى /var/lib/systemd/linger)؛ يحاول أولًا من دون sudo.
    • اختيار وقت التشغيل: Node (موصى به؛ مطلوب لـ WhatsApp/Telegram). Bun غير موصى به.
    • إذا كانت مصادقة الرمز المميز تتطلب رمزًا وكان gateway.auth.token مُدارًا بواسطة SecretRef، يتحقق تثبيت الخدمة الخلفية منه لكنه لا يحفظ قيم الرمز المميز المحلولة بنص عادي في بيانات تعريف بيئة خدمة المشرف.
    • إذا كانت مصادقة الرمز المميز تتطلب رمزًا وكان SecretRef المكوّن للرمز غير محلول، يتم حظر تثبيت الخدمة الخلفية مع إرشادات قابلة للتنفيذ.
    • إذا كان كل من gateway.auth.token وgateway.auth.password مكوّنين وكان gateway.auth.mode غير مضبوط، يتم حظر تثبيت الخدمة الخلفية حتى يتم ضبط الوضع صراحةً.

  • Health check

    • يبدأ Gateway (إذا لزم الأمر) ويشغّل openclaw health.
    • نصيحة: يضيف openclaw status --deep مسبار صحة Gateway الحي إلى مخرجات الحالة، بما في ذلك مسابر القنوات عند دعمها (يتطلب Gateway قابلًا للوصول).

  • Skills (recommended)

    • يقرأ Skills المتاحة ويتحقق من المتطلبات.
    • يتيح لك اختيار مدير Node: npm / pnpm (bun غير موصى به).
    • يثبت التبعيات الاختيارية (يستخدم بعضها Homebrew على macOS).

  • Finish

    • ملخص + الخطوات التالية، بما في ذلك مطالبة كيف تريد تفريخ عميلك؟ لـ Terminal أو Browser أو لاحقًا.

    • الوضع غير التفاعلي

    استخدم --non-interactive لأتمتة الإعداد الأولي أو كتابته كسكربت:

    bash
    openclaw onboard --non-interactive \  --mode local \  --auth-choice apiKey \  --anthropic-api-key "$ANTHROPIC_API_KEY" \  --gateway-port 18789 \  --gateway-bind loopback \  --install-daemon \  --daemon-runtime node \  --skip-skills

    أضف --json للحصول على ملخص قابل للقراءة آليًا.

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

    bash
    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

    --gateway-token و--gateway-token-ref-env متنافيان.

    توجد أمثلة أوامر خاصة بالموفرين في أتمتة CLI. استخدم صفحة المرجع هذه لدلالات الأعلام وترتيب الخطوات.

    إضافة عميل (غير تفاعلي)

    bash
    openclaw agents add work \  --workspace ~/.openclaw/workspace-work \  --model openai/gpt-5.5 \  --bind whatsapp:biz \  --non-interactive \  --json

    RPC لمعالج Gateway

    يعرض Gateway تدفق الإعداد الأولي عبر RPC (wizard.start, wizard.next, wizard.cancel, wizard.status). يمكن للعملاء (تطبيق macOS، وControl UI) عرض الخطوات من دون إعادة تنفيذ منطق الإعداد الأولي.

    إعداد Signal (signal-cli)

    يمكن للإعداد الأولي تثبيت signal-cli من إصدارات GitHub:

    • ينزل أصل الإصدار المناسب.
    • يخزنه ضمن ~/.openclaw/tools/signal-cli/<version>/.
    • يكتب channels.signal.cliPath إلى تكوينك.

    ملاحظات:

    • تتطلب إصدارات JVM Java 21.
    • تُستخدم الإصدارات الأصلية عند توفرها.
    • يستخدم Windows ‏WSL2؛ يتبع تثبيت signal-cli تدفق Linux داخل WSL.

    ما يكتبه المعالج

    الحقول النموذجية في ~/.openclaw/openclaw.json:

    • agents.defaults.workspace
    • agents.defaults.model / models.providers (إذا تم اختيار Minimax)
    • tools.profile (تكون إعدادات الإعداد المحلي الافتراضية "coding" عند عدم ضبطها؛ وتُحفظ القيم الصريحة الموجودة)
    • gateway.* (الوضع، الربط، المصادقة، tailscale)
    • session.dmScope (تفاصيل السلوك: مرجع إعداد CLI)
    • 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.
      • لا يزال بإمكان التكوين اليدوي استخدام yarn عبر ضبط skills.install.nodeManager مباشرة.
    • 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/.

    تُقدَّم بعض القنوات بصفتها plugins. عند اختيار واحدة أثناء الإعداد، سيطالبك الإعداد بتثبيتها (npm أو مسار محلي) قبل أن يمكن تكوينها.

    مستندات ذات صلة

    Was this useful?
    On this page

    On this page