التكوين

لكل قناة قسم إعداد خاص بها ضمن channels.<provider>. راجع صفحة القناة المخصصة لمعرفة خطوات الإعداد:

• Discord - channels.discord
• Feishu - channels.feishu
• Google Chat - channels.googlechat
• iMessage - channels.imessage
• Mattermost - channels.mattermost
• Microsoft Teams - channels.msteams
• Signal - channels.signal
• Slack - channels.slack
• Telegram - channels.telegram
• WhatsApp - channels.whatsapp

تشترك جميع القنوات في نمط سياسة الرسائل المباشرة نفسه:

{  channels: {    telegram: {      enabled: true,      botToken: "123:abc",      dmPolicy: "pairing",   // pairing | allowlist | open | disabled      allowFrom: ["tg:123"], // فقط عند استخدام allowlist/open    },  },}

عيّن النموذج الأساسي والبدائل الاختيارية:

{  agents: {    defaults: {      model: {        primary: "anthropic/claude-sonnet-4-6",        fallbacks: ["openai/gpt-5.4"],      },      models: {        "anthropic/claude-sonnet-4-6": { alias: "Sonnet" },        "openai/gpt-5.4": { alias: "GPT" },      },    },  },}

• يعرّف agents.defaults.models كتالوج النماذج ويعمل بوصفه قائمة السماح لـ/model؛ وتصفّي إدخالات provider/* كلًا من /model و/models ومنتقيات النماذج لتقتصر على المزوّدين المحددين مع استمرار استخدام الاكتشاف الديناميكي للنماذج.
• استخدم openclaw config set agents.defaults.models '<json>' --strict-json --merge لإضافة إدخالات إلى قائمة السماح دون إزالة النماذج الموجودة. تُرفض عمليات الاستبدال العادية التي قد تزيل إدخالات ما لم تمرّر --replace.
• تستخدم مراجع النماذج تنسيق provider/model (مثل anthropic/claude-opus-4-6).
• يتحكم agents.defaults.imageMaxDimensionPx في تصغير صور النصوص المنسوخة/الأدوات (القيمة الافتراضية 1200)؛ وعادةً ما تقلّل القيم الأدنى استخدام رموز الرؤية في عمليات التشغيل كثيفة لقطات الشاشة.
• راجع CLI النماذج لتبديل النماذج في المحادثة وتجاوز فشل النموذج لمعرفة سلوك تدوير المصادقة والبدائل.
• بالنسبة إلى المزوّدين المخصصين/المستضافين ذاتيًا، راجع المزوّدين المخصصين في المرجع.

يُتحكم في الوصول عبر الرسائل المباشرة لكل قناة من خلال dmPolicy (القيمة الافتراضية "pairing"):

• "pairing": يحصل المرسلون غير المعروفين على رمز اقتران يُستخدم مرة واحدة للموافقة عليهم
• "allowlist": يُسمح فقط للمرسلين الموجودين في allowFrom (أو مخزن السماح للمقترنين)
• "open": السماح بجميع الرسائل المباشرة الواردة (يتطلب allowFrom: ["*"])
• "disabled": تجاهل جميع الرسائل المباشرة

للمجموعات، استخدم groupPolicy ("allowlist" | "open" | "disabled") بالإضافة إلى groupAllowFrom أو قوائم السماح الخاصة بالقنوات.

راجع المرجع الكامل لمعرفة التفاصيل الخاصة بكل قناة.

تتطلب رسائل المجموعة الإشارة افتراضيًا. اضبط أنماط التشغيل لكل وكيل. تُنشر الردود العادية في المجموعات/القنوات تلقائيًا؛ فعّل مسار أداة الرسائل للغرف المشتركة التي ينبغي للوكيل أن يقرر فيها متى يتحدث:

{  messages: {    visibleReplies: "automatic", // عيّن "message_tool" لاشتراط الإرسال عبر أداة الرسائل في كل مكان    groupChat: {      visibleReplies: "message_tool", // تفعيل اختياري؛ يتطلب الإخراج المرئي message(action=send)      unmentionedInbound: "room_event", // أحاديث المجموعة الدائمة بلا إشارة سياق صامت    },  },  agents: {    list: [      {        id: "main",        groupChat: {          mentionPatterns: ["@openclaw", "openclaw"],        },      },    ],  },  channels: {    whatsapp: {      groups: { "*": { requireMention: true } },    },  },}

• إشارات البيانات الوصفية: إشارات @ الأصلية (النقر للإشارة في WhatsApp، و@bot في Telegram، وغيرها)
• أنماط النص: أنماط تعبيرات نمطية آمنة في mentionPatterns
• الردود المرئية: يمكن لـmessages.visibleReplies اشتراط الإرسال عبر أداة الرسائل عموميًا؛ ويتجاوز messages.groupChat.visibleReplies ذلك للمجموعات/القنوات.
• راجع المرجع الكامل لمعرفة أوضاع الرد المرئي، والتجاوزات الخاصة بكل قناة، ووضع المحادثة الذاتية.

استخدم agents.defaults.skills كأساس مشترك، ثم تجاوز إعدادات وكلاء محددين باستخدام agents.list[].skills:

{  agents: {    defaults: {      skills: ["github", "weather"],    },    list: [      { id: "writer" }, // يرث github وweather      { id: "docs", skills: ["docs-search"] }, // يستبدل الإعدادات الافتراضية      { id: "locked-down", skills: [] }, // بلا Skills    ],  },}

• احذف agents.defaults.skills للسماح غير المقيّد بـSkills افتراضيًا.
• احذف agents.list[].skills لوراثة الإعدادات الافتراضية.
• عيّن agents.list[].skills: [] لعدم استخدام أي Skills.
• راجع Skills، وإعداد Skills، و مرجع الإعدادات.

تحكم في مدى قوة إعادة تشغيل Gateway للقنوات التي تبدو قديمة:

{  gateway: {    channelHealthCheckMinutes: 5,    channelStaleEventThresholdMinutes: 30,    channelMaxRestartsPerHour: 10,  },  channels: {    telegram: {      healthMonitor: { enabled: false },      accounts: {        alerts: {          healthMonitor: { enabled: true },        },      },    },  },}

• القيم المعروضة هي القيم الافتراضية. عيّن gateway.channelHealthCheckMinutes: 0 لتعطيل عمليات إعادة التشغيل الناتجة عن مراقبة السلامة عموميًا.
• ينبغي أن يكون channelStaleEventThresholdMinutes أكبر من فاصل الفحص أو مساويًا له.
• استخدم channels.<provider>.healthMonitor.enabled أو channels.<provider>.accounts.<id>.healthMonitor.enabled لتعطيل عمليات إعادة التشغيل التلقائية لقناة أو حساب واحد دون تعطيل المراقب العام.
• راجع فحوصات السلامة لتصحيح المشكلات التشغيلية والمرجع الكامل للاطلاع على جميع الحقول.

امنح العملاء المحليين وقتًا أطول لإكمال مصافحة WebSocket السابقة للمصادقة على المضيفات المحمّلة أو منخفضة الطاقة:

{  gateway: {    handshakeTimeoutMs: 30000,  },}

• القيمة الافتراضية هي 15000 مللي ثانية.
• تظل OPENCLAW_HANDSHAKE_TIMEOUT_MS ذات أولوية للتجاوزات المؤقتة للخدمة أو الصدفة.
• يُفضّل إصلاح حالات تعطل بدء التشغيل/حلقة الأحداث أولًا؛ فهذا الضابط مخصص للمضيفات السليمة التي تكون بطيئة أثناء الإحماء.

تتحكم الجلسات في استمرارية المحادثة وعزلها:

{  session: {    dmScope: "per-channel-peer",  // موصى به لتعدد المستخدمين    threadBindings: {      enabled: true,      idleHours: 24,      maxAgeHours: 0,    },    reset: {      mode: "daily",      atHour: 4,      idleMinutes: 120,    },  },}

• dmScope: main (مشتركة) | per-peer | per-channel-peer | per-account-channel-peer
• threadBindings: الإعدادات الافتراضية العامة لتوجيه الجلسات المرتبطة بسلاسل المحادثات. تقوم /focus و/unfocus و/agents و/session idle و/session max-age بالربط وإلغاء الربط والسرد والضبط لكل جلسة (يربط Discord سلاسل المحادثات، ويربط Telegram الموضوعات/المحادثات).
• راجع إدارة الجلسات لمعرفة تحديد النطاق وروابط الهوية وسياسة الإرسال.
• راجع المرجع الكامل للاطلاع على جميع الحقول.

شغّل جلسات الوكيل في بيئات تشغيل معزولة:

{  agents: {    defaults: {      sandbox: {        mode: "non-main",  // off | non-main | all        scope: "agent",    // session | agent | shared      },    },  },}

أنشئ الصورة أولًا - من نسخة مصدر مشحونة شغّل scripts/sandbox-setup.sh، أو من تثبيت npm راجع أمر docker build المضمّن في العزل § الصور والإعداد.

راجع العزل للاطلاع على الدليل الكامل والمرجع الكامل لجميع الخيارات.

يستخدم الدفع المدعوم بالمرحل لإصدارات App Store العامة مرحل OpenClaw المستضاف: https://ios-push-relay.openclaw.ai.

تتطلب عمليات نشر المرحل المخصص مسارًا منفصلًا عمدًا لبناء iOS ونشره، بحيث يتطابق عنوان URL للمرحل فيه مع عنوان URL لمرحل Gateway. إذا كنت تستخدم إصدار مرحل مخصصًا، فعيّن ما يلي في تهيئة Gateway:

{  gateway: {    push: {      apns: {        relay: {          baseUrl: "https://relay.example.com",          // اختياري. القيمة الافتراضية: 10000          timeoutMs: 10000,        },      },    },  },}

المكافئ في CLI:

openclaw config set gateway.push.apns.relay.baseUrl https://relay.example.com

ما يفعله هذا:

• يتيح لـ Gateway إرسال push.test وتنبيهات التنشيط وتنبيهات إعادة الاتصال عبر المرحل الخارجي.
• يستخدم إذن إرسال مقيّدًا بالتسجيل يمرره تطبيق iOS المقترن. لا يحتاج Gateway إلى رمز مرحل يشمل عملية النشر بأكملها.
• يربط كل تسجيل مدعوم بالمرحل بهوية Gateway التي اقترن بها تطبيق iOS، بحيث لا يتمكن Gateway آخر من إعادة استخدام التسجيل المخزّن.
• يُبقي إصدارات iOS المحلية/اليدوية على APNs المباشر. لا تنطبق عمليات الإرسال المدعومة بالمرحل إلا على الإصدارات الرسمية الموزعة التي سجّلت عبر المرحل.
• يجب أن يتطابق مع عنوان URL الأساسي للمرحل المضمّن في إصدار iOS، حتى تصل حركة التسجيل والإرسال إلى عملية نشر المرحل نفسها.

التدفق من البداية إلى النهاية:

1. ثبّت تطبيق iOS الرسمي.
2. اختياري: هيّئ gateway.push.apns.relay.baseUrl على Gateway فقط عند استخدام إصدار مرحل مخصص منفصل عمدًا.
3. اقرن تطبيق iOS بـ Gateway واترك جلستي Node والمشغّل تتصلان.
4. يجلب تطبيق iOS هوية Gateway، ويسجّل لدى المرحل باستخدام App Attest بالإضافة إلى إيصال التطبيق، ثم ينشر حمولة push.apns.register المدعومة بالمرحل إلى Gateway المقترن.
5. يخزّن Gateway معرّف المرحل وإذن الإرسال، ثم يستخدمهما من أجل push.test وتنبيهات التنشيط وتنبيهات إعادة الاتصال.

ملاحظات تشغيلية:

• إذا بدّلت تطبيق iOS إلى Gateway مختلف، فأعد توصيل التطبيق حتى يتمكن من نشر تسجيل مرحل جديد مرتبط بذلك الـ Gateway.
• إذا شحنت إصدار iOS جديدًا يشير إلى عملية نشر مرحل مختلفة، فسيحدّث التطبيق تسجيل المرحل المخزّن مؤقتًا بدلًا من إعادة استخدام أصل المرحل القديم.

ملاحظة التوافق:

• تظل OPENCLAW_APNS_RELAY_BASE_URL وOPENCLAW_APNS_RELAY_TIMEOUT_MS تعملان كتجاوزات مؤقتة عبر متغيرات البيئة.
• يجب أن تتطابق عناوين URL المخصصة لمرحل Gateway مع عنوان URL الأساسي للمرحل المضمّن في إصدار iOS؛ ويرفض مسار إصدار App Store العام تجاوزات عنوان URL المخصص لمرحل iOS.
• تظل OPENCLAW_APNS_RELAY_ALLOW_HTTP=true منفذًا احتياطيًا للتطوير مقتصرًا على واجهة الاسترجاع؛ لا تحفظ عناوين URL لمرحل HTTP في التهيئة.

راجع تطبيق iOS للاطلاع على التدفق من البداية إلى النهاية وتدفق المصادقة والثقة للاطلاع على نموذج أمان المرحل.

{  agents: {    defaults: {      heartbeat: {        every: "30m",        target: "last",      },    },  },}

• every: سلسلة مدة (30m، 2h). عيّن 0m للتعطيل. القيمة الافتراضية: 30m.
• target: last | none | <channel-id> (مثلًا discord أو matrix أو telegram أو whatsapp)
• directPolicy: allow (الافتراضي) أو block لأهداف Heartbeat بنمط الرسائل المباشرة
• راجع Heartbeat للاطلاع على الدليل الكامل.

{  cron: {    enabled: true,    maxConcurrentRuns: 8, // القيمة الافتراضية؛ إرسال cron + تنفيذ دورة وكيل cron معزولة    sessionRetention: "24h",  },}

• sessionRetention: يحذف جلسات التشغيل المعزولة المكتملة من صفوف جلسات SQLite (القيمة الافتراضية 24h؛ عيّن false للتعطيل).
• يحتفظ سجل التشغيل تلقائيًا بأحدث 2000 صف نهائي لكل مهمة؛ وتحتفظ الصفوف المفقودة بنافذة التنظيف البالغة 24 ساعة.
• راجع مهام Cron للاطلاع على نظرة عامة على الميزة وأمثلة CLI.

مكّن نقاط نهاية Webhook عبر HTTP على Gateway:

{  hooks: {    enabled: true,    token: "shared-secret",    path: "/hooks",    defaultSessionKey: "hook:ingress",    allowRequestSessionKey: false,    allowedSessionKeyPrefixes: ["hook:"],    mappings: [      {        match: { path: "gmail" },        action: "agent",        agentId: "main",        deliver: true,      },    ],  },}

ملاحظة أمنية:

• تعامل مع جميع محتويات حمولات الخطافات/Webhook بوصفها مدخلات غير موثوقة.
• استخدم hooks.token مخصصًا؛ ولا تعِد استخدام أسرار مصادقة Gateway النشطة (gateway.auth.token / OPENCLAW_GATEWAY_TOKEN أو gateway.auth.password / OPENCLAW_GATEWAY_PASSWORD).
• تقتصر مصادقة الخطافات على الترويسة (Authorization: Bearer ... أو x-openclaw-token)؛ وتُرفض الرموز الموجودة في سلسلة الاستعلام.
• لا يمكن أن تكون hooks.path هي /؛ احتفظ بإدخال Webhook في مسار فرعي مخصص مثل /hooks.
• أبقِ علامات تجاوز المحتوى غير الآمن معطّلة (hooks.gmail.allowUnsafeExternalContent، hooks.mappings[].allowUnsafeExternalContent) إلا عند إجراء تصحيح أخطاء محدود النطاق بدقة.
• إذا مكّنت hooks.allowRequestSessionKey، فعيّن أيضًا hooks.allowedSessionKeyPrefixes لتقييد مفاتيح الجلسة التي يحددها المستدعي.
• بالنسبة إلى الوكلاء المشغّلين بالخطافات، فضّل مستويات النماذج الحديثة القوية وسياسة أدوات صارمة (مثل الاقتصار على المراسلة مع العزل حيثما أمكن).

راجع المرجع الكامل للاطلاع على جميع خيارات التعيين وتكامل Gmail.

شغّل عدة وكلاء معزولين بمساحات عمل وجلسات منفصلة:

{  agents: {    list: [      { id: "home", default: true, workspace: "~/.openclaw/workspace-home" },      { id: "work", workspace: "~/.openclaw/workspace-work" },    ],  },  bindings: [    { agentId: "home", match: { channel: "whatsapp", accountId: "personal" } },    { agentId: "work", match: { channel: "whatsapp", accountId: "biz" } },  ],}

راجع تعدد الوكلاء والمرجع الكامل لمعرفة قواعد الربط وملفات تعريف الوصول لكل وكيل.

استخدم $include لتنظيم ملفات التهيئة الكبيرة:

// ~/.openclaw/openclaw.json{  gateway: { port: 18789 },  agents: { $include: "./agents.json5" },  broadcast: {    $include: ["./clients/a.json5", "./clients/b.json5"],  },}

• ملف واحد: يحل محل الكائن الحاوي
• مصفوفة ملفات: تُدمج بعمق حسب الترتيب (تتغلب القيم اللاحقة)، حتى 10 مستويات متداخلة
• المفاتيح الشقيقة: تُدمج بعد عمليات التضمين (وتتجاوز القيم المضمّنة)
• المسارات النسبية: تُحل بالنسبة إلى الملف الذي يجري التضمين
• تنسيق المسار: يجب ألا تحتوي مسارات التضمين على بايتات فارغة، ويجب أن يقل طولها قطعًا عن 4096 حرفًا قبل الحل وبعده
• عمليات الكتابة المملوكة لـ OpenClaw: عندما تغيّر عملية كتابة قسمًا واحدًا فقط من المستوى الأعلى تدعمه عملية تضمين لملف واحد مثل plugins: { $include: "./plugins.json5" }، يحدّث OpenClaw ذلك الملف المضمّن ويترك openclaw.json سليمًا
• الكتابة العابرة غير المدعومة: تفشل عمليات تضمين الجذر ومصفوفات التضمين وعمليات التضمين ذات التجاوزات الشقيقة بشكل مغلق لعمليات الكتابة المملوكة لـ OpenClaw بدلًا من تسطيح التهيئة
• الاحتواء: يجب أن تُحل مسارات $include ضمن الدليل الذي يحتوي على openclaw.json. لمشاركة شجرة عبر عدة أجهزة أو مستخدمين، عيّن OPENCLAW_INCLUDE_ROOTS إلى قائمة مسارات (: على POSIX و; على Windows) من الأدلة الإضافية التي يمكن لعمليات التضمين الرجوع إليها. تُحل الروابط الرمزية ويُعاد التحقق منها، ولذلك يظل المسار الذي يقع نصيًا داخل دليل تهيئة لكن هدفه الحقيقي يخرج من كل جذر مسموح به مرفوضًا.
• معالجة الأخطاء: أخطاء واضحة للملفات المفقودة وأخطاء التحليل وعمليات التضمين الدائرية وتنسيق المسار غير الصالح والطول المفرط