> ## Documentation Index
> Fetch the complete documentation index at: https://docs2.openclaw.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# الإعداد

<Note>
  إذا كنت تُعدّ OpenClaw لأول مرة، فابدأ بـ [بدء الاستخدام](/ar/start/getting-started).
  لتفاصيل الإعداد الأولي، راجع [الإعداد الأولي (CLI)](/ar/start/wizard).
</Note>

## الخلاصة

اختر سير عمل الإعداد بناءً على عدد المرات التي تريد فيها التحديثات وما إذا كنت تريد تشغيل 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](/ar/install/docker))

## استراتيجية التخصيص (حتى لا تؤذيك التحديثات)

إذا كنت تريد "مخصصًا لي 100%" *مع* تحديثات سهلة، فاحتفظ بتخصيصك في:

* **الإعدادات:** `~/.openclaw/openclaw.json` (بصيغة تشبه JSON/JSON5)
* **مساحة العمل:** `~/.openclaw/workspace` (Skills، مطالبات، ذاكرات؛ اجعلها مستودع git خاصًا)

ابدأ التهيئة مرة واحدة:

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
openclaw setup
```

من داخل هذا المستودع، استخدم مدخل CLI المحلي:

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
openclaw setup
```

إذا لم يكن لديك تثبيت عام بعد، فشغّله عبر `pnpm openclaw setup`.

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

بعد `pnpm build`، يمكنك تشغيل CLI المجمّع مباشرةً:

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
node openclaw.mjs gateway --port 18789 --verbose
```

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

1. ثبّت وشغّل **OpenClaw\.app** (شريط القوائم).
2. أكمل قائمة تحقق الإعداد الأولي/الأذونات (مطالبات TCC).
3. تأكد أن Gateway في الوضع **محلي** ويعمل (يديره التطبيق).
4. اربط الأسطح (مثال: WhatsApp):

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
openclaw channels login
```

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

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
openclaw health
```

إذا لم يكن الإعداد الأولي متاحًا في إصدارك:

* شغّل `openclaw setup`، ثم `openclaw channels login`، ثم ابدأ Gateway يدويًا (`openclaw gateway`).

## سير عمل أحدث التغييرات (Gateway في طرفية)

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

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

إذا كنت تريد تطبيق macOS على أحدث التغييرات أيضًا:

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
./scripts/restart-mac.sh
```

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

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
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` لوضع المراقبة في الواجهة. يعيد المراقب
التحميل عند تغييرات المصدر والإعدادات وبيانات تعريف 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:

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
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`
  مزيد من التفاصيل: [الأمان](/ar/gateway/security#credential-storage-map).

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

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

## Linux (خدمة مستخدم systemd)

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

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
sudo loginctl enable-linger $USER
```

للخوادم الدائمة التشغيل أو متعددة المستخدمين، فكّر في خدمة **نظام** بدلًا من
خدمة مستخدم (لا حاجة إلى الإبقاء). راجع [دليل تشغيل Gateway](/ar/gateway) لملاحظات systemd.

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

* [دليل تشغيل Gateway](/ar/gateway) (الأعلام، الإشراف، المنافذ)
* [إعدادات Gateway](/ar/gateway/configuration) (مخطط الإعدادات + أمثلة)
* [Discord](/ar/channels/discord) و[Telegram](/ar/channels/telegram) (وسوم الرد + إعدادات replyToMode)
* [إعداد مساعد OpenClaw](/ar/start/openclaw)
* [تطبيق macOS](/ar/platforms/macos) (دورة حياة Gateway)