پیکربندی

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

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

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

{  channels: {    telegram: {      enabled: true,      botToken: "123:abc",      dmPolicy: "pairing",   // جفت‌سازی | فهرست مجاز | باز | غیرفعال      allowFrom: ["tg:123"], // فقط برای فهرست مجاز/باز    },  },}

مدل اصلی و جایگزین‌های اختیاری را تنظیم کنید:

{  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 نام‌های مستعار و تنظیمات هر مدل را ذخیره می‌کند؛ افزودن یک ورودی هرگز بازنویسی‌های /model یا --model را محدود نمی‌کند.
• agents.defaults.modelPolicy.allow فهرست مجاز صریح برای بازنویسی‌ها و انتخابگرهای مدل است. این فهرست ارجاع‌های دقیق و نویسه‌های عام provider/* را می‌پذیرد؛ برای مجاز کردن هر مدلی، آن را حذف کنید یا از [] استفاده کنید.
• ارجاع‌های مدل از قالب provider/model استفاده می‌کنند (برای مثال anthropic/claude-opus-4-6).
• agents.defaults.imageMaxDimensionPx کوچک‌سازی تصاویر رونوشت/ابزار را کنترل می‌کند (پیش‌فرض 1200)؛ مقادیر کمتر معمولاً مصرف توکن بینایی را در اجراهای دارای اسکرین‌شات زیاد کاهش می‌دهند.
• برای تعویض مدل‌ها در گفت‌وگو، CLI مدل‌ها و برای چرخش احراز هویت و رفتار جایگزینی، جایگزینی مدل را ببینید.
• برای ارائه‌دهندگان سفارشی/خودمیزبان، بخش ارائه‌دهندگان سفارشی را در مرجع ببینید.

دسترسی پیام مستقیم برای هر کانال از طریق dmPolicy کنترل می‌شود (پیش‌فرض "pairing"):

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

برای گروه‌ها، از groupPolicy ("allowlist" | "open" | "disabled") همراه با groupAllowFrom یا فهرست‌های مجاز مختص کانال استفاده کنید.

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

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

{  messages: {    visibleReplies: "automatic", // برای الزام ارسال با ابزار پیام در همه‌جا، روی "message_tool" تنظیم کنید    groupChat: {      visibleReplies: "message_tool", // اختیاری؛ خروجی قابل‌مشاهده به message(action=send) نیاز دارد      unmentionedInbound: "room_event", // گفت‌وگوی گروهی همیشگیِ بدون اشاره، زمینه‌ای بی‌صدا است    },  },  agents: {    list: [      {        id: "main",        groupChat: {          mentionPatterns: ["@openclaw", "openclaw"],        },      },    ],  },  channels: {    whatsapp: {      groups: { "*": { requireMention: true } },    },  },}

• اشاره‌های فراداده‌ای: اشاره‌های بومی @ (اشاره با لمس در WhatsApp، ‎@bot در Telegram و غیره)
• الگوهای متنی: الگوهای عبارت منظم امن در mentionPatterns
• پاسخ‌های قابل‌مشاهده: messages.visibleReplies می‌تواند ارسال با ابزار پیام را به‌صورت سراسری الزامی کند؛ messages.groupChat.visibleReplies آن را برای گروه‌ها/کانال‌ها بازنویسی می‌کند.
• برای حالت‌های پاسخ قابل‌مشاهده، بازنویسی‌های هر کانال و حالت گفت‌وگو با خود، مرجع کامل را ببینید.

برای خط پایه مشترک از agents.defaults.skills استفاده کنید، سپس عامل‌های مشخص را با agents.entries.*.skills بازنویسی کنید:

{  agents: {    defaults: {      skills: ["github", "weather"],    },    list: [      { id: "writer" }, // github و weather را به ارث می‌برد      { id: "docs", skills: ["docs-search"] }, // پیش‌فرض‌ها را جایگزین می‌کند      { id: "locked-down", skills: [] }, // بدون Skills    ],  },}

• برای نامحدود بودن Skills به‌طور پیش‌فرض، agents.defaults.skills را حذف کنید.
• برای به‌ارث‌بردن پیش‌فرض‌ها، agents.entries.*.skills را حذف کنید.
• برای نداشتن Skills، agents.entries.*.skills: [] را تنظیم کنید.
• Skills، پیکربندی Skills و مرجع پیکربندی را ببینید.

راه‌اندازی مجدد خودکار سلامت را برای یک کانال یا حساب غیرفعال یا فعال کنید:

{  channels: {    telegram: {      healthMonitor: { enabled: false },      accounts: {        alerts: {          healthMonitor: { enabled: true },        },      },    },  },}

• برای کنترل راه‌اندازی مجدد خودکار یک کانال یا حساب، از channels.<provider>.healthMonitor.enabled یا channels.<provider>.accounts.<id>.healthMonitor.enabled استفاده کنید.
• برای اشکال‌زدایی عملیاتی، بررسی‌های سلامت و برای همه فیلدها، مرجع کامل را ببینید.

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

{  session: {    dmScope: "per-channel-peer",  // برای چندکاربر توصیه می‌شود    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: پیش‌فرض‌های سراسری برای مسیریابی نشست متصل به رشته. /focus، /unfocus، /agents، /session idle و /session max-age این اتصال را برای هر نشست برقرار، قطع، فهرست و تنظیم می‌کنند (Discord رشته‌ها را متصل می‌کند و Telegram موضوع‌ها/مکالمه‌ها را).
• برای محدوده‌بندی، پیوندهای هویتی و سیاست ارسال، به مدیریت نشست مراجعه کنید.
• برای همه فیلدها، مرجع کامل را ببینید.

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

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

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

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

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

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

{  gateway: {    push: {      apns: {        relay: {          baseUrl: "https://relay.example.com",          // اختیاری. پیش‌فرض: 10000          timeoutMs: 10000,        },      },    },  },}

معادل CLI:

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

کارکرد این تنظیم:

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

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

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

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

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

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

• OPENCLAW_APNS_RELAY_BASE_URL و OPENCLAW_APNS_RELAY_TIMEOUT_MS همچنان به‌عنوان بازنویسی‌های موقت محیطی کار می‌کنند.
• URLهای رله سفارشی Gateway باید با URL پایه رله تعبیه‌شده در بیلد iOS مطابقت داشته باشند؛ مسیر انتشار عمومی App Store بازنویسی‌های URL رله سفارشی iOS را رد می‌کند.
• OPENCLAW_APNS_RELAY_ALLOW_HTTP=true همچنان یک راه گریز توسعه‌ای محدود به loopback است؛ URLهای رله HTTP را در پیکربندی ماندگار نکنید.

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

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

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

{  cron: {    enabled: true,    sessionRetention: "24h",  },}

• sessionRetention: نشست‌های تکمیل‌شده اجرای ایزوله را از ردیف‌های نشست SQLite پاک‌سازی می‌کند (پیش‌فرض 24h؛ برای غیرفعال‌سازی، false را تنظیم کنید).
• تاریخچه اجرا به‌طور خودکار جدیدترین 2000 ردیف ترمینال را برای هر کار نگه می‌دارد؛ ردیف‌های گم‌شده بازه پاک‌سازی 24 ساعته خود را حفظ می‌کنند.
• برای نمای کلی قابلیت و نمونه‌های CLI به کارهای Cron مراجعه کنید.

نقاط پایانی 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,      },    ],  },}

نکته امنیتی:

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

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

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

{  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 استفاده کنید:

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

• یک فایل: شیء دربرگیرنده را جایگزین می‌کند
• آرایه‌ای از فایل‌ها: به‌ترتیب به‌صورت عمیق ادغام می‌شوند (مورد بعدی اولویت دارد)، تا عمق 10 سطح تودرتو
• کلیدهای هم‌سطح: پس از includeها ادغام می‌شوند (مقادیر includeشده را بازنویسی می‌کنند)
• مسیرهای نسبی: نسبت به فایل includeکننده تفکیک می‌شوند
• قالب مسیر: مسیرهای include نباید شامل بایت null باشند و باید پیش و پس از تفکیک، اکیداً کوتاه‌تر از 4096 نویسه باشند
• نوشتن‌های متعلق به OpenClaw: وقتی یک نوشتن فقط یک بخش سطح‌بالا را تغییر می‌دهد که پشتوانه آن یک include تک‌فایلی مانند plugins: { $include: "./plugins.json5" } است، OpenClaw همان فایل includeشده را به‌روزرسانی می‌کند و openclaw.json را دست‌نخورده باقی می‌گذارد
• نوشتن عبوری پشتیبانی‌نشده: includeهای ریشه، آرایه‌های include و includeهایی که بازنویسی هم‌سطح دارند، برای نوشتن‌های متعلق به OpenClaw به‌صورت بسته و ایمن شکست می‌خورند، به‌جای اینکه پیکربندی را تخت کنند
• محصورسازی: مسیرهای $include باید در دایرکتوری نگهدارنده openclaw.json تفکیک شوند. برای اشتراک‌گذاری یک درخت میان چند ماشین یا کاربر، OPENCLAW_INCLUDE_ROOTS را روی فهرستی از مسیرها (: در POSIX، ‏; در Windows) شامل دایرکتوری‌های اضافی قابل ارجاع توسط includeها تنظیم کنید. پیوندهای نمادین تفکیک و دوباره بررسی می‌شوند؛ بنابراین مسیری که از نظر واژگانی در دایرکتوری پیکربندی قرار دارد، اما مقصد واقعی‌اش از همه ریشه‌های مجاز خارج می‌شود، همچنان رد خواهد شد.
• مدیریت خطا: خطاهای روشن برای فایل‌های مفقود، خطاهای تجزیه، includeهای حلقوی، قالب نامعتبر مسیر و طول بیش‌ازحد