الإعداد
يقرأ OpenClaw إعدادًا اختياريًا بصيغة من~/.openclaw/openclaw.json.
إذا كان الملف مفقودًا، يستخدم OpenClaw إعدادات افتراضية آمنة. من الأسباب الشائعة لإضافة إعداد:
- توصيل القنوات والتحكم في من يمكنه مراسلة البوت
- ضبط النماذج والأدوات والعزل أو الأتمتة (cron، وhooks)
- ضبط الجلسات والوسائط والشبكات أو واجهة المستخدم
الحد الأدنى من الإعداد
تعديل الإعداد
- المعالج التفاعلي
- CLI (أوامر مختصرة)
- واجهة التحكم
- تعديل مباشر
التحقق الصارم
ملاحظات أدوات المخطط:- يطبع
openclaw config schemaنفس عائلة JSON Schema المستخدمة في واجهة التحكم والتحقق من الإعداد. - اعتبر خرج هذا المخطط العقد المقروء آليًا الرسمي لملف
openclaw.json؛ فهذه النظرة العامة ومرجع الإعداد يوجزان محتواه. - تُنقل قيم الحقلين
titleوdescriptionإلى خرج المخطط من أجل المحررات وأدوات النماذج. - ترث إدخالات الكائنات المتداخلة، وأحرف البدل (
*)، وعناصر المصفوفات ([]) نفس بيانات التوثيق الوصفية حيثما وُجد توثيق للحقل المطابق. - ترث فروع التركيب
anyOf/oneOf/allOfنفس بيانات التوثيق الوصفية أيضًا، بحيث تحتفظ متغيرات union/intersection بنفس مساعدة الحقول. - يعيد
config.schema.lookupمسار إعداد واحدًا مُطبّعًا مع عقدة مخطط سطحية (titleوdescriptionوtypeوenumوconstوالحدود الشائعة وحقول تحقق مشابهة)، وبيانات تلميحات واجهة المستخدم المطابقة، وملخصات العناصر الفرعية المباشرة لأدوات التعمق في التفاصيل. - تُدمج مخططات plugin/channel وقت التشغيل عندما تتمكن البوابة من تحميل سجل manifest الحالي.
- يكتشف
pnpm config:docs:checkالانحراف بين عناصر baseline الخاصة بالإعداد الموجّهة للتوثيق وسطح المخطط الحالي.
- لا تقلع البوابة
- تعمل فقط أوامر التشخيص (
openclaw doctorوopenclaw logsوopenclaw healthوopenclaw status) - شغّل
openclaw doctorلرؤية المشكلات الدقيقة - شغّل
openclaw doctor --fix(أو--yes) لتطبيق الإصلاحات
المهام الشائعة
إعداد قناة (WhatsApp أو Telegram أو Discord وما إلى ذلك)
إعداد قناة (WhatsApp أو Telegram أو Discord وما إلى ذلك)
لكل قناة قسم إعداد خاص بها تحت
channels.<provider>. راجع صفحة القناة المخصصة لخطوات الإعداد:- WhatsApp —
channels.whatsapp - Telegram —
channels.telegram - Discord —
channels.discord - Feishu —
channels.feishu - Google Chat —
channels.googlechat - Microsoft Teams —
channels.msteams - Slack —
channels.slack - Signal —
channels.signal - iMessage —
channels.imessage - Mattermost —
channels.mattermost
اختيار النماذج وضبطها
اختيار النماذج وضبطها
اضبط النموذج الأساسي وبدائل اختيارية:
- يعرّف
agents.defaults.modelsفهرس النماذج ويعمل كقائمة سماح لأمر/model. - تستخدم مراجع النماذج تنسيق
provider/model(مثلanthropic/claude-opus-4-6). - يتحكم
agents.defaults.imageMaxDimensionPxفي تصغير صور السجل/الأداة (القيمة الافتراضية1200)؛ وعادةً ما تقلل القيم الأقل من استخدام رموز الرؤية في التشغيلات التي تكثر فيها لقطات الشاشة. - راجع Models CLI لتبديل النماذج في الدردشة وModel Failover لمعرفة سلوك تدوير المصادقة والبدائل.
- بالنسبة إلى المزوّدين المخصصين/المستضافين ذاتيًا، راجع المزوّدون المخصصون في المرجع.
التحكم في من يمكنه مراسلة البوت
التحكم في من يمكنه مراسلة البوت
يُتحكم في الوصول عبر الرسائل الخاصة لكل قناة من خلال
dmPolicy:"pairing"(الافتراضي): يحصل المرسلون غير المعروفين على رمز اقتران لمرة واحدة للموافقة"allowlist": فقط المرسلون الموجودون فيallowFrom(أو مخزن السماح المقترن)"open": السماح بكل الرسائل الخاصة الواردة (يتطلبallowFrom: ["*"])"disabled": تجاهل كل الرسائل الخاصة
groupPolicy مع groupAllowFrom أو قوائم السماح الخاصة بالقناة.راجع المرجع الكامل للتفاصيل الخاصة بكل قناة.إعداد تقييد الإشارات في الدردشة الجماعية
إعداد تقييد الإشارات في الدردشة الجماعية
تستخدم رسائل المجموعات افتراضيًا اشتراط الإشارة. اضبط الأنماط لكل وكيل:
- إشارات البيانات الوصفية: إشارات @ الأصلية (@-mentions) (الإشارة بالنقر في WhatsApp، وTelegram @bot، وما إلى ذلك)
- أنماط النص: أنماط regex آمنة في
mentionPatterns - راجع المرجع الكامل للتجاوزات الخاصة بكل قناة ووضع الدردشة الذاتية.
تقييد Skills لكل وكيل
تقييد Skills لكل وكيل
استخدم
agents.defaults.skills كخط أساس مشترك، ثم تجاوز إعدادات
وكلاء محددين باستخدام agents.list[].skills:- احذف
agents.defaults.skillsللحصول على Skills غير مقيّدة افتراضيًا. - احذف
agents.list[].skillsلوراثة الإعدادات الافتراضية. - اضبط
agents.list[].skills: []لعدم استخدام أي Skills. - راجع Skills وإعداد Skills و مرجع الإعداد.
ضبط مراقبة سلامة قنوات البوابة
ضبط مراقبة سلامة قنوات البوابة
تحكّم في مدى شدة إعادة تشغيل البوابة للقنوات التي تبدو متوقفة:
- اضبط
gateway.channelHealthCheckMinutes: 0لتعطيل عمليات إعادة التشغيل الخاصة بمراقبة السلامة عالميًا. - يجب أن تكون قيمة
channelStaleEventThresholdMinutesأكبر من أو تساوي فترة التحقق. - استخدم
channels.<provider>.healthMonitor.enabledأوchannels.<provider>.accounts.<id>.healthMonitor.enabledلتعطيل إعادة التشغيل التلقائية لقناة أو حساب واحد دون تعطيل المراقبة العامة. - راجع فحوصات السلامة لتصحيح الأخطاء التشغيلية والمرجع الكامل لجميع الحقول.
ضبط الجلسات وإعادة التعيين
ضبط الجلسات وإعادة التعيين
تتحكم الجلسات في استمرارية المحادثة وعزلها:
dmScope: main(مشترك) |per-peer|per-channel-peer|per-account-channel-peerthreadBindings: الإعدادات الافتراضية العامة لتوجيه الجلسات المرتبط بالخيوط (يدعم Discord الأوامر/focusو/unfocusو/agentsو/session idleو/session max-age).- راجع إدارة الجلسات لمعرفة النطاق وروابط الهوية وسياسة الإرسال.
- راجع المرجع الكامل لجميع الحقول.
تمكين العزل
تمكين العزل
شغّل جلسات الوكلاء داخل حاويات Docker معزولة:أنشئ الصورة أولًا:
scripts/sandbox-setup.shراجع العزل للدليل الكامل والمرجع الكامل لكل الخيارات.تمكين الإشعارات الفورية المعتمدة على relay لإصدارات iOS الرسمية
تمكين الإشعارات الفورية المعتمدة على relay لإصدارات iOS الرسمية
تُضبط الإشعارات الفورية المعتمدة على relay في المكافئ في CLI:ما الذي يفعله هذا:
openclaw.json.اضبط ما يلي في إعداد البوابة:- يتيح للبوابة إرسال
push.testوتنبيهات التنبيه والاستيقاظات الخاصة بإعادة الاتصال عبر relay خارجي. - يستخدم تصريح إرسال مرتبطًا بالتسجيل ويمرره تطبيق iOS المقترن. لا تحتاج البوابة إلى رمز relay مخصص على مستوى النشر بالكامل.
- يربط كل تسجيل مدعوم بـ relay بهوية البوابة التي اقترن بها تطبيق iOS، بحيث لا يمكن لبوابة أخرى إعادة استخدام التسجيل المخزن.
- يُبقي إصدارات iOS المحلية/اليدوية على APNs المباشر. تنطبق الإرسالات المعتمدة على relay فقط على الإصدارات الرسمية الموزعة التي سُجلت عبر relay.
- يجب أن يتطابق مع عنوان URL الأساسي لـ relay المضمّن في إصدار iOS الرسمي/TestFlight، حتى تصل حركة التسجيل والإرسال إلى نفس نشر relay.
- ثبّت إصدار iOS رسميًا/TestFlight تم تجميعه باستخدام نفس عنوان URL الأساسي لـ relay.
- اضبط
gateway.push.apns.relay.baseUrlعلى البوابة. - اقترن تطبيق iOS بالبوابة ودع كلًا من جلسات العقدة والمشغّل تتصل.
- يجلب تطبيق iOS هوية البوابة، ويسجل لدى relay باستخدام App Attest مع إيصال التطبيق، ثم ينشر حمولة
push.apns.registerالمعتمدة على relay إلى البوابة المقترنة. - تخزن البوابة مقبض relay وتصريح الإرسال، ثم تستخدمهما في
push.testوتنبيهات التنبيه واستيقاظات إعادة الاتصال.
- إذا بدّلت تطبيق iOS إلى بوابة مختلفة، فأعد توصيل التطبيق حتى يتمكن من نشر تسجيل relay جديد مرتبط بتلك البوابة.
- إذا أصدرت إصدار iOS جديدًا يشير إلى نشر relay مختلف، فسيقوم التطبيق بتحديث تسجيل relay المخزن مؤقتًا بدلًا من إعادة استخدام مصدر relay القديم.
- ما زال
OPENCLAW_APNS_RELAY_BASE_URLوOPENCLAW_APNS_RELAY_TIMEOUT_MSيعملان كتجاوزات مؤقتة عبر env. - يظل
OPENCLAW_APNS_RELAY_ALLOW_HTTP=trueمنفذ هروب للتطوير مخصصًا لـ loopback فقط؛ لا تحفظ عناوين URL الخاصة بـ HTTP relay في الإعداد.
إعداد heartbeat (عمليات تحقق دورية)
إعداد heartbeat (عمليات تحقق دورية)
every: سلسلة مدة (30m،2h). اضبط0mللتعطيل.target: last|none|<channel-id>(على سبيل المثالdiscordأوmatrixأوtelegramأوwhatsapp)directPolicy: allow(الافتراضي) أوblockلأهداف heartbeat ذات نمط الرسائل الخاصة- راجع Heartbeat للدليل الكامل.
ضبط مهام cron
ضبط مهام cron
sessionRetention: إزالة جلسات التشغيل المعزولة المكتملة منsessions.json(الافتراضي24h؛ اضبطfalseللتعطيل).runLog: تقليمcron/runs/<jobId>.jsonlحسب الحجم وعدد الأسطر المحتفظ بها.- راجع مهام Cron لنظرة عامة على الميزة وأمثلة CLI.
إعداد webhooks (hooks)
إعداد webhooks (hooks)
فعّل نقاط نهاية HTTP webhook على البوابة:ملاحظة أمنية:
- تعامل مع كل محتوى حمولة hook/webhook على أنه إدخال غير موثوق.
- استخدم
hooks.tokenمخصصًا؛ ولا تعِد استخدام رمز Gateway المشترك. - مصادقة Hook تعتمد على الترويسة فقط (
Authorization: Bearer ...أوx-openclaw-token)؛ ورموز سلسلة الاستعلام مرفوضة. - لا يمكن أن يكون
hooks.pathهو/؛ أبقِ إدخال webhook على مسار فرعي مخصص مثل/hooks. - أبقِ علامات تجاوز المحتوى غير الآمن معطّلة (
hooks.gmail.allowUnsafeExternalContentوhooks.mappings[].allowUnsafeExternalContent) ما لم تكن تجري تصحيح أخطاء محدود النطاق بإحكام. - إذا فعّلت
hooks.allowRequestSessionKey، فاضبط أيضًاhooks.allowedSessionKeyPrefixesلتقييد مفاتيح الجلسات التي يحددها المستدعي. - بالنسبة إلى الوكلاء المعتمدين على hook، ففضّل طبقات النماذج الحديثة والقوية وسياسة أدوات صارمة (على سبيل المثال، المراسلة فقط مع العزل حيثما أمكن).
ضبط التوجيه متعدد الوكلاء
ضبط التوجيه متعدد الوكلاء
شغّل عدة وكلاء معزولين بمساحات عمل وجلسات منفصلة:راجع Multi-Agent والمرجع الكامل لقواعد الربط وملفات تعريف الوصول الخاصة بكل وكيل.
تقسيم الإعداد إلى ملفات متعددة ($include)
تقسيم الإعداد إلى ملفات متعددة ($include)
استخدم
$include لتنظيم الإعدادات الكبيرة:- ملف واحد: يستبدل الكائن الحاوي
- مصفوفة من الملفات: دمج عميق بالترتيب (اللاحق يفوز)
- المفاتيح المجاورة: تُدمج بعد التضمينات (وتتجاوز القيم المضمّنة)
- التضمينات المتداخلة: مدعومة حتى عمق 10 مستويات
- المسارات النسبية: تُحل نسبةً إلى الملف الذي يتضمنها
- معالجة الأخطاء: أخطاء واضحة للملفات المفقودة، وأخطاء التحليل، والتضمينات الدائرية
إعادة التحميل السريع للإعداد
تراقب البوابة~/.openclaw/openclaw.json وتطبّق التغييرات تلقائيًا — ولا حاجة إلى إعادة تشغيل يدوية لمعظم الإعدادات.
أوضاع إعادة التحميل
| الوضع | السلوك |
|---|---|
hybrid (الافتراضي) | يطبّق التغييرات الآمنة فورًا. ويعيد التشغيل تلقائيًا للتغييرات الحرجة. |
hot | يطبّق التغييرات الآمنة فقط. ويسجل تحذيرًا عند الحاجة إلى إعادة تشغيل — وتتولى ذلك أنت. |
restart | يعيد تشغيل البوابة عند أي تغيير في الإعداد، سواء كان آمنًا أم لا. |
off | يعطّل مراقبة الملفات. تصبح التغييرات فعالة عند إعادة التشغيل اليدوية التالية. |
ما الذي يُطبَّق مباشرة وما الذي يحتاج إلى إعادة تشغيل
تُطبَّق معظم الحقول مباشرة دون توقف. وفي وضعhybrid، تُعالَج التغييرات التي تتطلب إعادة تشغيل تلقائيًا.
| الفئة | الحقول | هل يلزم إعادة تشغيل؟ |
|---|---|---|
| القنوات | channels.*، web (WhatsApp) — جميع القنوات المضمنة وقنوات extension | لا |
| الوكيل والنماذج | agent، agents، models، routing | لا |
| الأتمتة | hooks، cron، agent.heartbeat | لا |
| الجلسات والرسائل | session، messages | لا |
| الأدوات والوسائط | tools، browser، skills، audio، talk | لا |
| واجهة المستخدم ومتفرقات | ui، logging، identity، bindings | لا |
| خادم البوابة | gateway.* (المنفذ، الربط، المصادقة، tailscale، TLS، HTTP) | نعم |
| البنية التحتية | discovery، canvasHost، plugins | نعم |
gateway.reload وgateway.remote استثناءان — فتغييرهما لا يؤدي إلى إعادة تشغيل.Config RPC (تحديثات برمجية)
تخضع RPC الخاصة بالكتابة على مستوى control-plane (
config.apply وconfig.patch وupdate.run) لتحديد معدل يبلغ 3 طلبات لكل 60 ثانية لكل deviceId+clientIp. وعند الوصول إلى الحد، تعيد RPC القيمة UNAVAILABLE مع retryAfterMs.config.schema.lookup: فحص شجرة فرعية واحدة من الإعداد محددة بمسار مع عقدة مخطط سطحية، وبيانات تلميحات مطابقة، وملخصات العناصر الفرعية المباشرةconfig.get: جلب اللقطة الحالية + hashconfig.patch: المسار المفضل للتحديث الجزئيconfig.apply: استبدال الإعداد بالكامل فقطupdate.run: تحديث ذاتي صريح + إعادة تشغيل
config.schema.lookup
ثم config.patch.
config.apply (استبدال كامل)
config.apply (استبدال كامل)
يتحقق من الإعداد الكامل ويكتبه ثم يعيد تشغيل البوابة في خطوة واحدة.المعلمات:
raw(string) — حمولة JSON5 للإعداد بالكاملbaseHash(اختياري) — hash الإعداد منconfig.get(مطلوب عندما يكون الإعداد موجودًا)sessionKey(اختياري) — مفتاح جلسة لتنبيه الاستيقاظ بعد إعادة التشغيلnote(اختياري) — ملاحظة لـ restart sentinelrestartDelayMs(اختياري) — التأخير قبل إعادة التشغيل (الافتراضي 2000)
config.patch (تحديث جزئي)
config.patch (تحديث جزئي)
يدمج تحديثًا جزئيًا في الإعداد الحالي (بدلالات JSON merge patch):
- تُدمج الكائنات بشكل تكراري
- تحذف
nullمفتاحًا - تستبدل المصفوفات
raw(string) — JSON5 يحتوي فقط على المفاتيح المراد تغييرهاbaseHash(مطلوب) — hash الإعداد منconfig.getsessionKeyوnoteوrestartDelayMs— مثلconfig.apply
config.apply: دمج لعمليات إعادة التشغيل المعلقة، بالإضافة إلى تبريد لمدة 30 ثانية بين دورات إعادة التشغيل.متغيرات البيئة
يقرأ OpenClaw متغيرات env من العملية الأب إضافة إلى:.envمن دليل العمل الحالي (إن وجد)~/.openclaw/.env(احتياطي عام)
استيراد env من الصدفة (اختياري)
استيراد env من الصدفة (اختياري)
إذا كان مفعّلًا ولم تكن المفاتيح المتوقعة مضبوطة، فسيشغّل OpenClaw صدفة تسجيل الدخول الخاصة بك ويستورد المفاتيح المفقودة فقط:المكافئ في متغير env:
OPENCLAW_LOAD_SHELL_ENV=1استبدال متغيرات env في قيم الإعداد
استبدال متغيرات env في قيم الإعداد
أشر إلى متغيرات env في أي قيمة سلسلة نصية ضمن الإعداد باستخدام القواعد:
${VAR_NAME}:- تُطابَق الأسماء المكتوبة بأحرف كبيرة فقط:
[A-Z_][A-Z0-9_]* - تؤدي المتغيرات المفقودة/الفارغة إلى خطأ عند وقت التحميل
- استخدم
$${VAR}للحصول على خرج حرفي - يعمل داخل ملفات
$include - الاستبدال المضمّن:
"${BASE}/v1"←"https://api.example.com/v1"
مراجع الأسرار (env وfile وexec)
مراجع الأسرار (env وfile وexec)
بالنسبة إلى الحقول التي تدعم كائنات SecretRef، يمكنك استخدام:توجد تفاصيل SecretRef (بما في ذلك
secrets.providers لـ env وfile وexec) في إدارة الأسرار.
وترد مسارات بيانات الاعتماد المدعومة في سطح بيانات اعتماد SecretRef.المرجع الكامل
للاطلاع على المرجع الكامل حقلًا بحقل، راجع مرجع الإعداد.ذو صلة: أمثلة الإعداد · مرجع الإعداد · Doctor