پیکربندی

هر کانال بخش پیکربندی خودش را زیر 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)؛ مقدارهای کمتر معمولاً مصرف vision-token را در اجراهای سنگین با screenshot کاهش می‌دهند.
• برای تغییر مدل‌ها در گفت‌وگو، CLI مدل‌ها و برای چرخش auth و رفتار fallback، Failover مدل را ببینید.
• برای ارائه‌دهندگان سفارشی/خودمیزبان، ارائه‌دهندگان سفارشی را در مرجع ببینید.

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

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

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

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

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

{  messages: {    visibleReplies: "automatic", // set "message_tool" to require message-tool sends everywhere    groupChat: {      visibleReplies: "message_tool", // default; use "automatic" for legacy room replies    },  },  agents: {    list: [      {        id: "main",        groupChat: {          mentionPatterns: ["@openclaw", "openclaw"],        },      },    ],  },  channels: {    whatsapp: {      groups: { "*": { requireMention: true } },    },  },}

• Metadata mentions: @-mentionهای بومی (tap-to-mention در WhatsApp، @bot در Telegram و غیره)
• الگوهای متنی: الگوهای 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های خودکار برای یک کانال یا حساب بدون غیرفعال کردن مانیتور سراسری، از channels.<provider>.healthMonitor.enabled یا channels.<provider>.accounts.<id>.healthMonitor.enabled استفاده کنید.
• برای دیباگ عملیاتی، Health Checks و برای همه فیلدها، مرجع کامل را ببینید.

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

{  gateway: {    handshakeTimeoutMs: 30000,  },}

• پیش‌فرض 15000 میلی‌ثانیه است.
• OPENCLAW_HANDSHAKE_TIMEOUT_MS همچنان برای overrideهای موردی سرویس یا shell اولویت دارد.
• ابتدا رفع گیرهای 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 پشتیبانی می‌کند).
• برای محدوده‌بندی، پیوندهای هویتی و سیاست ارسال، مدیریت نشست را ببینید.
• برای همه فیلدها، مرجع کامل را ببینید.

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

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

ابتدا image را بسازید - از یک checkout سورس scripts/sandbox-setup.sh را اجرا کنید، یا از نصب npm، دستور درون‌خطی docker build را در Sandboxing § Images and setup ببینید.

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

push مبتنی بر relay در openclaw.json پیکربندی می‌شود.

این را در پیکربندی Gateway تنظیم کنید:

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

معادل CLI:

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

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

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

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

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

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

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

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

• OPENCLAW_APNS_RELAY_BASE_URL و OPENCLAW_APNS_RELAY_TIMEOUT_MS همچنان به‌عنوان overrideهای موقت env کار می‌کنند.
• 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: allow (پیش‌فرض) یا block برای هدف‌های Heartbeat به سبک DM
• برای راهنمای کامل، Heartbeat را ببینید.

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

• sessionRetention: نشست‌های اجرای ایزوله تکمیل‌شده را از sessions.json پاک‌سازی می‌کند (پیش‌فرض 24h؛ برای غیرفعال‌سازی false را تنظیم کنید).
• runLog: فایل cron/runs/<jobId>.jsonl را بر اساس اندازه و خط‌های نگه‌داری‌شده پاک‌سازی می‌کند.
• برای نمای کلی قابلیت و مثال‌های CLI، jobهای Cron را ببینید.

endpointهای Webhook مبتنی بر HTTP را روی 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 اختصاصی استفاده کنید؛ token مشترک Gateway را دوباره استفاده نکنید.
• احراز هویت hook فقط از طریق header است (Authorization: Bearer ... یا x-openclaw-token)؛ tokenهای query-string رد می‌شوند.
• hooks.path نمی‌تواند / باشد؛ ورودی webhook را روی یک زیردامنه مسیر اختصاصی مانند /hooks نگه دارید.
• پرچم‌های عبور از محتوای ناامن را غیرفعال نگه دارید (hooks.gmail.allowUnsafeExternalContent، hooks.mappings[].allowUnsafeExternalContent) مگر برای اشکال‌زدایی با محدوده بسیار محدود.
• اگر hooks.allowRequestSessionKey را فعال می‌کنید، hooks.allowedSessionKeyPrefixes را هم تنظیم کنید تا کلیدهای نشست انتخاب‌شده توسط فراخواننده محدود شوند.
• برای عامل‌های مبتنی بر hook، tierهای مدل مدرن و قوی و سیاست ابزار سخت‌گیرانه را ترجیح دهید (برای مثال فقط پیام‌رسانی به‌همراه sandboxing در صورت امکان).

برای همه گزینه‌های mapping و یکپارچه‌سازی 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" } },  ],}

برای قواعد binding و profileهای دسترسی به‌ازای هر عامل، چندعاملی و مرجع کامل را ببینید.

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

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

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