مرجع معالج التهيئة الأولية¶

هذا هو المرجع الكامل لمعالج CLI ‏openclaw onboard. للحصول على نظرة عامة عالية المستوى، راجع Onboarding Wizard.

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

- إذا كان ~/.openclaw/openclaw.json موجودًا، فاختر الاحتفاظ / التعديل / إعادة الضبط. - إعادة تشغيل المعالج لا تمسح أي شيء ما لم تختر إعادة الضبط صراحةً (أو تمرّر --reset). - إذا كانت التهيئة غير صالحة أو تحتوي على مفاتيح قديمة، يتوقف المعالج ويطلب منك تشغيل openclaw doctor قبل المتابعة. - تستخدم إعادة الضبط trash (ولا تستخدم أبدًا rm) وتعرض نطاقات: - التهيئة فقط - التهيئة + بيانات الاعتماد + الجلسات - إعادة ضبط كاملة (تزيل أيضًا مساحة العمل)
- مفتاح Anthropic API (موصى به): يستخدم ANTHROPIC_API_KEY إن وُجد أو يطلب مفتاحًا، ثم يحفظه لاستخدامه من قِبل الـ daemon. - Anthropic OAuth (Claude Code CLI): على macOS يتحقق المعالج من عنصر Keychain «Claude Code-credentials» (اختر «Always Allow» كي لا تمنع عمليات بدء launchd)؛ على Linux/Windows يعيد استخدام ~/.claude/.credentials.json إن وُجد. - رمز Anthropic (لصق setup-token): شغّل claude setup-token على أي جهاز، ثم الصق الرمز (يمكنك تسميته؛ الفراغ = الافتراضي). - اشتراك OpenAI Code (Codex) (Codex CLI): إذا كان ~/.codex/auth.json موجودًا، يمكن للمعالج إعادة استخدامه. - اشتراك OpenAI Code (Codex) (OAuth): تدفّق عبر المتصفح؛ الصق code#state. - يعيّن agents.defaults.model إلى openai-codex/gpt-5.2 عندما يكون النموذج غير معيّن أو openai/*. - مفتاح OpenAI API: يستخدم OPENAI_API_KEY إن وُجد أو يطلب مفتاحًا، ثم يحفظه في ~/.openclaw/.env ليتمكّن launchd من قراءته. - مفتاح xAI (Grok) API: يطلب XAI_API_KEY ويُهيّئ xAI كموفّر نماذج. - OpenCode Zen (وكيل متعدد النماذج): يطلب OPENCODE_API_KEY (أو OPENCODE_ZEN_API_KEY، احصل عليه من https://opencode.ai/auth). - مفتاح API: يخزّن المفتاح لك. - Vercel AI Gateway (وكيل متعدد النماذج): يطلب AI_GATEWAY_API_KEY. - مزيد من التفاصيل: Vercel AI Gateway - Cloudflare AI Gateway: يطلب معرّف الحساب، ومعرّف Gateway، وCLOUDFLARE_AI_GATEWAY_API_KEY. - مزيد من التفاصيل: Cloudflare AI Gateway - MiniMax M2.1: تُكتب التهيئة تلقائيًا. - مزيد من التفاصيل: MiniMax - Synthetic (متوافق مع Anthropic): يطلب SYNTHETIC_API_KEY. - مزيد من التفاصيل: Synthetic - Moonshot (Kimi K2): تُكتب التهيئة تلقائيًا. - Kimi Coding: تُكتب التهيئة تلقائيًا. - مزيد من التفاصيل: Moonshot AI (Kimi + Kimi Coding) - تخطي: لا تتم تهيئة المصادقة بعد. - اختر نموذجًا افتراضيًا من الخيارات المكتشفة (أو أدخل الموفّر/النموذج يدويًا). - يُجري المعالج فحصًا للنموذج ويُحذّر إذا كان النموذج المُهيّأ غير معروف أو تنقصه المصادقة. - تعيش بيانات اعتماد OAuth في ~/.openclaw/credentials/oauth.json؛ وتعيش ملفات تعريف المصادقة في ~/.openclaw/agents/<agentId>/agent/auth-profiles.json (مفاتيح API + OAuth). - مزيد من التفاصيل: /concepts/oauth
نصيحة للرؤوس/الخوادم: أكمل OAuth على جهاز يحتوي على متصفح، ثم انسخ ~/.openclaw/credentials/oauth.json (أو $OPENCLAW_STATE_DIR/credentials/oauth.json) إلى مضيف Gateway. - الافتراضي ~/.openclaw/workspace (قابل للتهيئة). - يزرع ملفات مساحة العمل اللازمة لطقس تمهيد الوكيل. - مخطط مساحة العمل الكامل + دليل النسخ الاحتياطي: Agent workspace
- المنفذ، والربط، ووضع المصادقة، والتعرّض عبر Tailscale. - توصية المصادقة: الإبقاء على Token حتى مع loopback كي تضطر عملاء WS المحليين إلى المصادقة. - عطّل المصادقة فقط إذا كنت تثق تمامًا بكل عملية محلية. - الربط غير loopback يتطلب المصادقة أيضًا. - WhatsApp: تسجيل دخول QR اختياري. - Telegram: رمز البوت. - Discord: رمز البوت. - Google Chat: JSON لحساب الخدمة + جمهور webhook. - Mattermost (ملحق): رمز البوت + عنوان URL الأساسي. - Signal: تثبيت signal-cli اختياري + تهيئة الحساب. - BlueBubbles: موصى به لـ iMessage؛ عنوان خادم + كلمة مرور + webhook. - iMessage: مسار CLI قديم imsg + وصول إلى قاعدة البيانات. - أمان الرسائل الخاصة (DM): الافتراضي هو الإقران. ترسل أول رسالة خاصة رمزًا؛ وافق عبر openclaw pairing approve <channel><code> أو استخدم قوائم السماح. أو استخدم قوائم السماح. </Step> <Step title="تثبيت الـ daemon"> - macOS: وكيل التشغيل - يتطلب جلسة مستخدم مسجّل الدخول؛ وللبيئات عديمة الواجهة، استخدم LaunchDaemon مخصصًا (غير مُضمّن). - Linux (وWindows عبر WSL2): وحدة systemd للمستخدم - يحاول المعالج تمكين الاستمرار عبرloginctl enable-linger ليظل Gateway يعمل بعد تسجيل الخروج. - قد يطلب sudo (يكتب/var/lib/systemd/linger)؛ يحاول بدون sudo أولًا. - **اختيار وقت التشغيل:** Node (موصى به؛ مطلوب لـ WhatsApp/Telegram). Bun **غير موصى به**. </Step> <Step title="فحص الصحة"> - يبدأ Gateway (إن لزم) ويشغّلopenclaw health. - نصيحة: يضيفopenclaw status --deep` مجسّات صحة Gateway إلى مخرجات الحالة (يتطلب Gateway قابلًا للوصول). - يقرأ Skills المتاحة ويتحقق من المتطلبات. - يتيح لك اختيار مدير عُقد: npm / pnpm (bun غير موصى به). - يثبّت تبعيات اختيارية (بعضها يستخدم Homebrew على macOS). - ملخص + الخطوات التالية، بما في ذلك تطبيقات iOS/Android/macOS لميزات إضافية.

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

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

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

--json لا يعني الوضع غير التفاعلي. استخدم --non-interactive (و--workspace) للسكربتات.

bash openclaw onboard --non-interactive \ --mode local \ --auth-choice gemini-api-key \ --gemini-api-key "$GEMINI_API_KEY" \ --gateway-port 18789 \ --gateway-bind loopback bash openclaw onboard --non-interactive \ --mode local \ --auth-choice zai-api-key \ --zai-api-key "$ZAI_API_KEY" \ --gateway-port 18789 \ --gateway-bind loopback bash openclaw onboard --non-interactive \ --mode local \ --auth-choice ai-gateway-api-key \ --ai-gateway-api-key "$AI_GATEWAY_API_KEY" \ --gateway-port 18789 \ --gateway-bind loopback bash openclaw onboard --non-interactive \ --mode local \ --auth-choice cloudflare-ai-gateway-api-key \ --cloudflare-ai-gateway-account-id "your-account-id" \ --cloudflare-ai-gateway-gateway-id "your-gateway-id" \ --cloudflare-ai-gateway-api-key "$CLOUDFLARE_AI_GATEWAY_API_KEY" \ --gateway-port 18789 \ --gateway-bind loopback bash openclaw onboard --non-interactive \ --mode local \ --auth-choice moonshot-api-key \ --moonshot-api-key "$MOONSHOT_API_KEY" \ --gateway-port 18789 \ --gateway-bind loopback bash openclaw onboard --non-interactive \ --mode local \ --auth-choice synthetic-api-key \ --synthetic-api-key "$SYNTHETIC_API_KEY" \ --gateway-port 18789 \ --gateway-bind loopback bash openclaw onboard --non-interactive \ --mode local \ --auth-choice opencode-zen \ --opencode-zen-api-key "$OPENCODE_API_KEY" \ --gateway-port 18789 \ --gateway-bind loopback

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

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

RPC لمعالج Gateway¶

يعرِض Gateway تدفّق المعالج عبر RPC (wizard.start، wizard.next، wizard.cancel، wizard.status). يمكن للعملاء (تطبيق macOS، واجهة التحكم) عرض الخطوات دون إعادة تنفيذ منطق التهيئة الأولية.

إعداد 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)
• gateway.* (الوضع، الربط، المصادقة، Tailscale)
• 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/<accountId>/. تُخزَّن الجلسات تحت ~/.openclaw/agents/<agentId>/sessions/.

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

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

• نظرة عامة على المعالج: Onboarding Wizard
• تهيئة تطبيق macOS: Onboarding
• مرجع التهيئة: Gateway configuration
• الموفّرون: WhatsApp، Telegram، Discord، Google Chat، Signal، BlueBubbles (iMessage)، iMessage (قديم)
• Skills: Skills، Skills config