Discord

OpenClaw از طریق Gateway رسمی Discord به‌عنوان یک بات به Discord متصل می‌شود. پیام‌های خصوصی و کانال‌های سرور پشتیبانی می‌شوند.

راه‌اندازی سریع

یک برنامه Discord همراه با یک بات بسازید، بات را به سرور خود اضافه کنید و آن را با OpenClaw جفت کنید. در صورت امکان از یک سرور خصوصی استفاده کنید؛ اگر لازم است، ابتدا یکی بسازید (Create My Own > For me and my friends).

export DISCORD_BOT_TOKEN="YOUR_BOT_TOKEN"cat > discord.patch.json5 <<'JSON5'{channels: {discord: {  enabled: true,  token: { source: "env", provider: "default", id: "DISCORD_BOT_TOKEN" },},},}JSON5openclaw config patch --file ./discord.patch.json5 --dry-runopenclaw config patch --file ./discord.patch.json5openclaw gateway

{channels: {discord: {enabled: true,token: {source: "env",provider: "default",id: "DISCORD_BOT_TOKEN",},},},}

DISCORD_BOT_TOKEN=...

{channels: {discord: {enabled: true,accounts: {personal: {  token: { source: "env", provider: "default", id: "DISCORD_PERSONAL_TOKEN" },  applicationId: "111111111111111111",},work: {  token: { source: "env", provider: "default", id: "DISCORD_WORK_TOKEN" },  applicationId: "222222222222222222",},},},},}

openclaw pairing list discordopenclaw pairing approve discord <CODE>

توصیه‌شده: راه‌اندازی فضای کاری سرور

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

{channels: {discord: {groupPolicy: "allowlist",guilds: {YOUR_SERVER_ID: {  requireMention: true,  users: ["YOUR_USER_ID"],},},},},}

{channels: {discord: {guilds: {YOUR_SERVER_ID: {  requireMention: false,},},},},}

اکنون کانال‌ها را بسازید و گفت‌وگو را آغاز کنید. عامل نام کانال را می‌بیند و هر کانال یک نشست مجزا است — #coding، #home، #research یا هر ساختاری را که با گردش‌کار شما سازگار است راه‌اندازی کنید.

مدل زمان اجرا

• Gateway مالک اتصال Discord است.
• مسیریابی پاسخ قطعی است: پاسخ ورودی Discord دوباره به Discord فرستاده می‌شود.
• فراداده سرور/کانال Discord به‌عنوان زمینه غیرقابل‌اعتماد به پرامپت مدل افزوده می‌شود، نه به‌عنوان پیشوند قابل‌مشاهده پاسخ کاربر. اگر مدلی آن پوشش را دوباره کپی کند، OpenClaw فراداده کپی‌شده را از پاسخ‌های خروجی و زمینه بازپخش آینده حذف می‌کند.
• به‌طور پیش‌فرض (session.dmScope=main)، گفت‌وگوهای مستقیم نشست اصلی عامل (agent:main:main) را به‌اشتراک می‌گذارند.
• کانال‌های سرور کلیدهای نشست مجزا هستند (agent:<agentId>:discord:channel:<channelId>).
• پیام‌های خصوصی گروهی به‌طور پیش‌فرض نادیده گرفته می‌شوند (channels.discord.dm.groupEnabled=false).
• دستورهای اسلش بومی در نشست‌های دستور مجزا اجرا می‌شوند (agent:<agentId>:discord:slash:<userId>)، در حالی که همچنان CommandTargetSessionKey را به نشست گفت‌وگوی مسیریابی‌شده منتقل می‌کنند.
• تحویل اعلان‌های Cron/Heartbeat صرفاً متنی به Discord به پاسخ نهایی قابل‌مشاهده دستیار تبدیل می‌شود و یک بار ارسال می‌گردد. هنگامی که عامل چند محتوای قابل‌تحویل تولید می‌کند، رسانه‌ها و محتوای ساختاریافته مؤلفه‌ها همچنان به‌صورت چندپیامی باقی می‌مانند.

کانال‌های انجمن

کانال‌های انجمن و رسانه‌ای Discord فقط نوشته‌های رشته را می‌پذیرند. OpenClaw از دو روش برای ایجاد آن‌ها پشتیبانی می‌کند:

• برای ایجاد خودکار یک رشته، پیامی به والد انجمن (channel:<forumId>) ارسال کنید. عنوان رشته نخستین خط غیرخالی پیام است (با کوتاه‌سازی مطابق محدودیت 100 نویسه‌ای Discord برای نام رشته).
• برای ایجاد مستقیم یک رشته، از openclaw message thread create استفاده کنید. برای کانال‌های انجمن، --message-id را ارسال نکنید.

برای ایجاد رشته، به والد انجمن ارسال کنید:

openclaw message send --channel discord --target channel:<forumId> \  --message "عنوان موضوع\nمتن نوشته"

یک رشته انجمن را به‌صراحت ایجاد کنید:

openclaw message thread create --channel discord --target channel:<forumId> \  --thread-name "عنوان موضوع" --message "متن نوشته"

والدهای انجمن مؤلفه‌های Discord را نمی‌پذیرند. اگر به مؤلفه‌ها نیاز دارید، پیام را به خود رشته (channel:<threadId>) ارسال کنید.

مؤلفه‌های تعاملی

OpenClaw از محفظه‌های مؤلفه v2 در Discord برای پیام‌های عامل پشتیبانی می‌کند. از ابزار پیام با محموله components استفاده کنید. نتایج تعامل به‌صورت پیام‌های ورودی عادی به عامل بازگردانده می‌شوند و از تنظیمات موجود replyToMode در Discord پیروی می‌کنند.

بلوک‌های پشتیبانی‌شده:

• text، section، separator، actions، media-gallery، file
• ردیف‌های کنش حداکثر 5 دکمه یا یک منوی انتخاب را مجاز می‌دانند
• انواع انتخاب: string، user، role، mentionable، channel

مؤلفه‌ها به‌طور پیش‌فرض یک‌بارمصرف هستند. برای اینکه دکمه‌ها، گزینه‌های انتخاب و فرم‌ها تا زمان انقضا چندین بار قابل‌استفاده باشند، components.reusable=true را تنظیم کنید.

برای محدودکردن افرادی که می‌توانند روی یک دکمه کلیک کنند، allowedUsers را روی آن دکمه تنظیم کنید (شناسه‌های کاربری Discord، برچسب‌ها یا *). کاربران نامنطبق یک پیام رد موقت دریافت می‌کنند.

فراخوان‌های بازگشتی مؤلفه‌ها به‌طور پیش‌فرض پس از 30 دقیقه منقضی می‌شوند. برای تغییر طول عمر رجیستری فراخوان بازگشتی حساب پیش‌فرض، channels.discord.agentComponents.ttlMs و برای هر حساب، channels.discord.accounts.<accountId>.agentComponents.ttlMs را تنظیم کنید. مقدار برحسب میلی‌ثانیه است، باید عدد صحیح مثبت باشد و حداکثر آن 86400000 (24 ساعت) است. TTLهای طولانی‌تر برای جریان‌های کاری بازبینی/تأیید مناسب‌اند که لازم است دکمه‌هایشان قابل‌استفاده بمانند، اما بازه‌ای را افزایش می‌دهند که طی آن یک پیام قدیمی Discord همچنان می‌تواند کنشی را فعال کند. کوتاه‌ترین TTL مناسب را ترجیح دهید و هنگامی که فراخوان‌های بازگشتی منسوخ غیرمنتظره خواهند بود، مقدار پیش‌فرض را حفظ کنید.

فرمان‌های اسلش /model و /models یک انتخاب‌گر تعاملی مدل را با فهرست‌های کشویی ارائه‌دهنده، مدل و زمان‌اجرای سازگار، به‌همراه مرحله Submit باز می‌کنند. /models add منسوخ شده است و به‌جای ثبت مدل‌ها از طریق گپ، پیام منسوخ‌شدن برمی‌گرداند. پاسخ انتخاب‌گر موقت است و فقط کاربری که آن را فراخوانده می‌تواند از آن استفاده کند. منوهای انتخاب Discord به 25 گزینه محدودند؛ بنابراین وقتی می‌خواهید انتخاب‌گر مدل‌های کشف‌شده پویا را فقط برای ارائه‌دهندگان منتخب مانند openai یا vllm نمایش دهد، ورودی‌های provider/* را به agents.defaults.modelPolicy.allow اضافه کنید.

پیوست‌های فایل:

• بلوک‌های file باید به یک ارجاع پیوست (attachment://<filename>) اشاره کنند
• پیوست را از طریق media/path/filePath (یک فایل) ارائه کنید؛ برای چند فایل از media-gallery استفاده کنید
• هنگامی که نام بارگذاری باید با ارجاع پیوست مطابقت داشته باشد، برای بازنویسی آن از filename استفاده کنید

فرم‌های مودال:

• components.modal را با حداکثر 5 فیلد اضافه کنید
• انواع فیلد: text، checkbox، radio، select، role-select، user-select
• OpenClaw به‌طور خودکار یک دکمه فعال‌سازی اضافه می‌کند

مثال:

{  channel: "discord",  action: "send",  to: "channel:123456789012345678",  message: "متن جایگزین اختیاری",  components: {    reusable: true,    text: "یک مسیر انتخاب کنید",    blocks: [      {        type: "actions",        buttons: [          {            label: "تأیید",            style: "success",            allowedUsers: ["123456789012345678"],          },          { label: "رد", style: "danger" },        ],      },      {        type: "actions",        select: {          type: "string",          placeholder: "یک گزینه انتخاب کنید",          options: [            { label: "گزینه A", value: "a" },            { label: "گزینه B", value: "b" },          ],        },      },    ],    modal: {      title: "جزئیات",      triggerLabel: "بازکردن فرم",      fields: [        { type: "text", label: "درخواست‌کننده" },        {          type: "select",          label: "اولویت",          options: [            { label: "کم", value: "low" },            { label: "زیاد", value: "high" },          ],        },      ],    },  },}

کنترل دسترسی و مسیریابی

{accessGroups: {operators: {  type: "message.senders",  members: {    "*": ["global-owner-id"],    discord: ["discord:123456789012345678"],    telegram: ["987654321"],  },},},channels: {discord: {  dmPolicy: "allowlist",  allowFrom: ["accessGroup:operators"],},},}

{accessGroups: {maintainers: {  type: "discord.channelAudience",  guildId: "1456350064065904867",  channelId: "1456744319972282449",  membership: "canViewChannel",},},channels: {discord: {  dmPolicy: "allowlist",  allowFrom: ["accessGroup:maintainers"],},},}

{accessGroups: {maintainers: {  type: "discord.channelAudience",  guildId: "1456350064065904867",  channelId: "1456744319972282449",},},channels: {discord: {  dmPolicy: "allowlist",  allowFrom: ["accessGroup:maintainers", "discord:123456789012345678"],},},}

{channels: {discord: {  groupPolicy: "allowlist",  guilds: {    "123456789012345678": {      requireMention: true,      ignoreOtherMentions: true,      users: ["987654321098765432"],      roles: ["123456789012345678"],      channels: {        general: { enabled: true },        help: { enabled: true, requireMention: true },      },    },  },},},}

مسیریابی عامل مبتنی بر نقش

برای مسیریابی اعضای انجمن Discord به عامل‌های مختلف براساس شناسه نقش، از bindings[].match.roles استفاده کنید. اتصال‌های مبتنی بر نقش فقط شناسه نقش را می‌پذیرند و پس از اتصال‌های همتا یا همتای والد و پیش از اتصال‌های صرفاً انجمن ارزیابی می‌شوند. اگر یک اتصال فیلدهای تطبیق دیگری نیز تنظیم کند (برای مثال peer + guildId + roles) همه فیلدهای پیکربندی‌شده باید مطابقت داشته باشند.

{  bindings: [    {      agentId: "opus",      match: {        channel: "discord",        guildId: "123456789012345678",        roles: ["111111111111111111"],      },    },    {      agentId: "sonnet",      match: {        channel: "discord",        guildId: "123456789012345678",      },    },  ],}

فرمان‌های بومی و احراز هویت فرمان‌ها

• commands.native به‌طور پیش‌فرض روی "auto" تنظیم شده و برای Discord فعال است.
• بازنویسی برای هر کانال: channels.discord.commands.native.
• commands.native=false ثبت و پاک‌سازی فرمان‌های اسلش Discord را هنگام راه‌اندازی نادیده می‌گیرد. فرمان‌هایی که پیش‌تر ثبت شده‌اند ممکن است تا زمانی که آن‌ها را از برنامه Discord حذف نکنید، در Discord قابل مشاهده بمانند.
• احراز هویت فرمان‌های بومی از همان فهرست‌های مجاز/سیاست‌های Discord در مدیریت پیام‌های عادی استفاده می‌کند.
• فرمان‌ها ممکن است همچنان در رابط کاربری Discord برای کاربران غیرمجاز قابل مشاهده باشند؛ هنگام اجرا، احراز هویت OpenClaw اعمال می‌شود و پاسخ "مجاز نیست" ارسال می‌شود.
• تنظیمات پیش‌فرض فرمان اسلش: ephemeral: true (channels.discord.slashCommand.ephemeral).

برای مشاهده فهرست فرمان‌ها و رفتار آن‌ها، به فرمان‌های اسلش مراجعه کنید.

جزئیات قابلیت‌ها

{channels: {discord: {  suppressEmbeds: false,},},}

{channels: {discord: {  streaming: {    mode: "progress",    progress: {      maxLines: 8,      maxLineChars: 120,      toolProgress: false,      commentary: false,    },  },},},}

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

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

{channels: {discord: {  subagentProgress: true,},},}

{agents: {entries: {  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,        },      },    },  },},},}

{  channels: {    discord: {      intents: { presence: true },      guilds: {        "111111111111111111": {          presenceEvents: {            channelId: "222222222222222222",            users: ["333333333333333333"], // اختیاری؛ محدودتر کردن مشاهده‌کنندگان کانال            reconnectSuppressSeconds: 300, // اختیاری؛ بازه سکوت نشست جدید (0 غیرفعال می‌کند)            burstLimit: 8, // اختیاری؛ حداکثر رویدادها در هر بازه جهشی            burstWindowSeconds: 60, // اختیاری؛ بازه لغزان تشخیص جهش          },        },      },    },  },}

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

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

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

{channels: {discord: {  pluralkit: {    enabled: true,    token: "pk_live_...", // اختیاری؛ برای سیستم‌های خصوصی لازم است  },},},}

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

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

{channels: {discord: {  activity: "زمان تمرکز",  activityType: 4,},},}

{channels: {discord: {  activity: "کدنویسی زنده",  activityType: 1,  activityUrl: "https://twitch.tv/openclaw",},},}

{channels: {discord: {  autoPresence: {    enabled: true,    intervalMs: 30000,    minUpdateIntervalMs: 15000,    exhaustedText: "توکن تمام شده است",  },},},}

ابزارها و دروازه‌های کنش

کنش‌های پیام Discord پیام‌رسانی، مدیریت کانال، نظارت، حضور و فراداده را پوشش می‌دهند.

نمونه‌های اصلی:

• پیام‌رسانی: sendMessage، readMessages، editMessage، deleteMessage، threadReply
• واکنش‌ها: react، reactions، emojiList
• نظارت: timeout، kick، ban
• حضور: setPresence

کنش event-create یک پارامتر اختیاری image (نشانی URL یا مسیر فایل محلی) را برای تنظیم تصویر روی جلد رویداد زمان‌بندی‌شده می‌پذیرد.

دروازه‌های کنش زیر channels.discord.actions.* قرار دارند.

رفتار پیش‌فرض دروازه:

رابط کاربری مؤلفه‌های v2

OpenClaw برای تأییدهای اجرا و نشانگرهای میان‌زمینه‌ای از مؤلفه‌های v2 در Discord استفاده می‌کند. کنش‌های پیام Discord همچنین می‌توانند برای رابط کاربری سفارشی، components را بپذیرند (پیشرفته؛ نیازمند ساخت یک بارِ مؤلفه از طریق ابزار discord است)، درحالی‌که embeds قدیمی همچنان در دسترس هستند اما توصیه نمی‌شوند.

• channels.discord.ui.components.accentColor رنگ تأکیدیِ استفاده‌شده در محفظه‌های مؤلفه Discord را تنظیم می‌کند (هگز). برای هر حساب: channels.discord.accounts.<id>.ui.components.accentColor.
• channels.discord.agentComponents.ttlMs مدت‌زمان ثبت‌ماندن فراخوانی‌های برگشتی مؤلفه Discord پس از ارسال را کنترل می‌کند (پیش‌فرض 1800000، حداکثر 86400000). برای هر حساب: channels.discord.accounts.<id>.agentComponents.ttlMs.
• embeds هنگام وجود مؤلفه‌های v2 نادیده گرفته می‌شوند.
• پیش‌نمایش URLهای ساده به‌طور پیش‌فرض سرکوب می‌شود. هنگامی که باید یک پیوند خروجی منفرد باز شود، suppressEmbeds: false را روی یک کنش پیام تنظیم کنید.

مثال:

{  channels: {    discord: {      ui: {        components: {          accentColor: "#5865F2",        },      },    },  },}

صوت

Discord دو سطح صوتی متمایز دارد: کانال‌های صوتی بلادرنگ (گفت‌وگوهای پیوسته) و پیوست‌های پیام صوتی (قالب پیش‌نمایش شکل موج). Gateway از هر دو پشتیبانی می‌کند.

کانال‌های صوتی

فهرست بررسی راه‌اندازی:

1. Message Content Intent را در Discord Developer Portal فعال کنید.
2. هنگام استفاده از فهرست‌های مجاز نقش/کاربر، Server Members Intent را فعال کنید.
3. بات را با دامنه‌های bot و applications.commands دعوت کنید.
4. مجوزهای Connect، Speak، Send Messages و Read Message History را در کانال صوتی مقصد اعطا کنید.
5. فرمان‌های بومی (commands.native یا channels.discord.commands.native) را فعال کنید.
6. channels.discord.voice را پیکربندی کنید.

برای کنترل نشست‌ها از /vc join|leave|status استفاده کنید. این فرمان از عامل پیش‌فرض حساب استفاده می‌کند و از همان قواعد فهرست مجاز و خط‌مشی گروهیِ دیگر فرمان‌های Discord پیروی می‌کند.

/vc join channel:<voice-channel-id>/vc status/vc leave

برای بررسی مجوزهای مؤثر بات پیش از پیوستن:

openclaw channels capabilities --channel discord --target channel:<voice-channel-id>

مثال پیوستن خودکار:

{  channels: {    discord: {      voice: {        enabled: true,        model: "openai/gpt-5.6-sol",        autoJoin: [          {            guildId: "123456789012345678",            channelId: "234567890123456789",          },        ],        allowedChannels: [          {            guildId: "123456789012345678",            channelId: "234567890123456789",          },        ],        daveEncryption: true,        decryptionFailureTolerance: 24,        connectTimeoutMs: 30000,        reconnectGraceMs: 15000,        realtime: {          provider: "openai",          model: "gpt-realtime-2.1",          speakerVoice: "cedar",        },      },    },  },}

نکته‌ها:

• صدای Discord برای پیکربندی‌های فقط‌متنی اختیاری است؛ برای فعال‌کردن فرمان‌های /vc، محیط اجرای صدا و intent مربوط به Gateway با نام GuildVoiceStates، مقدار channels.discord.voice.enabled=true را تنظیم کنید (یا بلوک موجود channels.discord.voice را نگه دارید). مقدار channels.discord.intents.voiceStates می‌تواند اشتراک intent را صراحتاً بازنویسی کند؛ برای پیروی از وضعیت مؤثر فعال‌بودن صدا، آن را تنظیم‌نشده بگذارید.
• voice.mode مسیر مکالمه را کنترل می‌کند. مقدار پیش‌فرض agent-proxy است: یک بخش جلویی صدای بی‌درنگ، زمان‌بندی نوبت‌ها، وقفه و پخش را مدیریت می‌کند، کارهای اساسی را از طریق openclaw_agent_consult به عامل مسیریابی‌شده OpenClaw واگذار می‌کند و نتیجه را مانند یک درخواست تایپ‌شده Discord از همان گوینده در نظر می‌گیرد. stt-tts جریان قدیمی STT دسته‌ای به‌همراه TTS را حفظ می‌کند. bidi به مدل بی‌درنگ اجازه می‌دهد مستقیماً مکالمه کند و درعین‌حال openclaw_agent_consult را برای مغز OpenClaw در دسترس قرار می‌دهد.
• voice.agentSession تعیین می‌کند کدام مکالمه OpenClaw نوبت‌های صوتی را دریافت کند. برای استفاده از نشست خود کانال صوتی، آن را تنظیم‌نشده بگذارید؛ یا { mode: "target", target: "channel:<text-channel-id>" } را تنظیم کنید تا کانال صوتی به‌عنوان افزونه میکروفون/بلندگوی نشست یک کانال متنی موجود Discord مانند #maintainers عمل کند.
• voice.model مغز عامل OpenClaw را برای پاسخ‌های صوتی Discord و مشورت‌های بی‌درنگ بازنویسی می‌کند. برای به‌ارث‌بردن مدل عامل مسیریابی‌شده، آن را تنظیم‌نشده بگذارید. این گزینه از voice.realtime.model جدا است.
• voice.followUsers به ربات اجازه می‌دهد همراه کاربران انتخاب‌شده به کانال صوتی Discord بپیوندد، میان کانال‌ها جابه‌جا شود و آن را ترک کند. به دنبال‌کردن کاربران در صدا مراجعه کنید.
• agent-proxy گفتار را از طریق discord-voice مسیریابی می‌کند؛ این مسیر مجوزدهی عادی مالک/ابزار را برای گوینده و نشست مقصد حفظ می‌کند، اما ابزار tts عامل را پنهان می‌کند، زیرا پخش در اختیار صدای Discord است. به‌طور پیش‌فرض، agent-proxy برای گویندگان مالک (voice.realtime.toolPolicy: "owner") دسترسی کامل به ابزارها، معادل مالک، به مشورت می‌دهد و اکیداً ترجیح می‌دهد پیش از پاسخ‌های اساسی با عامل OpenClaw مشورت شود (voice.realtime.consultPolicy: "always"). در این حالت پیش‌فرض always، لایه بی‌درنگ پیش از پاسخ مشورت، عبارات پُرکننده را خودکار بیان نمی‌کند؛ گفتار را دریافت و رونویسی می‌کند، سپس پاسخ مسیریابی‌شده OpenClaw را بیان می‌کند. اگر هنگام پخش نخستین پاسخ در Discord، چند پاسخ مشورت اجباری تکمیل شوند، پاسخ‌های گفتاری دقیق بعدی به‌جای جایگزین‌کردن گفتار در میانه جمله، تا بیکارشدن پخش در صف می‌مانند.
• در حالت stt-tts، STT از tools.media.audio استفاده می‌کند؛ voice.model بر رونویسی تأثیری ندارد.
• در حالت‌های بی‌درنگ، voice.realtime.provider، voice.realtime.model و voice.realtime.speakerVoice نشست صوتی بی‌درنگ را پیکربندی می‌کنند. برای OpenAI Realtime 2.1 به‌همراه مغز Codex، از voice.realtime.model: "gpt-realtime-2.1" و voice.model: "openai/gpt-5.6-sol" استفاده کنید.
• حالت‌های صدای بی‌درنگ به‌طور پیش‌فرض فایل‌های نمایه کوچک IDENTITY.md، USER.md و SOUL.md را در دستورالعمل‌های ارائه‌دهنده بی‌درنگ می‌گنجانند تا نوبت‌های مستقیم و سریع، همان هویت، زمینه کاربر و شخصیت عامل مسیریابی‌شده OpenClaw را حفظ کنند. برای سفارشی‌سازی، voice.realtime.bootstrapContextFiles را روی یک زیرمجموعه تنظیم کنید، یا برای غیرفعال‌کردن آن از [] استفاده کنید. فقط همین فایل‌های نمایه پشتیبانی می‌شوند؛ AGENTS.md در زمینه عادی عامل باقی می‌ماند. زمینه نمایه تزریق‌شده، جایگزین openclaw_agent_consult برای کارهای فضای کاری، واقعیت‌های جاری، جست‌وجوی حافظه یا اقدام‌های متکی بر ابزار نمی‌شود.
• در حالت بی‌درنگ OpenAI با agent-proxy، محدودسازی با نام بیدارباش به‌طور پیش‌فرض با اتاق سازگار می‌شود: یک انسان می‌تواند بدون نام بیدارباش به‌طور طبیعی صحبت کند، اما دو یا چند انسان باید نوبت را با یکی از این نام‌ها آغاز یا پایان دهند. ربات‌های دیگر انسان به شمار نمی‌آیند. برای الزام همیشگی نام بیدارباش، voice.realtime.requireWakeName: true را تنظیم کنید؛ برای اینکه هرگز الزامی نباشد، false را تنظیم کنید. نام‌های بیدارباش پیکربندی‌شده باید یک یا دو کلمه باشند. اگر voice.realtime.wakeNames تنظیم نشده باشد، OpenClaw از name عامل مسیریابی‌شده به‌همراه OpenClaw استفاده می‌کند و در صورت نبود آن، به شناسه عامل به‌همراه OpenClaw برمی‌گردد. یک دروازه فعال نام بیدارباش، پاسخ خودکار ارائه‌دهنده بی‌درنگ را غیرفعال می‌کند، نوبت‌های پذیرفته‌شده را از مسیر مشورت عامل OpenClaw عبور می‌دهد و وقتی پیش از رسیدن رونویسی نهایی، نام بیدارباش ابتدایی از رونویسی جزئی تشخیص داده شود، یک تأیید صوتی کوتاه ارائه می‌دهد. این سیاست بدون اتصال مجدد صدا، پیوستن‌ها و ترک‌کردن‌های زنده را دنبال می‌کند.
• ارائه‌دهنده بی‌درنگ OpenAI نام رویدادهای جاری Realtime 2 و نام‌های مستعار قدیمی سازگار با Codex را برای رویدادهای صدای خروجی و رونویسی می‌پذیرد؛ بنابراین نسخه‌های سازگار ارائه‌دهنده می‌توانند بدون ازدست‌رفتن صدای دستیار تغییر کنند.
• voice.realtime.bargeIn تعیین می‌کند آیا رویدادهای آغاز گفتار در Discord پخش بی‌درنگ فعال را قطع کنند یا نه. اگر تنظیم نشده باشد، از تنظیم وقفه صدای ورودی ارائه‌دهنده بی‌درنگ پیروی می‌کند.
• voice.realtime.minBargeInAudioEndMs حداقل مدت پخش دستیار را پیش از آنکه ورود ناگهانی به گفت‌وگوی بی‌درنگ OpenAI صدا را کوتاه کند، کنترل می‌کند. پیش‌فرض: 250. برای وقفه فوری در اتاق‌های کم‌پژواک، 0 را تنظیم کنید؛ برای محیط‌های بلندگویی با پژواک زیاد، مقدار آن را افزایش دهید.
• voice.tts فقط برای پخش صوتی stt-tts، مقدار tts را بازنویسی می‌کند؛ حالت‌های بی‌درنگ به‌جای آن از voice.realtime.speakerVoice استفاده می‌کنند. برای استفاده از یک صدای OpenAI در پخش Discord، voice.tts.provider: "openai" را تنظیم کنید و در voice.tts.providers.openai.speakerVoice یک صدای تبدیل متن به گفتار انتخاب کنید. cedar در مدل فعلی TTS متعلق به OpenAI، انتخاب مناسبی با صدای مردانه است.
• بازنویسی‌های مختص هر کانال Discord در systemPrompt برای نوبت‌های رونویسی صوتی همان کانال صوتی اعمال می‌شوند.
• هنگامی که OpenClaw به یک کانال صوتی می‌پیوندد، نشست عامل مسیریابی‌شده یک رویداد سیستمی بی‌صدا حاوی فهرست کنونی شرکت‌کنندگان دریافت می‌کند. پیوستن‌ها و ترک‌کردن‌های بعدی شرکت‌کنندگان، آن نشست را بدون ایجاد پاسخ صوتی ناخواسته به‌روزرسانی می‌کنند؛ نام‌های نمایشی Discord به‌عنوان برچسب‌های غیرقابل‌اعتماد در نظر گرفته می‌شوند. نوبت‌های صوتی مجاز نیز یک تصویر فوری تازه از فهرست شرکت‌کنندگان دریافت می‌کنند.
• نوبت‌های رونویسی صوتی و فرمان‌های /vc برای وضعیت مالک از ورودی‌های Discord در commands.ownerAllowFrom استفاده می‌کنند. وقتی هیچ مالک فرمان Discord پیکربندی نشده باشد، allowFrom حساب انتخاب‌شده Discord (یا dm.allowFrom قدیمی) همچنان می‌تواند بدون اعطای وضعیت مالک، دسترسی صوتی را مجاز کند. مشاهده‌پذیری ابزارهای عامل از سیاست ابزار پیکربندی‌شده برای نشست مسیریابی‌شده پیروی می‌کند.
• اگر voice.autoJoin برای یک سرور چند ورودی داشته باشد، OpenClaw به آخرین کانال پیکربندی‌شده برای آن سرور می‌پیوندد.
• voice.allowedChannels یک فهرست مجاز اختیاری برای محل استقرار است. برای اجازه‌دادن به /vc join جهت پیوستن به هر کانال صوتی مجاز Discord، آن را تنظیم‌نشده بگذارید. وقتی تنظیم شود، /vc join، پیوستن خودکار هنگام راه‌اندازی و جابه‌جایی‌های وضعیت صوتی ربات به ورودی‌های فهرست‌شده در { guildId, channelId } محدود می‌شوند. برای ردکردن همه پیوستن‌ها به صدای Discord، آن را روی یک آرایه خالی تنظیم کنید. اگر Discord ربات را به خارج از فهرست مجاز منتقل کند، OpenClaw آن کانال را ترک می‌کند و در صورت وجود مقصد پیکربندی‌شده برای پیوستن خودکار، دوباره به آن می‌پیوندد.
• voice.daveEncryption و voice.decryptionFailureTolerance بدون تغییر به گزینه‌های پیوستن @discordjs/voice منتقل می‌شوند؛ مقادیر پیش‌فرض بالادستی daveEncryption=true و decryptionFailureTolerance=24 هستند.
• OpenClaw برای دریافت صدای Discord و پخش خام PCM بی‌درنگ از کدک همراه libopus-wasm استفاده می‌کند. این کدک یک ساخت WebAssembly سنجاق‌شده از libopus را همراه دارد و به افزونه‌های بومی opus نیاز ندارد.
• voice.connectTimeoutMs زمان انتظار اولیه برای Ready در @discordjs/voice را برای /vc join و تلاش‌های پیوستن خودکار کنترل می‌کند. پیش‌فرض: 30000.
• voice.reconnectGraceMs مدت انتظار OpenClaw برای آغاز اتصال مجدد یک نشست صوتی قطع‌شده، پیش از نابودکردن آن، را کنترل می‌کند. پیش‌فرض: 15000.
• در حالت stt-tts، پخش صدا صرفاً به‌دلیل شروع صحبت کاربر دیگری متوقف نمی‌شود. برای جلوگیری از حلقه‌های بازخورد، OpenClaw هنگام پخش TTS دریافت صدای جدید را نادیده می‌گیرد؛ برای نوبت بعدی، پس از پایان پخش صحبت کنید. حالت‌های بی‌درنگ آغاز گفتار را به‌عنوان سیگنال ورود ناگهانی به گفت‌وگو به ارائه‌دهنده بی‌درنگ ارسال می‌کنند.
• در حالت‌های بی‌درنگ، پژواک بلندگوها در یک میکروفون باز ممکن است مانند ورود ناگهانی به گفت‌وگو به نظر برسد و پخش را قطع کند. برای اتاق‌های Discord با پژواک زیاد، voice.realtime.providers.openai.interruptResponseOnInputAudio: false را تنظیم کنید تا OpenAI در اثر صدای ورودی به‌طور خودکار وقفه ایجاد نکند. اگر همچنان می‌خواهید رویدادهای آغاز گفتار Discord پخش فعال را قطع کنند، voice.realtime.bargeIn: true را اضافه کنید. پل بی‌درنگ OpenAI کوتاه‌سازی‌های پخش کمتر از voice.realtime.minBargeInAudioEndMs را که احتمالاً پژواک/نویز هستند نادیده می‌گیرد و به‌جای پاک‌کردن پخش Discord، آن‌ها را به‌عنوان ردشده ثبت می‌کند.
• voice.captureSilenceGraceMs مدت انتظار OpenClaw پس از گزارش پایان صحبت یک گوینده توسط Discord، پیش از نهایی‌کردن آن بخش صوتی برای STT، را کنترل می‌کند. پیش‌فرض: 2000؛ اگر Discord مکث‌های عادی را به رونویسی‌های جزئی و منقطع تقسیم می‌کند، آن را افزایش دهید.
• وقتی ElevenLabs ارائه‌دهنده انتخاب‌شده TTS باشد، پخش صوتی Discord از TTS جریانی استفاده می‌کند و از جریان پاسخ ارائه‌دهنده آغاز می‌شود. ارائه‌دهندگانی که از جریان پشتیبانی نمی‌کنند، به مسیر فایل موقت تولیدشده برمی‌گردند.
• OpenClaw خطاهای رمزگشایی دریافت را زیر نظر می‌گیرد و پس از تکرار خطاها در یک بازه کوتاه، با ترک و پیوستن دوباره به کانال صوتی به‌طور خودکار بازیابی می‌شود.
• اگر پس از به‌روزرسانی، گزارش‌های دریافت مکرراً DecryptionFailed(UnencryptedWhenPassthroughDisabled) را نشان می‌دهند، یک گزارش وابستگی و گزارش‌های رویداد را جمع‌آوری کنید. خط همراه @discordjs/voice شامل اصلاح بالادستی padding از PR شماره #11449 در discord.js است که issue شماره #11419 در discord.js را بست.
• رویدادهای دریافت The operation was aborted هنگام نهایی‌کردن یک بخش دریافت‌شده از گوینده توسط OpenClaw مورد انتظار هستند؛ این‌ها اطلاعات تشخیصی تفصیلی‌اند، نه هشدار.
• گزارش‌های تفصیلی صدای Discord برای هر بخش پذیرفته‌شده گوینده، یک پیش‌نمایش محدود و تک‌خطی از رونویسی STT دارند؛ بنابراین اشکال‌زدایی، بدون تخلیه متن رونویسی نامحدود، هم سمت کاربر و هم سمت پاسخ عامل را نشان می‌دهد.
• در حالت agent-proxy، بازگشت جایگزین مشورت اجباری، قطعه‌های احتمالاً ناقص رونویسی مانند متن پایان‌یافته با ... یا یک حرف ربط پایانی مانند «و»، و نیز عبارت‌های پایانی آشکارا غیرقابل‌اقدام مانند «الان برمی‌گردم» یا «خداحافظ» را نادیده می‌گیرد. وقتی این کار از یک پاسخ قدیمی در صف جلوگیری کند، گزارش‌ها forced agent consult skipped reason=... را نشان می‌دهند.

دنبال‌کردن کاربران در صدا

وقتی می‌خواهید ربات صوتی Discord به‌جای پیوستن به یک کانال ثابت هنگام راه‌اندازی یا انتظار برای /vc join، همراه یک یا چند کاربر شناخته‌شده Discord بماند، از voice.followUsers استفاده کنید.

{  channels: {    discord: {      voice: {        enabled: true,        followUsersEnabled: true,        followUsers: ["discord:123456789012345678"],        allowedChannels: [          {            guildId: "123456789012345678",            channelId: "234567890123456789",          },        ],      },    },  },}

رفتار:

• followUsers شناسه‌های خام کاربران Discord و مقادیر discord:<id> را می‌پذیرد. OpenClaw پیش از تطبیق رویدادهای وضعیت صوتی، هر دو قالب را نرمال‌سازی می‌کند.
• followUsersEnabled هنگامی که followUsers پیکربندی شده باشد، به‌طور پیش‌فرض true است. برای حفظ فهرست ذخیره‌شده و در عین حال توقف دنبال‌کردن خودکار صوتی، آن را روی false تنظیم کنید.
• followUsers فقط ماندگاری در کانال صوتی را کنترل می‌کند. این گزینه دسترسی سخن‌گو یا اختیار مالک را اعطا نمی‌کند؛ commands.ownerAllowFrom و کاربران و نقش‌های سرور یا کانال را جداگانه پیکربندی کنید.
• هنگامی که کاربر دنبال‌شده‌ای به یک کانال صوتی مجاز می‌پیوندد، OpenClaw نیز به آن کانال می‌پیوندد. وقتی کاربر جابه‌جا می‌شود، OpenClaw نیز همراه او جابه‌جا می‌شود. هنگامی که کاربر دنبال‌شده فعال قطع اتصال می‌کند، OpenClaw کانال را ترک می‌کند.
• اگر چند کاربر دنبال‌شده در یک سرور باشند و کاربر دنبال‌شده فعال خارج شود، OpenClaw پیش از ترک سرور به کانال یکی دیگر از کاربران دنبال‌شده تحت ردیابی منتقل می‌شود. اگر چند کاربر دنبال‌شده هم‌زمان جابه‌جا شوند، آخرین رویداد وضعیت صوتی مشاهده‌شده ملاک قرار می‌گیرد.
• allowedChannels همچنان اعمال می‌شود. کاربر دنبال‌شده در کانال غیرمجاز نادیده گرفته می‌شود و نشست تحت مالکیت دنبال‌کردن به کاربر دنبال‌شده دیگری منتقل می‌شود یا کانال را ترک می‌کند.
• OpenClaw رویدادهای ازدست‌رفته وضعیت صوتی را هنگام راه‌اندازی و در فاصله‌های زمانی محدود همگام‌سازی می‌کند. همگام‌سازی از سرورهای پیکربندی‌شده نمونه‌برداری می‌کند و تعداد جست‌وجوهای REST را در هر اجرا محدود می‌سازد؛ بنابراین ممکن است همگرایی فهرست‌های بسیار بزرگ followUsers بیش از یک فاصله زمانی طول بکشد.
• اگر Discord یا یک مدیر، ربات را هنگام دنبال‌کردن کاربر جابه‌جا کند، OpenClaw نشست صوتی را بازسازی می‌کند و در صورت مجاز بودن مقصد، مالکیت دنبال‌کردن را حفظ می‌کند. اگر ربات به خارج از allowedChannels منتقل شود، OpenClaw کانال را ترک می‌کند و در صورت وجود هدف پیکربندی‌شده، دوباره به آن می‌پیوندد.
• بازیابی دریافت DAVE ممکن است پس از خرابی‌های مکرر رمزگشایی، همان کانال را ترک کند و دوباره به آن بپیوندد. نشست‌های تحت مالکیت دنبال‌کردن در این مسیر بازیابی، مالکیت دنبال‌کردن خود را حفظ می‌کنند؛ بنابراین قطع اتصال بعدی کاربر دنبال‌شده همچنان باعث ترک کانال می‌شود.

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

• برای راه‌اندازی‌های شخصی یا اپراتوری که ربات باید هنگام حضور شما در کانال صوتی به‌طور خودکار در آن حضور داشته باشد، از followUsers استفاده کنید.
• برای ربات‌های اتاق ثابت که باید حتی در صورت نبود هیچ کاربر تحت ردیابی در کانال صوتی حضور داشته باشند، از autoJoin استفاده کنید.
• برای پیوستن‌های موردی یا اتاق‌هایی که حضور خودکار صوتی در آن‌ها غیرمنتظره خواهد بود، از /vc join استفاده کنید.

کُدک صوتی Discord:

• گزارش‌های دریافت صوت، discord voice: opus decoder: libopus-wasm را نشان می‌دهند.
• پخش بی‌درنگ، PCM خام استریوی 48 kHz را با همان بسته همراه libopus-wasm به Opus کدگذاری می‌کند و سپس بسته‌ها را به @discordjs/voice تحویل می‌دهد.
• پخش فایل و جریان ارائه‌دهنده با ffmpeg به PCM خام استریوی 48 kHz تبدیل می‌شود، سپس برای جریان بسته Opus ارسالی به Discord از libopus-wasm استفاده می‌کند.

پایپ‌لاین STT به‌همراه TTS:

• ضبط PCM از Discord به یک فایل موقت WAV تبدیل می‌شود.
• tools.media.audio وظیفه STT را بر عهده دارد؛ برای نمونه openai/gpt-4o-mini-transcribe.
• رونوشت از مسیر ورودی و مسیریابی Discord ارسال می‌شود، در حالی که LLM پاسخ با سیاست خروجی صوتی اجرا می‌شود که ابزار tts عامل را پنهان می‌کند و متن بازگشتی می‌خواهد، زیرا پخش نهایی TTS در اختیار صوت Discord است.
• voice.model در صورت تنظیم، فقط LLM پاسخ را برای این نوبت کانال صوتی بازنویسی می‌کند.
• voice.tts روی tts ادغام می‌شود؛ ارائه‌دهندگان دارای قابلیت جریان‌دهی، داده را مستقیماً به پخش‌کننده می‌فرستند و در غیر این صورت فایل صوتی حاصل در کانال پیوسته‌شده پخش می‌شود.

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

{  channels: {    discord: {      voice: {        enabled: true,        model: "openai/gpt-5.6-sol",        followUsersEnabled: true,        followUsers: ["123456789012345678"],        realtime: {          provider: "openai",          model: "gpt-realtime-2.1",          speakerVoice: "cedar",        },      },    },  },}

در نبود بلوک voice.agentSession، هر کانال صوتی نشست مسیریابی‌شده OpenClaw مخصوص خود را دریافت می‌کند. برای مثال، /vc join channel:234567890123456789 با نشست همان کانال صوتی Discord صحبت می‌کند. مدل بی‌درنگ فقط بخش جلویی صوتی است؛ درخواست‌های محتوایی به عامل پیکربندی‌شده OpenClaw سپرده می‌شوند. اگر مدل بی‌درنگ بدون فراخوانی ابزار مشورت، رونوشت نهایی تولید کند، OpenClaw به‌عنوان سازوکار پشتیبان، مشورت را اجباری می‌کند تا رفتار پیش‌فرض همچنان مانند صحبت‌کردن با عامل باشد.

نمونه قدیمی STT به‌همراه TTS:

{  channels: {    discord: {      voice: {        enabled: true,        mode: "stt-tts",        model: "openai/gpt-5.4-mini",        tts: {          provider: "openai",          providers: {            openai: {              model: "gpt-4o-mini-tts",              speakerVoice: "cedar",            },          },        },      },    },  },}

نمونه ارتباط دوسویه بی‌درنگ:

{  channels: {    discord: {      voice: {        enabled: true,        mode: "bidi",        model: "openai/gpt-5.6-sol",        realtime: {          provider: "openai",          model: "gpt-realtime-2.1",          speakerVoice: "cedar",          toolPolicy: "safe-read-only",          consultPolicy: "always",        },      },    },  },}

صوت به‌عنوان گسترش یک نشست موجود کانال Discord:

{  channels: {    discord: {      voice: {        enabled: true,        mode: "agent-proxy",        model: "openai/gpt-5.6-sol",        agentSession: {          mode: "target",          target: "channel:123456789012345678",        },        realtime: {          provider: "openai",          model: "gpt-realtime-2.1",          speakerVoice: "cedar",        },      },    },  },}

در حالت agent-proxy، ربات به کانال صوتی پیکربندی‌شده می‌پیوندد، اما نوبت‌های عامل OpenClaw از نشست و عامل معمولِ مسیریابی‌شده کانال هدف استفاده می‌کنند. نشست صوتی بی‌درنگ، نتیجه بازگشتی را در کانال صوتی بازگو می‌کند. عامل ناظر همچنان می‌تواند طبق سیاست ابزار خود از ابزارهای معمول پیام استفاده کند؛ از جمله، اگر اقدام مناسب همین باشد، یک پیام جداگانه Discord ارسال کند.

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

قالب‌های مفید هدف:

• target: "channel:123456789012345678" از طریق نشست کانال متنی Discord مسیریابی می‌شود.
• target: "123456789012345678" به‌عنوان هدف کانال در نظر گرفته می‌شود.
• target: "dm:123456789012345678" یا target: "user:123456789012345678" از طریق نشست همان پیام مستقیم مسیریابی می‌شود.

نمونه OpenAI Realtime با پژواک زیاد:

{  channels: {    discord: {      voice: {        enabled: true,        mode: "bidi",        model: "openai/gpt-5.6-sol",        realtime: {          provider: "openai",          model: "gpt-realtime-2.1",          speakerVoice: "cedar",          bargeIn: true,          minBargeInAudioEndMs: 500,          consultPolicy: "always",          providers: {            openai: {              interruptResponseOnInputAudio: false,            },          },        },      },    },  },}

زمانی از این گزینه استفاده کنید که مدل، پخش صدای خود در Discord را از طریق میکروفن باز می‌شنود، اما همچنان می‌خواهید با صحبت‌کردن آن را متوقف کنید. OpenClaw مانع می‌شود OpenAI با دریافت صدای ورودی خام به‌طور خودکار پاسخ را قطع کند، در حالی که bargeIn: true به رویدادهای آغاز سخن‌گویی Discord و صدای سخن‌گوی از قبل فعال اجازه می‌دهد پاسخ‌های بی‌درنگ فعال را پیش از رسیدن نوبت ضبط‌شده بعدی به OpenAI لغو کنند. سیگنال‌های بسیار زودهنگام ورود میان صحبت با audioEndMs کمتر از minBargeInAudioEndMs به‌عنوان پژواک یا نویز احتمالی در نظر گرفته و نادیده گرفته می‌شوند تا مدل در نخستین فریم پخش، صدای خود را قطع نکند.

گزارش‌های صوتی مورد انتظار:

• هنگام پیوستن: discord voice: joining ... voiceSession=... supervisorSession=... agentSessionMode=... voiceModel=... realtimeModel=...
• هنگام آغاز بی‌درنگ: discord voice: realtime bridge starting ... autoRespond=false interruptResponse=false bargeIn=false minBargeInAudioEndMs=...
• هنگام دریافت صدای سخن‌گو: discord voice: realtime speaker turn opened ...، discord voice: realtime input audio started ... outputAudioMs=... outputActive=... و discord voice: realtime speaker turn closed ... chunks=... discordBytes=... realtimeBytes=... interruptedPlayback=...
• هنگام ردکردن گفتار منقضی: discord voice: realtime forced agent consult skipped reason=incomplete-transcript ... یا reason=non-actionable-closing ...
• هنگام تکمیل پاسخ بی‌درنگ: discord voice: realtime audio playback finishing reason=response.done ... audioMs=... chunks=...
• هنگام توقف یا بازنشانی پخش: discord voice: realtime audio playback stopped reason=... audioMs=... elapsedMs=... chunks=...
• هنگام مشورت بی‌درنگ: discord voice: realtime consult requested ... voiceSession=... supervisorSession=... question=...
• هنگام پاسخ عامل: discord voice: agent turn answer ...
• هنگام قرارگرفتن گفتار دقیق در صف: discord voice: realtime exact speech queued ... queued=... outputAudioMs=... outputActive=... و سپس discord voice: realtime exact speech dequeued reason=player-idle ...
• هنگام تشخیص ورود میان صحبت: discord voice: realtime barge-in detected source=speaker-start ... یا discord voice: realtime barge-in detected source=active-speaker-audio ... و سپس discord voice: realtime barge-in requested reason=... outputAudioMs=... outputActive=...
• هنگام قطع پاسخ بی‌درنگ: discord voice: realtime model interrupt requested client:response.cancel reason=barge-in و سپس یکی از discord voice: realtime model audio truncated client:conversation.item.truncate reason=barge-in audioEndMs=... یا discord voice: realtime model interrupt confirmed server:response.done status=cancelled ...
• هنگام نادیده‌گرفتن پژواک یا نویز: discord voice: realtime model interrupt ignored client:conversation.item.truncate.skipped reason=barge-in audioEndMs=0 minAudioEndMs=250
• هنگام غیرفعال‌بودن ورود میان صحبت: discord voice: realtime capture ignored during playback (barge-in disabled) ...
• هنگام پخش بی‌کار: discord voice: realtime barge-in ignored reason=... outputActive=false ... playbackChunks=0

برای اشکال‌زدایی صدای قطع‌شده، گزارش‌های صوتی بی‌درنگ را به‌صورت یک خط زمانی بخوانید:

1. realtime audio playback started یعنی Discord پخش صدای دستیار را آغاز کرده است. پل از این نقطه شمارش قطعه‌های خروجی دستیار، بایت‌های PCM در Discord، بایت‌های بی‌درنگ ارائه‌دهنده و مدت صدای تولیدشده را آغاز می‌کند.
2. realtime speaker turn opened فعال‌شدن یک سخن‌گو در Discord را مشخص می‌کند. اگر پخش از قبل فعال باشد و bargeIn فعال شده باشد، ممکن است پس از آن barge-in detected source=speaker-start ثبت شود.
3. realtime input audio started نخستین فریم صوتی واقعی دریافت‌شده برای آن نوبت سخن‌گو را مشخص می‌کند. وجود outputActive=true یا مقدار غیرصفر outputAudioMs در اینجا یعنی میکروفن در حالی ورودی ارسال می‌کند که پخش دستیار هنوز فعال است.
4. barge-in detected source=active-speaker-audio یعنی OpenClaw هنگام فعال‌بودن پخش دستیار، صدای زنده سخن‌گو را مشاهده کرده است. این مورد برای تشخیص یک وقفه واقعی از رویداد آغاز سخن‌گویی Discord که صدای مفیدی ندارد، کاربرد دارد.
5. barge-in requested reason=... یعنی OpenClaw از ارائه‌دهنده بی‌درنگ خواسته پاسخ فعال را لغو یا کوتاه کند. این گزارش شامل outputAudioMs، outputActive و playbackChunks است تا بتوانید ببینید پیش از وقفه، واقعاً چه مقدار از صدای دستیار پخش شده بود.
6. realtime audio playback stopped reason=... نقطه بازنشانی پخش محلی Discord است. دلیل مشخص می‌کند چه کسی پخش را متوقف کرده است: barge-in، player-idle، provider-clear-audio، forced-agent-consult، stream-close یا session-close.
7. realtime speaker turn closed نوبت ورودی ضبط‌شده را خلاصه می‌کند. chunks=0 یا hasAudio=false یعنی نوبت سخن‌گو آغاز شده، اما هیچ صدای قابل‌استفاده‌ای به پل بی‌درنگ نرسیده است. interruptedPlayback=true یعنی آن نوبت ورودی با خروجی دستیار هم‌پوشانی داشته و منطق ورود میان صحبت را فعال کرده است.

فیلدهای مفید:

• outputAudioMs: مدت صدای دستیار که ارائه‌دهنده بی‌درنگ پیش از این خط گزارش تولید کرده است.
• audioMs: مدت صدای دستیار که OpenClaw پیش از توقف پخش محاسبه کرده است.
• elapsedMs: زمان سپری‌شده واقعی بین باز و بسته‌شدن جریان پخش یا نوبت سخن‌گو.
• discordBytes: بایت‌های PCM استریوی 48 kHz ارسال‌شده به صوت Discord یا دریافت‌شده از آن.
• realtimeBytes: بایت‌های PCM با قالب ارائه‌دهنده که به ارائه‌دهنده بی‌درنگ ارسال شده یا از آن دریافت شده‌اند.
• playbackChunks: قطعه‌های صدای دستیار که برای پاسخ فعال به Discord فرستاده شده‌اند.
• sinceLastAudioMs: فاصله میان آخرین فریم صوتی ضبط‌شده سخن‌گو و بسته‌شدن نوبت سخن‌گو.

الگوهای رایج:

• قطع فوری همراه با source=active-speaker-audio، outputAudioMs کوچک و حضور همان کاربر در نزدیکی معمولاً نشان می‌دهد پژواک بلندگو وارد میکروفون می‌شود. voice.realtime.minBargeInAudioEndMs را افزایش دهید، صدای بلندگو را کاهش دهید، از هدفون استفاده کنید یا voice.realtime.providers.openai.interruptResponseOnInputAudio: false را تنظیم کنید.
• source=speaker-start که پس از آن speaker turn closed ... hasAudio=false می‌آید، یعنی Discord شروع صدای گوینده را گزارش کرده اما هیچ صوتی به OpenClaw نرسیده است. این وضعیت می‌تواند ناشی از یک رویداد گذرای صوتی Discord، رفتار دروازهٔ نویز یا فعال‌شدن لحظه‌ای میکروفون توسط یک کلاینت باشد.
• audio playback stopped reason=stream-close بدون وقوع قطع گفتار یا provider-clear-audio در نزدیکی آن، یعنی جریان پخش محلی Discord به‌طور غیرمنتظره پایان یافته است. لاگ‌های پیشین ارائه‌دهنده و پخش‌کنندهٔ Discord را بررسی کنید.
• capture ignored during playback (barge-in disabled) یعنی OpenClaw هنگام فعال‌بودن صدای دستیار، ورودی را عمداً کنار گذاشته است. اگر می‌خواهید گفتار پخش را متوقف کند، voice.realtime.bargeIn را فعال کنید.
• barge-in ignored ... outputActive=false یعنی VAD مربوط به Discord یا ارائه‌دهنده، گفتار را گزارش کرده است، اما OpenClaw پخش فعالی برای متوقف‌کردن نداشته است. این وضعیت نباید صدا را قطع کند.

اعتبارنامه‌ها برای هر مؤلفه جداگانه برطرف می‌شوند: احراز هویت مسیر LLM برای voice.model، احراز هویت STT برای tools.media.audio، احراز هویت TTS برای tts/voice.tts و احراز هویت ارائه‌دهندهٔ بلادرنگ برای voice.realtime.providers یا پیکربندی عادی احراز هویت ارائه‌دهنده.

پیام‌های صوتی

پیام‌های صوتی Discord پیش‌نمایش شکل موج را نمایش می‌دهند و به صوت OGG/Opus نیاز دارند. OpenClaw شکل موج را به‌طور خودکار تولید می‌کند، اما برای بررسی و تبدیل، به ffmpeg و ffprobe روی میزبان Gateway نیاز دارد.

• یک مسیر فایل محلی ارائه کنید (URLها رد می‌شوند).
• محتوای متنی را حذف کنید (Discord وجود هم‌زمان متن و پیام صوتی در یک payload را رد می‌کند).
• هر قالب صوتی پذیرفته می‌شود؛ OpenClaw در صورت نیاز آن را به OGG/Opus تبدیل می‌کند.

message(action="send", channel="discord", target="channel:123", path="/path/to/audio.mp3", asVoice=true)

عیب‌یابی

openclaw doctoropenclaw channels status --probeopenclaw logs --follow

{channels: {defaults: {  botLoopProtection: {    maxEventsPerWindow: 20,    windowSeconds: 60,    cooldownSeconds: 60,  },},discord: {  // بازنویسی اختیاری در سراسر Discord. بلوک‌های حساب، فیلدهای منفرد را بازنویسی  // و فیلدهای حذف‌شده را از اینجا به ارث می‌برند.  botLoopProtection: {    maxEventsPerWindow: 4,  },  accounts: {    alpha: {      // Alpha فقط هنگامی به بات‌های دیگر گوش می‌دهد که به آن اشاره کنند.      allowBots: "mentions",    },    bravo: {      // Bravo به همهٔ پیام‌های Discord نوشته‌شده توسط بات گوش می‌دهد.      allowBots: true,      mentionAliases: {        // به Bravo اجازه می‌دهد با شناسهٔ کاربر پیکربندی‌شده، اشارهٔ Discord مربوط به Alpha را بنویسد.        Alpha: "ALPHA_DISCORD_USER_ID",      },      botLoopProtection: {        // پیش از سرکوب جفت، حداکثر پنج پیام در دقیقه مجاز است.        maxEventsPerWindow: 5,        windowSeconds: 60,        cooldownSeconds: 90,      },    },  },},},}

مرجع پیکربندی

مرجع اصلی: مرجع پیکربندی - Discord.

فعالیت‌های Discord

channels.discord.activities را تنظیم کنید تا عامل‌ها بتوانند ویجت‌های HTML مستقل ارسال کنند که داخل Discord باز می‌شوند. این بلوک اختیاری است؛ در صورت نبود آن، OpenClaw هیچ مسیر Activity، ابزار یا کنترل‌کنندهٔ تعاملی ثبت نمی‌کند. برای راه‌اندازی Developer Portal، تونل، امنیت و عیب‌یابی به فعالیت‌های Discord مراجعه کنید.

• activities.clientSecret: رمز کلاینت OAuth2 برای برنامهٔ Discord؛ در صورت نبود از DISCORD_CLIENT_SECRET استفاده می‌شود
• activities.applicationId: شناسهٔ اختیاری برنامهٔ Activity؛ مقدار پیش‌فرض، شناسهٔ برنامهٔ بات است که هنگام راه‌اندازی gateway شناسایی می‌شود

ایمنی و عملیات

• توکن‌های بات را محرمانه در نظر بگیرید (DISCORD_BOT_TOKEN در محیط‌های تحت نظارت ترجیح داده می‌شود).
• حداقل مجوزهای لازم Discord را اعطا کنید.
• اگر استقرار/وضعیت دستور قدیمی است، gateway را راه‌اندازی مجدد کنید و با openclaw channels status --probe دوباره بررسی کنید.

مرتبط