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

Documentation Index

Fetch the complete documentation index at: https://docs.openclaw.ai/llms.txt

Use this file to discover all available pages before exploring further.

إذا كنت تُعدّه للمرة الأولى، فابدأ بـ بدء الاستخدام. لتفاصيل الإعداد الأولي، راجع الإعداد الأولي (CLI).

​
الخلاصة

اختر مسار إعداد بناءً على مدى رغبتك في تلقي التحديثات، وما إذا كنت تريد تشغيل Gateway بنفسك:
  • التخصيص يبقى خارج المستودع: أبقِ إعداداتك ومساحة عملك في ~/.openclaw/openclaw.json و~/.openclaw/workspace/ حتى لا تمسّها تحديثات المستودع.
  • مسار مستقر (موصى به لمعظم المستخدمين): ثبّت تطبيق macOS واتركه يشغّل Gateway المضمّن.
  • مسار الإصدارات الأحدث (للتطوير): شغّل Gateway بنفسك عبر pnpm gateway:watch، ثم دع تطبيق macOS يتصل في وضع Local.

​
المتطلبات المسبقة (من المصدر)

  • يوصى باستخدام Node 24 (ما زال Node 22 LTS، حاليًا 22.16+، مدعومًا)
  • pnpm مطلوب لنسخ المصدر. يحمّل OpenClaw المكوّنات الإضافية المضمّنة من حزم مساحة عمل pnpm extensions/* في وضع التطوير، لذلك لا يجهّز npm install في الجذر شجرة المصدر الكاملة.
  • Docker (اختياري؛ فقط للإعداد/اختبارات e2e داخل حاويات - راجع Docker)

​
استراتيجية التخصيص (حتى لا تضرّك التحديثات)

إذا أردت “تخصيصًا بنسبة 100% يناسبني” مع تحديثات سهلة، فأبقِ تخصيصك في:
  • الإعدادات: ~/.openclaw/openclaw.json (على نمط JSON/JSON5)
  • مساحة العمل: ~/.openclaw/workspace (Skills، مطالبات، ذاكرات؛ اجعلها مستودع git خاصًا)
مهّد مرة واحدة: 
openclaw setup
من داخل هذا المستودع، استخدم مدخل CLI المحلي: 
openclaw setup
إذا لم يكن لديك تثبيت عام بعد، فشغّله عبر pnpm openclaw setup.

​
تشغيل Gateway من هذا المستودع

بعد pnpm build، يمكنك تشغيل CLI المحزّم مباشرة: 
node openclaw.mjs gateway --port 18789 --verbose

​
المسار المستقر (تطبيق macOS أولًا)

  1. ثبّت وشغّل OpenClaw.app (شريط القوائم).
  2. أكمل قائمة التحقق الخاصة بالإعداد الأولي/الأذونات (مطالبات TCC).
  3. تأكد أن Gateway في وضع Local وقيد التشغيل (يديره التطبيق).
  4. اربط الواجهات (مثال: WhatsApp):
openclaw channels login
  1. تحقق من السلامة:
openclaw health
إذا لم يكن الإعداد الأولي متاحًا في البنية لديك:
  • شغّل openclaw setup، ثم openclaw channels login، ثم ابدأ Gateway يدويًا (openclaw gateway).

​
مسار الإصدارات الأحدث (Gateway في طرفية)

الهدف: العمل على Gateway المكتوب بـ TypeScript، والحصول على إعادة تحميل ساخنة، وإبقاء واجهة تطبيق macOS متصلة.

​
0) (اختياري) شغّل تطبيق macOS من المصدر أيضًا

إذا كنت تريد تطبيق macOS على الإصدارات الأحدث أيضًا: 
./scripts/restart-mac.sh

​
1) ابدأ Gateway التطوير

pnpm install
# First run only (or after resetting local OpenClaw config/workspace)
pnpm openclaw setup
pnpm gateway:watch
يبدأ gateway:watch عملية مراقبة Gateway أو يعيد تشغيلها داخل جلسة tmux مسمّاة، ويتصل تلقائيًا من الطرفيات التفاعلية. تبقى الأصداف غير التفاعلية منفصلة وتطبع tmux attach -t openclaw-gateway-watch-main؛ استخدم OPENCLAW_GATEWAY_WATCH_ATTACH=0 pnpm gateway:watch لإبقاء التشغيل التفاعلي منفصلًا، أو pnpm gateway:watch:raw لوضع المراقبة في الواجهة. يعيد المراقب التحميل عند تغييرات المصدر والإعدادات وبيانات وصف المكوّنات الإضافية المضمّنة ذات الصلة. إذا خرج Gateway المراقَب أثناء بدء التشغيل، يشغّل gateway:watch openclaw doctor --fix --non-interactive مرة واحدة ثم يعيد المحاولة؛ عيّن OPENCLAW_GATEWAY_WATCH_AUTO_DOCTOR=0 لتعطيل خطوة الإصلاح الخاصة بالتطوير فقط. pnpm openclaw setup هي خطوة تهيئة الإعدادات/مساحة العمل المحلية لمرة واحدة لنسخة مصدر جديدة. لا يعيد pnpm gateway:watch بناء dist/control-ui، لذلك أعد تشغيل pnpm ui:build بعد تغييرات ui/ أو استخدم pnpm ui:dev أثناء تطوير Control UI.

​
2) وجّه تطبيق macOS إلى Gateway العامل لديك

في OpenClaw.app:
  • وضع الاتصال: Local سيتصل التطبيق بـ Gateway العامل على المنفذ المضبوط.

​
3) تحقق

  • يجب أن تعرض حالة Gateway داخل التطبيق “Using existing gateway …”
  • أو عبر CLI:
openclaw health

​
مشكلات شائعة

  • منفذ خاطئ: الإعداد الافتراضي لـ Gateway WS هو ws://127.0.0.1:18789؛ أبقِ التطبيق وCLI على المنفذ نفسه.
  • مكان وجود الحالة:
    • حالة القناة/المزوّد: ~/.openclaw/credentials/
    • ملفات تعريف مصادقة النموذج: ~/.openclaw/agents/<agentId>/agent/auth-profiles.json
    • الجلسات: ~/.openclaw/agents/<agentId>/sessions/
    • السجلات: /tmp/openclaw/

​
خريطة تخزين بيانات الاعتماد

استخدم هذا عند تصحيح المصادقة أو تحديد ما يجب نسخه احتياطيًا:
  • WhatsApp: ~/.openclaw/credentials/whatsapp/<accountId>/creds.json
  • رمز Telegram للبوت: الإعدادات/env أو channels.telegram.tokenFile (ملف عادي فقط؛ تُرفض الروابط الرمزية)
  • رمز Discord للبوت: الإعدادات/env أو SecretRef (مزوّدو env/file/exec)
  • رموز Slack: الإعدادات/env (channels.slack.*)
  • قوائم السماح للاقتران:
    • ~/.openclaw/credentials/<channel>-allowFrom.json (الحساب الافتراضي)
    • ~/.openclaw/credentials/<channel>-<accountId>-allowFrom.json (الحسابات غير الافتراضية)
  • ملفات تعريف مصادقة النموذج: ~/.openclaw/agents/<agentId>/agent/auth-profiles.json
  • حمولة الأسرار المدعومة بملف (اختياري): ~/.openclaw/secrets.json
  • استيراد OAuth القديم: ~/.openclaw/credentials/oauth.json تفاصيل أكثر: الأمان.

​
التحديث (من دون إتلاف إعدادك)

  • أبقِ ~/.openclaw/workspace و~/.openclaw/ باعتبارهما “أشياءك الخاصة”؛ لا تضع المطالبات/الإعدادات الشخصية داخل مستودع openclaw.
  • تحديث المصدر: git pull + pnpm install + الاستمرار في استخدام pnpm gateway:watch.

​
Linux (خدمة systemd للمستخدم)

تستخدم تثبيتات Linux خدمة systemd للمستخدم. افتراضيًا، يوقف systemd خدمات المستخدم عند تسجيل الخروج/الخمول، ما يقتل Gateway. يحاول الإعداد الأولي تفعيل الاستبقاء نيابةً عنك (قد يطلب sudo). إذا بقي متوقفًا، فشغّل: 
sudo loginctl enable-linger $USER
للخوادم التي تعمل دائمًا أو متعددة المستخدمين، فكّر في خدمة نظام بدلًا من خدمة مستخدم (لا حاجة للاستبقاء). راجع دليل تشغيل Gateway لملاحظات systemd.

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