التكوين — الوكلاء

​

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

​

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 الخاص بمساحة العمل، مما يقلل حجم المطالبة. أما تشغيلات 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": لا يحقن نص تحذير في مطالبة النظام مطلقًا.
• "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 المضغوطة المحقونة في مطالبة النظام.
• 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-2",
        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-2 لـ OpenAI Images.
  • إذا اخترت مزودًا/نموذجًا مباشرةً، فاضبط أيضًا مصادقة المزوّد المطابقة (على سبيل المثال GEMINI_API_KEY أو GOOGLE_API_KEY لـ google/*، أو OPENAI_API_KEY أو OpenAI Codex OAuth لـ openai/gpt-image-2، أو 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 ما يصل إلى 1 فيديو ناتج، و1 صورة إدخال، و4 فيديوهات إدخال، ومدة 10 ثوانٍ، وخيارات على مستوى المزوّد هي size وaspectRatio وresolution وaudio وwatermark.
• pdfModel: يقبل إما سلسلة ("provider/model") أو كائنًا ({ primary, fallbacks }).
  • يُستخدم بواسطة أداة pdf لتوجيه النموذج.
  • إذا تم حذفه، تعود أداة PDF إلى imageModel، ثم إلى نموذج الجلسة/النموذج الافتراضي المحلَّل.
• pdfMaxBytesMb: الحد الافتراضي لحجم PDF لأداة pdf عندما لا يتم تمرير maxBytesMb وقت الاستدعاء.
• pdfMaxPages: الحد الأقصى الافتراضي للصفحات التي تؤخذ في الاعتبار بواسطة وضع الاستخراج الاحتياطي في أداة pdf.
• verboseDefault: المستوى الافتراضي للإسهاب للوكلاء. القيم: "off" أو "on" أو "full". الافتراضي: "off".
• elevatedDefault: المستوى الافتراضي للمخرجات المرتفعة الصلاحية للوكلاء. القيم: "off" أو "on" أو "ask" أو "full". الافتراضي: "on".
• model.primary: الصيغة provider/model (مثل openai/gpt-5.4 للوصول عبر مفتاح API أو openai-codex/gpt-5.5 لـ Codex OAuth). إذا حذفت المزوّد، يحاول OpenClaw أولًا اسمًا مستعارًا، ثم مطابقة فريدة لمزوّد مكوّن لذلك المعرّف الدقيق للنموذج، وبعدها فقط يعود إلى المزوّد الافتراضي المكوّن (سلوك توافق قديم، لذا يفضَّل استخدام provider/model الصريح). وإذا لم يعد ذلك المزوّد يوفّر النموذج الافتراضي المكوّن، يعود OpenClaw إلى أول مزوّد/نموذج مكوّن بدلًا من إظهار افتراضي قديم لمزوّد تمت إزالته.
• models: فهرس النماذج المكوّن وقائمة السماح لـ /model. يمكن أن تتضمن كل قيمة alias (اختصار) وparams (خاصة بالمزوّد، مثل temperature وmaxTokens وcacheRetention وcontext1m وresponsesServerCompaction وresponsesCompactThreshold).
  • تعديلات آمنة: استخدم openclaw config set agents.defaults.models '<json>' --strict-json --merge لإضافة إدخالات. يرفض config set الاستبدالات التي قد تزيل إدخالات موجودة من قائمة السماح ما لم تمرر --replace.
  • تقوم تدفقات configure/onboarding ذات النطاق الخاص بالمزوّد بدمج نماذج المزوّد المحددة في هذه الخريطة وتحافظ على المزوّدين الآخرين المكوّنين وغير المرتبطين.
  • بالنسبة إلى نماذج OpenAI Responses المباشرة، يتم تفعيل Compaction على جانب الخادم تلقائيًا. استخدم params.responsesServerCompaction: false لإيقاف حقن context_management، أو params.responsesCompactThreshold لتجاوز العتبة. راجع Compaction على جانب خادم OpenAI.
• params: معلمات المزوّد الافتراضية العامة المطبقة على جميع النماذج. تُضبط في agents.defaults.params (مثل { cacheRetention: "long" }).
• أسبقية دمج params (في التكوين): يتم تجاوز agents.defaults.params (الأساس العام) بواسطة agents.defaults.models["provider/model"].params (لكل نموذج)، ثم يتجاوز agents.list[].params (للـ agent id المطابق) حسب المفتاح. راجع التخزين المؤقت للمطالبة للتفاصيل.
• embeddedHarness: سياسة وقت تشغيل الوكيل المضمّن منخفضة المستوى الافتراضية. استخدم runtime: "auto" للسماح لحزم Plugin المسجلة بادعاء النماذج المدعومة، أو runtime: "pi" لفرض harness المدمج PI، أو معرّف harness مسجل مثل runtime: "codex". اضبط fallback: "none" لتعطيل الاحتياط التلقائي إلى PI.
• تقوم كاتبات التكوين التي تعدّل هذه الحقول (على سبيل المثال /models set و/models set-image وأوامر إضافة/إزالة الاحتياط) بحفظ الصيغة القياسية للكائن والحفاظ على قوائم الاحتياط الموجودة عندما يكون ذلك ممكنًا.
• maxConcurrent: الحد الأقصى لتشغيلات الوكيل المتوازية عبر الجلسات (مع بقاء كل جلسة مُسلسلة). الافتراضي: 4.

​

agents.defaults.embeddedHarness

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

• runtime: "auto" أو "pi" أو معرّف Plugin harness مسجل. يسجل Plugin ‏Codex المضمّن المعرف codex.
• fallback: "pi" أو "none". تبقي "pi" على harness المدمج PI كاحتياط للتوافق عندما لا يتم اختيار أي Plugin harness. أما "none" فيجعل اختيار Plugin harness المفقود أو غير المدعوم يفشل بدلًا من استخدام PI بصمت. وتظهر دائمًا إخفاقات Plugin harness المحدد مباشرة.
• تجاوزات البيئة: يتجاوز OPENCLAW_AGENT_RUNTIME=<id|auto|pi> القيمة runtime؛ ويعطّل OPENCLAW_AGENT_HARNESS_FALLBACK=none الاحتياط إلى PI لتلك العملية.
• بالنسبة إلى عمليات النشر المعتمدة على Codex فقط، اضبط model: "openai/gpt-5.5" وembeddedHarness.runtime: "codex" وembeddedHarness.fallback: "none".
• يتم تثبيت اختيار harness لكل معرّف جلسة بعد أول تشغيل مضمّن. تؤثر تغييرات التكوين/البيئة في الجلسات الجديدة أو المعاد تعيينها، وليس في نص موجود. وتُعامل الجلسات القديمة ذات سجل النصوص ولكن من دون تثبيت مسجل على أنها مثبّتة على PI. يعرض /status معرّفات harness غير التابعة لـ PI مثل codex بجوار Fast.
• يتحكم هذا فقط في chat 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.promptOverlays

{
  agents: {
    defaults: {
      promptOverlays: {
        gpt5: {
          personality: "friendly", // friendly | on | off
        },
      },
    },
  },
}

• يفعّل "friendly" (الافتراضي) و"on" طبقة أسلوب التفاعل الودي.
• يعطّل "off" الطبقة الودية فقط؛ بينما يبقى عقد السلوك الموسوم لـ GPT-5 مفعّلًا.
• لا يزال يتم قراءة plugins.entries.openai.config.personality القديم عندما لا يكون هذا الإعداد المشترك مضبوطًا.

​

agents.defaults.heartbeat

{
  agents: {
    defaults: {
      heartbeat: {
        every: "30m", // 0m يعطّل
        model: "openai/gpt-5.4-mini",
        includeReasoning: false,
        includeSystemPromptSection: true, // الافتراضي: true؛ وfalse يحذف قسم Heartbeat من مطالبة النظام
        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 من مطالبة النظام ويتخطى حقن HEARTBEAT.md في سياق bootstrap. الافتراضي: true.
• suppressToolErrorWarnings: عندما تكون true، يمنع حمولات تحذير أخطاء الأدوات أثناء تشغيلات 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، تشغّل Heartbeats لهؤلاء الوكلاء فقط.
• تعمل Heartbeats على أدوار وكيل كاملة — والفواصل الأقصر تستهلك مزيدًا من الرموز المميزة.

​

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 complete”). ويكون معطّلًا افتراضيًا لإبقاء 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"] },
      },
    },
  },
}

​

Block streaming

{
  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", // تجاوز مستوى إظهار reasoning لكل وكيل
        fastModeDefault: false, // تجاوز fast mode لكل وكيل
        embeddedHarness: { runtime: "auto", fallback: "pi" },
        params: { cacheRetention: "none" }, // يتجاوز params الخاصة بـ defaults.models المطابقة حسب المفتاح
        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 | max). ويتجاوز agents.defaults.thinkingDefault لهذا الوكيل عندما لا يكون هناك تجاوز لكل رسالة أو لكل جلسة.
• reasoningDefault: القيمة الافتراضية الاختيارية لإظهار reasoning لكل وكيل (on | off | stream). وتُطبَّق عندما لا يوجد تجاوز reasoning لكل رسالة أو لكل جلسة.
• fastModeDefault: القيمة الافتراضية الاختيارية لـ fast mode لكل وكيل (true | false). وتُطبَّق عندما لا يوجد تجاوز fast-mode لكل رسالة أو لكل جلسة.
• embeddedHarness: تجاوز اختياري لسياسة harness منخفض المستوى لكل وكيل. استخدم { runtime: "codex", fallback: "none" } لجعل وكيل واحد معتمدًا على Codex فقط بينما يحتفظ بقية الوكلاء بالاحتياط الافتراضي PI.
• runtime: واصف 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" } },
  ],
}

​

حقول مطابقة الربط

• 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, // تخطَّ تفرع الخيط الأصل فوق هذا العدد من الرموز المميزة (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", // قديم (يستخدم Runtime دائمًا "main")
    agentToAgent: { maxPingPongTurns: 5 },
    sendPolicy: {
      rules: [{ action: "deny", match: { channel: "discord", chatType: "group" } }],
      default: "allow",
    },
  },
}

​

الرسائل

{
  messages: {
    responsePrefix: "🦞", // أو "auto"
    ackReaction: "👀",
    ackReactionScope: "group-mentions", // group-mentions | group-all | direct | all
    removeAckAfterReply: false,
    queue: {
      mode: "collect", // steer | followup | collect | steer-backlog | steer+backlog | queue | interrupt
      debounceMs: 1000,
      cap: 20,
      drop: "summarize", // old | new | summarize
      byChannel: {
        whatsapp: "collect",
        telegram: "collect",
      },
    },
    inbound: {
      debounceMs: 2000, // 0 يعطّل
      byChannel: {
        whatsapp: 5000,
        slack: 1500,
      },
    },
  },
}

​

بادئة الرد

​

تفاعل الإقرار

• تكون القيمة الافتراضية identity.emoji للوكيل النشط، وإلا "👀". اضبطها على "" للتعطيل.
• تجاوزات لكل قناة: channels.<channel>.ackReaction وchannels.<channel>.accounts.<id>.ackReaction.
• ترتيب التحليل: الحساب → القناة → messages.ackReaction → الاحتياط من الهوية.
• النطاق: group-mentions (الافتراضي)، أو group-all، أو direct، أو all.
• يقوم removeAckAfterReply بإزالة الإقرار بعد الرد في Slack وDiscord وTelegram.
• يفعّل messages.statusReactions.enabled تفاعلات الحالة الدورية في Slack وDiscord وTelegram. في Slack وDiscord، يبقي عدم الضبط تفاعلات الحالة مفعلة عندما تكون تفاعلات الإقرار نشطة. في Telegram، اضبطه صراحةً على true لتفعيل تفاعلات الحالة الدورية.

​

إزالة الاهتزاز للرسائل الواردة

​

TTS (تحويل النص إلى كلام)

{
  messages: {
    tts: {
      auto: "always", // off | always | inbound | tagged
      mode: "final", // final | all
      provider: "elevenlabs",
      summaryModel: "openai/gpt-4.1-mini",
      modelOverrides: { enabled: true },
      maxTextLength: 4000,
      timeoutMs: 30000,
      prefsPath: "~/.openclaw/settings/tts.json",
      elevenlabs: {
        apiKey: "elevenlabs_api_key",
        baseUrl: "https://api.elevenlabs.io",
        voiceId: "voice_id",
        modelId: "eleven_multilingual_v2",
        seed: 42,
        applyTextNormalization: "auto",
        languageCode: "en",
        voiceSettings: {
          stability: 0.5,
          similarityBoost: 0.75,
          style: 0.0,
          useSpeakerBoost: true,
          speed: 1.0,
        },
      },
      openai: {
        apiKey: "openai_api_key",
        baseUrl: "https://api.openai.com/v1",
        model: "gpt-4o-mini-tts",
        voice: "alloy",
      },
    },
  },
}

• يتحكم auto في وضع TTS التلقائي الافتراضي: off أو always أو inbound أو tagged. ويمكن لـ /tts on|off تجاوز التفضيلات المحلية، كما يعرض /tts status الحالة الفعلية.
• يتجاوز summaryModel قيمة agents.defaults.model.primary للتلخيص التلقائي.
• يكون modelOverrides مفعّلًا افتراضيًا؛ أما modelOverrides.allowProvider فتكون قيمته الافتراضية false (اشتراك اختياري).
• تعود مفاتيح API إلى ELEVENLABS_API_KEY/XI_API_KEY وOPENAI_API_KEY.
• يتجاوز openai.baseUrl نقطة نهاية OpenAI TTS. وترتيب التحليل هو: التكوين، ثم OPENAI_TTS_BASE_URL، ثم https://api.openai.com/v1.
• عندما يشير openai.baseUrl إلى نقطة نهاية غير تابعة لـ OpenAI، يتعامل OpenClaw معها على أنها خادم TTS متوافق مع OpenAI ويخفف من التحقق من النموذج/الصوت.

​

Talk

{
  talk: {
    provider: "elevenlabs",
    providers: {
      elevenlabs: {
        voiceId: "elevenlabs_voice_id",
        voiceAliases: {
          Clawd: "EXAVITQu4vr4xnSDxMaL",
          Roger: "CwhRBWXzGAHq8TQ4Fs17",
        },
        modelId: "eleven_v3",
        outputFormat: "mp3_44100_128",
        apiKey: "elevenlabs_api_key",
      },
    },
    silenceTimeoutMs: 1500,
    interruptOnSpeech: true,
  },
}

• يجب أن تطابق talk.provider مفتاحًا في talk.providers عند تكوين عدة مزوّدات Talk.
• تكون مفاتيح Talk القديمة المسطحة (talk.voiceId وtalk.voiceAliases وtalk.modelId وtalk.outputFormat وtalk.apiKey) خاصة بالتوافق فقط، وتُنقل تلقائيًا إلى talk.providers.<provider>.
• تعود معرّفات الصوت إلى ELEVENLABS_VOICE_ID أو SAG_VOICE_ID.
• يقبل providers.*.apiKey سلاسل نصية صريحة أو كائنات SecretRef.
• يُطبّق الاحتياط ELEVENLABS_API_KEY فقط عندما لا يكون هناك مفتاح API لـ Talk مكوّن.
• يتيح providers.*.voiceAliases لتوجيهات Talk استخدام أسماء ودية.
• يتحكم silenceTimeoutMs في مدة انتظار وضع Talk بعد صمت المستخدم قبل إرسال النص المنسوخ. وعند عدم ضبطه، يحتفظ بنافذة التوقف المؤقت الافتراضية الخاصة بالمنصة (700 ms على macOS وAndroid، و900 ms على iOS).

​

ذو صلة

• مرجع التكوين — جميع مفاتيح التكوين الأخرى
• التكوين — المهام الشائعة والإعداد السريع
• أمثلة التكوين