التكوين

لكل قناة قسم إعداد خاص بها تحت 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

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

{  channels: {    telegram: {      enabled: true,      botToken: "123:abc",      dmPolicy: "pairing",   // pairing | allowlist | open | disabled      allowFrom: ["tg:123"], // only for 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" (افتراضي): يحصل المرسلون غير المعروفين على رمز اقتران لمرة واحدة للموافقة
• "allowlist": المرسلون الموجودون في allowFrom فقط (أو مخزن السماح المقترن)
• "open": السماح بكل الرسائل المباشرة الواردة (يتطلب allowFrom: ["*"])
• "disabled": تجاهل كل الرسائل المباشرة

للمجموعات، استخدم groupPolicy + groupAllowFrom أو قوائم السماح الخاصة بالقنوات.

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

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

{  messages: {    visibleReplies: "automatic", // set "message_tool" to require message-tool sends everywhere    groupChat: {      visibleReplies: "message_tool", // opt-in; visible output requires message(action=send)      unmentionedInbound: "room_event", // unmentioned always-on group chatter is quiet context    },  },  agents: {    list: [      {        id: "main",        groupChat: {          mentionPatterns: ["@openclaw", "openclaw"],        },      },    ],  },  channels: {    whatsapp: {      groups: { "*": { requireMention: true } },    },  },}

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

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

{  agents: {    defaults: {      skills: ["github", "weather"],    },    list: [      { id: "writer" }, // inherits github, weather      { id: "docs", skills: ["docs-search"] }, // replaces defaults      { id: "locked-down", skills: [] }, // no 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",  // recommended for multi-user    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: الإعدادات الافتراضية العامة لتوجيه الجلسات المرتبطة بالسلاسل (يدعم Discord أوامر /focus و/unfocus و/agents و/session idle و/session max-age).
• راجع إدارة الجلسات لمعرفة النطاق، وروابط الهوية، وسياسة الإرسال.
• راجع المرجع الكامل للاطلاع على جميع الحقول.

شغّل جلسات الوكيل في أوقات تشغيل معزولة داخل صندوق عزل:

{  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",          // Optional. Default: 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 ودع كلاً من جلسات العقدة والمشغل تتصل.
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 منفذ هروب تطويرياً مقتصراً على local loopback؛ لا تحفظ عناوين URL لمرحل HTTP في التكوين.

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

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

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

{  cron: {    enabled: true,    maxConcurrentRuns: 8, // default; cron dispatch + isolated cron agent-turn execution    sessionRetention: "24h",    runLog: {      maxBytes: "2mb",      keepLines: 2000,    },  },}

• sessionRetention: يشذّب جلسات التشغيل المعزولة المكتملة من sessions.json (الافتراضي 24h؛ اضبط false للتعطيل).
• runLog: يشذّب صفوف سجل تشغيل Cron المحتفظ بها لكل مهمة. يظل maxBytes مقبولاً لسجلات التشغيل القديمة المدعومة بالملفات.
• راجع مهام 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 مستويات
• المسارات النسبية: تُحل نسبةً إلى الملف الذي يتضمنها
• تنسيق المسار: يجب ألا تحتوي مسارات التضمين على بايتات null ويجب أن تكون أقصر بصرامة من 4096 حرفاً قبل الحل وبعده
• كتابات مملوكة لـ OpenClaw: عندما يغير إجراء كتابة قسماً واحداً فقط من المستوى الأعلى مدعوماً بتضمين ملف واحد مثل plugins: { $include: "./plugins.json5" }، يحدّث OpenClaw ذلك الملف المضمّن ويترك openclaw.json دون تغيير
• تمرير الكتابة غير المدعوم: التضمينات الجذرية، ومصفوفات التضمين، والتضمينات ذات التجاوزات الشقيقة تفشل بشكل مغلق في الكتابات المملوكة لـ OpenClaw بدلاً من تسطيح التكوين
• الحصر: يجب أن تُحل مسارات $include تحت الدليل الذي يحتوي openclaw.json. لمشاركة شجرة عبر أجهزة أو مستخدمين، اضبط OPENCLAW_INCLUDE_ROOTS إلى قائمة مسارات (: على POSIX، و; على Windows) من أدلة إضافية قد تشير إليها التضمينات. تُحل الروابط الرمزية وتُفحص مرة أخرى، لذلك لا يزال المسار الذي يقع نصياً داخل دليل تكوين ولكن هدفه الحقيقي يخرج من كل جذر مسموح مرفوضاً.
• معالجة الأخطاء: أخطاء واضحة للملفات المفقودة، وأخطاء التحليل، والتضمينات الدائرية، وتنسيق المسار غير الصالح، والطول المفرط