التكوين

لكل قناة قسم إعداد خاص بها ضمن 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.
• استخدم openclaw config set agents.defaults.models '<json>' --strict-json --merge لإضافة مدخلات قائمة السماح دون إزالة النماذج الموجودة. يتم رفض الاستبدالات العادية التي قد تزيل مدخلات ما لم تمرر --replace.
• تستخدم مراجع النماذج صيغة provider/model (مثل anthropic/claude-opus-4-6).
• يتحكم agents.defaults.imageMaxDimensionPx في تصغير صور النص المنسوخ/الأداة (الافتراضي 1200)؛ عادةً ما تقلل القيم الأدنى استخدام رموز الرؤية في التشغيلات كثيرة لقطات الشاشة.
• راجع Models 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", // default; use "automatic" for legacy room replies
    },
  },
  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 المضمّن في العزل § الصور والإعداد.

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

يُضبط الدفع المدعوم بالترحيل في openclaw.json.

اضبط هذا في إعدادات 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 الرسمي/TestFlight، حتى تصل حركة التسجيل والإرسال إلى نشر المرحّل نفسه.

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

1. ثبّت إصدار iOS رسميًا/TestFlight تم تجميعه باستخدام عنوان URL الأساسي نفسه للمرحّل.
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 يعملان كتجاوزات بيئية مؤقتة.
• يبقى 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: 2, // cron dispatch + isolated cron agent-turn execution
    sessionRetention: "24h",
    runLog: {
      maxBytes: "2mb",
      keepLines: 2000,
    },
  },
}

• sessionRetention: تقليم جلسات التشغيل المعزولة المكتملة من sessions.json (الافتراضي 24h؛ اضبط false للتعطيل).
• runLog: تقليم cron/runs/<jobId>.jsonl حسب الحجم والأسطر المحتفظ بها.
• راجع مهام Cron لنظرة عامة على الميزة وأمثلة CLI.

فعّل نقاط نهاية HTTP Webhook على 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,
      },
    ],
  },
}

ملاحظة أمان:

• تعامل مع كل محتوى حمولات 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، فضّل طبقات نماذج حديثة قوية وسياسة أدوات صارمة (على سبيل المثال المراسلة فقط مع العزل حيثما أمكن).

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