English简体中文繁體中文日本語EspañolPortuguês (BR)한국어DeutschFrançaisالعربيةItalianoTiếng ViệtNederlandsTürkçeУкраїнськаBahasa IndonesiaPolskiفارسیไทย

Technical reference

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

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

تفاصيل سير العمل (الوضع المحلي)

  • اكتشاف الإعدادات الحالية

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

  • النموذج/المصادقة

    • مفتاح Anthropic API: يستخدم ANTHROPIC_API_KEY إذا كان موجودًا أو يطلب مفتاحًا، ثم يحفظه لاستخدام الخادم الخفي.
    • مفتاح Anthropic API: خيار مساعد Anthropic المفضل في الإعداد الأولي/التهيئة.
    • رمز إعداد Anthropic: لا يزال متاحًا في الإعداد الأولي/التهيئة، رغم أن OpenClaw يفضل الآن إعادة استخدام Claude CLI عند توفره.
    • اشتراك OpenAI Code (Codex) (OAuth): تدفق المتصفح؛ الصق code#state.
      • يضبط agents.defaults.model على openai-codex/gpt-5.5 عندما لا يكون النموذج مضبوطًا أو كان من عائلة OpenAI بالفعل.
    • اشتراك OpenAI Code (Codex) (إقران الجهاز): تدفق إقران عبر المتصفح مع رمز جهاز قصير العمر.
      • يضبط agents.defaults.model على openai-codex/gpt-5.5 عندما لا يكون النموذج مضبوطًا أو كان من عائلة OpenAI بالفعل.
    • مفتاح OpenAI API: يستخدم OPENAI_API_KEY إذا كان موجودًا أو يطلب مفتاحًا، ثم يخزنه في ملفات تعريف المصادقة.
      • يضبط agents.defaults.model على openai/gpt-5.5 عندما لا يكون النموذج مضبوطًا، أو openai/*، أو openai-codex/*.
    • مفتاح xAI (Grok) API: يطلب XAI_API_KEY ويهيئ 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-M2.7. يستخدم إعداد مفتاح 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

  • مساحة العمل

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

  • Gateway

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

  • القنوات

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

  • بحث الويب

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

  • تثبيت الخادم الخفي

    • 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 غير مضبوط، يُحظر تثبيت الخادم الخفي حتى يُضبط الوضع صراحة.

  • فحص الصحة

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

  • Skills (موصى بها)

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

  • الإنهاء

    • ملخص + الخطوات التالية، بما في ذلك تطبيقات iOS/Android/macOS للميزات الإضافية.

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

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

    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 للحصول على ملخص قابل للقراءة آليًا.

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

    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. استخدم صفحة المرجع هذه لدلالات العلامات وترتيب الخطوات.

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

    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 أو مسار محلي) قبل أن يمكن تهيئتها.

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