پیکربندی — عامل‌ها

کلیدهای پیکربندی محدود به عامل زیر agents.*، multiAgent.*، session.*، messages.* و talk.*. برای کانال‌ها، ابزارها، زمان اجرای Gateway و سایر کلیدهای سطح بالا، مرجع پیکربندی را ببینید.

# پیش‌فرض‌های عامل

# agents.defaults.workspace

پیش‌فرض: ~/.openclaw/workspace.

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

# agents.defaults.repoRoot

ریشه مخزن اختیاری که در خط Runtime پرامپت سیستم نمایش داده می‌شود. اگر تنظیم نشود، OpenClaw با پیمایش رو به بالا از workspace آن را به‌صورت خودکار تشخیص می‌دهد.

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

# agents.defaults.skills

فهرست مجاز Skills پیش‌فرض اختیاری برای عامل‌هایی که agents.list[].skills را تنظیم نمی‌کنند.

{
  agents: {
    defaults: { skills: ["github", "weather"] },
    list: [
      { id: "writer" }, // inherits github, weather
      { id: "docs", skills: ["docs-search"] }, // replaces defaults
      { id: "locked-down", skills: [] }, // no skills
    ],
  },
}

• برای Skills نامحدود به‌صورت پیش‌فرض، agents.defaults.skills را حذف کنید.
• برای ارث‌بری از پیش‌فرض‌ها، agents.list[].skills را حذف کنید.
• برای نداشتن Skills، agents.list[].skills: [] را تنظیم کنید.
• یک فهرست غیرخالی agents.list[].skills مجموعه نهایی آن عامل است؛ با پیش‌فرض‌ها ادغام نمی‌شود.

# agents.defaults.skipBootstrap

ایجاد خودکار فایل‌های راه‌انداز workspace را غیرفعال می‌کند (AGENTS.md، SOUL.md، TOOLS.md، IDENTITY.md، USER.md، HEARTBEAT.md، BOOTSTRAP.md).

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

# agents.defaults.skipOptionalBootstrapFiles

ایجاد فایل‌های اختیاری انتخاب‌شده workspace را نادیده می‌گیرد، در حالی که همچنان فایل‌های راه‌انداز الزامی را می‌نویسد. مقدارهای معتبر: SOUL.md، USER.md، HEARTBEAT.md و IDENTITY.md.

{
  agents: {
    defaults: {
      skipOptionalBootstrapFiles: ["SOUL.md", "USER.md"],
    },
  },
}

# agents.defaults.contextInjection

کنترل می‌کند فایل‌های راه‌انداز workspace چه زمانی در پرامپت سیستم تزریق شوند. پیش‌فرض: "always".

• "continuation-skip": نوبت‌های ادامه امن (پس از پاسخ تکمیل‌شده دستیار) تزریق دوباره راه‌انداز workspace را نادیده می‌گیرند و اندازه پرامپت را کاهش می‌دهند. اجراهای Heartbeat و تلاش‌های مجدد پس از Compaction همچنان context را بازسازی می‌کنند.
• "never": راه‌انداز workspace و تزریق فایل‌های context را در هر نوبت غیرفعال می‌کند. این گزینه را فقط برای عامل‌هایی استفاده کنید که چرخه حیات پرامپت خود را کاملا مالک هستند (موتورهای context سفارشی، زمان‌های اجرای بومی که context خود را می‌سازند، یا workflowهای تخصصی بدون راه‌انداز). نوبت‌های Heartbeat و بازیابی Compaction نیز تزریق را نادیده می‌گیرند.

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

# agents.defaults.bootstrapMaxChars

حداکثر تعداد نویسه‌ها برای هر فایل راه‌انداز workspace پیش از کوتاه‌سازی. پیش‌فرض: 12000.

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

# agents.defaults.bootstrapTotalMaxChars

حداکثر تعداد کل نویسه‌های تزریق‌شده در همه فایل‌های راه‌انداز workspace. پیش‌فرض: 60000.

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

# agents.defaults.bootstrapPromptTruncationWarning

اعلان قابل مشاهده برای عامل در پرامپت سیستم را هنگام کوتاه شدن context راه‌انداز کنترل می‌کند. پیش‌فرض: "once".

• "off": هرگز متن اعلان کوتاه‌سازی را در پرامپت سیستم تزریق نکن.
• "once": برای هر امضای کوتاه‌سازی یکتا، یک بار اعلان کوتاه تزریق کن (توصیه‌شده).
• "always": هر بار که کوتاه‌سازی وجود دارد، در هر اجرا اعلان کوتاه تزریق کن.

شمارش‌های خام/تزریق‌شده تفصیلی و فیلدهای تنظیم پیکربندی در عیب‌یابی‌هایی مانند گزارش‌های context/status و لاگ‌ها باقی می‌مانند؛ context روتین کاربر/زمان اجرای WebChat فقط اعلان کوتاه بازیابی را دریافت می‌کند.

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

# نقشه مالکیت بودجه context

OpenClaw چندین بودجه پرحجم پرامپت/context دارد و این بودجه‌ها عمدا بر اساس زیرسامانه جدا شده‌اند، نه اینکه همگی از یک دکمه تنظیم عمومی عبور کنند.

• agents.defaults.bootstrapMaxChars / agents.defaults.bootstrapTotalMaxChars: تزریق عادی راه‌انداز workspace.
• agents.defaults.startupContext.*: مقدمه یک‌باره اجرای مدل برای reset/startup، شامل فایل‌های روزانه اخیر memory/*.md. فرمان‌های چت خام /new و /reset بدون فراخوانی مدل تایید می‌شوند.
• skills.limits.*: فهرست فشرده Skills که در پرامپت سیستم تزریق می‌شود.
• agents.defaults.contextLimits.*: گزیده‌های محدود زمان اجرا و بلوک‌های تزریق‌شده تحت مالکیت زمان اجرا.
• memory.qmd.limits.*: قطعه جست‌وجوی حافظه نمایه‌شده و اندازه‌بندی تزریق.

فقط وقتی یک عامل به بودجه متفاوتی نیاز دارد، override متناظر برای هر عامل را استفاده کنید:

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

# agents.defaults.startupContext

مقدمه startup نوبت اول را که در اجراهای مدل هنگام reset/startup تزریق می‌شود کنترل می‌کند. فرمان‌های چت خام /new و /reset بدون فراخوانی مدل، reset را تایید می‌کنند، بنابراین این مقدمه را بارگذاری نمی‌کنند.

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

# agents.defaults.contextLimits

پیش‌فرض‌های مشترک برای سطح‌های context محدود زمان اجرا.

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

• memoryGetMaxChars: سقف پیش‌فرض گزیده memory_get پیش از افزوده شدن فراداده کوتاه‌سازی و اعلان ادامه.
• memoryGetDefaultLines: پنجره خط پیش‌فرض memory_get وقتی lines حذف شده است.
• toolResultMaxChars: سقف زنده نتیجه ابزار که برای نتایج پایدارشده و بازیابی overflow استفاده می‌شود.
• postCompactionMaxChars: سقف گزیده AGENTS.md که هنگام تزریق refresh پس از Compaction استفاده می‌شود.

# agents.list[].contextLimits

override برای هر عامل برای دکمه‌های تنظیم مشترک contextLimits. فیلدهای حذف‌شده از agents.defaults.contextLimits ارث‌بری می‌کنند.

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

# skills.limits.maxSkillsPromptChars

سقف سراسری برای فهرست فشرده Skills که در پرامپت سیستم تزریق می‌شود. این خواندن فایل‌های SKILL.md در صورت نیاز را تحت تاثیر قرار نمی‌دهد.

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

# agents.list[].skillsLimits.maxSkillsPromptChars

override برای هر عامل برای بودجه پرامپت Skills.

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

# agents.defaults.imageMaxDimensionPx

حداکثر اندازه پیکسلی برای بلندترین ضلع تصویر در بلوک‌های تصویر transcript/tool پیش از فراخوانی provider. پیش‌فرض: 1200.

مقادیر کمتر معمولا مصرف توکن vision و اندازه payload درخواست را برای اجراهای پر از screenshot کاهش می‌دهند. مقادیر بالاتر جزئیات بصری بیشتری را حفظ می‌کنند.

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

# agents.defaults.userTimezone

منطقه زمانی برای context پرامپت سیستم (نه timestampهای پیام). به منطقه زمانی میزبان fallback می‌کند.

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

# agents.defaults.timeFormat

قالب زمان در پرامپت سیستم. پیش‌فرض: auto (ترجیح سیستم‌عامل).

{
  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" }, // global default provider params
      agentRuntime: {
        id: "pi", // pi | auto | registered harness id, e.g. codex
      },
      pdfMaxBytesMb: 10,
      pdfMaxPages: 20,
      thinkingDefault: "low",
      verboseDefault: "off",
      toolProgressDetail: "explain",
      reasoningDefault: "off",
      elevatedDefault: "on",
      timeoutSeconds: 600,
      mediaMaxMb: 5,
      contextTokens: 200000,
      maxConcurrent: 3,
    },
  },
}

• model: یا یک رشته ("provider/model") یا یک شیء ({ primary, fallbacks }) را می‌پذیرد.
  • فرم رشته فقط مدل اصلی را تنظیم می‌کند.
  • فرم شیء، مدل اصلی را همراه با مدل‌های جایگزینِ مرتب‌شده برای failover تنظیم می‌کند.
• imageModel: یا یک رشته ("provider/model") یا یک شیء ({ primary, fallbacks }) را می‌پذیرد.
  • در مسیر ابزار image به‌عنوان پیکربندی مدل بینایی آن استفاده می‌شود.
  • همچنین وقتی مدل انتخاب‌شده/پیش‌فرض نمی‌تواند ورودی تصویر را بپذیرد، برای مسیریابی جایگزین استفاده می‌شود.
  • ارجاع‌های صریح provider/model را ترجیح دهید. شناسه‌های ساده برای سازگاری پذیرفته می‌شوند؛ اگر یک شناسه ساده به‌طور یکتا با یک ورودی پیکربندی‌شده و دارای قابلیت تصویر در models.providers.*.models منطبق شود، OpenClaw آن را به همان provider نسبت می‌دهد. تطابق‌های پیکربندی‌شده مبهم به پیشوند صریح provider نیاز دارند.
• 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، یا openai/gpt-image-1.5 برای خروجی PNG/WebP با پس‌زمینه شفاف از OpenAI.
  • اگر یک provider/model را مستقیم انتخاب می‌کنید، احراز هویت provider متناظر را هم پیکربندی کنید (برای مثال GEMINI_API_KEY یا GOOGLE_API_KEY برای google/*،‏ OPENAI_API_KEY یا OpenAI Codex OAuth برای openai/gpt-image-2 / openai/gpt-image-1.5،‏ FAL_KEY برای fal/*).
  • اگر حذف شود، image_generate همچنان می‌تواند یک پیش‌فرض provider مبتنی بر احراز هویت را استنباط کند. ابتدا provider پیش‌فرض فعلی را امتحان می‌کند، سپس providerهای ثبت‌شده باقی‌مانده برای تولید تصویر را به‌ترتیب شناسه provider امتحان می‌کند.
• musicGenerationModel: یا یک رشته ("provider/model") یا یک شیء ({ primary, fallbacks }) را می‌پذیرد.
  • توسط قابلیت مشترک تولید موسیقی و ابزار داخلی music_generate استفاده می‌شود.
  • مقادیر معمول: google/lyria-3-clip-preview،‏ google/lyria-3-pro-preview، یا minimax/music-2.6.
  • اگر حذف شود، music_generate همچنان می‌تواند یک پیش‌فرض provider مبتنی بر احراز هویت را استنباط کند. ابتدا provider پیش‌فرض فعلی را امتحان می‌کند، سپس providerهای ثبت‌شده باقی‌مانده برای تولید موسیقی را به‌ترتیب شناسه provider امتحان می‌کند.
  • اگر یک provider/model را مستقیم انتخاب می‌کنید، احراز هویت/کلید API provider متناظر را هم پیکربندی کنید.
• 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 همچنان می‌تواند یک پیش‌فرض provider مبتنی بر احراز هویت را استنباط کند. ابتدا provider پیش‌فرض فعلی را امتحان می‌کند، سپس providerهای ثبت‌شده باقی‌مانده برای تولید ویدئو را به‌ترتیب شناسه provider امتحان می‌کند.
  • اگر یک provider/model را مستقیم انتخاب می‌کنید، احراز هویت/کلید API provider متناظر را هم پیکربندی کنید.
  • provider تولید ویدئوی Qwen که همراه بسته ارائه می‌شود، حداکثر از 1 ویدئوی خروجی، 1 تصویر ورودی، 4 ویدئوی ورودی، مدت 10 ثانیه، و گزینه‌های سطح provider شامل 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".
• toolProgressDetail: حالت جزئیات برای خلاصه‌های ابزار /verbose و خطوط ابزار در پیش‌نویس پیشرفت. مقادیر: "explain" (پیش‌فرض، برچسب‌های انسانی فشرده) یا "raw" (در صورت وجود، فرمان/جزئیات خام را اضافه می‌کند). agents.list[].toolProgressDetail هر عامل این پیش‌فرض را بازنویسی می‌کند.
• reasoningDefault: نمایش پیش‌فرض reasoning برای عامل‌ها. مقادیر: "off"،‏ "on"،‏ "stream". agents.list[].reasoningDefault هر عامل این پیش‌فرض را بازنویسی می‌کند. پیش‌فرض‌های reasoning پیکربندی‌شده فقط برای مالکان، فرستنده‌های مجاز، یا زمینه‌های Gateway با مدیر اپراتور اعمال می‌شوند، آن هم وقتی هیچ بازنویسی reasoning در سطح پیام یا نشست تنظیم نشده باشد.
• elevatedDefault: سطح پیش‌فرض خروجی elevated برای عامل‌ها. مقادیر: "off"،‏ "on"،‏ "ask"،‏ "full". پیش‌فرض: "on".
• model.primary: قالب provider/model (مثلاً openai/gpt-5.5 برای دسترسی با کلید API یا openai-codex/gpt-5.5 برای Codex OAuth). اگر provider را حذف کنید، OpenClaw ابتدا یک نام مستعار را امتحان می‌کند، سپس یک تطابق یکتای provider پیکربندی‌شده برای همان شناسه دقیق مدل را، و فقط پس از آن به provider پیش‌فرض پیکربندی‌شده بازمی‌گردد (رفتار سازگاری منسوخ‌شده، پس provider/model صریح را ترجیح دهید). اگر آن provider دیگر مدل پیش‌فرض پیکربندی‌شده را ارائه نکند، OpenClaw به‌جای نمایش پیش‌فرض کهنه مربوط به provider حذف‌شده، به اولین provider/model پیکربندی‌شده بازمی‌گردد.
• models: کاتالوگ مدل پیکربندی‌شده و allowlist برای /model. هر ورودی می‌تواند شامل alias (میان‌بر) و params (مختص provider، برای مثال temperature،‏ maxTokens،‏ cacheRetention،‏ context1m،‏ responsesServerCompaction،‏ responsesCompactThreshold،‏ chat_template_kwargs،‏ extra_body/extraBody) باشد.
  • ویرایش‌های امن: برای افزودن ورودی‌ها از openclaw config set agents.defaults.models '<json>' --strict-json --merge استفاده کنید. config set جایگزینی‌هایی را که ورودی‌های موجود allowlist را حذف کنند رد می‌کند، مگر اینکه --replace را ارسال کنید.
  • جریان‌های پیکربندی/آنبوردینگ با دامنه provider، مدل‌های provider انتخاب‌شده را در این نگاشت ادغام می‌کنند و providerهای نامرتبطی را که از قبل پیکربندی شده‌اند حفظ می‌کنند.
  • برای مدل‌های مستقیم OpenAI Responses، Compaction سمت سرور به‌طور خودکار فعال می‌شود. برای متوقف‌کردن تزریق context_management از params.responsesServerCompaction: false استفاده کنید، یا برای بازنویسی آستانه از params.responsesCompactThreshold استفاده کنید. Compaction سمت سرور OpenAI را ببینید.
• params: پارامترهای provider پیش‌فرض سراسری که به همه مدل‌ها اعمال می‌شوند. در agents.defaults.params تنظیم می‌شود (مثلاً { cacheRetention: "long" }).
• تقدم ادغام params (پیکربندی): agents.defaults.params (پایه سراسری) توسط agents.defaults.models["provider/model"].params (در سطح مدل) بازنویسی می‌شود، سپس agents.list[].params (شناسه عامل منطبق) به‌ازای کلید بازنویسی می‌کند. برای جزئیات، کش‌کردن پرامپت را ببینید.
• params.extra_body/params.extraBody: JSON عبوری پیشرفته که در بدنه‌های درخواست api: "openai-completions" برای پراکسی‌های سازگار با OpenAI ادغام می‌شود. اگر با کلیدهای درخواست تولیدشده تداخل داشته باشد، بدنه اضافی اولویت دارد؛ مسیرهای completions غیربومی همچنان بعداً store مخصوص OpenAI را حذف می‌کنند.
• params.chat_template_kwargs: آرگومان‌های chat-template سازگار با vLLM/OpenAI که در بدنه‌های درخواست سطح بالای api: "openai-completions" ادغام می‌شوند. برای vllm/nemotron-3-* وقتی thinking خاموش است، Plugin همراه vLLM به‌طور خودکار enable_thinking: false و force_nonempty_content: true را ارسال می‌کند؛ chat_template_kwargs صریح پیش‌فرض‌های تولیدشده را بازنویسی می‌کند، و extra_body.chat_template_kwargs همچنان اولویت نهایی را دارد. برای کنترل‌های thinking در Qwen با vLLM، روی همان ورودی مدل، params.qwenThinkingFormat را روی "chat-template" یا "top-level" تنظیم کنید.
• compat.supportedReasoningEfforts: فهرست reasoning effort سازگار با OpenAI در سطح مدل. برای endpointهای سفارشی که واقعاً آن را می‌پذیرند، "xhigh" را اضافه کنید؛ سپس OpenClaw در منوهای فرمان، ردیف‌های نشست Gateway، اعتبارسنجی patch نشست، اعتبارسنجی CLI عامل، و اعتبارسنجی llm-task برای آن provider/model پیکربندی‌شده، /think xhigh را نمایش می‌دهد. وقتی backend برای یک سطح canonical به مقدار مختص provider نیاز دارد، از compat.reasoningEffortMap استفاده کنید.
• params.preserveThinking: گزینه opt-in فقط برای Z.AI برای thinking حفظ‌شده. وقتی فعال باشد و thinking روشن باشد، OpenClaw مقدار thinking.clear_thinking: false را ارسال می‌کند و reasoning_content قبلی را دوباره پخش می‌کند؛ thinking در Z.AI و thinking حفظ‌شده را ببینید.
• agentRuntime: سیاست پیش‌فرض runtime سطح پایین عامل. شناسه حذف‌شده به‌طور پیش‌فرض OpenClaw Pi است. از id: "pi" برای اجبار به harness داخلی PI، از id: "auto" برای اجازه‌دادن به harnessهای Plugin ثبت‌شده تا مدل‌های پشتیبانی‌شده را claim کنند و وقتی هیچ موردی منطبق نیست از PI استفاده شود، از شناسه harness ثبت‌شده‌ای مانند id: "codex" برای الزام به همان harness، یا از نام مستعار backend پشتیبانی‌شده CLI مانند id: "claude-cli" استفاده کنید. runtimeهای صریح Plugin وقتی harness در دسترس نباشد یا شکست بخورد به‌صورت بسته شکست می‌خورند. ارجاع‌های مدل را به‌صورت canonical یعنی provider/model نگه دارید؛ Codex،‏ Claude CLI،‏ Gemini CLI و backendهای اجرایی دیگر را به‌جای پیشوندهای provider مربوط به runtime قدیمی، از طریق پیکربندی runtime انتخاب کنید. برای تفاوت این مورد با انتخاب provider/model، runtimeهای عامل را ببینید.
• نویسنده‌های پیکربندی که این فیلدها را تغییر می‌دهند (برای مثال /models set،‏ /models set-image و فرمان‌های افزودن/حذف جایگزین)، فرم شیء canonical را ذخیره می‌کنند و در صورت امکان فهرست‌های fallback موجود را حفظ می‌کنند.
• maxConcurrent: حداکثر اجرای موازی عامل‌ها در سراسر نشست‌ها (هر نشست همچنان سریالی است). پیش‌فرض: 4.

# agents.defaults.agentRuntime

agentRuntime کنترل می‌کند کدام executor سطح پایین نوبت‌های عامل را اجرا کند. بیشتر استقرارها باید runtime پیش‌فرض OpenClaw Pi را نگه دارند. وقتی یک Plugin مورداعتماد یک harness بومی ارائه می‌کند، مانند harness app-server همراه Codex، یا وقتی یک backend پشتیبانی‌شده CLI مانند Claude CLI می‌خواهید، از آن استفاده کنید. برای مدل ذهنی، runtimeهای عامل را ببینید.

{
  agents: {
    defaults: {
      model: "openai/gpt-5.5",
      agentRuntime: {
        id: "codex",
      },
    },
  },
}

• id: "auto"،‏ "pi"، شناسه harness ثبت‌شده Plugin، یا نام مستعار backend پشتیبانی‌شده CLI. Plugin همراه Codex مقدار codex را ثبت می‌کند؛ Plugin همراه Anthropic، backend CLI به نام claude-cli را ارائه می‌کند.
• id: "auto" به harnessهای Plugin ثبت‌شده اجازه می‌دهد نوبت‌های پشتیبانی‌شده را claim کنند و وقتی هیچ harness منطبق نیست از PI استفاده می‌کند. یک runtime صریح Plugin مانند id: "codex" به همان harness نیاز دارد و اگر در دسترس نباشد یا شکست بخورد، به‌صورت بسته شکست می‌خورد.
• بازنویسی محیطی: OPENCLAW_AGENT_RUNTIME=<id|auto|pi> مقدار id را برای همان فرایند بازنویسی می‌کند.
• برای استقرارهای فقط Codex، مقدار model: "openai/gpt-5.5" و agentRuntime.id: "codex" را تنظیم کنید.
• برای استقرارهای Claude CLI،‏ model: "anthropic/claude-opus-4-7" همراه با agentRuntime.id: "claude-cli" را ترجیح دهید. ارجاع‌های مدل قدیمی claude-cli/claude-opus-4-7 همچنان برای سازگاری کار می‌کنند، اما پیکربندی جدید باید انتخاب provider/model را canonical نگه دارد و backend اجرایی را در agentRuntime.id قرار دهد.
• کلیدهای قدیمی سیاست runtime توسط openclaw doctor --fix به agentRuntime بازنویسی می‌شوند.
• انتخاب harness پس از نخستین اجرای embedded برای هر شناسه نشست pin می‌شود. تغییرات پیکربندی/محیط روی نشست‌های جدید یا resetشده اثر می‌گذارند، نه روی transcript موجود. نشست‌های قدیمی با سابقه transcript اما بدون pin ثبت‌شده، به‌عنوان pinشده به PI در نظر گرفته می‌شوند. /status runtime مؤثر را گزارش می‌کند، برای مثال Runtime: OpenClaw Pi Default یا Runtime: OpenAI Codex.
• این فقط اجرای نوبت‌های متنی عامل را کنترل می‌کند. تولید رسانه، بینایی، PDF، موسیقی، ویدئو و TTS همچنان از تنظیمات provider/model خودشان استفاده می‌کنند.

میان‌برهای نام مستعار داخلی (فقط وقتی اعمال می‌شوند که مدل در agents.defaults.models باشد):

نام‌های مستعار پیکربندی‌شده شما همیشه بر پیش‌فرض‌ها اولویت دارند.

مدل‌های Z.AI GLM-4.x به‌طور خودکار حالت تفکر را فعال می‌کنند، مگر اینکه --thinking off را تنظیم کنید یا خودتان agents.defaults.models["zai/<model>"].params.thinking را تعریف کنید. مدل‌های Z.AI به‌طور پیش‌فرض tool_stream را برای استریم فراخوانی ابزار فعال می‌کنند. برای غیرفعال‌کردن آن، agents.defaults.models["zai/<model>"].params.tool_stream را روی false تنظیم کنید. مدل‌های Anthropic Claude 4.6 وقتی سطح تفکر صریحی تنظیم نشده باشد، به‌طور پیش‌فرض از تفکر adaptive استفاده می‌کنند.

# agents.defaults.cliBackends

بک‌اندهای CLI اختیاری برای اجراهای جایگزین فقط‌متنی (بدون فراخوانی ابزار). وقتی ارائه‌دهندگان API شکست می‌خورند، به‌عنوان پشتیبان مفید است.

{
  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",
          // Or use systemPromptFileArg when the CLI accepts a prompt file flag.
          systemPromptWhen: "first",
          imageArg: "--image",
          imageMode: "repeat",
        },
      },
    },
  },
}

• بک‌اندهای CLI متن‌محور هستند؛ ابزارها همیشه غیرفعال‌اند.
• وقتی sessionArg تنظیم شده باشد، نشست‌ها پشتیبانی می‌شوند.
• عبور مستقیم تصویر وقتی پشتیبانی می‌شود که imageArg مسیرهای فایل را بپذیرد.

# agents.defaults.systemPromptOverride

کل پرامپت سیستمی مونتاژشده توسط OpenClaw را با یک رشته ثابت جایگزین می‌کند. در سطح پیش‌فرض (agents.defaults.systemPromptOverride) یا برای هر عامل (agents.list[].systemPromptOverride) تنظیم کنید. مقدارهای مختص عامل اولویت دارند؛ مقدار خالی یا فقط شامل فاصله نادیده گرفته می‌شود. برای آزمایش‌های کنترل‌شده پرامپت مفید است.

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

# agents.defaults.promptOverlays

پوشش‌های پرامپت مستقل از ارائه‌دهنده که بر اساس خانواده مدل اعمال می‌شوند. شناسه‌های مدل خانواده GPT-5 قرارداد رفتاری مشترک را در میان ارائه‌دهندگان دریافت می‌کنند؛ personality فقط لایه سبک تعامل دوستانه را کنترل می‌کند.

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

• "friendly" (پیش‌فرض) و "on" لایه سبک تعامل دوستانه را فعال می‌کنند.
• "off" فقط لایه دوستانه را غیرفعال می‌کند؛ قرارداد رفتاری برچسب‌خورده GPT-5 همچنان فعال می‌ماند.
• اگر این تنظیم مشترک تنظیم نشده باشد، plugins.entries.openai.config.personality قدیمی همچنان خوانده می‌شود.

# agents.defaults.heartbeat

اجراهای Heartbeat دوره‌ای.

{
  agents: {
    defaults: {
      heartbeat: {
        every: "30m", // 0m disables
        model: "openai/gpt-5.4-mini",
        includeReasoning: false,
        includeSystemPromptSection: true, // default: true; false omits the Heartbeat section from the system prompt
        lightContext: false, // default: false; true keeps only HEARTBEAT.md from workspace bootstrap files
        isolatedSession: false, // default: false; true runs each heartbeat in a fresh session (no conversation history)
        skipWhenBusy: false, // default: false; true also waits for subagent/nested lanes
        session: "main",
        to: "+15555550123",
        directPolicy: "allow", // allow (default) | block
        target: "none", // default: none | options: 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 به زمینه بوت‌استرپ را رد می‌کند. پیش‌فرض: true.
• suppressToolErrorWarnings: وقتی true باشد، بارهای هشدار خطای ابزار را طی اجراهای Heartbeat سرکوب می‌کند.
• timeoutSeconds: حداکثر زمان مجاز بر حسب ثانیه برای یک نوبت عامل Heartbeat پیش از لغو آن. اگر تنظیم نشود، از agents.defaults.timeoutSeconds استفاده می‌شود.
• directPolicy: سیاست تحویل مستقیم/DM. allow (پیش‌فرض) تحویل به مقصد مستقیم را مجاز می‌کند. block تحویل به مقصد مستقیم را سرکوب می‌کند و reason=dm-blocked منتشر می‌کند.
• lightContext: وقتی true باشد، اجراهای Heartbeat از زمینه بوت‌استرپ سبک استفاده می‌کنند و فقط HEARTBEAT.md را از فایل‌های بوت‌استرپ فضای کاری نگه می‌دارند.
• isolatedSession: وقتی true باشد، هر Heartbeat در یک نشست تازه بدون تاریخچه گفت‌وگوی قبلی اجرا می‌شود. همان الگوی ایزوله‌سازی cron sessionTarget: "isolated". هزینه توکن هر Heartbeat را از حدود 100K به حدود 2-5K توکن کاهش می‌دهد.
• skipWhenBusy: وقتی true باشد، اجراهای Heartbeat در مسیرهای مشغول اضافی به تعویق می‌افتند: کار زیرعامل یا فرمان تودرتو. مسیرهای Cron همیشه Heartbeatها را به تعویق می‌اندازند، حتی بدون این پرچم.
• برای هر عامل: agents.list[].heartbeat را تنظیم کنید. وقتی هر عاملی heartbeat را تعریف کند، فقط همان عامل‌ها Heartbeat اجرا می‌کنند.
• Heartbeatها نوبت‌های کامل عامل را اجرا می‌کنند — بازه‌های کوتاه‌تر توکن‌های بیشتری مصرف می‌کنند.

# agents.defaults.compaction

{
  agents: {
    defaults: {
      compaction: {
        mode: "safeguard", // default | safeguard
        provider: "my-provider", // id of a registered compaction provider plugin (optional)
        timeoutSeconds: 900,
        reserveTokensFloor: 24000,
        keepRecentTokens: 50000,
        identifierPolicy: "strict", // strict | off | custom
        identifierInstructions: "Preserve deployment IDs, ticket IDs, and host:port pairs exactly.", // used when identifierPolicy=custom
        qualityGuard: { enabled: true, maxRetries: 1 },
        midTurnPrecheck: { enabled: false }, // optional Pi tool-loop pressure check
        postCompactionSections: ["Session Startup", "Red Lines"], // [] disables reinjection
        model: "openrouter/anthropic/claude-sonnet-4-6", // optional compaction-only model override
        truncateAfterCompaction: true, // rotate to a smaller successor JSONL after compaction
        maxActiveTranscriptBytes: "20mb", // optional preflight local compaction trigger
        notifyUser: true, // send brief notices when compaction starts and completes (default: false)
        memoryFlush: {
          enabled: true,
          model: "ollama/qwen3:8b", // optional memory-flush-only model override
          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 ثبت‌شده. وقتی تنظیم شود، به‌جای خلاصه‌سازی LLM داخلی، summarize() ارائه‌دهنده فراخوانی می‌شود. در صورت شکست، به داخلی بازمی‌گردد. تنظیم ارائه‌دهنده، mode: "safeguard" را اجباری می‌کند. Compaction را ببینید.
• timeoutSeconds: حداکثر ثانیه‌های مجاز برای یک عملیات Compaction منفرد پیش از آنکه OpenClaw آن را لغو کند. پیش‌فرض: 900.
• keepRecentTokens: بودجه نقطه برش Pi برای نگه‌داشتن دنباله تازه‌ترین رونوشت به‌صورت عین‌به‌عین. /compact دستی وقتی صریحاً تنظیم شده باشد به آن پایبند است؛ در غیر این صورت Compaction دستی یک نقطه وارسی سخت است.
• identifierPolicy: strict (پیش‌فرض)، off، یا custom. strict راهنمای داخلی نگه‌داری شناسه‌های مبهم را طی خلاصه‌سازی Compaction در ابتدا اضافه می‌کند.
• identifierInstructions: متن سفارشی اختیاری برای حفظ شناسه که وقتی identifierPolicy=custom باشد استفاده می‌شود.
• qualityGuard: بررسی‌های تلاش دوباره در صورت خروجی بدقالب برای خلاصه‌های safeguard. در حالت safeguard به‌طور پیش‌فرض فعال است؛ برای ردکردن بازرسی، enabled: false را تنظیم کنید.
• midTurnPrecheck: بررسی اختیاری فشار حلقه ابزار Pi. وقتی enabled: true باشد، OpenClaw پس از افزوده‌شدن نتایج ابزار و پیش از فراخوانی بعدی مدل، فشار زمینه را بررسی می‌کند. اگر زمینه دیگر جا نشود، تلاش جاری را پیش از ارسال پرامپت لغو می‌کند و از مسیر بازیابی پیش‌بررسی موجود برای کوتاه‌کردن نتایج ابزار یا انجام Compaction و تلاش دوباره استفاده می‌کند. با هر دو حالت Compaction یعنی default و safeguard کار می‌کند. پیش‌فرض: غیرفعال.
• postCompactionSections: نام‌های اختیاری بخش‌های H2/H3 در AGENTS.md برای تزریق دوباره پس از Compaction. پیش‌فرض ["Session Startup", "Red Lines"] است؛ برای غیرفعال‌کردن تزریق دوباره، [] را تنظیم کنید. وقتی تنظیم نشده باشد یا صریحاً روی همان جفت پیش‌فرض تنظیم شود، سرعنوان‌های قدیمی‌تر Every Session/Safety نیز به‌عنوان جایگزین قدیمی پذیرفته می‌شوند.
• model: بازنویسی اختیاری provider/model-id فقط برای خلاصه‌سازی Compaction. وقتی نشست اصلی باید یک مدل را نگه دارد اما خلاصه‌های Compaction باید روی مدل دیگری اجرا شوند، از این استفاده کنید؛ وقتی تنظیم نشده باشد، Compaction از مدل اصلی نشست استفاده می‌کند.
• maxActiveTranscriptBytes: آستانه بایت اختیاری (number یا رشته‌هایی مانند "20mb") که وقتی JSONL فعال از آستانه عبور کند، پیش از یک اجرا Compaction محلی عادی را راه‌اندازی می‌کند. به truncateAfterCompaction نیاز دارد تا Compaction موفق بتواند به رونوشت جانشین کوچک‌تری بچرخد. وقتی تنظیم نشده باشد یا 0 باشد، غیرفعال است.
• notifyUser: وقتی true باشد، هنگام آغاز Compaction و هنگام تکمیل آن اعلان‌های کوتاهی به کاربر می‌فرستد (برای مثال، «در حال Compaction زمینه...» و «Compaction کامل شد»). به‌طور پیش‌فرض غیرفعال است تا Compaction بی‌صدا بماند.
• memoryFlush: نوبت عاملی بی‌صدا پیش از Compaction خودکار برای ذخیره خاطره‌های پایدار. وقتی این نوبت نگه‌داری باید روی یک مدل محلی بماند، model را روی یک ارائه‌دهنده/مدل دقیق مانند ollama/qwen3:8b تنظیم کنید؛ این بازنویسی زنجیره جایگزین نشست فعال را به ارث نمی‌برد. وقتی فضای کاری فقط‌خواندنی باشد رد می‌شود.

# agents.defaults.contextPruning

نتایج ابزار قدیمی را پیش از ارسال به LLM از زمینه درون‌حافظه‌ای هرس می‌کند. تاریخچه نشست روی دیسک را تغییر نمی‌دهد.

{
  agents: {
    defaults: {
      contextPruning: {
        mode: "cache-ttl", // off | cache-ttl
        ttl: "1h", // duration (ms/s/m/h), default unit: minutes
        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 (use 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 / inline contents also supported:
          // 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", // optional
        gatewayEndpoint: "https://lab.example", // optional
        policy: "strict", // optional OpenShell policy id
        providers: ["openai"], // optional
        autoProviders: true,
        timeoutSeconds: 120,
      },
    },
  },
},
}

سندباکسینگ مرورگر و sandbox.docker.binds فقط مخصوص Docker هستند.

ساخت تصویرها (از یک checkout منبع):

scripts/sandbox-setup.sh           # main sandbox image
scripts/sandbox-browser-setup.sh   # optional browser image

برای نصب‌های npm بدون checkout منبع، برای فرمان‌های درون‌خطی docker build، سندباکسینگ § تصویرها و راه‌اندازی را ببینید.

# agents.list (بازنویسی‌های هر عامل)

از agents.list[].tts استفاده کنید تا به یک عامل ارائه‌دهنده TTS، صدا، مدل، سبک، یا حالت TTS خودکار اختصاصی بدهید. بلوک عامل روی messages.tts سراسری به‌صورت deep-merge ادغام می‌شود، بنابراین اعتبارنامه‌های مشترک می‌توانند در یک مکان بمانند و عامل‌های جداگانه فقط فیلدهای صدا یا ارائه‌دهنده‌ای را که نیاز دارند بازنویسی کنند. بازنویسی عامل فعال روی پاسخ‌های گفتاری خودکار، /tts audio، /tts status، و ابزار عامل tts اعمال می‌شود. برای مثال‌های ارائه‌دهنده و اولویت، تبدیل متن به گفتار را ببینید.

{
  agents: {
    list: [
      {
        id: "main",
        default: true,
        name: "Main Agent",
        workspace: "~/.openclaw/workspace",
        agentDir: "~/.openclaw/agents/main/agent",
        model: "anthropic/claude-opus-4-6", // or { primary, fallbacks }
        thinkingDefault: "high", // per-agent thinking level override
        reasoningDefault: "on", // per-agent reasoning visibility override
        fastModeDefault: false, // per-agent fast mode override
        agentRuntime: { id: "auto" },
        params: { cacheRetention: "none" }, // overrides matching defaults.models params by key
        tts: {
          providers: {
            elevenlabs: { voiceId: "EXAVITQu4vr4xnSDxMaL" },
          },
        },
        skills: ["docs-search"], // replaces agents.defaults.skills when set
        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: فرم رشته‌ای، مدل اصلی سخت‌گیرانهٔ مخصوص هر عامل را بدون fallback مدل تنظیم می‌کند؛ فرم شیء { primary } نیز سخت‌گیرانه است مگر اینکه fallbacks را اضافه کنید. از { primary, fallbacks: [...] } برای فعال‌کردن fallback برای آن عامل استفاده کنید، یا از { primary, fallbacks: [] } برای صریح‌کردن رفتار سخت‌گیرانه. کارهای Cron که فقط primary را بازنویسی می‌کنند همچنان fallbackهای پیش‌فرض را به ارث می‌برند، مگر اینکه fallbacks: [] را تنظیم کنید.
• params: پارامترهای جریان مخصوص هر عامل که روی ورودی مدل انتخاب‌شده در agents.defaults.models ادغام می‌شوند. از این برای بازنویسی‌های مخصوص عامل مانند cacheRetention،‏ temperature یا maxTokens بدون تکرار کل کاتالوگ مدل استفاده کنید.
• tts: بازنویسی‌های اختیاری متن‌به‌گفتار مخصوص هر عامل. این بلوک به‌صورت عمیق روی messages.tts ادغام می‌شود، بنابراین اعتبارنامه‌های ارائه‌دهندهٔ مشترک و سیاست fallback را در messages.tts نگه دارید و فقط مقدارهای مخصوص شخصیت مانند ارائه‌دهنده، صدا، مدل، سبک یا حالت خودکار را اینجا تنظیم کنید.
• skills: فهرست مجاز اختیاری Skills مخصوص هر عامل. اگر حذف شود، عامل در صورت تنظیم‌بودن agents.defaults.skills آن را به ارث می‌برد؛ یک فهرست صریح به‌جای ادغام، پیش‌فرض‌ها را جایگزین می‌کند، و [] یعنی بدون Skills.
• thinkingDefault: سطح پیش‌فرض اختیاری تفکر مخصوص هر عامل (off | minimal | low | medium | high | xhigh | adaptive | max). وقتی هیچ بازنویسی مخصوص پیام یا نشست تنظیم نشده باشد، agents.defaults.thinkingDefault را برای این عامل بازنویسی می‌کند. پروفایل ارائه‌دهنده/مدل انتخاب‌شده کنترل می‌کند کدام مقدارها معتبر هستند؛ برای Google Gemini، مقدار adaptive تفکر پویای تحت مالکیت ارائه‌دهنده را حفظ می‌کند (thinkingLevel در Gemini 3/3.1 حذف می‌شود، و thinkingBudget: -1 در Gemini 2.5).
• reasoningDefault: نمایانی پیش‌فرض اختیاری استدلال مخصوص هر عامل (on | off | stream). وقتی هیچ بازنویسی استدلال مخصوص پیام یا نشست تنظیم نشده باشد، agents.defaults.reasoningDefault را برای این عامل بازنویسی می‌کند.
• fastModeDefault: پیش‌فرض اختیاری مخصوص هر عامل برای حالت سریع (true | false). وقتی هیچ بازنویسی حالت سریع مخصوص پیام یا نشست تنظیم نشده باشد اعمال می‌شود.
• agentRuntime: بازنویسی اختیاری سیاست runtime سطح پایین مخصوص هر عامل. از { id: "codex" } استفاده کنید تا یک عامل فقط Codex باشد، در حالی که عامل‌های دیگر fallback پیش‌فرض PI را در حالت auto حفظ می‌کنند.
• runtime: توصیفگر runtime اختیاری مخصوص هر عامل. وقتی عامل باید به‌طور پیش‌فرض از نشست‌های ACP harness استفاده کند، از type: "acp" همراه با پیش‌فرض‌های runtime.acp (agent،‏ backend،‏ mode،‏ cwd) استفاده کنید.
• identity.avatar: مسیر نسبی به workspace، نشانی http(s)، یا URI از نوع data:.
• identity پیش‌فرض‌ها را استخراج می‌کند: ackReaction از emoji، و mentionPatterns از name/emoji.
• subagents.allowAgents: فهرست مجاز شناسه‌های عامل برای هدف‌های صریح sessions_spawn.agentId (["*"] = هرکدام؛ پیش‌فرض: فقط همان عامل). وقتی فراخوانی‌های self-targeted با agentId باید مجاز باشند، شناسهٔ درخواست‌کننده را اضافه کنید.
• نگهبان وراثت sandbox: اگر نشست درخواست‌کننده sandbox شده باشد، sessions_spawn هدف‌هایی را که بدون sandbox اجرا می‌شوند رد می‌کند.
• subagents.requireAgentId: وقتی true باشد، فراخوانی‌های sessions_spawn را که agentId را حذف کرده‌اند مسدود می‌کند (انتخاب صریح پروفایل را اجباری می‌کند؛ پیش‌فرض: false).

# مسیریابی چندعاملی

چند عامل ایزوله را داخل یک Gateway اجرا کنید. چندعاملی را ببینید.

{
  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 برای bindingهای گفت‌وگوی پایدار 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. عامل پیش‌فرض

در هر سطح، اولین ورودی منطبق در bindings برنده است.

برای ورودی‌های type: "acp"، OpenClaw بر اساس هویت دقیق گفت‌وگو (match.channel + حساب + match.peer.id) resolve می‌کند و از ترتیب سطح‌بندی binding مسیریابی بالا استفاده نمی‌کند.

# پروفایل‌های دسترسی مخصوص هر عامل

{
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",
    maintenance: {
      mode: "warn", // warn | enforce
      pruneAfter: "30d",
      maxEntries: 500,
      resetArchiveRetention: "30d", // duration or false
      maxDiskBytes: "500mb", // optional hard budget
      highWaterBytes: "400mb", // optional cleanup target
    },
    threadBindings: {
      enabled: true,
      idleHours: 24, // default inactivity auto-unfocus in hours (`0` disables)
      maxAgeHours: 0, // default hard max age in hours (`0` disables)
    },
    mainKey: "main", // legacy (runtime always uses "main")
    agentToAgent: { maxPingPongTurns: 5 },
    sendPolicy: {
      rules: [{ action: "deny", match: { channel: "discord", chatType: "group" } }],
      default: "allow",
    },
  },
}

# پیام‌ها

{
  messages: {
    responsePrefix: "🦞", // or "auto"
    ackReaction: "👀",
    ackReactionScope: "group-mentions", // group-mentions | group-all | direct | all
    removeAckAfterReply: false,
    queue: {
      mode: "steer", // steer | queue (legacy one-at-a-time) | followup | collect | steer-backlog | steer+backlog | interrupt
      debounceMs: 500,
      cap: 20,
      drop: "summarize", // old | new | summarize
      byChannel: {
        whatsapp: "steer",
        telegram: "steer",
      },
    },
    inbound: {
      debounceMs: 2000, // 0 disables
      byChannel: {
        whatsapp: 5000,
        slack: 1500,
      },
    },
  },
}

# پیشوند پاسخ

لغوهای مخصوص هر کانال/حساب: channels.<channel>.responsePrefix، channels.<channel>.accounts.<id>.responsePrefix.

حل‌وفصل (مشخص‌ترین مورد برنده است): حساب → کانال → سراسری. "" غیرفعال می‌کند و زنجیره را متوقف می‌کند. "auto" مقدار [{identity.name}] را استخراج می‌کند.

متغیرهای قالب:

متغیرها به بزرگی و کوچکی حروف حساس نیستند. {think} نام مستعار {thinkingLevel} است.

# واکنش تأیید

• مقدار پیش‌فرض identity.emoji مربوط به agent فعال است، و در غیر این صورت "👀". برای غیرفعال‌سازی روی "" تنظیم کنید.
• لغوهای مخصوص هر کانال: channels.<channel>.ackReaction، channels.<channel>.accounts.<id>.ackReaction.
• ترتیب حل‌وفصل: حساب → کانال → messages.ackReaction → جایگزین هویت.
• دامنه: group-mentions (پیش‌فرض)، group-all، direct، all.
• removeAckAfterReply: تأیید را پس از پاسخ در کانال‌هایی که از واکنش پشتیبانی می‌کنند، مانند Slack، Discord، Telegram، WhatsApp و BlueBubbles حذف می‌کند.
• messages.statusReactions.enabled: واکنش‌های وضعیت چرخه عمر را در Slack، Discord و Telegram فعال می‌کند. در Slack و Discord، تنظیم‌نکردن آن باعث می‌شود وقتی واکنش‌های تأیید فعال هستند، واکنش‌های وضعیت هم فعال بمانند. در Telegram، برای فعال‌کردن واکنش‌های وضعیت چرخه عمر، آن را صریحاً روی true تنظیم کنید.

# debounce ورودی

پیام‌های فقط متنی سریع از یک فرستنده را در یک نوبت واحد agent دسته‌بندی می‌کند. رسانه/پیوست‌ها بلافاصله تخلیه می‌شوند. فرمان‌های کنترلی از debounce عبور می‌کنند.

# 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",
      providers: {
        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,
          },
        },
        microsoft: {
          voice: "en-US-AvaMultilingualNeural",
          lang: "en-US",
          outputFormat: "audio-24khz-48kbitrate-mono-mp3",
        },
        openai: {
          apiKey: "openai_api_key",
          baseUrl: "https://api.openai.com/v1",
          model: "gpt-4o-mini-tts",
          voice: "alloy",
        },
      },
    },
  },
}

• auto حالت پیش‌فرض auto-TTS را کنترل می‌کند: off، always، inbound یا tagged. /tts on|off می‌تواند ترجیحات محلی را لغو کند، و /tts status وضعیت مؤثر را نشان می‌دهد.
• summaryModel مقدار agents.defaults.model.primary را برای خلاصه خودکار لغو می‌کند.
• modelOverrides به‌طور پیش‌فرض فعال است؛ مقدار پیش‌فرض modelOverrides.allowProvider برابر false است (نیازمند opt-in).
• کلیدهای API به ELEVENLABS_API_KEY/XI_API_KEY و OPENAI_API_KEY fallback می‌شوند.
• ارائه‌دهندگان گفتار همراه، متعلق به Plugin هستند. اگر plugins.allow تنظیم شده است، هر Plugin ارائه‌دهنده TTS را که می‌خواهید استفاده کنید اضافه کنید، برای نمونه microsoft برای Edge TTS. شناسه قدیمی ارائه‌دهنده edge به‌عنوان نام مستعار microsoft پذیرفته می‌شود.
• providers.openai.baseUrl endpoint مربوط به OpenAI TTS را لغو می‌کند. ترتیب حل‌وفصل ابتدا پیکربندی، سپس OPENAI_TTS_BASE_URL و سپس https://api.openai.com/v1 است.
• وقتی providers.openai.baseUrl به یک endpoint غیر OpenAI اشاره کند، OpenClaw آن را به‌عنوان سرور TTS سازگار با OpenAI در نظر می‌گیرد و اعتبارسنجی مدل/صدا را آسان‌تر می‌کند.

# گفت‌وگو

پیش‌فرض‌های حالت گفت‌وگو (macOS/iOS/Android).

{
  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",
      },
      mlx: {
        modelId: "mlx-community/Soprano-80M-bf16",
      },
      system: {},
    },
    speechLocale: "ru-RU",
    silenceTimeoutMs: 1500,
    interruptOnSpeech: true,
    realtime: {
      provider: "openai",
      providers: {
        openai: {
          model: "gpt-realtime",
          voice: "alloy",
        },
      },
      mode: "realtime",
      transport: "webrtc",
      brain: "agent-consult",
    },
  },
}

• talk.provider باید وقتی چند ارائه‌دهنده گفت‌وگو پیکربندی شده‌اند، با یک کلید در talk.providers مطابقت داشته باشد.
• کلیدهای مسطح قدیمی گفت‌وگو (talk.voiceId، talk.voiceAliases، talk.modelId، talk.outputFormat، talk.apiKey) فقط برای سازگاری هستند. برای بازنویسی پیکربندی پایدارشده به talk.providers.<provider>، openclaw doctor --fix را اجرا کنید.
• شناسه‌های صدا به ELEVENLABS_VOICE_ID یا SAG_VOICE_ID fallback می‌شوند.
• providers.*.apiKey رشته‌های متن ساده یا اشیای SecretRef را می‌پذیرد.
• fallback مربوط به ELEVENLABS_API_KEY فقط زمانی اعمال می‌شود که هیچ کلید API گفت‌وگو پیکربندی نشده باشد.
• providers.*.voiceAliases به دستورهای گفت‌وگو اجازه می‌دهد از نام‌های دوستانه استفاده کنند.
• providers.mlx.modelId مخزن Hugging Face استفاده‌شده توسط کمک‌کننده محلی MLX در macOS را انتخاب می‌کند. اگر حذف شود، macOS از mlx-community/Soprano-80M-bf16 استفاده می‌کند.
• پخش MLX در macOS از طریق کمک‌کننده همراه openclaw-mlx-tts، در صورت وجود، یا یک فایل اجرایی در PATH اجرا می‌شود؛ OPENCLAW_MLX_TTS_BIN مسیر کمک‌کننده را برای توسعه لغو می‌کند.
• speechLocale شناسه locale از نوع BCP 47 را که تشخیص گفتار گفت‌وگو در iOS/macOS استفاده می‌کند تنظیم می‌کند. برای استفاده از پیش‌فرض دستگاه، آن را تنظیم‌نشده بگذارید.
• silenceTimeoutMs کنترل می‌کند حالت گفت‌وگو پس از سکوت کاربر چه مدت منتظر بماند و سپس متن گفتار را ارسال کند. تنظیم‌نکردن آن پنجره مکث پیش‌فرض پلتفرم را حفظ می‌کند (700 ms on macOS and Android, 900 ms on iOS).

# مرتبط

• مرجع پیکربندی — همه کلیدهای پیکربندی دیگر
• پیکربندی — کارهای رایج و راه‌اندازی سریع
• نمونه‌های پیکربندی