الإعداد

الخلاصة

اختر سير عمل الإعداد بناءً على عدد المرات التي تريد فيها التحديثات وما إذا كنت تريد تشغيل Gateway بنفسك:

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

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

• يوصى بـ Node 24 (لا يزال Node 22 LTS، حاليًا 22.19+، مدعومًا)
• pnpm مطلوب لنسخ المصدر. يحمّل OpenClaw Plugins المضمّنة من حزم مساحة عمل 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 في الوضع محلي ويعمل (يديره التطبيق).
4. اربط الأسطح (مثال: WhatsApp):

openclaw channels login

5. تحقق سريعًا:

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 setuppnpm 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 لوضع المراقبة في الواجهة. يعيد المراقب التحميل عند تغييرات المصدر والإعدادات وبيانات تعريف Plugins المضمّنة ذات الصلة. إذا خرج 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:

• وضع الاتصال: محلي سيتصل التطبيق بالبوابة العاملة على المنفذ المُعدّ.

3) تحقق

• يجب أن تعرض حالة Gateway داخل التطبيق "استخدام 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.

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

• دليل تشغيل Gateway (الأعلام، الإشراف، المنافذ)
• إعدادات Gateway (مخطط الإعدادات + أمثلة)
• Discord وTelegram (وسوم الرد + إعدادات replyToMode)
• إعداد مساعد OpenClaw
• تطبيق macOS (دورة حياة Gateway)