​

مرجع الإعدادات

• يطبع openclaw config schema مخطط JSON Schema الفعلي المستخدم للتحقق وواجهة Control UI، مع دمج بيانات التعريف الخاصة بالحزم المضمّنة/Plugin/القنوات عند توفرها
• يعيد config.schema.lookup عقدة مخطط واحدة محددة بالمسار لأدوات الاستكشاف التفصيلي
• يتحقق pnpm config:docs:check / pnpm config:docs:gen من تجزئة خط الأساس لوثائق الإعدادات مقارنةً بسطح المخطط الحالي

• مرجع إعدادات الذاكرة لـ agents.defaults.memorySearch.* وmemory.qmd.* وmemory.citations وإعدادات Dreaming تحت plugins.entries.memory-core.config.dreaming
• Slash Commands لفهرس الأوامر الحالي المضمن + المجمّع
• صفحات القنوات/Plugin المالكة لأسطح الأوامر الخاصة بكل قناة

​

القنوات

​

الوصول إلى الرسائل المباشرة والمجموعات

​

تجاوزات نموذج القناة

{
  channels: {
    modelByChannel: {
      discord: {
        "123456789012345678": "anthropic/claude-opus-4-6",
      },
      slack: {
        C1234567890: "openai/gpt-4.1",
      },
      telegram: {
        "-1001234567890": "openai/gpt-4.1-mini",
        "-1001234567890:topic:99": "anthropic/claude-sonnet-4-6",
      },
    },
  },
}

​

الإعدادات الافتراضية للقنوات وHeartbeat

{
  channels: {
    defaults: {
      groupPolicy: "allowlist", // open | allowlist | disabled
      contextVisibility: "all", // all | allowlist | allowlist_quote
      heartbeat: {
        showOk: false,
        showAlerts: true,
        useIndicator: true,
      },
    },
  },
}

• channels.defaults.groupPolicy: سياسة المجموعات الاحتياطية عندما لا تكون groupPolicy على مستوى المزوّد معيّنة.
• channels.defaults.contextVisibility: وضع إظهار السياق التكميلي الافتراضي لجميع القنوات. القيم: all (الافتراضي، تضمين كل سياق الاقتباس/المواضيع/السجل)، وallowlist (تضمين السياق فقط من المرسلين الموجودين في قائمة السماح)، وallowlist_quote (مثل allowlist لكن مع الاحتفاظ بسياق الاقتباس/الرد الصريح). تجاوز لكل قناة: channels.<channel>.contextVisibility.
• channels.defaults.heartbeat.showOk: تضمين حالات القنوات السليمة في مخرجات Heartbeat.
• channels.defaults.heartbeat.showAlerts: تضمين الحالات المتدهورة/حالات الخطأ في مخرجات Heartbeat.
• channels.defaults.heartbeat.useIndicator: عرض مخرجات Heartbeat بأسلوب مؤشرات مضغوط.

​

WhatsApp

{
  channels: {
    whatsapp: {
      dmPolicy: "pairing", // pairing | allowlist | open | disabled
      allowFrom: ["+15555550123", "+447700900123"],
      textChunkLimit: 4000,
      chunkMode: "length", // length | newline
      mediaMaxMb: 50,
      sendReadReceipts: true, // علامتا الصح الزرقاوان (false في وضع الدردشة الذاتية)
      groups: {
        "*": { requireMention: true },
      },
      groupPolicy: "allowlist",
      groupAllowFrom: ["+15551234567"],
    },
  },
  web: {
    enabled: true,
    heartbeatSeconds: 60,
    reconnect: {
      initialMs: 2000,
      maxMs: 120000,
      factor: 1.4,
      jitter: 0.2,
      maxAttempts: 0,
    },
  },
}

{
  channels: {
    whatsapp: {
      accounts: {
        default: {},
        personal: {},
        biz: {
          // authDir: "~/.openclaw/credentials/whatsapp/biz",
        },
      },
    },
  },
}

​

Telegram

{
  channels: {
    telegram: {
      enabled: true,
      botToken: "your-bot-token",
      dmPolicy: "pairing",
      allowFrom: ["tg:123456789"],
      groups: {
        "*": { requireMention: true },
        "-1001234567890": {
          allowFrom: ["@admin"],
          systemPrompt: "Keep answers brief.",
          topics: {
            "99": {
              requireMention: false,
              skills: ["search"],
              systemPrompt: "Stay on topic.",
            },
          },
        },
      },
      customCommands: [
        { command: "backup", description: "Git backup" },
        { command: "generate", description: "Create an image" },
      ],
      historyLimit: 50,
      replyToMode: "first", // off | first | all | batched
      linkPreview: true,
      streaming: "partial", // off | partial | block | progress (الافتراضي: off؛ فعّله صراحةً لتجنب حدود معدل تعديل المعاينة)
      actions: { reactions: true, sendMessage: true },
      reactionNotifications: "own", // off | own | all
      mediaMaxMb: 100,
      retry: {
        attempts: 3,
        minDelayMs: 400,
        maxDelayMs: 30000,
        jitter: 0.1,
      },
      network: {
        autoSelectFamily: true,
        dnsResultOrder: "ipv4first",
      },
      proxy: "socks5://localhost:9050",
      webhookUrl: "https://example.com/telegram-webhook",
      webhookSecret: "secret",
      webhookPath: "/telegram-webhook",
    },
  },
}

• رمز البوت: channels.telegram.botToken أو channels.telegram.tokenFile (ملف عادي فقط؛ تُرفض الروابط الرمزية)، مع TELEGRAM_BOT_TOKEN كقيمة احتياطية للحساب الافتراضي.
• يتجاوز channels.telegram.defaultAccount الاختياري اختيار الحساب الافتراضي عندما يطابق معرّف حساب مُهيأ.
• في إعدادات الحسابات المتعددة (معرّفا حساب أو أكثر)، عيّن افتراضيًا صريحًا (channels.telegram.defaultAccount أو channels.telegram.accounts.default) لتجنب التوجيه الاحتياطي؛ ويحذّر openclaw doctor عندما يكون هذا مفقودًا أو غير صالح.
• يؤدي configWrites: false إلى حظر عمليات كتابة الإعدادات التي يبدؤها Telegram (ترحيل معرّفات supergroup، و/config set|unset).
• تُهيّئ إدخالات bindings[] ذات المستوى الأعلى مع type: "acp" ارتباطات ACP دائمة لموضوعات المنتدى (استخدم الصيغة القانونية chatId:topic:topicId في match.peer.id). دلالات الحقول مشتركة في ACP Agents.
• تستخدم معاينات البث في Telegram كلًا من sendMessage وeditMessageText (وتعمل في الدردشات المباشرة والجماعية).
• سياسة إعادة المحاولة: راجع سياسة إعادة المحاولة.

​

Discord

{
  channels: {
    discord: {
      enabled: true,
      token: "your-bot-token",
      mediaMaxMb: 100,
      allowBots: false,
      actions: {
        reactions: true,
        stickers: true,
        polls: true,
        permissions: true,
        messages: true,
        threads: true,
        pins: true,
        search: true,
        memberInfo: true,
        roleInfo: true,
        roles: false,
        channelInfo: true,
        voiceStatus: true,
        events: true,
        moderation: false,
      },
      replyToMode: "off", // off | first | all | batched
      dmPolicy: "pairing",
      allowFrom: ["1234567890", "123456789012345678"],
      dm: { enabled: true, groupEnabled: false, groupChannels: ["openclaw-dm"] },
      guilds: {
        "123456789012345678": {
          slug: "friends-of-openclaw",
          requireMention: false,
          ignoreOtherMentions: true,
          reactionNotifications: "own",
          users: ["987654321098765432"],
          channels: {
            general: { allow: true },
            help: {
              allow: true,
              requireMention: true,
              users: ["987654321098765432"],
              skills: ["docs"],
              systemPrompt: "Short answers only.",
            },
          },
        },
      },
      historyLimit: 20,
      textChunkLimit: 2000,
      chunkMode: "length", // length | newline
      streaming: "off", // off | partial | block | progress (تُطابق progress مع partial على Discord)
      maxLinesPerMessage: 17,
      ui: {
        components: {
          accentColor: "#5865F2",
        },
      },
      threadBindings: {
        enabled: true,
        idleHours: 24,
        maxAgeHours: 0,
        spawnSubagentSessions: false, // تفعيل اختياري لـ sessions_spawn({ thread: true })
      },
      voice: {
        enabled: true,
        autoJoin: [
          {
            guildId: "123456789012345678",
            channelId: "234567890123456789",
          },
        ],
        daveEncryption: true,
        decryptionFailureTolerance: 24,
        tts: {
          provider: "openai",
          openai: { voice: "alloy" },
        },
      },
      execApprovals: {
        enabled: "auto", // true | false | "auto"
        approvers: ["987654321098765432"],
        agentFilter: ["default"],
        sessionFilter: ["discord:"],
        target: "dm", // dm | channel | both
        cleanupAfterResolve: false,
      },
      retry: {
        attempts: 3,
        minDelayMs: 500,
        maxDelayMs: 30000,
        jitter: 0.1,
      },
    },
  },
}

• الرمز المميز: channels.discord.token، مع DISCORD_BOT_TOKEN كقيمة احتياطية للحساب الافتراضي.
• تستخدم الاستدعاءات الصادرة المباشرة التي توفّر token صريحًا لـ Discord ذلك الرمز المميز لهذا الاستدعاء؛ بينما تستمر إعدادات إعادة المحاولة/السياسة الخاصة بالحساب في الاعتماد على الحساب المحدد في اللقطة النشطة أثناء التشغيل.
• يتجاوز channels.discord.defaultAccount الاختياري اختيار الحساب الافتراضي عندما يطابق معرّف حساب مُهيأ.
• استخدم user:<id> (رسالة مباشرة) أو channel:<id> (قناة guild) كأهداف للتسليم؛ وتُرفض المعرّفات الرقمية المجردة.
• تكون الأسماء المختصرة لـ guild بأحرف صغيرة مع استبدال المسافات بـ -؛ وتستخدم مفاتيح القنوات الاسم المختصر (من دون #). ويُفضّل استخدام معرّفات guild.
• تُتجاهل الرسائل التي ينشئها البوت افتراضيًا. يفعّل allowBots: true قبولها؛ واستخدم allowBots: "mentions" لقبول رسائل البوت التي تذكر البوت فقط (مع استمرار تصفية رسائله الذاتية).
• يؤدي channels.discord.guilds.<id>.ignoreOtherMentions (وتجاوزات القنوات) إلى إسقاط الرسائل التي تذكر مستخدمًا آخر أو دورًا آخر ولكنها لا تذكر البوت (باستثناء @everyone/@here).
• يقسم maxLinesPerMessage (الافتراضي 17) الرسائل الطويلة عموديًا حتى عندما تكون أقل من 2000 حرف.
• يتحكم channels.discord.threadBindings في التوجيه المرتبط بسلاسل Discord:
  • enabled: تجاوز Discord لميزات الجلسات المرتبطة بالسلاسل (/focus و/unfocus و/agents و/session idle و/session max-age، والتسليم/التوجيه المرتبط)
  • idleHours: تجاوز Discord لإلغاء التركيز التلقائي بعد عدم النشاط، بالساعات (0 للتعطيل)
  • maxAgeHours: تجاوز Discord للحد الأقصى الصارم للعمر، بالساعات (0 للتعطيل)
  • spawnSubagentSessions: مفتاح تفعيل اختياري لإنشاء/ربط السلاسل تلقائيًا بواسطة sessions_spawn({ thread: true })
• تُهيّئ إدخالات bindings[] ذات المستوى الأعلى مع type: "acp" ارتباطات ACP دائمة للقنوات والسلاسل (استخدم معرّف القناة/السلسلة في match.peer.id). دلالات الحقول مشتركة في ACP Agents.
• يضبط channels.discord.ui.components.accentColor لون التمييز لحاويات مكونات Discord v2.
• يفعّل channels.discord.voice محادثات القنوات الصوتية في Discord وتجاوزات الانضمام التلقائي وTTS الاختيارية.
• يُمرَّر channels.discord.voice.daveEncryption وchannels.discord.voice.decryptionFailureTolerance إلى خيارات DAVE في @discordjs/voice (القيم الافتراضية true و24).
• يحاول OpenClaw أيضًا استعادة استقبال الصوت عبر مغادرة الجلسة الصوتية وإعادة الانضمام إليها بعد تكرار إخفاقات فك التشفير.
• يُعد channels.discord.streaming مفتاح وضع البث القانوني. وتُرحَّل تلقائيًا القيم القديمة streamMode وقيم streaming المنطقية.
• يربط channels.discord.autoPresence حالة التوفر أثناء التشغيل بحضور البوت (سليم => online، متدهور => idle، مستنفد => dnd)، ويسمح بتجاوزات اختيارية لنص الحالة.
• يعيد channels.discord.dangerouslyAllowNameMatching تفعيل المطابقة القابلة للتغيير للاسم/الوسم (وضع توافق طارئ).
• channels.discord.execApprovals: تسليم موافقات exec الأصلية في Discord وتفويض الموافقين.
  • enabled: القيم true أو false أو "auto" (الافتراضي). في وضع auto، تُفعَّل موافقات exec عندما يمكن حلّ الموافقين من approvers أو commands.ownerAllowFrom.
  • approvers: معرّفات مستخدمي Discord المسموح لهم بالموافقة على طلبات exec. ويُستخدم commands.ownerAllowFrom كقيمة احتياطية عند حذفه.
  • agentFilter: قائمة سماح اختيارية لمعرّفات الوكلاء. احذفها لتمرير الموافقات لجميع الوكلاء.
  • sessionFilter: أنماط مفاتيح جلسات اختيارية (سلسلة فرعية أو regex).
  • target: مكان إرسال مطالبات الموافقة. ترسل "dm" (الافتراضي) إلى الرسائل المباشرة للموافقين، وترسل "channel" إلى القناة الأصلية، وترسل "both" إلى كليهما. وعندما يتضمن الهدف "channel"، لا تكون الأزرار قابلة للاستخدام إلا من قبل الموافقين الذين تم حلّهم.
  • cleanupAfterResolve: عند تعيينه إلى true، يحذف رسائل الموافقة المباشرة بعد الموافقة أو الرفض أو انتهاء المهلة.

​

Google Chat

{
  channels: {
    googlechat: {
      enabled: true,
      serviceAccountFile: "/path/to/service-account.json",
      audienceType: "app-url", // app-url | project-number
      audience: "https://gateway.example.com/googlechat",
      webhookPath: "/googlechat",
      botUser: "users/1234567890",
      dm: {
        enabled: true,
        policy: "pairing",
        allowFrom: ["users/1234567890"],
      },
      groupPolicy: "allowlist",
      groups: {
        "spaces/AAAA": { allow: true, requireMention: true },
      },
      actions: { reactions: true },
      typingIndicator: "message",
      mediaMaxMb: 20,
    },
  },
}

• JSON لحساب الخدمة: مضمّن (serviceAccount) أو مستند إلى ملف (serviceAccountFile).
• كما أن SecretRef لحساب الخدمة مدعوم أيضًا (serviceAccountRef).
• القيم الاحتياطية من البيئة: GOOGLE_CHAT_SERVICE_ACCOUNT أو GOOGLE_CHAT_SERVICE_ACCOUNT_FILE.
• استخدم spaces/<spaceId> أو users/<userId> كأهداف للتسليم.
• يعيد channels.googlechat.dangerouslyAllowNameMatching تفعيل مطابقة كيان البريد الإلكتروني القابلة للتغيير (وضع توافق طارئ).

​

Slack

{
  channels: {
    slack: {
      enabled: true,
      botToken: "xoxb-...",
      appToken: "xapp-...",
      dmPolicy: "pairing",
      allowFrom: ["U123", "U456", "*"],
      dm: { enabled: true, groupEnabled: false, groupChannels: ["G123"] },
      channels: {
        C123: { allow: true, requireMention: true, allowBots: false },
        "#general": {
          allow: true,
          requireMention: true,
          allowBots: false,
          users: ["U123"],
          skills: ["docs"],
          systemPrompt: "Short answers only.",
        },
      },
      historyLimit: 50,
      allowBots: false,
      reactionNotifications: "own",
      reactionAllowlist: ["U123"],
      replyToMode: "off", // off | first | all | batched
      thread: {
        historyScope: "thread", // thread | channel
        inheritParent: false,
      },
      actions: {
        reactions: true,
        messages: true,
        pins: true,
        memberInfo: true,
        emojiList: true,
      },
      slashCommand: {
        enabled: true,
        name: "openclaw",
        sessionPrefix: "slack:slash",
        ephemeral: true,
      },
      typingReaction: "hourglass_flowing_sand",
      textChunkLimit: 4000,
      chunkMode: "length",
      streaming: {
        mode: "partial", // off | partial | block | progress
        nativeTransport: true, // استخدم واجهة Slack الأصلية للبث عندما يكون mode=partial
      },
      mediaMaxMb: 20,
      execApprovals: {
        enabled: "auto", // true | false | "auto"
        approvers: ["U123"],
        agentFilter: ["default"],
        sessionFilter: ["slack:"],
        target: "dm", // dm | channel | both
      },
    },
  },
}

• يتطلب وضع Socket كلًا من botToken وappToken (SLACK_BOT_TOKEN + SLACK_APP_TOKEN كقيمة احتياطية من البيئة للحساب الافتراضي).
• يتطلب وضع HTTP botToken بالإضافة إلى signingSecret (على المستوى الجذري أو لكل حساب).
• تقبل botToken وappToken وsigningSecret وuserToken سلاسل نصية صريحة أو كائنات SecretRef.
• تعرض لقطات حساب Slack حقول المصدر/الحالة لكل اعتماد مثل botTokenSource وbotTokenStatus وappTokenStatus، وفي وضع HTTP، signingSecretStatus. وتعني configured_unavailable أن الحساب مهيأ عبر SecretRef لكن مسار الأمر/التشغيل الحالي لم يتمكن من حل قيمة السر.
• يؤدي configWrites: false إلى حظر عمليات كتابة الإعدادات التي يبدؤها Slack.
• يتجاوز channels.slack.defaultAccount الاختياري اختيار الحساب الافتراضي عندما يطابق معرّف حساب مُهيأ.
• يُعد channels.slack.streaming.mode مفتاح وضع بث Slack القانوني. ويتحكم channels.slack.streaming.nativeTransport في وسيلة النقل الأصلية للبث في Slack. وتُرحَّل تلقائيًا القيم القديمة streamMode وقيم streaming المنطقية وnativeStreaming.
• استخدم user:<id> (رسالة مباشرة) أو channel:<id> كأهداف للتسليم.

• يتطلب البث الأصلي في Slack بالإضافة إلى حالة السلسلة بأسلوب Slack assistant “is typing…” هدف ردّ داخل سلسلة. وتبقى الرسائل المباشرة ذات المستوى الأعلى خارج السلاسل افتراضيًا، لذلك تستخدم typingReaction أو التسليم العادي بدلًا من المعاينة بأسلوب السلسلة.
• تضيف typingReaction تفاعلًا مؤقتًا إلى رسالة Slack الواردة أثناء تشغيل الرد، ثم تزيله عند الاكتمال. استخدم اختصار emoji في Slack مثل "hourglass_flowing_sand".
• channels.slack.execApprovals: تسليم موافقات exec الأصلية في Slack وتفويض الموافقين. نفس مخطط Discord: enabled (true/false/"auto")، وapprovers (معرّفات مستخدمي Slack)، وagentFilter، وsessionFilter، وtarget ("dm" أو "channel" أو "both").

​

Mattermost

{
  channels: {
    mattermost: {
      enabled: true,
      botToken: "mm-token",
      baseUrl: "https://chat.example.com",
      dmPolicy: "pairing",
      chatmode: "oncall", // oncall | onmessage | onchar
      oncharPrefixes: [">", "!"],
      groups: {
        "*": { requireMention: true },
        "team-channel-id": { requireMention: false },
      },
      commands: {
        native: true, // تفعيل اختياري
        nativeSkills: true,
        callbackPath: "/api/channels/mattermost/command",
        // عنوان URL صريح اختياري لعمليات النشر العامة/خلف وكيل عكسي
        callbackUrl: "https://gateway.example.com/api/channels/mattermost/command",
      },
      textChunkLimit: 4000,
      chunkMode: "length",
    },
  },
}

• يجب أن يكون commands.callbackPath مسارًا (على سبيل المثال /api/channels/mattermost/command)، وليس عنوان URL كاملًا.
• يجب أن يشير commands.callbackUrl إلى نقطة نهاية Gateway الخاصة بـ OpenClaw وأن يكون قابلاً للوصول من خادم Mattermost.
• تُصادَق عمليات الاستدعاء العكسي الأصلية لـ slash بواسطة الرموز المميزة الخاصة بكل أمر التي يعيدها Mattermost أثناء تسجيل slash command. وإذا فشل التسجيل أو لم تُفعَّل أي أوامر، يرفض OpenClaw عمليات الاستدعاء العكسي بالرسالة Unauthorized: invalid command token.
• بالنسبة إلى مستضيفي الاستدعاء العكسي الخاصين/داخليي tailnet/الداخليين، قد يتطلب Mattermost أن يتضمن ServiceSettings.AllowedUntrustedInternalConnections مستضيف/نطاق الاستدعاء العكسي. استخدم قيم المستضيف/النطاق، وليس عناوين URL كاملة.
• channels.mattermost.configWrites: السماح أو الرفض لعمليات كتابة الإعدادات التي يبدؤها Mattermost.
• channels.mattermost.requireMention: طلب @mention قبل الرد في القنوات.
• channels.mattermost.groups.<channelId>.requireMention: تجاوز اشتراط الإشارة لكل قناة ("*" للافتراضي).
• يتجاوز channels.mattermost.defaultAccount الاختياري اختيار الحساب الافتراضي عندما يطابق معرّف حساب مُهيأ.

​

Signal

{
  channels: {
    signal: {
      enabled: true,
      account: "+15555550123", // ربط حساب اختياري
      dmPolicy: "pairing",
      allowFrom: ["+15551234567", "uuid:123e4567-e89b-12d3-a456-426614174000"],
      configWrites: true,
      reactionNotifications: "own", // off | own | all | allowlist
      reactionAllowlist: ["+15551234567", "uuid:123e4567-e89b-12d3-a456-426614174000"],
      historyLimit: 50,
    },
  },
}

• channels.signal.account: تثبيت بدء تشغيل القناة على هوية حساب Signal محددة.
• channels.signal.configWrites: السماح أو الرفض لعمليات كتابة الإعدادات التي يبدؤها Signal.
• يتجاوز channels.signal.defaultAccount الاختياري اختيار الحساب الافتراضي عندما يطابق معرّف حساب مُهيأ.

​

BlueBubbles

{
  channels: {
    bluebubbles: {
      enabled: true,
      dmPolicy: "pairing",
      // serverUrl, password, webhookPath, group controls, and advanced actions:
      // راجع /channels/bluebubbles
    },
  },
}

• مسارات المفاتيح الأساسية المغطاة هنا: channels.bluebubbles وchannels.bluebubbles.dmPolicy.
• يتجاوز channels.bluebubbles.defaultAccount الاختياري اختيار الحساب الافتراضي عندما يطابق معرّف حساب مُهيأ.
• يمكن لإدخالات bindings[] ذات المستوى الأعلى مع type: "acp" ربط محادثات BlueBubbles بجلسات ACP دائمة. استخدم مقبض BlueBubbles أو سلسلة الهدف (chat_id:* أو chat_guid:* أو chat_identifier:*) في match.peer.id. دلالات الحقول المشتركة: ACP Agents.
• إعداد قناة BlueBubbles الكامل موثق في BlueBubbles.

​

iMessage

{
  channels: {
    imessage: {
      enabled: true,
      cliPath: "imsg",
      dbPath: "~/Library/Messages/chat.db",
      remoteHost: "user@gateway-host",
      dmPolicy: "pairing",
      allowFrom: ["+15555550123", "user@example.com", "chat_id:123"],
      historyLimit: 50,
      includeAttachments: false,
      attachmentRoots: ["/Users/*/Library/Messages/Attachments"],
      remoteAttachmentRoots: ["/Users/*/Library/Messages/Attachments"],
      mediaMaxMb: 16,
      service: "auto",
      region: "US",
    },
  },
}

• يتجاوز channels.imessage.defaultAccount الاختياري اختيار الحساب الافتراضي عندما يطابق معرّف حساب مُهيأ.
• يتطلب Full Disk Access إلى قاعدة بيانات Messages.
• يُفضل استخدام أهداف chat_id:<id>. استخدم imsg chats --limit 20 لسرد الدردشات.
• يمكن أن يشير cliPath إلى غلاف SSH؛ اضبط remoteHost (host أو user@host) لجلب المرفقات عبر SCP.
• يقيّد attachmentRoots وremoteAttachmentRoots مسارات المرفقات الواردة (الافتراضي: /Users/*/Library/Messages/Attachments).
• يستخدم SCP التحقق الصارم من مفتاح المستضيف، لذا تأكد من أن مفتاح مستضيف الترحيل موجود مسبقًا في ~/.ssh/known_hosts.
• channels.imessage.configWrites: السماح أو الرفض لعمليات كتابة الإعدادات التي يبدؤها iMessage.
• يمكن لإدخالات bindings[] ذات المستوى الأعلى مع type: "acp" ربط محادثات iMessage بجلسات ACP دائمة. استخدم مقبضًا مُطبَّعًا أو هدف دردشة صريحًا (chat_id:* أو chat_guid:* أو chat_identifier:*) في match.peer.id. دلالات الحقول المشتركة: ACP Agents.

#!/usr/bin/env bash
exec ssh -T gateway-host imsg "$@"

​

Matrix

{
  channels: {
    matrix: {
      enabled: true,
      homeserver: "https://matrix.example.org",
      accessToken: "syt_bot_xxx",
      proxy: "http://127.0.0.1:7890",
      encryption: true,
      initialSyncLimit: 20,
      defaultAccount: "ops",
      accounts: {
        ops: {
          name: "Ops",
          userId: "@ops:example.org",
          accessToken: "syt_ops_xxx",
        },
        alerts: {
          userId: "@alerts:example.org",
          password: "secret",
          proxy: "http://127.0.0.1:7891",
        },
      },
    },
  },
}

• تستخدم مصادقة الرمز accessToken؛ وتستخدم مصادقة كلمة المرور userId + password.
• يوجّه channels.matrix.proxy حركة HTTP الخاصة بـ Matrix عبر وكيل HTTP(S) صريح. ويمكن للحسابات المسماة تجاوزه باستخدام channels.matrix.accounts.<id>.proxy.
• يسمح channels.matrix.network.dangerouslyAllowPrivateNetwork بخوادم homeserver الخاصة/الداخلية. ويُعد كل من proxy وخيار الشبكة هذا عنصرَي تحكم مستقلين.
• يحدد channels.matrix.defaultAccount الحساب المفضل في إعدادات الحسابات المتعددة.
• تكون القيمة الافتراضية لـ channels.matrix.autoJoin هي off، لذا تُتجاهل الغرف المدعوّة ودعوات الرسائل المباشرة الجديدة حتى تعيّن autoJoin: "allowlist" مع autoJoinAllowlist أو autoJoin: "always".
• channels.matrix.execApprovals: تسليم موافقات exec الأصلية في Matrix وتفويض الموافقين.
  • enabled: القيم true أو false أو "auto" (الافتراضي). في وضع auto، تُفعَّل موافقات exec عندما يمكن حلّ الموافقين من approvers أو commands.ownerAllowFrom.
  • approvers: معرّفات مستخدمي Matrix ‏(مثل @owner:example.org) المسموح لهم بالموافقة على طلبات exec.
  • agentFilter: قائمة سماح اختيارية لمعرّفات الوكلاء. احذفها لتمرير الموافقات لجميع الوكلاء.
  • sessionFilter: أنماط مفاتيح جلسات اختيارية (سلسلة فرعية أو regex).
  • target: مكان إرسال مطالبات الموافقة. "dm" (الافتراضي) أو "channel" (الغرفة الأصلية) أو "both".
  • تجاوزات لكل حساب: channels.matrix.accounts.<id>.execApprovals.
• يتحكم channels.matrix.dm.sessionScope في كيفية تجميع الرسائل المباشرة في Matrix ضمن الجلسات: يشارك per-user (الافتراضي) حسب النظير الموجّه، بينما يعزل per-room كل غرفة رسائل مباشرة على حدة.
• تستخدم مجسات الحالة في Matrix وعمليات بحث الدليل الحية سياسة الوكيل نفسها المستخدمة في حركة التشغيل.
• إعداد Matrix الكامل وقواعد الاستهداف وأمثلة الإعداد موثقة في Matrix.

​

Microsoft Teams

{
  channels: {
    msteams: {
      enabled: true,
      configWrites: true,
      // appId, appPassword, tenantId, webhook, team/channel policies:
      // راجع /channels/msteams
    },
  },
}

• مسارات المفاتيح الأساسية المغطاة هنا: channels.msteams وchannels.msteams.configWrites.
• إعداد Teams الكامل (بيانات الاعتماد وWebhook وسياسة الرسائل المباشرة/المجموعات والتجاوزات لكل فريق/قناة) موثق في Microsoft Teams.

​

IRC

{
  channels: {
    irc: {
      enabled: true,
      dmPolicy: "pairing",
      configWrites: true,
      nickserv: {
        enabled: true,
        service: "NickServ",
        password: "${IRC_NICKSERV_PASSWORD}",
        register: false,
        registerEmail: "bot@example.com",
      },
    },
  },
}

• مسارات المفاتيح الأساسية المغطاة هنا: channels.irc وchannels.irc.dmPolicy وchannels.irc.configWrites وchannels.irc.nickserv.*.
• يتجاوز channels.irc.defaultAccount الاختياري اختيار الحساب الافتراضي عندما يطابق معرّف حساب مُهيأ.
• إعداد قناة IRC الكامل (المستضيف/المنفذ/TLS/القنوات/قوائم السماح/اشتراط الإشارة) موثق في IRC.

​

تعدد الحسابات (كل القنوات)

{
  channels: {
    telegram: {
      accounts: {
        default: {
          name: "Primary bot",
          botToken: "123456:ABC...",
        },
        alerts: {
          name: "Alerts bot",
          botToken: "987654:XYZ...",
        },
      },
    },
  },
}

• يُستخدم default عند حذف accountId (في CLI والتوجيه).
• لا تنطبق الرموز المميزة من البيئة إلا على الحساب default.
• تنطبق إعدادات القناة الأساسية على جميع الحسابات ما لم تُتجاوز لكل حساب.
• استخدم bindings[].match.accountId لتوجيه كل حساب إلى وكيل مختلف.
• إذا أضفت حسابًا غير افتراضي عبر openclaw channels add (أو إعداد القناة) بينما لا تزال تستخدم إعداد قناة أحادي الحساب على المستوى الأعلى، فسيقوم OpenClaw أولًا بترقية قيم الحساب الأحادي على المستوى الأعلى والمحددة بنطاق الحساب إلى خريطة حسابات القناة لكي يستمر الحساب الأصلي في العمل. تنقلها معظم القنوات إلى channels.<channel>.accounts.default؛ ويمكن لـ Matrix بدلًا من ذلك الحفاظ على هدف مسمّى/افتراضي مطابق موجود.
• تظل ارتباطات القناة فقط الحالية (من دون accountId) تطابق الحساب الافتراضي؛ وتبقى الارتباطات المحددة بنطاق الحساب اختيارية.
• يقوم openclaw doctor --fix أيضًا بإصلاح الأشكال المختلطة عبر نقل قيم الحساب الأحادي على المستوى الأعلى والمحددة بنطاق الحساب إلى الحساب المُرقّى المختار لتلك القناة. تستخدم معظم القنوات accounts.default؛ ويمكن لـ Matrix بدلًا من ذلك الحفاظ على هدف مسمّى/افتراضي مطابق موجود.

​

قنوات extension الأخرى

​

اشتراط الإشارة في الدردشة الجماعية

• الإشارات في بيانات التعريف: إشارات @-mention الأصلية للمنصة. تُتجاهل في وضع الدردشة الذاتية في WhatsApp.
• أنماط النص: أنماط regex آمنة في agents.list[].groupChat.mentionPatterns. تُتجاهل الأنماط غير الصالحة والتكرار المتداخل غير الآمن.
• لا يُفرض اشتراط الإشارة إلا عندما يكون الاكتشاف ممكنًا (إشارات أصلية أو نمط واحد على الأقل).

{
  messages: {
    groupChat: { historyLimit: 50 },
  },
  agents: {
    list: [{ id: "main", groupChat: { mentionPatterns: ["@openclaw", "openclaw"] } }],
  },
}

​

حدود سجل الرسائل المباشرة

{
  channels: {
    telegram: {
      dmHistoryLimit: 30,
      dms: {
        "123456789": { historyLimit: 50 },
      },
    },
  },
}

​

وضع الدردشة الذاتية

{
  channels: {
    whatsapp: {
      allowFrom: ["+15555550123"],
      groups: { "*": { requireMention: true } },
    },
  },
  agents: {
    list: [
      {
        id: "main",
        groupChat: { mentionPatterns: ["reisponde", "@openclaw"] },
      },
    ],
  },
}

​

الأوامر (معالجة أوامر الدردشة)

{
  commands: {
    native: "auto", // سجّل الأوامر الأصلية عندما تكون مدعومة
    nativeSkills: "auto", // سجّل أوامر Skills الأصلية عندما تكون مدعومة
    text: true, // حلّل /commands في رسائل الدردشة
    bash: false, // السماح بـ ! (الاسم البديل: /bash)
    bashForegroundMs: 2000,
    config: false, // السماح بـ /config
    mcp: false, // السماح بـ /mcp
    plugins: false, // السماح بـ /plugins
    debug: false, // السماح بـ /debug
    restart: true, // السماح بـ /restart + أداة إعادة تشغيل gateway
    ownerAllowFrom: ["discord:123456789012345678"],
    ownerDisplay: "raw", // raw | hash
    ownerDisplaySecret: "${OWNER_ID_HASH_SECRET}",
    allowFrom: {
      "*": ["user1"],
      discord: ["user:123"],
    },
    useAccessGroups: true,
  },
}

​

الإعدادات الافتراضية للوكلاء

​

agents.defaults.workspace

{
  agents: { defaults: { workspace: "~/.openclaw/workspace" } },
}

​

agents.defaults.repoRoot

{
  agents: { defaults: { repoRoot: "~/Projects/openclaw" } },
}

​

agents.defaults.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.
• تمثل قائمة agents.list[].skills غير الفارغة المجموعة النهائية لذلك الوكيل؛ وهي لا تندمج مع القيم الافتراضية.

​

agents.defaults.skipBootstrap

{
  agents: { defaults: { skipBootstrap: true } },
}

​

agents.defaults.contextInjection

• "continuation-skip": تتجاوز أدوار المتابعة الآمنة (بعد اكتمال استجابة المساعد) إعادة حقن bootstrap الخاص بمساحة العمل، مما يقلل حجم prompt. وتستمر تشغيلات Heartbeat وإعادات المحاولة بعد Compaction في إعادة بناء السياق.

{
  agents: { defaults: { contextInjection: "continuation-skip" } },
}

​

agents.defaults.bootstrapMaxChars

{
  agents: { defaults: { bootstrapMaxChars: 12000 } },
}

​

agents.defaults.bootstrapTotalMaxChars

{
  agents: { defaults: { bootstrapTotalMaxChars: 60000 } },
}

​

agents.defaults.bootstrapPromptTruncationWarning

• "off": لا تحقن نص التحذير مطلقًا في system prompt.
• "once": احقن التحذير مرة واحدة لكل توقيع اقتطاع فريد (موصى به).
• "always": احقن التحذير في كل تشغيل عندما يوجد اقتطاع.

{
  agents: { defaults: { bootstrapPromptTruncationWarning: "once" } }, // off | once | always
}

​

خريطة ملكية ميزانية السياق

• agents.defaults.bootstrapMaxChars / agents.defaults.bootstrapTotalMaxChars: حقن bootstrap العادي لمساحة العمل.
• agents.defaults.startupContext.*: تمهيد بدء التشغيل لمرة واحدة لأوامر /new و/reset، بما في ذلك ملفات memory/*.md اليومية الحديثة.
• skills.limits.*: قائمة Skills المدمجة المحقونة في system prompt.
• agents.defaults.contextLimits.*: مقتطفات التشغيل المحدودة والكتل المملوكة لوقت التشغيل والمحقونة.
• memory.qmd.limits.*: مقتطفات البحث في الذاكرة المفهرسة وتحجيم الحقن.

• agents.list[].skillsLimits.maxSkillsPromptChars
• agents.list[].contextLimits.*

​

agents.defaults.startupContext

{
  agents: {
    defaults: {
      startupContext: {
        enabled: true,
        applyOn: ["new", "reset"],
        dailyMemoryDays: 2,
        maxFileBytes: 16384,
        maxFileChars: 1200,
        maxTotalChars: 2800,
      },
    },
  },
}

​

agents.defaults.contextLimits

{
  agents: {
    defaults: {
      contextLimits: {
        memoryGetMaxChars: 12000,
        memoryGetDefaultLines: 120,
        toolResultMaxChars: 16000,
        postCompactionMaxChars: 1800,
      },
    },
  },
}

• memoryGetMaxChars: الحد الافتراضي لمقتطف memory_get قبل إضافة بيانات وصفية للاقتطاع وإشعار بالمتابعة.
• memoryGetDefaultLines: نافذة الأسطر الافتراضية لـ memory_get عند حذف lines.
• toolResultMaxChars: الحد الأقصى لنتائج الأدوات أثناء التشغيل والمستخدم للنتائج المحفوظة ومعالجة الفائض.
• postCompactionMaxChars: الحد الأقصى لمقتطفات AGENTS.md المستخدمة أثناء حقن التحديث بعد Compaction.

​

agents.list[].contextLimits

{
  agents: {
    defaults: {
      contextLimits: {
        memoryGetMaxChars: 12000,
        toolResultMaxChars: 16000,
      },
    },
    list: [
      {
        id: "tiny-local",
        contextLimits: {
          memoryGetMaxChars: 6000,
          toolResultMaxChars: 8000,
        },
      },
    ],
  },
}

​

skills.limits.maxSkillsPromptChars

{
  skills: {
    limits: {
      maxSkillsPromptChars: 18000,
    },
  },
}

​

agents.list[].skillsLimits.maxSkillsPromptChars

{
  agents: {
    list: [
      {
        id: "tiny-local",
        skillsLimits: {
          maxSkillsPromptChars: 6000,
        },
      },
    ],
  },
}

​

agents.defaults.imageMaxDimensionPx

{
  agents: { defaults: { imageMaxDimensionPx: 1200 } },
}

​

agents.defaults.userTimezone

{
  agents: { defaults: { userTimezone: "America/Chicago" } },
}

​

agents.defaults.timeFormat

{
  agents: { defaults: { timeFormat: "auto" } }, // auto | 12 | 24
}

​

agents.defaults.model

{
  agents: {
    defaults: {
      models: {
        "anthropic/claude-opus-4-6": { alias: "opus" },
        "minimax/MiniMax-M2.7": { alias: "minimax" },
      },
      model: {
        primary: "anthropic/claude-opus-4-6",
        fallbacks: ["minimax/MiniMax-M2.7"],
      },
      imageModel: {
        primary: "openrouter/qwen/qwen-2.5-vl-72b-instruct:free",
        fallbacks: ["openrouter/google/gemini-2.0-flash-vision:free"],
      },
      imageGenerationModel: {
        primary: "openai/gpt-image-1",
        fallbacks: ["google/gemini-3.1-flash-image-preview"],
      },
      videoGenerationModel: {
        primary: "qwen/wan2.6-t2v",
        fallbacks: ["qwen/wan2.6-i2v"],
      },
      pdfModel: {
        primary: "anthropic/claude-opus-4-6",
        fallbacks: ["openai/gpt-5.4-mini"],
      },
      params: { cacheRetention: "long" }, // معاملات المزوّد الافتراضية العامة
      embeddedHarness: {
        runtime: "auto", // auto | pi | registered harness id, e.g. codex
        fallback: "pi", // pi | none
      },
      pdfMaxBytesMb: 10,
      pdfMaxPages: 20,
      thinkingDefault: "low",
      verboseDefault: "off",
      elevatedDefault: "on",
      timeoutSeconds: 600,
      mediaMaxMb: 5,
      contextTokens: 200000,
      maxConcurrent: 3,
    },
  },
}

• model: يقبل إما سلسلة ("provider/model") أو كائنًا ({ primary, fallbacks }).
  • يضبط نموذج السلسلة النموذج الأساسي فقط.
  • يضبط نموذج الكائن النموذج الأساسي بالإضافة إلى نماذج التحويل الاحتياطي المرتبة.
• imageModel: يقبل إما سلسلة ("provider/model") أو كائنًا ({ primary, fallbacks }).
  • يُستخدم في مسار أداة image كإعداد لنموذج الرؤية الخاص بها.
  • ويُستخدم أيضًا كتوجيه احتياطي عندما لا يستطيع النموذج المحدد/الافتراضي قبول مدخلات الصور.
• imageGenerationModel: يقبل إما سلسلة ("provider/model") أو كائنًا ({ primary, fallbacks }).
  • يُستخدم في إمكانية توليد الصور المشتركة وأي سطح أداة/Plugin مستقبلي يولد صورًا.
  • القيم النموذجية: google/gemini-3.1-flash-image-preview لتوليد صور Gemini الأصلي، أو fal/fal-ai/flux/dev لـ fal، أو openai/gpt-image-1 لـ OpenAI Images.
  • إذا اخترت مزودًا/نموذجًا مباشرةً، فاضبط أيضًا مصادقة المزوّد/مفتاح API المطابق (على سبيل المثال GEMINI_API_KEY أو GOOGLE_API_KEY لـ google/*، وOPENAI_API_KEY لـ openai/*، وFAL_KEY لـ fal/*).
  • إذا لم يُعيَّن، يمكن لـ image_generate مع ذلك استنتاج افتراضي مزوّد مدعوم بالمصادقة. إذ يحاول أولًا المزوّد الافتراضي الحالي، ثم بقية مزوّدي توليد الصور المسجلين حسب ترتيب معرّف المزوّد.
• musicGenerationModel: يقبل إما سلسلة ("provider/model") أو كائنًا ({ primary, fallbacks }).
  • يُستخدم في إمكانية توليد الموسيقى المشتركة وفي الأداة المضمنة music_generate.
  • القيم النموذجية: google/lyria-3-clip-preview أو google/lyria-3-pro-preview أو minimax/music-2.5+.
  • إذا لم يُعيَّن، يمكن لـ music_generate مع ذلك استنتاج افتراضي مزوّد مدعوم بالمصادقة. إذ يحاول أولًا المزوّد الافتراضي الحالي، ثم بقية مزوّدي توليد الموسيقى المسجلين حسب ترتيب معرّف المزوّد.
  • إذا اخترت مزودًا/نموذجًا مباشرةً، فاضبط أيضًا مصادقة المزوّد/مفتاح API المطابق.
• videoGenerationModel: يقبل إما سلسلة ("provider/model") أو كائنًا ({ primary, fallbacks }).
  • يُستخدم في إمكانية توليد الفيديو المشتركة وفي الأداة المضمنة video_generate.
  • القيم النموذجية: qwen/wan2.6-t2v أو qwen/wan2.6-i2v أو qwen/wan2.6-r2v أو qwen/wan2.6-r2v-flash أو qwen/wan2.7-r2v.
  • إذا لم يُعيَّن، يمكن لـ video_generate مع ذلك استنتاج افتراضي مزوّد مدعوم بالمصادقة. إذ يحاول أولًا المزوّد الافتراضي الحالي، ثم بقية مزوّدي توليد الفيديو المسجلين حسب ترتيب معرّف المزوّد.
  • إذا اخترت مزودًا/نموذجًا مباشرةً، فاضبط أيضًا مصادقة المزوّد/مفتاح API المطابق.
  • يدعم مزود توليد الفيديو المضمّن Qwen ما يصل إلى فيديو مخرج واحد، وصورة إدخال واحدة، و4 فيديوهات إدخال، ومدة 10 ثوانٍ، وخيارات على مستوى المزوّد مثل size وaspectRatio وresolution وaudio وwatermark.
• pdfModel: يقبل إما سلسلة ("provider/model") أو كائنًا ({ primary, fallbacks }).
  • يُستخدم بواسطة أداة pdf لتوجيه النموذج.
  • إذا لم يُعيَّن، تعود أداة PDF إلى imageModel، ثم إلى النموذج المحلول للجلسة/الافتراضي.
• pdfMaxBytesMb: حد حجم PDF الافتراضي لأداة pdf عندما لا يُمرَّر maxBytesMb وقت الاستدعاء.
• pdfMaxPages: الحد الأقصى الافتراضي للصفحات التي ينظر فيها وضع الاستخراج الاحتياطي في أداة pdf.
• verboseDefault: مستوى verbose الافتراضي للوكلاء. القيم: "off" و"on" و"full". الافتراضي: "off".
• elevatedDefault: مستوى المخرجات المرتفعة الافتراضي للوكلاء. القيم: "off" و"on" و"ask" و"full". الافتراضي: "on".
• model.primary: التنسيق provider/model (مثل openai/gpt-5.4). إذا حذفت المزوّد، يحاول OpenClaw أولًا اسمًا مستعارًا، ثم تطابقًا فريدًا لمزوّد مهيأ لذلك المعرّف الدقيق للنموذج، وبعدها فقط يعود إلى المزوّد الافتراضي المهيأ (سلوك توافق قديم ومهجور، لذا يُفضّل استخدام provider/model الصريح). وإذا لم يعد ذلك المزوّد يوفّر النموذج الافتراضي المهيأ، يعود OpenClaw إلى أول مزوّد/نموذج مهيأ بدلًا من إظهار افتراضي قديم لمزوّد تمت إزالته.
• models: فهرس النماذج المهيأ وقائمة السماح الخاصة بـ /model. يمكن أن يتضمن كل إدخال alias (اختصارًا) وparams (خاصة بالمزوّد، مثل temperature وmaxTokens وcacheRetention وcontext1m).
• params: معاملات المزوّد الافتراضية العامة المطبقة على جميع النماذج. تُضبط في agents.defaults.params (مثل { cacheRetention: "long" }).
• أولوية دمج params (في الإعدادات): يتم تجاوز agents.defaults.params (الأساس العام) بواسطة agents.defaults.models["provider/model"].params (لكل نموذج)، ثم يتجاوز agents.list[].params (لمعرّف الوكيل المطابق) بالمفتاح. راجع Prompt Caching للتفاصيل.
• embeddedHarness: سياسة وقت التشغيل المضمن منخفضة المستوى الافتراضية للوكيل. استخدم runtime: "auto" للسماح لـ harnesses الخاصة بـ Plugin المسجلة بادعاء النماذج المدعومة، أو runtime: "pi" لفرض harness المضمن PI، أو معرّف harness مسجل مثل runtime: "codex". عيّن fallback: "none" لتعطيل الرجوع التلقائي إلى PI.
• تقوم كاتبات الإعدادات التي تعدّل هذه الحقول (مثل /models set و/models set-image وأوامر إضافة/إزالة الاحتياطي) بحفظ صيغة الكائن القانونية مع الحفاظ على قوائم fallback الموجودة متى أمكن.
• maxConcurrent: الحد الأقصى لتشغيلات الوكلاء المتوازية عبر الجلسات (مع بقاء كل جلسة متسلسلة داخليًا). الافتراضي: 4.

​

agents.defaults.embeddedHarness

{
  agents: {
    defaults: {
      model: "codex/gpt-5.4",
      embeddedHarness: {
        runtime: "codex",
        fallback: "none",
      },
    },
  },
}

• runtime: القيم "auto" أو "pi" أو معرّف harness مسجل لأحد Plugin. يسجل Plugin Codex المضمّن المعرف codex.
• fallback: القيم "pi" أو "none". تبقي "pi" harness PI المضمن كاحتياطي توافق. وتؤدي "none" إلى فشل اختيار harness الخاص بـ Plugin عندما يكون مفقودًا أو غير مدعوم بدلًا من استخدام PI بصمت.
• تجاوزات البيئة: يتجاوز OPENCLAW_AGENT_RUNTIME=<id|auto|pi> القيمة runtime؛ ويعطّل OPENCLAW_AGENT_HARNESS_FALLBACK=none الرجوع إلى PI لتلك العملية.
• لعمليات النشر الخاصة بـ Codex فقط، اضبط model: "codex/gpt-5.4" وembeddedHarness.runtime: "codex" وembeddedHarness.fallback: "none".
• يتحكم هذا فقط في harness الدردشة المضمن. أما توليد الوسائط والرؤية وPDF والموسيقى والفيديو وTTS فما زالت تستخدم إعدادات المزوّد/النموذج الخاصة بها.

​

agents.defaults.cliBackends

{
  agents: {
    defaults: {
      cliBackends: {
        "codex-cli": {
          command: "/opt/homebrew/bin/codex",
        },
        "my-cli": {
          command: "my-cli",
          args: ["--json"],
          output: "json",
          modelArg: "--model",
          sessionArg: "--session",
          sessionMode: "existing",
          systemPromptArg: "--system",
          systemPromptWhen: "first",
          imageArg: "--image",
          imageMode: "repeat",
        },
      },
    },
  },
}

• الواجهات الخلفية CLI موجهة للنص أولًا؛ وتكون الأدوات معطلة دائمًا.
• تُدعَم الجلسات عندما يكون sessionArg معيّنًا.
• يُدعَم تمرير الصور عندما يقبل imageArg مسارات الملفات.

​

agents.defaults.systemPromptOverride

{
  agents: {
    defaults: {
      systemPromptOverride: "You are a helpful assistant.",
    },
  },
}

​

agents.defaults.heartbeat

{
  agents: {
    defaults: {
      heartbeat: {
        every: "30m", // 0m للتعطيل
        model: "openai/gpt-5.4-mini",
        includeReasoning: false,
        includeSystemPromptSection: true, // الافتراضي: true؛ false يحذف قسم Heartbeat من system prompt
        lightContext: false, // الافتراضي: false؛ true يُبقي فقط HEARTBEAT.md من ملفات bootstrap الخاصة بمساحة العمل
        isolatedSession: false, // الافتراضي: false؛ true يشغّل كل Heartbeat في جلسة جديدة (بلا سجل محادثة)
        session: "main",
        to: "+15555550123",
        directPolicy: "allow", // allow (الافتراضي) | block
        target: "none", // الافتراضي: none | الخيارات: last | whatsapp | telegram | discord | ...
        prompt: "Read HEARTBEAT.md if it exists...",
        ackMaxChars: 300,
        suppressToolErrorWarnings: false,
        timeoutSeconds: 45,
      },
    },
  },
}

• every: سلسلة مدة (ms/s/m/h). الافتراضي: 30m (مصادقة مفتاح API) أو 1h (مصادقة OAuth). عيّنها إلى 0m للتعطيل.
• includeSystemPromptSection: عند تعيينها إلى false، تُحذف فقرة Heartbeat من system prompt ويُتخطى حقن HEARTBEAT.md في سياق bootstrap. الافتراضي: true.
• suppressToolErrorWarnings: عند تعيينه إلى true، ي suppress حمولة تحذيرات أخطاء الأدوات أثناء تشغيلات Heartbeat.
• timeoutSeconds: الحد الأقصى بالثواني المسموح به لدور وكيل Heartbeat قبل إيقافه. اتركه غير معيّن لاستخدام agents.defaults.timeoutSeconds.
• directPolicy: سياسة التسليم المباشر/للرسائل المباشرة. تسمح allow (الافتراضي) بالتسليم المباشر إلى الهدف. وتؤدي block إلى منع التسليم المباشر إلى الهدف وإخراج reason=dm-blocked.
• lightContext: عند تعيينه إلى true، تستخدم تشغيلات Heartbeat سياق bootstrap خفيفًا وتُبقي فقط HEARTBEAT.md من ملفات bootstrap الخاصة بمساحة العمل.
• isolatedSession: عند تعيينه إلى true، تعمل كل Heartbeat في جلسة جديدة من دون أي سجل محادثة سابق. وهو نفس نمط العزل في Cron مع sessionTarget: "isolated". ويقلل تكلفة الرموز لكل Heartbeat من نحو ~100K إلى ~2-5K رمز.
• لكل وكيل: اضبط agents.list[].heartbeat. وعندما يعرّف أي وكيل heartbeat، تعمل هؤلاء الوكلاء فقط على تشغيل Heartbeat.
• تشغّل Heartbeat أدوار وكلاء كاملة — والفواصل الأقصر تستهلك مزيدًا من الرموز.

​

agents.defaults.compaction

{
  agents: {
    defaults: {
      compaction: {
        mode: "safeguard", // default | safeguard
        provider: "my-provider", // معرّف Plugin مزوّد Compaction مسجل (اختياري)
        timeoutSeconds: 900,
        reserveTokensFloor: 24000,
        identifierPolicy: "strict", // strict | off | custom
        identifierInstructions: "Preserve deployment IDs, ticket IDs, and host:port pairs exactly.", // يُستخدم عندما يكون identifierPolicy=custom
        postCompactionSections: ["Session Startup", "Red Lines"], // تؤدي [] إلى تعطيل إعادة الحقن
        model: "openrouter/anthropic/claude-sonnet-4-6", // تجاوز اختياري للنموذج خاص بـ Compaction فقط
        notifyUser: true, // أرسل إشعارًا موجزًا عند بدء Compaction (الافتراضي: false)
        memoryFlush: {
          enabled: true,
          softThresholdTokens: 6000,
          systemPrompt: "Session nearing compaction. Store durable memories now.",
          prompt: "Write any lasting notes to memory/YYYY-MM-DD.md; reply with the exact silent token NO_REPLY if nothing to store.",
        },
      },
    },
  },
}

• mode: ‏default أو safeguard (تلخيص مجزأ للسجلات الطويلة). راجع Compaction.
• provider: معرّف Plugin مزوّد Compaction مسجل. عند تعيينه، يُستدعى summarize() الخاص بالمزوّد بدلًا من التلخيص المضمن في LLM. ويعود إلى المضمن عند الفشل. ويؤدي تعيين مزوّد إلى فرض mode: "safeguard". راجع Compaction.
• timeoutSeconds: الحد الأقصى بالثواني المسموح به لعملية Compaction واحدة قبل أن يقوم OpenClaw بإيقافها. الافتراضي: 900.
• identifierPolicy: ‏strict (الافتراضي) أو off أو custom. تضيف strict تلقائيًا إرشادات مضمنة للحفاظ على المعرّفات المعتمة أثناء تلخيص Compaction.
• identifierInstructions: نص اختياري مخصص للحفاظ على المعرّفات يُستخدم عندما يكون identifierPolicy=custom.
• postCompactionSections: أسماء أقسام H2/H3 اختيارية من AGENTS.md لإعادة حقنها بعد Compaction. القيمة الافتراضية ["Session Startup", "Red Lines"]؛ عيّن [] لتعطيل إعادة الحقن. وعندما لا تكون معيّنة أو تكون معيّنة صراحةً إلى هذا الزوج الافتراضي، تُقبل أيضًا العناوين الأقدم Every Session/Safety كقيمة احتياطية قديمة.
• model: تجاوز اختياري provider/model-id لتلخيص Compaction فقط. استخدم هذا عندما يجب أن تبقي الجلسة الرئيسية نموذجًا معينًا بينما تعمل ملخصات Compaction على نموذج آخر؛ وعند عدم تعيينه، يستخدم Compaction النموذج الأساسي للجلسة.
• notifyUser: عند تعيينه إلى true، يرسل إشعارًا موجزًا إلى المستخدم عند بدء Compaction (على سبيل المثال: “Compacting context…”). وهو معطّل افتراضيًا لإبقاء Compaction صامتًا.
• memoryFlush: دور وكيلي صامت قبل Compaction التلقائي لتخزين الذكريات الدائمة. ويُتخطى عندما تكون مساحة العمل للقراءة فقط.

​

agents.defaults.contextPruning

{
  agents: {
    defaults: {
      contextPruning: {
        mode: "cache-ttl", // off | cache-ttl
        ttl: "1h", // مدة (ms/s/m/h)، وحدة القياس الافتراضية: الدقائق
        keepLastAssistants: 3,
        softTrimRatio: 0.3,
        hardClearRatio: 0.5,
        minPrunableToolChars: 50000,
        softTrim: { maxChars: 4000, headChars: 1500, tailChars: 1500 },
        hardClear: { enabled: true, placeholder: "[Old tool result content cleared]" },
        tools: { deny: ["browser", "canvas"] },
      },
    },
  },
}

​

البث على شكل كتل

{
  agents: {
    defaults: {
      blockStreamingDefault: "off", // on | off
      blockStreamingBreak: "text_end", // text_end | message_end
      blockStreamingChunk: { minChars: 800, maxChars: 1200 },
      blockStreamingCoalesce: { idleMs: 1000 },
      humanDelay: { mode: "natural" }, // off | natural | custom (استخدم minMs/maxMs)
    },
  },
}

• تتطلب القنوات غير Telegram تعيين *.blockStreaming: true صراحةً لتفعيل الردود على شكل كتل.
• تجاوزات القنوات: channels.<channel>.blockStreamingCoalesce (ومتغيرات كل حساب). تستخدم Signal/Slack/Discord/Google Chat افتراضيًا minChars: 1500.
• humanDelay: توقف عشوائي بين الردود على شكل كتل. تعني natural = ‏800–2500ms. تجاوز لكل وكيل: agents.list[].humanDelay.

​

مؤشرات الكتابة

{
  agents: {
    defaults: {
      typingMode: "instant", // never | instant | thinking | message
      typingIntervalSeconds: 6,
    },
  },
}

• القيم الافتراضية: instant للدردشات المباشرة/الإشارات، وmessage للدردشات الجماعية غير المشار فيها.
• تجاوزات لكل جلسة: session.typingMode وsession.typingIntervalSeconds.

​

agents.defaults.sandbox

{
  agents: {
    defaults: {
      sandbox: {
        mode: "non-main", // off | non-main | all
        backend: "docker", // docker | ssh | openshell
        scope: "agent", // session | agent | shared
        workspaceAccess: "none", // none | ro | rw
        workspaceRoot: "~/.openclaw/sandboxes",
        docker: {
          image: "openclaw-sandbox:bookworm-slim",
          containerPrefix: "openclaw-sbx-",
          workdir: "/workspace",
          readOnlyRoot: true,
          tmpfs: ["/tmp", "/var/tmp", "/run"],
          network: "none",
          user: "1000:1000",
          capDrop: ["ALL"],
          env: { LANG: "C.UTF-8" },
          setupCommand: "apt-get update && apt-get install -y git curl jq",
          pidsLimit: 256,
          memory: "1g",
          memorySwap: "2g",
          cpus: 1,
          ulimits: {
            nofile: { soft: 1024, hard: 2048 },
            nproc: 256,
          },
          seccompProfile: "/path/to/seccomp.json",
          apparmorProfile: "openclaw-sandbox",
          dns: ["1.1.1.1", "8.8.8.8"],
          extraHosts: ["internal.service:10.0.0.5"],
          binds: ["/home/user/source:/source:rw"],
        },
        ssh: {
          target: "user@gateway-host:22",
          command: "ssh",
          workspaceRoot: "/tmp/openclaw-sandboxes",
          strictHostKeyChecking: true,
          updateHostKeys: true,
          identityFile: "~/.ssh/id_ed25519",
          certificateFile: "~/.ssh/id_ed25519-cert.pub",
          knownHostsFile: "~/.ssh/known_hosts",
          // كما أن SecretRefs / المحتويات المضمنة مدعومة أيضًا:
          // identityData: { source: "env", provider: "default", id: "SSH_IDENTITY" },
          // certificateData: { source: "env", provider: "default", id: "SSH_CERTIFICATE" },
          // knownHostsData: { source: "env", provider: "default", id: "SSH_KNOWN_HOSTS" },
        },
        browser: {
          enabled: false,
          image: "openclaw-sandbox-browser:bookworm-slim",
          network: "openclaw-sandbox-browser",
          cdpPort: 9222,
          cdpSourceRange: "172.21.0.1/32",
          vncPort: 5900,
          noVncPort: 6080,
          headless: false,
          enableNoVnc: true,
          allowHostControl: false,
          autoStart: true,
          autoStartTimeoutMs: 12000,
        },
        prune: {
          idleHours: 24,
          maxAgeDays: 7,
        },
      },
    },
  },
  tools: {
    sandbox: {
      tools: {
        allow: [
          "exec",
          "process",
          "read",
          "write",
          "edit",
          "apply_patch",
          "sessions_list",
          "sessions_history",
          "sessions_send",
          "sessions_spawn",
          "session_status",
        ],
        deny: ["browser", "canvas", "nodes", "cron", "discord", "gateway"],
      },
    },
  },
}

{
  plugins: {
    entries: {
      openshell: {
        enabled: true,
        config: {
          mode: "mirror", // mirror | remote
          from: "openclaw",
          remoteWorkspaceDir: "/sandbox",
          remoteAgentWorkspaceDir: "/agent",
          gateway: "lab", // اختياري
          gatewayEndpoint: "https://lab.example", // اختياري
          policy: "strict", // معرّف سياسة OpenShell اختياري
          providers: ["openai"], // اختياري
          autoProviders: true,
          timeoutSeconds: 120,
        },
      },
    },
  },
}

scripts/sandbox-setup.sh           # صورة sandbox الرئيسية
scripts/sandbox-browser-setup.sh   # صورة المتصفح الاختيارية

​

agents.list (تجاوزات لكل وكيل)

{
  agents: {
    list: [
      {
        id: "main",
        default: true,
        name: "Main Agent",
        workspace: "~/.openclaw/workspace",
        agentDir: "~/.openclaw/agents/main/agent",
        model: "anthropic/claude-opus-4-6", // أو { primary, fallbacks }
        thinkingDefault: "high", // تجاوز مستوى التفكير الافتراضي لكل وكيل
        reasoningDefault: "on", // تجاوز إظهار الاستدلال الافتراضي لكل وكيل
        fastModeDefault: false, // تجاوز الوضع السريع الافتراضي لكل وكيل
        embeddedHarness: { runtime: "auto", fallback: "pi" },
        params: { cacheRetention: "none" }, // يتجاوز قيم defaults.models.params المطابقة حسب المفتاح
        skills: ["docs-search"], // يستبدل agents.defaults.skills عند التعيين
        identity: {
          name: "Samantha",
          theme: "helpful sloth",
          emoji: "🦥",
          avatar: "avatars/samantha.png",
        },
        groupChat: { mentionPatterns: ["@openclaw"] },
        sandbox: { mode: "off" },
        runtime: {
          type: "acp",
          acp: {
            agent: "codex",
            backend: "acpx",
            mode: "persistent",
            cwd: "/workspace/openclaw",
          },
        },
        subagents: { allowAgents: ["*"] },
        tools: {
          profile: "coding",
          allow: ["browser"],
          deny: ["canvas"],
          elevated: { enabled: true },
        },
      },
    ],
  },
}

• id: معرّف وكيل ثابت (مطلوب).
• default: عند تعيين عدة قيم، يفوز الأول (مع تسجيل تحذير). وإذا لم تُعيَّن أي قيمة، يكون أول إدخال في القائمة هو الافتراضي.
• model: يتجاوز نموذج السلسلة القيمة primary فقط؛ أما نموذج الكائن { primary, fallbacks } فيتجاوز كليهما ([] يعطّل القيم الاحتياطية العامة). وتظل مهام Cron التي تتجاوز primary فقط ترث القيم الاحتياطية الافتراضية ما لم تعيّن fallbacks: [].
• params: معاملات البث لكل وكيل، وتُدمج فوق إدخال النموذج المحدد في agents.defaults.models. استخدم هذا لتجاوزات خاصة بالوكيل مثل cacheRetention أو temperature أو maxTokens من دون تكرار فهرس النماذج بالكامل.
• skills: قائمة سماح اختيارية لـ Skills لكل وكيل. إذا حُذفت، يرث الوكيل agents.defaults.skills عند تعيينها؛ وتستبدل القائمة الصريحة القيم الافتراضية بدلًا من دمجها، وتعني [] عدم وجود Skills.
• thinkingDefault: مستوى التفكير الافتراضي الاختياري لكل وكيل (off | minimal | low | medium | high | xhigh | adaptive). ويتجاوز agents.defaults.thinkingDefault لهذا الوكيل عندما لا يكون هناك تجاوز لكل رسالة أو جلسة.
• reasoningDefault: إظهار الاستدلال الافتراضي الاختياري لكل وكيل (on | off | stream). ويُطبَّق عندما لا يكون هناك تجاوز للاستدلال لكل رسالة أو جلسة.
• fastModeDefault: القيمة الافتراضية الاختيارية لكل وكيل للوضع السريع (true | false). وتُطبَّق عندما لا يكون هناك تجاوز للوضع السريع لكل رسالة أو جلسة.
• embeddedHarness: تجاوز اختياري لسياسة harness منخفضة المستوى لكل وكيل. استخدم { runtime: "codex", fallback: "none" } لجعل أحد الوكلاء يعمل بـ Codex فقط بينما يحتفظ الآخرون بالقيمة الاحتياطية الافتراضية PI.
• runtime: واصف وقت تشغيل اختياري لكل وكيل. استخدم type: "acp" مع القيم الافتراضية runtime.acp ‏(agent وbackend وmode وcwd) عندما يجب أن يستخدم الوكيل افتراضيًا جلسات ACP harness.
• identity.avatar: مسار نسبي إلى مساحة العمل، أو عنوان URL من نوع http(s)، أو معرّف URI من نوع data:.
• تستمد identity القيم الافتراضية: ackReaction من emoji، وmentionPatterns من name/emoji.
• subagents.allowAgents: قائمة سماح لمعرّفات الوكلاء لـ sessions_spawn ‏(["*"] = أي وكيل؛ الافتراضي: الوكيل نفسه فقط).
• حماية وراثة sandbox: إذا كانت جلسة الطالب داخل sandbox، فإن sessions_spawn يرفض الأهداف التي ستعمل خارج sandbox.
• subagents.requireAgentId: عند تعيينه إلى true، يحظر استدعاءات sessions_spawn التي تحذف agentId (يفرض اختيار ملف تعريف صريح؛ الافتراضي: false).

​

توجيه الوكلاء المتعددين

{
  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" } },
  ],
}

​

حقول المطابقة في Binding

• type (اختياري): route للتوجيه العادي (وعند غياب النوع تكون القيمة الافتراضية route)، وacp لارتباطات المحادثات الدائمة الخاصة بـ ACP.
• match.channel (مطلوب)
• match.accountId (اختياري؛ * = أي حساب؛ والحذف = الحساب الافتراضي)
• match.peer (اختياري؛ { kind: direct|group|channel, id })
• match.guildId / match.teamId (اختياري؛ خاص بالقناة)
• acp (اختياري؛ فقط لإدخالات type: "acp"): ‏{ mode, label, cwd, backend }

1. match.peer
2. match.guildId
3. match.teamId
4. match.accountId (مطابقة تامة، بلا peer/guild/team)
5. match.accountId: "*" (على مستوى القناة)
6. الوكيل الافتراضي

​

ملفات الوصول لكل وكيل

{
  agents: {
    list: [
      {
        id: "personal",
        workspace: "~/.openclaw/workspace-personal",
        sandbox: { mode: "off" },
      },
    ],
  },
}

{
  agents: {
    list: [
      {
        id: "family",
        workspace: "~/.openclaw/workspace-family",
        sandbox: { mode: "all", scope: "agent", workspaceAccess: "ro" },
        tools: {
          allow: [
            "read",
            "sessions_list",
            "sessions_history",
            "sessions_send",
            "sessions_spawn",
            "session_status",
          ],
          deny: ["write", "edit", "apply_patch", "exec", "process", "browser"],
        },
      },
    ],
  },
}

{
  agents: {
    list: [
      {
        id: "public",
        workspace: "~/.openclaw/workspace-public",
        sandbox: { mode: "all", scope: "agent", workspaceAccess: "none" },
        tools: {
          allow: [
            "sessions_list",
            "sessions_history",
            "sessions_send",
            "sessions_spawn",
            "session_status",
            "whatsapp",
            "telegram",
            "slack",
            "discord",
            "gateway",
          ],
          deny: [
            "read",
            "write",
            "edit",
            "apply_patch",
            "exec",
            "process",
            "browser",
            "canvas",
            "nodes",
            "cron",
            "gateway",
            "image",
          ],
        },
      },
    ],
  },
}

​

الجلسة

{
  session: {
    scope: "per-sender",
    dmScope: "main", // main | per-peer | per-channel-peer | per-account-channel-peer
    identityLinks: {
      alice: ["telegram:123456789", "discord:987654321012345678"],
    },
    reset: {
      mode: "daily", // daily | idle
      atHour: 4,
      idleMinutes: 60,
    },
    resetByType: {
      thread: { mode: "daily", atHour: 4 },
      direct: { mode: "idle", idleMinutes: 240 },
      group: { mode: "idle", idleMinutes: 120 },
    },
    resetTriggers: ["/new", "/reset"],
    store: "~/.openclaw/agents/{agentId}/sessions/sessions.json",
    parentForkMaxTokens: 100000, // تخطَّ fork السلسلة الأم فوق هذا العدد من الرموز (0 للتعطيل)
    maintenance: {
      mode: "warn", // warn | enforce
      pruneAfter: "30d",
      maxEntries: 500,
      rotateBytes: "10mb",
      resetArchiveRetention: "30d", // مدة أو false
      maxDiskBytes: "500mb", // ميزانية قصوى صلبة اختيارية
      highWaterBytes: "400mb", // هدف تنظيف اختياري
    },
    threadBindings: {
      enabled: true,
      idleHours: 24, // القيمة الافتراضية لإلغاء التركيز التلقائي بعد عدم النشاط، بالساعات (`0` للتعطيل)
      maxAgeHours: 0, // القيمة الافتراضية للحد الأقصى الصارم للعمر، بالساعات (`0` للتعطيل)
    },
    mainKey: "main", // قديم (يستخدم وقت التشغيل دائمًا "main")
    agentToAgent: { maxPingPongTurns: 5 },
    sendPolicy: {
      rules: [{ action: "deny", match: { channel: "discord", chatType: "group" } }],
      default: "allow",
    },
  },
}