پیکربندی

هر کانال بخش پیکربندی خودش را زیر channels.<provider> دارد. برای مراحل راه‌اندازی، صفحه اختصاصی کانال را ببینید:

• WhatsApp - channels.whatsapp
• Telegram - channels.telegram
• Discord - channels.discord
• Feishu - channels.feishu
• Google Chat - channels.googlechat
• Microsoft Teams - channels.msteams
• Slack - channels.slack
• Signal - channels.signal
• iMessage - channels.imessage
• Mattermost - channels.mattermost

همه کانال‌ها از الگوی سیاست DM یکسانی استفاده می‌کنند:

{  channels: {    telegram: {      enabled: true,      botToken: "123:abc",      dmPolicy: "pairing",   // pairing | allowlist | open | disabled      allowFrom: ["tg:123"], // only for allowlist/open    },  },}

مدل اصلی و fallbackهای اختیاری را تنظیم کنید:

{  agents: {    defaults: {      model: {        primary: "anthropic/claude-sonnet-4-6",        fallbacks: ["openai/gpt-5.4"],      },      models: {        "anthropic/claude-sonnet-4-6": { alias: "Sonnet" },        "openai/gpt-5.4": { alias: "GPT" },      },    },  },}

• agents.defaults.models کاتالوگ مدل را تعریف می‌کند و به‌عنوان allowlist برای /model عمل می‌کند؛ ورودی‌های provider/*، /model، /models و انتخابگرهای مدل را به ارائه‌دهندگان منتخب محدود می‌کنند، در حالی که همچنان از کشف پویای مدل استفاده می‌شود.
• برای افزودن ورودی‌های allowlist بدون حذف مدل‌های موجود، از openclaw config set agents.defaults.models '<json>' --strict-json --merge استفاده کنید. جایگزینی‌های ساده‌ای که ورودی‌ها را حذف کنند رد می‌شوند، مگر اینکه --replace را پاس بدهید.
• ارجاع‌های مدل از قالب provider/model استفاده می‌کنند (مثلا anthropic/claude-opus-4-6).
• agents.defaults.imageMaxDimensionPx کوچک‌سازی تصویرهای transcript/tool را کنترل می‌کند (پیش‌فرض 1200)؛ مقدارهای کمتر معمولا مصرف توکن بینایی را در اجراهای پر از اسکرین‌شات کاهش می‌دهند.
• برای تغییر مدل‌ها در چت، CLI مدل‌ها را ببینید و برای چرخش auth و رفتار fallback، Failover مدل را ببینید.
• برای ارائه‌دهندگان سفارشی/خودمیزبان، ارائه‌دهندگان سفارشی را در مرجع ببینید.

دسترسی DM برای هر کانال از طریق dmPolicy کنترل می‌شود:

• "pairing" (پیش‌فرض): فرستندگان ناشناخته یک کد pair یک‌بارمصرف برای تایید دریافت می‌کنند
• "allowlist": فقط فرستندگان موجود در allowFrom (یا ذخیره allow جفت‌شده)
• "open": همه DMهای ورودی را مجاز می‌کند (به allowFrom: ["*"] نیاز دارد)
• "disabled": همه DMها را نادیده می‌گیرد

برای گروه‌ها، از groupPolicy + groupAllowFrom یا allowlistهای مخصوص کانال استفاده کنید.

برای جزئیات هر کانال، مرجع کامل را ببینید.

پیام‌های گروهی به‌صورت پیش‌فرض نیازمند mention هستند. الگوهای trigger را برای هر عامل پیکربندی کنید. پاسخ‌های معمول گروه/کانال به‌طور خودکار ارسال می‌شوند؛ برای اتاق‌های مشترکی که عامل باید تصمیم بگیرد چه زمانی صحبت کند، مسیر message-tool را فعال کنید:

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

• mentionهای metadata: @-mentionهای بومی (WhatsApp tap-to-mention، Telegram @bot، و غیره)
• الگوهای متن: الگوهای regex امن در mentionPatterns
• پاسخ‌های قابل مشاهده: messages.visibleReplies می‌تواند ارسال با message-tool را به‌صورت سراسری الزامی کند؛ messages.groupChat.visibleReplies این را برای گروه‌ها/کانال‌ها override می‌کند.
• برای حالت‌های پاسخ قابل مشاهده، overrideهای هر کانال، و حالت self-chat، مرجع کامل را ببینید.

برای baseline مشترک از agents.defaults.skills استفاده کنید، سپس عامل‌های خاص را با agents.list[].skills override کنید:

{  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: [] را تنظیم کنید.
• Skills، پیکربندی Skills، و مرجع پیکربندی را ببینید.

کنترل کنید Gateway با چه شدتی کانال‌هایی را که کهنه به نظر می‌رسند restart کند:

{  gateway: {    channelHealthCheckMinutes: 5,    channelStaleEventThresholdMinutes: 30,    channelMaxRestartsPerHour: 10,  },  channels: {    telegram: {      healthMonitor: { enabled: false },      accounts: {        alerts: {          healthMonitor: { enabled: true },        },      },    },  },}

• برای غیرفعال کردن restartهای health-monitor به‌صورت سراسری، gateway.channelHealthCheckMinutes: 0 را تنظیم کنید.
• channelStaleEventThresholdMinutes باید بزرگ‌تر یا مساوی بازه بررسی باشد.
• برای غیرفعال کردن restart خودکار برای یک کانال یا حساب بدون غیرفعال کردن monitor سراسری، از channels.<provider>.healthMonitor.enabled یا channels.<provider>.accounts.<id>.healthMonitor.enabled استفاده کنید.
• برای اشکال‌زدایی عملیاتی، بررسی‌های سلامت و برای همه فیلدها مرجع کامل را ببینید.

به clientهای محلی زمان بیشتری بدهید تا دست‌دهی WebSocket پیش از auth را روی میزبان‌های پربار یا کم‌قدرت کامل کنند:

{  gateway: {    handshakeTimeoutMs: 30000,  },}

• پیش‌فرض 15000 میلی‌ثانیه است.
• OPENCLAW_HANDSHAKE_TIMEOUT_MS همچنان برای overrideهای موردی service یا shell اولویت دارد.
• ابتدا رفع stallهای startup/event-loop را ترجیح دهید؛ این knob برای میزبان‌هایی است که سالم‌اند اما هنگام warmup کند هستند.

نشست‌ها تداوم و جداسازی مکالمه را کنترل می‌کنند:

{  session: {    dmScope: "per-channel-peer",  // recommended for multi-user    threadBindings: {      enabled: true,      idleHours: 24,      maxAgeHours: 0,    },    reset: {      mode: "daily",      atHour: 4,      idleMinutes: 120,    },  },}

• dmScope: main (مشترک) | per-peer | per-channel-peer | per-account-channel-peer
• threadBindings: پیش‌فرض‌های سراسری برای مسیریابی نشست‌های وابسته به رشته (Discord از /focus، /unfocus، /agents، /session idle، و /session max-age پشتیبانی می‌کند).
• برای دامنه‌بندی، پیوندهای هویت، و سیاست ارسال، مدیریت نشست را ببینید.
• برای همه فیلدها، مرجع کامل را ببینید.

نشست‌های عامل را در زمان‌اجرای ایزوله‌شده اجرا کنید:

{  agents: {    defaults: {      sandbox: {        mode: "non-main",  // off | non-main | all        scope: "agent",    // session | agent | shared      },    },  },}

ابتدا تصویر را بسازید - از یک checkout منبع، scripts/sandbox-setup.sh را اجرا کنید، یا از یک نصب npm، دستور درون‌خطی docker build را در ایزوله‌سازی § تصاویر و راه‌اندازی ببینید.

برای راهنمای کامل، ایزوله‌سازی و برای همه گزینه‌ها مرجع کامل را ببینید.

push مبتنی بر relay برای buildهای عمومی App Store از relay میزبانی‌شده OpenClaw استفاده می‌کند: https://ios-push-relay.openclaw.ai.

استقرارهای relay سفارشی به یک مسیر build/استقرار iOS عمدا جداگانه نیاز دارند که URL relay آن با URL relay در gateway مطابقت داشته باشد. اگر از یک build relay سفارشی استفاده می‌کنید، این را در پیکربندی gateway تنظیم کنید:

{  gateway: {    push: {      apns: {        relay: {          baseUrl: "https://relay.example.com",          // Optional. Default: 10000          timeoutMs: 10000,        },      },    },  },}

معادل CLI:

openclaw config set gateway.push.apns.relay.baseUrl https://relay.example.com

این کار چه می‌کند:

• به gateway اجازه می‌دهد push.test، تلنگرهای بیدارباش، و بیدارباش‌های اتصال مجدد را از طریق relay خارجی ارسال کند.
• از یک مجوز ارسال محدود به ثبت‌نام استفاده می‌کند که توسط اپ iOS جفت‌شده منتقل می‌شود. gateway به توکن relay سراسری برای استقرار نیاز ندارد.
• هر ثبت‌نام مبتنی بر relay را به هویت gateway که اپ iOS با آن جفت شده متصل می‌کند، بنابراین gateway دیگر نمی‌تواند از ثبت‌نام ذخیره‌شده دوباره استفاده کند.
• buildهای محلی/دستی iOS را روی APNs مستقیم نگه می‌دارد. ارسال‌های مبتنی بر relay فقط برای buildهای رسمی توزیع‌شده‌ای اعمال می‌شوند که از طریق relay ثبت‌نام کرده‌اند.
• باید با URL پایه relay که در build iOS تعبیه شده مطابقت داشته باشد، تا ترافیک ثبت‌نام و ارسال به همان استقرار relay برسد.

جریان سرتاسری:

1. اپ رسمی iOS را نصب کنید.
2. اختیاری: gateway.push.apns.relay.baseUrl را فقط زمانی روی gateway پیکربندی کنید که از یک build relay سفارشی عمدا جداگانه استفاده می‌کنید.
3. اپ iOS را با gateway جفت کنید و اجازه دهید هر دو نشست نود و اپراتور متصل شوند.
4. اپ iOS هویت gateway را دریافت می‌کند، با استفاده از App Attest به‌همراه رسید اپ در relay ثبت‌نام می‌کند، و سپس بار push.apns.register مبتنی بر relay را در gateway جفت‌شده منتشر می‌کند.
5. gateway دسته relay و مجوز ارسال را ذخیره می‌کند، سپس از آن‌ها برای push.test، تلنگرهای بیدارباش، و بیدارباش‌های اتصال مجدد استفاده می‌کند.

نکات عملیاتی:

• اگر اپ iOS را به gateway دیگری منتقل کردید، اپ را دوباره متصل کنید تا بتواند یک ثبت‌نام relay جدیدِ متصل به آن gateway منتشر کند.
• اگر build جدیدی از iOS منتشر کنید که به استقرار relay متفاوتی اشاره دارد، اپ به‌جای استفاده مجدد از مبدا relay قدیمی، ثبت‌نام relay کش‌شده خود را تازه‌سازی می‌کند.

نکته سازگاری:

• OPENCLAW_APNS_RELAY_BASE_URL و OPENCLAW_APNS_RELAY_TIMEOUT_MS همچنان به‌عنوان بازنویسی‌های موقت env کار می‌کنند.
• URLهای relay سفارشی gateway باید با URL پایه relay که در build iOS تعبیه شده مطابقت داشته باشند. مسیر انتشار عمومی App Store، بازنویسی‌های URL relay سفارشی iOS را رد می‌کند.
• OPENCLAW_APNS_RELAY_ALLOW_HTTP=true همچنان یک راه فرار توسعه فقط برای loopback باقی می‌ماند؛ URLهای relay مبتنی بر HTTP را در config پایدار نکنید.

برای جریان سرتاسری، اپ iOS و برای مدل امنیتی relay، جریان احراز هویت و اعتماد را ببینید.

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

• every: رشته مدت‌زمان (30m، 2h). برای غیرفعال‌سازی، 0m را تنظیم کنید.
• target: last | none | <channel-id> (برای مثال discord، matrix، telegram، یا whatsapp)
• directPolicy: برای اهداف Heartbeat به سبک DM، allow (پیش‌فرض) یا block
• برای راهنمای کامل، Heartbeat را ببینید.

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

• sessionRetention: نشست‌های اجرای ایزوله تکمیل‌شده را از sessions.json پاک‌سازی می‌کند (پیش‌فرض 24h؛ برای غیرفعال‌سازی false را تنظیم کنید).
• runLog: ردیف‌های تاریخچه اجرای Cron نگه‌داری‌شده را برای هر کار پاک‌سازی می‌کند. maxBytes همچنان برای لاگ‌های اجرای قدیمی‌ترِ مبتنی بر فایل پذیرفته می‌شود.
• برای نمای کلی قابلیت و مثال‌های CLI، کارهای Cron را ببینید.

endpointهای HTTP Webhook را روی Gateway فعال کنید:

{  hooks: {    enabled: true,    token: "shared-secret",    path: "/hooks",    defaultSessionKey: "hook:ingress",    allowRequestSessionKey: false,    allowedSessionKeyPrefixes: ["hook:"],    mappings: [      {        match: { path: "gmail" },        action: "agent",        agentId: "main",        deliver: true,      },    ],  },}

نکته امنیتی:

• همه محتوای payload مربوط به hook/webhook را ورودی غیرقابل اعتماد در نظر بگیرید.
• از یک hooks.token اختصاصی استفاده کنید؛ secretهای فعال احراز هویت Gateway (gateway.auth.token / OPENCLAW_GATEWAY_TOKEN یا gateway.auth.password / OPENCLAW_GATEWAY_PASSWORD) را دوباره استفاده نکنید.
• احراز هویت hook فقط از طریق header است (Authorization: Bearer ... یا x-openclaw-token)؛ توکن‌های query-string رد می‌شوند.
• hooks.path نمی‌تواند / باشد؛ ورودی webhook را روی یک زیرمسیر اختصاصی مانند /hooks نگه دارید.
• flagهای عبور از محتوای ناامن را غیرفعال نگه دارید (hooks.gmail.allowUnsafeExternalContent، hooks.mappings[].allowUnsafeExternalContent) مگر برای اشکال‌زدایی با دامنه بسیار محدود.
• اگر hooks.allowRequestSessionKey را فعال می‌کنید، hooks.allowedSessionKeyPrefixes را نیز تنظیم کنید تا کلیدهای نشست انتخاب‌شده توسط فراخوان محدود شوند.
• برای عامل‌های هدایت‌شده با hook، tierهای مدل مدرن قوی و سیاست ابزار سخت‌گیرانه را ترجیح دهید (برای مثال فقط پیام‌رسانی به‌همراه ایزوله‌سازی هر جا ممکن است).

برای همه گزینه‌های نگاشت و یکپارچه‌سازی Gmail، مرجع کامل را ببینید.

چند عامل ایزوله را با workspaceها و نشست‌های جداگانه اجرا کنید:

{  agents: {    list: [      { id: "home", default: true, workspace: "~/.openclaw/workspace-home" },      { id: "work", workspace: "~/.openclaw/workspace-work" },    ],  },  bindings: [    { agentId: "home", match: { channel: "whatsapp", accountId: "personal" } },    { agentId: "work", match: { channel: "whatsapp", accountId: "biz" } },  ],}

برای قواعد اتصال و پروفایل‌های دسترسی برای هر عامل، چندعاملی و مرجع کامل را ببینید.

از $include برای سازمان‌دهی configهای بزرگ استفاده کنید:

// ~/.openclaw/openclaw.json{  gateway: { port: 18789 },  agents: { $include: "./agents.json5" },  broadcast: {    $include: ["./clients/a.json5", "./clients/b.json5"],  },}

• فایل تکی: شیء دربرگیرنده را جایگزین می‌کند
• آرایه‌ای از فایل‌ها: به‌ترتیب به‌صورت عمیق ادغام می‌شوند (موردهای بعدی برنده‌اند)
• کلیدهای هم‌سطح: پس از includeها ادغام می‌شوند (مقادیر includeشده را بازنویسی می‌کنند)
• includeهای تو در تو: تا عمق 10 سطح پشتیبانی می‌شوند
• مسیرهای نسبی: نسبت به فایلِ includeکننده resolve می‌شوند
• فرمت مسیر: مسیرهای include نباید شامل بایت null باشند و باید پیش و پس از resolve شدن، اکیدا کوتاه‌تر از 4096 کاراکتر باشند
• نوشتن‌های مالکیت‌شده توسط OpenClaw: وقتی یک نوشتن فقط یک بخش سطح‌بالا را تغییر می‌دهد که توسط یک include تک‌فایلی مانند plugins: { $include: "./plugins.json5" } پشتیبانی می‌شود، OpenClaw همان فایل includeشده را به‌روزرسانی می‌کند و openclaw.json را دست‌نخورده باقی می‌گذارد
• write-through پشتیبانی‌نشده: includeهای root، آرایه‌های include، و includeهایی با بازنویسی‌های هم‌سطح، برای نوشتن‌های مالکیت‌شده توسط OpenClaw به‌جای تخت کردن config، fail closed می‌شوند
• محدودسازی: مسیرهای $include باید زیر دایرکتوری نگه‌دارنده openclaw.json resolve شوند. برای اشتراک‌گذاری یک درخت میان ماشین‌ها یا کاربران، OPENCLAW_INCLUDE_ROOTS را روی یک path-list (: در POSIX، ; در Windows) از دایرکتوری‌های اضافی تنظیم کنید که includeها می‌توانند به آن‌ها ارجاع دهند. symlinkها resolve و دوباره بررسی می‌شوند، بنابراین مسیری که از نظر لغوی در یک دایرکتوری config قرار دارد اما مقصد واقعی آن از همه rootهای مجاز خارج می‌شود همچنان رد می‌شود.
• مدیریت خطا: خطاهای روشن برای فایل‌های گم‌شده، خطاهای parse، includeهای چرخه‌ای، فرمت مسیر نامعتبر، و طول بیش از حد