Discord

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

• [[reply_to_current]]
• [[reply_to:<id>]]

توسط channels.discord.replyToMode کنترل می‌شود:

• off (پیش‌فرض)
• first
• all
• batched

نکته: off رشته‌سازی ضمنی پاسخ را غیرفعال می‌کند. برچسب‌های صریح [[reply_to_*]] همچنان رعایت می‌شوند. first همیشه ارجاع پاسخ بومی ضمنی را به نخستین پیام خروجی Discord برای آن نوبت متصل می‌کند. batched فقط زمانی ارجاع پاسخ بومی ضمنی Discord را متصل می‌کند که نوبت ورودی یک دسته کاهش‌نوسان‌یافته از چند پیام باشد. این زمانی مفید است که پاسخ‌های بومی را عمدتا برای چت‌های مبهم و انفجاری بخواهید، نه برای هر نوبت تک‌پیامی.

شناسه‌های پیام در زمینه/تاریخچه ارائه می‌شوند تا عامل‌ها بتوانند پیام‌های خاص را هدف بگیرند.

OpenClaw می‌تواند با ارسال یک پیام موقت و ویرایش آن هم‌زمان با رسیدن متن، پاسخ‌های پیش‌نویس را پخش کند. channels.discord.streaming مقدارهای off | partial | block | progress (پیش‌فرض) را می‌پذیرد. progress یک پیش‌نویس وضعیت قابل ویرایش نگه می‌دارد و تا تحویل نهایی آن را با پیشرفت ابزار به‌روزرسانی می‌کند؛ streamMode یک نام مستعار قدیمی زمان اجرا است. openclaw doctor --fix را اجرا کنید تا پیکربندی ماندگارشده به کلید استاندارد بازنویسی شود.

برای غیرفعال کردن ویرایش‌های پیش‌نمایش Discord، channels.discord.streaming.mode را روی off بگذارید. اگر پخش بلوکی Discord صراحتا فعال شده باشد، OpenClaw برای جلوگیری از پخش دوباره، جریان پیش‌نمایش را رد می‌کند.

{
channels: {
discord: {
  streaming: {
    mode: "progress",
    progress: {
      label: "auto",
      maxLines: 8,
      toolProgress: true,
    },
  },
},
},
}

• partial هنگام رسیدن توکن‌ها یک پیام پیش‌نمایش واحد را ویرایش می‌کند.
• block قطعه‌هایی به اندازه پیش‌نویس منتشر می‌کند (برای تنظیم اندازه و نقاط شکست از draftChunk استفاده کنید؛ محدود به textChunkLimit).
• رسانه، خطا، و نهایی‌های پاسخ صریح، ویرایش‌های پیش‌نمایش معلق را لغو می‌کنند.
• streaming.preview.toolProgress (پیش‌فرض true) کنترل می‌کند که آیا به‌روزرسانی‌های ابزار/پیشرفت از پیام پیش‌نمایش دوباره استفاده کنند یا نه.
• streaming.preview.commandText / streaming.progress.commandText جزئیات دستور/اجرا را در خط‌های پیشرفت فشرده کنترل می‌کند: raw (پیش‌فرض) یا status (فقط برچسب ابزار).

متن خام دستور/اجرا را پنهان کنید، در حالی که خط‌های پیشرفت فشرده حفظ می‌شوند:

{
  "channels": {
    "discord": {
      "streaming": {
        "mode": "progress",
        "progress": {
          "toolProgress": true,
          "commandText": "status"
        }
      }
    }
  }
}

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

زمینه تاریخچه Guild:

• پیش‌فرض channels.discord.historyLimit برابر 20
• جایگزین: messages.groupChat.historyLimit
• 0 غیرفعال می‌کند

کنترل‌های تاریخچه DM:

• channels.discord.dmHistoryLimit
• channels.discord.dms["<user_id>"].historyLimit

رفتار رشته:

• رشته‌های Discord به عنوان نشست‌های کانال مسیریابی می‌شوند و مگر اینکه بازنویسی شده باشند، پیکربندی کانال والد را به ارث می‌برند.
• نشست‌های رشته، انتخاب /model در سطح نشست کانال والد را فقط به عنوان جایگزین مدل به ارث می‌برند؛ انتخاب‌های /model محلی رشته همچنان اولویت دارند و تاریخچه رونوشت والد کپی نمی‌شود مگر اینکه ارث‌بری رونوشت فعال باشد.
• channels.discord.thread.inheritParent (پیش‌فرض false) رشته‌های خودکار جدید را وارد بذرگذاری از رونوشت والد می‌کند. بازنویسی‌های هر حساب زیر channels.discord.accounts.<id>.thread.inheritParent قرار دارند.
• واکنش‌های ابزار پیام می‌توانند هدف‌های DM با قالب user:<id> را حل کنند.
• guilds.<guild>.channels.<channel>.requireMention: false هنگام جایگزین فعال‌سازی مرحله پاسخ حفظ می‌شود.

موضوع‌های کانال به عنوان زمینه نامطمئن تزریق می‌شوند. فهرست‌های مجاز کنترل می‌کنند چه کسی می‌تواند عامل را فعال کند، نه یک مرز کامل حذف زمینه تکمیلی.

Discord می‌تواند یک رشته را به هدف نشست متصل کند تا پیام‌های بعدی در آن رشته همچنان به همان نشست مسیریابی شوند (از جمله نشست‌های زیرعامل).

دستورها:

• /focus <target> رشته فعلی/جدید را به یک هدف زیرعامل/نشست متصل می‌کند
• /unfocus اتصال رشته فعلی را حذف می‌کند
• /agents اجراهای فعال و وضعیت اتصال را نشان می‌دهد
• /session idle <duration|off> عدم فعالیت auto-unfocus را برای اتصال‌های متمرکز بررسی/به‌روزرسانی می‌کند
• /session max-age <duration|off> حداکثر عمر سخت را برای اتصال‌های متمرکز بررسی/به‌روزرسانی می‌کند

پیکربندی:

{
session: {
threadBindings: {
  enabled: true,
  idleHours: 24,
  maxAgeHours: 0,
},
},
channels: {
discord: {
  threadBindings: {
    enabled: true,
    idleHours: 24,
    maxAgeHours: 0,
    spawnSessions: true,
    defaultSpawnContext: "fork",
  },
},
},
}

نکته‌ها:

• session.threadBindings.* پیش‌فرض‌های سراسری را تنظیم می‌کند.
• channels.discord.threadBindings.* رفتار Discord را بازنویسی می‌کند.
• spawnSessions ایجاد/اتصال خودکار رشته‌ها را برای sessions_spawn({ thread: true }) و ایجاد رشته‌های ACP کنترل می‌کند. پیش‌فرض: true.
• defaultSpawnContext زمینه بومی زیرعامل را برای ایجادهای وابسته به رشته کنترل می‌کند. پیش‌فرض: "fork".
• کلیدهای منسوخ spawnSubagentSessions/spawnAcpSessions توسط openclaw doctor --fix مهاجرت داده می‌شوند.
• اگر اتصال‌های رشته برای یک حساب غیرفعال باشند، /focus و عملیات مرتبط اتصال رشته در دسترس نیستند.

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

برای فضاهای کاری ACP پایدار و "always-on"، اتصال‌های ACP تایپ‌شده سطح بالا را پیکربندی کنید که گفت‌وگوهای Discord را هدف می‌گیرند.

مسیر پیکربندی:

• bindings[] با type: "acp" و match.channel: "discord"

نمونه:

{
agents: {
list: [
  {
    id: "codex",
    runtime: {
      type: "acp",
      acp: {
        agent: "codex",
        backend: "acpx",
        mode: "persistent",
        cwd: "/workspace/openclaw",
      },
    },
  },
],
},
bindings: [
{
  type: "acp",
  agentId: "codex",
  match: {
    channel: "discord",
    accountId: "default",
    peer: { kind: "channel", id: "222222222222222222" },
  },
  acp: { label: "codex-main" },
},
],
channels: {
discord: {
  guilds: {
    "111111111111111111": {
      channels: {
        "222222222222222222": {
          requireMention: false,
        },
      },
    },
  },
},
},
}

نکته‌ها:

• /acp spawn codex --bind here کانال یا رشته فعلی را در همان‌جا متصل می‌کند و پیام‌های آینده را روی همان نشست ACP نگه می‌دارد. پیام‌های رشته اتصال کانال والد را به ارث می‌برند.
• در یک کانال یا رشته متصل، /new و /reset همان نشست ACP را در همان‌جا بازنشانی می‌کنند. اتصال‌های موقت رشته می‌توانند در زمان فعال بودن، حل هدف را بازنویسی کنند.
• spawnSessions ایجاد/اتصال رشته فرزند را از طریق --thread auto|here کنترل می‌کند.

برای جزئیات رفتار اتصال، عامل‌های ACP را ببینید.

حالت اعلان واکنش برای هر Guild:

• off
• own (پیش‌فرض)
• all
• allowlist (از guilds.<id>.users استفاده می‌کند)

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

ackReaction هنگامی که OpenClaw در حال پردازش یک پیام ورودی است، یک ایموجی تأیید ارسال می‌کند.

ترتیب حل:

• channels.discord.accounts.<accountId>.ackReaction
• channels.discord.ackReaction
• messages.ackReaction
• جایگزین ایموجی هویت عامل (agents.list[].identity.emoji، در غیر این صورت "👀")

نکته‌ها:

• Discord ایموجی یونیکد یا نام‌های ایموجی سفارشی را می‌پذیرد.
• برای غیرفعال کردن واکنش برای یک کانال یا حساب از "" استفاده کنید.

نوشتن‌های پیکربندی آغازشده از کانال به طور پیش‌فرض فعال هستند.

این بر جریان‌های /config set|unset اثر می‌گذارد (وقتی قابلیت‌های دستور فعال باشند).

غیرفعال‌سازی:

{
channels: {
discord: {
  configWrites: false,
},
},
}

ترافیک WebSocket گیت‌وی Discord و جست‌وجوهای REST هنگام راه‌اندازی (شناسه برنامه + حل فهرست مجاز) را با channels.discord.proxy از طریق یک پراکسی HTTP(S) مسیریابی کنید.

{
channels: {
discord: {
  proxy: "http://proxy.example:8080",
},
},
}

بازنویسی برای هر حساب:

{
channels: {
discord: {
  accounts: {
    primary: {
      proxy: "http://proxy.example:8080",
    },
  },
},
},
}

حل PluralKit را فعال کنید تا پیام‌های پروکسی‌شده به هویت عضو سامانه نگاشت شوند:

{
channels: {
discord: {
  pluralkit: {
    enabled: true,
    token: "pk_live_...", // optional; needed for private systems
  },
},
},
}

نکته‌ها:

• فهرست‌های مجاز می‌توانند از pk:<memberId> استفاده کنند
• نام‌های نمایشی عضو فقط وقتی با نام/slug تطبیق داده می‌شوند که channels.discord.dangerouslyAllowNameMatching: true باشد
• جست‌وجوها از شناسه پیام اصلی استفاده می‌کنند و به پنجره زمانی محدود هستند
• اگر جست‌وجو ناموفق باشد، پیام‌های پروکسی‌شده به عنوان پیام‌های ربات در نظر گرفته می‌شوند و حذف می‌شوند، مگر اینکه allowBots=true باشد

وقتی عامل‌ها به منشن‌های خروجی قطعی برای کاربران شناخته‌شده Discord نیاز دارند، از mentionAliases استفاده کنید. کلیدها هندل‌های بدون @ ابتدایی هستند؛ مقدارها شناسه‌های کاربر Discord هستند. هندل‌های ناشناخته، @everyone، @here، و منشن‌های داخل code spanهای Markdown بدون تغییر باقی می‌مانند.

{
channels: {
discord: {
  mentionAliases: {
    Vladislava: "123456789012345678",
  },
  accounts: {
    ops: {
      mentionAliases: {
        OpsLead: "234567890123456789",
      },
    },
  },
},
},
}

وقتی یک وضعیت یا فیلد فعالیت تنظیم می‌کنید، یا وقتی حضور خودکار را فعال می‌کنید، به‌روزرسانی‌های حضور اعمال می‌شوند.

نمونه فقط وضعیت:

{
channels: {
discord: {
  status: "idle",
},
},
}

نمونه فعالیت (وضعیت سفارشی نوع فعالیت پیش‌فرض است):

{
channels: {
discord: {
  activity: "Focus time",
  activityType: 4,
},
},
}

نمونه پخش:

{
channels: {
discord: {
  activity: "Live coding",
  activityType: 1,
  activityUrl: "https://twitch.tv/openclaw",
},
},
}

نگاشت نوع فعالیت:

• 0: در حال بازی
• 1: در حال پخش (به activityUrl نیاز دارد)
• 2: در حال گوش دادن
• 3: در حال تماشا
• 4: سفارشی (از متن فعالیت به عنوان وضعیت استفاده می‌کند؛ ایموجی اختیاری است)
• 5: در حال رقابت

نمونه حضور خودکار (سیگنال سلامت زمان اجرا):

{
channels: {
discord: {
  autoPresence: {
    enabled: true,
    intervalMs: 30000,
    minUpdateIntervalMs: 15000,
    exhaustedText: "token exhausted",
  },
},
},
}

حضور خودکار، دسترسی‌پذیری زمان اجرا را به وضعیت Discord نگاشت می‌کند: healthy => online، degraded یا unknown => idle، exhausted یا unavailable => dnd. بازنویسی‌های اختیاری متن:

• autoPresence.healthyText
• autoPresence.degradedText
• autoPresence.exhaustedText (از جای‌نگهدار {reason} پشتیبانی می‌کند)

Discord از رسیدگی به تاییدهای مبتنی بر دکمه در پیام‌های خصوصی پشتیبانی می‌کند و می‌تواند به‌صورت اختیاری درخواست‌های تایید را در کانال مبدا ارسال کند.

مسیر پیکربندی:

• channels.discord.execApprovals.enabled
• channels.discord.execApprovals.approvers (اختیاری؛ در صورت امکان به commands.ownerAllowFrom برمی‌گردد)
• channels.discord.execApprovals.target (dm | channel | both، پیش‌فرض: dm)
• agentFilter، sessionFilter، cleanupAfterResolve

وقتی enabled تنظیم نشده باشد یا "auto" باشد و حداقل یک تاییدکننده قابل حل باشد، چه از execApprovals.approvers و چه از commands.ownerAllowFrom، Discord تاییدهای exec بومی را به‌صورت خودکار فعال می‌کند. Discord تاییدکنندگان exec را از allowFrom کانال، dm.allowFrom قدیمی، یا defaultTo پیام مستقیم استنتاج نمی‌کند. برای غیرفعال‌کردن صریح Discord به‌عنوان کلاینت تایید بومی، enabled: false را تنظیم کنید.

برای فرمان‌های گروهی حساس و فقط مالک، مانند /diagnostics و /export-trajectory، OpenClaw درخواست‌های تایید و نتایج نهایی را به‌صورت خصوصی ارسال می‌کند. ابتدا وقتی مالک فراخواننده یک مسیر مالک Discord داشته باشد، پیام خصوصی Discord را امتحان می‌کند؛ اگر در دسترس نباشد، به اولین مسیر مالک در دسترس از commands.ownerAllowFrom، مانند Telegram، برمی‌گردد.

وقتی target برابر channel یا both باشد، درخواست تایید در کانال قابل مشاهده است. فقط تاییدکنندگان حل‌شده می‌توانند از دکمه‌ها استفاده کنند؛ کاربران دیگر یک رد موقت دریافت می‌کنند. درخواست‌های تایید شامل متن فرمان هستند، بنابراین تحویل در کانال را فقط در کانال‌های مورد اعتماد فعال کنید. اگر شناسه کانال از کلید نشست قابل استخراج نباشد، OpenClaw به تحویل از طریق پیام خصوصی برمی‌گردد.

Discord همچنین دکمه‌های تایید مشترکی را که کانال‌های چت دیگر استفاده می‌کنند نمایش می‌دهد. آداپتر بومی Discord عمدتا مسیریابی پیام خصوصی تاییدکننده و انتشار در کانال را اضافه می‌کند. وقتی آن دکمه‌ها وجود داشته باشند، UX اصلی تایید هستند؛ OpenClaw فقط زمانی باید فرمان دستی /approve را شامل کند که نتیجه ابزار بگوید تاییدهای چت در دسترس نیستند یا تایید دستی تنها مسیر است. اگر زمان اجرای تایید بومی Discord فعال نباشد، OpenClaw اعلان قطعی محلی /approve <id> <decision> را قابل مشاهده نگه می‌دارد. اگر زمان اجرا فعال باشد اما کارت بومی به هیچ هدفی قابل تحویل نباشد، OpenClaw یک اعلان جایگزین در همان چت با فرمان دقیق /approve از تایید در انتظار ارسال می‌کند.

احراز هویت Gateway و حل تایید از قرارداد مشترک کلاینت Gateway پیروی می‌کنند (شناسه‌های plugin: از طریق plugin.approval.resolve حل می‌شوند؛ شناسه‌های دیگر از طریق exec.approval.resolve). تاییدها به‌صورت پیش‌فرض پس از ۳۰ دقیقه منقضی می‌شوند.

تاییدهای exec را ببینید.

• Message Content Intent را فعال کنید
• وقتی به حل کاربر/عضو وابسته هستید، Server Members Intent را فعال کنید
• پس از تغییر intentها، gateway را راه‌اندازی مجدد کنید

• groupPolicy را بررسی کنید
• allowlist گیلد را زیر channels.discord.guilds بررسی کنید
• اگر نگاشت channels گیلد وجود داشته باشد، فقط کانال‌های فهرست‌شده مجاز هستند
• رفتار requireMention و الگوهای mention را بررسی کنید

بررسی‌های مفید:

openclaw doctor
openclaw channels status --probe
openclaw logs --follow

علت‌های رایج:

• groupPolicy="allowlist" بدون allowlist گیلد/کانال منطبق
• requireMention در جای اشتباه پیکربندی شده است (باید زیر channels.discord.guilds یا ورودی کانال باشد)
• فرستنده توسط allowlist users گیلد/کانال مسدود شده است

لاگ‌های معمول:

• Slow listener detected ...
• stuck session: sessionKey=agent:...:discord:... state=processing ...

پیچ‌های تنظیم صف Gateway در Discord:

• حساب تکی: channels.discord.eventQueue.listenerTimeout
• چندحسابی: channels.discord.accounts.<accountId>.eventQueue.listenerTimeout
• این فقط کار listener Gateway در Discord را کنترل می‌کند، نه طول عمر نوبت agent

Discord برای نوبت‌های agent صف‌شده، timeout متعلق به کانال اعمال نمی‌کند. listenerهای پیام بلافاصله تحویل می‌دهند، و اجراهای صف‌شده Discord ترتیب هر نشست را تا زمانی که چرخه عمر نشست/ابزار/زمان اجرا کامل شود یا کار را لغو کند حفظ می‌کنند.

{
channels: {
discord: {
  accounts: {
    default: {
      eventQueue: {
        listenerTimeout: 120000,
      },
    },
  },
},
},
}

OpenClaw پیش از اتصال، فراداده Discord /gateway/bot را دریافت می‌کند. شکست‌های گذرا به URL پیش‌فرض Gateway در Discord بازمی‌گردند و در لاگ‌ها محدودیت نرخ دارند.

تنظیمات اتمام مهلت فراداده:

• تک‌حساب: channels.discord.gatewayInfoTimeoutMs
• چندحساب: channels.discord.accounts.<accountId>.gatewayInfoTimeoutMs
• جایگزین محیطی وقتی پیکربندی تنظیم نشده باشد: OPENCLAW_DISCORD_GATEWAY_INFO_TIMEOUT_MS
• پیش‌فرض: 30000 (۳۰ ثانیه)، حداکثر: 120000

OpenClaw هنگام راه‌اندازی و پس از اتصال‌های مجدد در زمان اجرا، منتظر رویداد READY مربوط به Gateway در Discord می‌ماند. راه‌اندازی‌های چندحساب با فاصله‌گذاری راه‌اندازی ممکن است به پنجره طولانی‌تری برای READY هنگام شروع نسبت به مقدار پیش‌فرض نیاز داشته باشند.

تنظیمات اتمام مهلت READY:

• راه‌اندازی تک‌حساب: channels.discord.gatewayReadyTimeoutMs
• راه‌اندازی چندحساب: channels.discord.accounts.<accountId>.gatewayReadyTimeoutMs
• جایگزین محیطی راه‌اندازی وقتی پیکربندی تنظیم نشده باشد: OPENCLAW_DISCORD_READY_TIMEOUT_MS
• پیش‌فرض راه‌اندازی: 15000 (۱۵ ثانیه)، حداکثر: 120000
• زمان اجرا تک‌حساب: channels.discord.gatewayRuntimeReadyTimeoutMs
• زمان اجرا چندحساب: channels.discord.accounts.<accountId>.gatewayRuntimeReadyTimeoutMs
• جایگزین محیطی زمان اجرا وقتی پیکربندی تنظیم نشده باشد: OPENCLAW_DISCORD_RUNTIME_READY_TIMEOUT_MS
• پیش‌فرض زمان اجرا: 30000 (۳۰ ثانیه)، حداکثر: 120000

بررسی‌های مجوز channels status --probe فقط برای شناسه‌های عددی کانال کار می‌کنند.

اگر از کلیدهای slug استفاده می‌کنید، تطبیق در زمان اجرا همچنان می‌تواند کار کند، اما probe نمی‌تواند مجوزها را به‌طور کامل راستی‌آزمایی کند.

• DM غیرفعال: channels.discord.dm.enabled=false
• سیاست DM غیرفعال: channels.discord.dmPolicy="disabled" (قدیمی: channels.discord.dm.policy)
• در انتظار تأیید جفت‌سازی در حالت pairing

به‌طور پیش‌فرض پیام‌های نوشته‌شده توسط bot نادیده گرفته می‌شوند.

اگر channels.discord.allowBots=true را تنظیم می‌کنید، از قوانین سخت‌گیرانه mention و allowlist استفاده کنید تا از رفتار حلقه‌ای جلوگیری شود. ترجیحاً از channels.discord.allowBots="mentions" استفاده کنید تا فقط پیام‌های bot را بپذیرید که به bot اشاره می‌کنند.

{
channels: {
discord: {
  accounts: {
    mantis: {
      // Mantis listens to other bots only when they mention her.
      allowBots: "mentions",
    },
    molty: {
      // Molty listens to all bot-authored Discord messages.
      allowBots: true,
      mentionAliases: {
        // Lets Molty write "@Mantis" and send a real Discord mention.
        Mantis: "MANTIS_DISCORD_USER_ID",
      },
    },
  },
},
},
}

• OpenClaw را به‌روز نگه دارید (openclaw update) تا منطق بازیابی دریافت صدای Discord وجود داشته باشد
• تأیید کنید channels.discord.voice.daveEncryption=true (پیش‌فرض)
• از channels.discord.voice.decryptionFailureTolerance=24 (پیش‌فرض upstream) شروع کنید و فقط در صورت نیاز تنظیم کنید
• لاگ‌ها را برای موارد زیر بررسی کنید:
  • discord voice: DAVE decrypt failures detected
  • discord voice: repeated decrypt failures; attempting rejoin
• اگر شکست‌ها پس از پیوستن مجدد خودکار ادامه داشتند، لاگ‌ها را جمع‌آوری کنید و با تاریخچه دریافت DAVE در upstream در discord.js #11419 و discord.js #11449 مقایسه کنید