الانتقال إلى المحتوى الرئيسي

أدلة

مرجع الإعداد الأولي عبر سطر الأوامر

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

ما يفعله الساحر​

يأخذك الوضع المحلي (الافتراضي) خلال الخطوات التالية:

  • إعداد النموذج والمصادقة (مصادقة OAuth لاشتراك OpenAI Code، مفتاح واجهة برمجة تطبيقات Anthropic أو رمز الإعداد، بالإضافة إلى خيارات MiniMax وGLM وMoonshot وAI Gateway)
  • موقع مساحة العمل وملفات التهيئة الأولية
  • إعدادات البوابة (المنفذ، الربط، المصادقة، tailscale)
  • القنوات والمزودين (Telegram، WhatsApp، Discord، Google Chat، إضافة Mattermost، Signal)
  • تثبيت الخدمة الخلفية (LaunchAgent أو وحدة systemd للمستخدم)
  • فحص الصحة
  • إعداد المهارات

يقوم الوضع البعيد بتكوين هذا الجهاز للاتصال ببوابة في مكان آخر. لا يقوم بتثبيت أو تعديل أي شيء على المضيف البعيد.

تفاصيل التدفق المحلي​

الخطوة 1: اكتشاف التكوين الحالي​

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

الخطوة 2: النموذج والمصادقة​

الخطوة 3: مساحة العمل​

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

الخطوة 4: البوابة​

  • يطلب المنفذ، والربط، ووضع المصادقة، والتعرض عبر tailscale.
  • موصى به: ابق تفعيل مصادقة الرمز المميز حتى للاتصال المحلي (loopback) بحيث يجب على عملاء WebSocket المحليين المصادقة.
  • في وضع الرمز المميز، يعرض الإعداد الأولي التفاعلي:
    • إنشاء/تخزين رمز مميز نصي عادي (الافتراضي)
    • استخدام SecretRef (اختياري)
  • في وضع كلمة المرور، يدعم الإعداد الأولي التفاعلي أيضًا التخزين النصي العادي أو عبر SecretRef.
  • مسار SecretRef للرمز المميز في الوضع غير التفاعلي: --gateway-token-ref-env <ENV_VAR>.
    • يتطلب وجود متغير بيئة غير فارغ في بيئة عملية الإعداد الأولي.
    • لا يمكن دمجه مع --gateway-token.
  • عطّل المصادقة فقط إذا كنت تثق تمامًا بكل عملية محلية.
  • عمليات الربط غير المحلية (non-loopback) لا تزال تتطلب مصادقة.

الخطوة 5: القنوات​

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

الخطوة 6: تثبيت الخدمة الخلفية​

  • macOS: LaunchAgent
    • يتطلب جلسة مستخدم مسجل الدخول؛ للاستخدام بدون واجهة، استخدم LaunchDaemon مخصصًا (غير مدرج).
  • Linux وWindows عبر WSL2: وحدة systemd للمستخدم
    • يحاول الساحر loginctl enable-linger لتبقى البوابة قيد التشغيل بعد تسجيل الخروج.
    • قد يطلب صلاحيات sudo (يكتب في /var/lib/systemd/linger)؛ يحاول أولاً بدون sudo.
  • اختيار وقت التشغيل: Node (موصى به؛ مطلوب لـ WhatsApp وTelegram). Bun غير موصى به.

الخطوة 7: فحص الصحة​

  • يبدأ تشغيل البوابة (إذا لزم الأمر) ويشغل openclaw health.
  • يضيف openclaw status --deep فحوصات صحة البوابة إلى ناتج الحالة.

الخطوة 8: المهارات​

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

الخطوة 9: الانتهاء​

  • ملخص والخطوات التالية، بما في ذلك خيارات تطبيقات iOS وAndroid وmacOS.

ℹ️ إذا لم يتم اكتشاف واجهة مستخدم رسومية، يطبع الساحر تعليمات توجيه المنفذ عبر SSH لواجهة التحكم بدلاً من فتح متصفح. إذا كانت أصول واجهة التحكم مفقودة، يحاول الساحر بناؤها؛ الاحتياطي هو pnpm ui:build (يثبت تبعيات الواجهة تلقائيًا).

تفاصيل الوضع البعيد​

يقوم الوضع البعيد بتكوين هذا الجهاز للاتصال ببوابة في مكان آخر.

ℹ️ الوضع البعيد لا يثبت أو يعدل أي شيء على المضيف البعيد.

ما تقوم بتعيينه:

  • عنوان URL للبوابة البعيدة (ws://...)
  • الرمز المميز إذا كانت مصادقة البوابة البعيدة مطلوبة (موصى به)

ℹ️ - إذا كانت البوابة للاتصال المحلي فقط، استخدم النفق عبر SSH أو شبكة tailnet.

  • تلميحات الاكتشاف:
    • macOS: Bonjour (dns-sd)
    • Linux: Avahi (avahi-browse)

خيارات المصادقة والنموذج​

يستخدم ANTHROPIC_API_KEY إذا كان موجودًا أو يطلب مفتاحًا، ثم يحفظه لاستخدام الخدمة الخلفية.

  • macOS: يتحقق من عنصر Keychain "Claude Code-credentials"
  • Linux وWindows: يعيد استخدام ~/.claude/.credentials.json إذا كان موجودًا

على macOS، اختر "السماح دائمًا" حتى لا تمنع عمليات بدء launchd.

شغل claude setup-token على أي جهاز، ثم الصق الرمز المميز. يمكنك تسميته؛ الفراغ يستخدم الافتراضي.

إذا كان ~/.codex/auth.json موجودًا، يمكن للساحر إعادة استخدامه.

تدفق المتصفح؛ الصق code#state.يضبط agents.defaults.model على openai-codex/gpt-5.4 عندما يكون النموذج غير مضبوط أو openai/*.

يستخدم OPENAI_API_KEY إذا كان موجودًا أو يطلب مفتاحًا، ثم يخزن بيانات الاعتماد في ملفات تعريف المصادقة.يضبط agents.defaults.model على openai/gpt-5.1-codex عندما يكون النموذج غير مضبوط، أو openai/*، أو openai-codex/*.

يطلب XAI_API_KEY ويضبط xAI كمزود نموذج.

يطلب OPENCODE_API_KEY (أو OPENCODE_ZEN_API_KEY). رابط الإعداد: opencode.ai/auth.

يخزن المفتاح لك.

يطلب AI_GATEWAY_API_KEY. المزيد من التفاصيل: Vercel AI Gateway.

يطلب معرف الحساب، ومعرف البوابة، و CLOUDFLARE_AI_GATEWAY_API_KEY. المزيد من التفاصيل: Cloudflare AI Gateway.

يتم كتابة التكوين تلقائيًا. المزيد من التفاصيل: MiniMax.

يطلب SYNTHETIC_API_KEY. المزيد من التفاصيل: Synthetic.

يتم كتابة تكوينات Moonshot (Kimi K2) و Kimi Coding تلقائيًا. المزيد من التفاصيل: Moonshot AI (Kimi + Kimi Coding).

يعمل مع نقاط نهاية متوافقة مع OpenAI ومتوافقة مع Anthropic.يدعم الإعداد الأولي التفاعلي نفس خيارات تخزين مفاتيح واجهة برمجة التطبيقات مثل تدفقات مفاتيح مزودي واجهة برمجة التطبيقات الأخرى:

  • الصق مفتاح واجهة برمجة التطبيقات الآن (نص عادي)
  • استخدام مرجع سري (مرجع متغير بيئة أو مرجع مزود مضبوط، مع التحقق المسبق)

الأعلام غير التفاعلية:

  • --auth-choice custom-api-key
  • --custom-base-url
  • --custom-model-id
  • --custom-api-key (اختياري؛ يتراجع إلى CUSTOM_API_KEY)
  • --custom-provider-id (اختياري)
  • --custom-compatibility <openai|anthropic> (اختياري؛ الافتراضي openai)

يترك المصادقة غير مضبوطة.

سلوك النموذج:

  • اختر النموذج الافتراضي من الخيارات المكتشفة، أو أدخل المزود والنموذج يدويًا.
  • يقوم الساحر بفحص النموذج وينذر إذا كان النموذج المضبوط غير معروف أو تفتقر مصادقته.

مسارات بيانات الاعتماد وملفات التعريف:

  • بيانات اعتماد OAuth: ~/.openclaw/credentials/oauth.json
  • ملفات تعريف المصادقة (مفاتيح واجهة برمجة التطبيقات + OAuth): ~/.openclaw/agents//agent/auth-profiles.json

وضع تخزين بيانات الاعتماد:

  • السلوك الافتراضي للإعداد الأولي يحفظ مفاتيح واجهة برمجة التطبيقات كقيم نصية عادية في ملفات تعريف المصادقة.
  • --secret-input-mode ref يمكّن وضع المرجع بدلاً من تخزين المفتاح النصي العادي. في الإعداد الأولي التفاعلي، يمكنك اختيار أي من:
    • مرجع متغير بيئة (على سبيل المثال keyRef: { source: "env", provider: "default", id: "OPENAI_API_KEY" })
    • مرجع مزود مضبوط (file أو exec) مع اسم مستعار للمزود + معرف
  • يقوم وضع المرجع التفاعلي بتشغيل تحقق مسبق سريع قبل الحفظ.
    • مراجع متغيرات البيئة: يتحقق من اسم المتغير + قيمة غير فارغة في بيئة الإعداد الأولي الحالية.
    • مراجع المزودين: يتحقق من تكوين المزود ويحل المعرف المطلوب.
    • إذا فشل التحقق المسبق، يعرض الإعداد الأولي الخطأ ويسمح لك بإعادة المحاولة.
  • في الوضع غير التفاعلي، يكون --secret-input-mode ref مدعومًا بمتغيرات البيئة فقط.
    • عيّن متغير بيئة المزود في بيئة عملية الإعداد الأولي.
    • تتطلب أعلام المفاتيح المضمنة (على سبيل المثال --openai-api-key) تعيين متغير البيئة هذا؛ وإذا لم يكن، يفشل الإعداد الأولي بسرعة.
    • للمزودين المخصصين، يخزن الوضع غير التفاعلي ref في models.providers..apiKey كـ { source: "env", provider: "default", id: "CUSTOM_API_KEY" }.
    • في حالة المزود المخصص تلك، يتطلب --custom-api-key تعيين CUSTOM_API_KEY؛ وإذا لم يكن، يفشل الإعداد الأولي بسرعة.
  • تدعم بيانات اعتماد مصادقة البوابة خيارات النص العادي و SecretRef في الإعداد الأولي التفاعلي:
    • وضع الرمز المميز: إنشاء/تخزين رمز مميز نصي عادي (الافتراضي) أو استخدام SecretRef.
    • وضع كلمة المرور: نص عادي أو SecretRef.
  • مسار SecretRef للرمز المميز في الوضع غير التفاعلي: --gateway-token-ref-env <ENV_VAR>.
  • تستمر الإعدادات النصية العادية الحالية في العمل دون تغيير.

ℹ️ نصيحة للخوادم والأنظمة بدون واجهة: أكمل OAuth على جهاز به متصفح، ثم انسخ ~/.openclaw/credentials/oauth.json (أو $OPENCLAW_STATE_DIR/credentials/oauth.json) إلى مضيف البوابة.

المخرجات والداخليات​

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

  • agents.defaults.workspace
  • agents.defaults.model / models.providers (إذا تم اختيار Minimax)
  • tools.profile (يضبط الإعداد الأولي المحلي افتراضيًا على "coding" عندما يكون غير مضبوط؛ يتم الاحتفاظ بالقيم الصريحة الحالية)
  • gateway.* (الوضع، الربط، المصادقة، tailscale)
  • session.dmScope (يضبط الإعداد الأولي المحلي هذا افتراضيًا على per-channel-peer عندما يكون غير مضبوط؛ يتم الاحتفاظ بالقيم الصريحة الحالية)
  • channels.telegram.botToken, channels.discord.token, channels.signal.*, channels.imessage.*
  • قوائم السماح للقنوات (Slack، Discord، Matrix، Microsoft Teams) عندما توافق أثناء المطالبات (يتم حل الأسماء إلى معرفات عندما يكون ذلك ممكنًا)
  • skills.install.nodeManager
  • wizard.lastRunAt
  • wizard.lastRunVersion
  • wizard.lastRunCommit
  • wizard.lastRunCommand
  • wizard.lastRunMode

يكتب openclaw agents add في agents.list[] و bindings الاختيارية. تذهب بيانات اعتماد WhatsApp تحت ~/.openclaw/credentials/whatsapp//. يتم تخزين الجلسات تحت ~/.openclaw/agents//sessions/.

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

RPC ساحر البوابة:

  • wizard.start
  • wizard.next
  • wizard.cancel
  • wizard.status

يمكن للعملاء (تطبيق macOS وواجهة التحكم) عرض الخطوات دون إعادة تنفيذ منطق الإعداد الأولي. سلوك إعداد Signal:

  • يقوم بتنزيل أصول الإصدار المناسبة
  • يخزنها تحت ~/.openclaw/tools/signal-cli//
  • يكتب channels.signal.cliPath في التكوين
  • تتطلب بناءات JVM Java 21
  • يتم استخدام البناءات الأصلية عند توفرها
  • يستخدم Windows WSL2 ويتبع تدفق signal-cli الخاص بـ Linux داخل WSL

وثائق ذات صلة​

إعداد المساعد الشخصيأتمتة سطر الأوامر