پیکربندی

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

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

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

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

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

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

{
  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 } },
    },
  },
}

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

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

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

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

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

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

{
  gateway: {
    handshakeTimeoutMs: 30000,
  },
}

• مقدار پیش‌فرض 15000 میلی‌ثانیه است.
• OPENCLAW_HANDSHAKE_TIMEOUT_MS همچنان برای بازنویسی‌های موردی سرویس یا پوسته اولویت دارد.
• ابتدا رفع توقف‌های راه‌اندازی/حلقه رویداد را ترجیح دهید؛ این کنترل برای میزبان‌هایی است که سالم‌اند اما هنگام گرم‌شدن کند هستند.

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

{
  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 پشتیبانی می‌کند).
• برای دامنه‌بندی، پیوندهای هویت، و سیاست ارسال، مدیریت نشست را ببینید.
• برای همه فیلدها، مرجع کامل را ببینید.

نشست‌های agent را در 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 § تصاویر و راه‌اندازی ببینید.

برای راهنمای کامل، 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 خارجی ارسال کند.
• از یک مجوز ارسال scoped به ثبت‌نام استفاده می‌کند که app جفت‌شده iOS آن را forward کرده است. gateway به token relay در سطح deployment نیاز ندارد.
• هر ثبت‌نام مبتنی بر relay را به هویت gatewayای که app iOS با آن جفت شده است bind می‌کند، بنابراین gateway دیگری نمی‌تواند از ثبت‌نام ذخیره‌شده دوباره استفاده کند.
• buildهای محلی/دستی iOS را روی APNs مستقیم نگه می‌دارد. ارسال‌های مبتنی بر relay فقط برای buildهای توزیع‌شده رسمی اعمال می‌شوند که از طریق relay ثبت‌نام کرده‌اند.
• باید با URL پایه relay که در build رسمی/TestFlight iOS baked شده است مطابقت داشته باشد، تا ترافیک ثبت‌نام و ارسال به همان deployment relay برسد.

جریان انتهابه‌انتها:

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

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

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

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

• OPENCLAW_APNS_RELAY_BASE_URL و OPENCLAW_APNS_RELAY_TIMEOUT_MS همچنان به‌عنوان overrideهای موقت env کار می‌کنند.
• OPENCLAW_APNS_RELAY_ALLOW_HTTP=true همچنان یک راه فرار توسعه فقط برای loopback است؛ URLهای relay مبتنی بر HTTP را در config ماندگار نکنید.

برای جریان انتهابه‌انتها، app 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: نشست‌های run ایزوله تکمیل‌شده را از sessions.json prune می‌کند (پیش‌فرض 24h؛ برای غیرفعال‌سازی false را تنظیم کنید).
• runLog: cron/runs/<jobId>.jsonl را بر اساس اندازه و خطوط نگه‌داشته‌شده prune می‌کند.
• برای نمای کلی قابلیت و مثال‌های CLI، jobهای 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 اختصاصی استفاده کنید؛ token مشترک Gateway را دوباره استفاده نکنید.
• احراز هویت hook فقط header-only است (Authorization: Bearer ... یا x-openclaw-token)؛ tokenهای query-string رد می‌شوند.
• hooks.path نمی‌تواند / باشد؛ ingress webhook را روی یک subpath اختصاصی مانند /hooks نگه دارید.
• flagهای bypass محتوای ناامن را غیرفعال نگه دارید (hooks.gmail.allowUnsafeExternalContent، hooks.mappings[].allowUnsafeExternalContent) مگر برای debugging با دامنه کاملا محدود.
• اگر hooks.allowRequestSessionKey را فعال می‌کنید، hooks.allowedSessionKeyPrefixes را هم تنظیم کنید تا کلیدهای نشست انتخاب‌شده توسط caller محدود شوند.
• برای agentهای hook-driven، tierهای مدل مدرن و قوی و policy سخت‌گیرانه ابزار را ترجیح دهید (برای مثال فقط messaging به‌همراه sandboxing در صورت امکان).

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

چند agent ایزوله را با 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های دسترسی per-agent، Multi-Agent و مرجع کامل را ببینید.

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

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

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