Discord

آماده برای DMها و کانال‌های guild از طریق Gateway رسمی 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>

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

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

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

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

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

مدل runtime

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

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

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

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

مثال: ارسال به والد انجمن برای ایجاد thread

openclaw message send --channel discord --target channel:<forumId> \  --message "Topic title\nBody of the post"

مثال: ایجاد صریح یک thread انجمن

openclaw message thread create --channel discord --target channel:<forumId> \  --thread-name "Topic title" --message "Body of the post"

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

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

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

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

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

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

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

/modelو/modelsیک انتخاب‌گر تعاملی مدل را باز می‌کنند که dropdownهای ارائه‌دهنده، مدل و runtime سازگار به‌همراه یک مرحلهٔ Submit دارد./models addمنسوخ شده و اکنون به‌جای ثبت مدل‌ها از گفت‌وگو، پیام منسوخ‌بودن برمی‌گرداند. پاسخ انتخاب‌گر موقت است و فقط کاربری که آن را فراخوانده می‌تواند از آن استفاده کند. منوهای انتخاب Discord به ۲۵ گزینه محدودند، پس وقتی می‌خواهید انتخاب‌گر مدل‌های کشف‌شدهٔ پویا را فقط برای ارائه‌دهندگان انتخاب‌شده‌ای مانندopenai-codexیاvllmنشان دهد، ورودی‌هایprovider/*را بهagents.defaults.models` اضافه کنید.

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

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

فرم‌های modal:

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

مثال: OC_I18N_900009

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

مسیریابی عامل مبتنی بر role

از bindings[].match.roles برای مسیریابی اعضای guild در Discord به عامل‌های متفاوت بر اساس شناسهٔ role استفاده کنید. bindingهای مبتنی بر role فقط شناسه‌های role را می‌پذیرند و پس از bindingهای peer یا parent-peer و پیش از bindingهای فقط-guild ارزیابی می‌شوند. اگر یک binding فیلدهای match دیگری هم تنظیم کند (برای مثال peer + guildId + roles)، همهٔ فیلدهای پیکربندی‌شده باید مطابق باشند. OC_I18N_900014

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

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

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

تنظیمات پیش‌فرض فرمان اسلش:

• ephemeral: true

جزئیات ویژگی

ابزارها و دروازه‌های اقدام

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

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

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

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

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

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

رابط کاربری Components v2

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

• channels.discord.ui.components.accentColor رنگ تاکیدی استفاده‌شده توسط کانتینرهای مؤلفه Discord را تنظیم می‌کند (hex).
• برای هر حساب با channels.discord.accounts.<id>.ui.components.accentColor تنظیم کنید.
• وقتی components v2 وجود داشته باشد، embeds نادیده گرفته می‌شود.

نمونه: OC_I18N_900028

صدا

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 پیروی می‌کند. OC_I18N_900029 برای بررسی مجوزهای مؤثر بات پیش از پیوستن، اجرا کنید: OC_I18N_900030 نمونه پیوستن خودکار: OC_I18N_900031 نکته‌ها:

• voice.tts فقط برای پخش صوتی stt-tts، messages.tts را بازنویسی می‌کند. حالت‌های بلادرنگ از voice.realtime.voice استفاده می‌کنند.
• 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 جدا است.
• 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.voice نشست صوتی بلادرنگ را پیکربندی می‌کنند. برای OpenAI Realtime 2 همراه با مغز Codex، از voice.realtime.model: "gpt-realtime-2" و voice.model: "openai-codex/gpt-5.5" استفاده کنید.
• ارائه‌دهنده بلادرنگ OpenAI نام‌های رویداد فعلی Realtime 2 و نام‌های مستعار قدیمی سازگار با Codex را برای رویدادهای صوت خروجی و رونویسی می‌پذیرد، بنابراین snapshotهای سازگار ارائه‌دهنده می‌توانند بدون از دست رفتن صدای دستیار تغییر کنند.
• voice.realtime.bargeIn کنترل می‌کند آیا رویدادهای شروع صحبت گوینده در Discord پخش بلادرنگ فعال را قطع کنند یا نه. اگر تنظیم نشده باشد، از تنظیم وقفه صوت ورودی ارائه‌دهنده بلادرنگ پیروی می‌کند.
• voice.realtime.minBargeInAudioEndMs حداقل مدت پخش دستیار پیش از آن را کنترل می‌کند که یک barge-in بلادرنگ OpenAI صدا را کوتاه کند. پیش‌فرض: 250. برای وقفه فوری در اتاق‌های کم‌اکو مقدار 0 را تنظیم کنید، یا برای چیدمان‌های بلندگوی پر‌اکو آن را افزایش دهید.
• برای صدای OpenAI روی پخش Discord، voice.tts.provider: "openai" را تنظیم کنید و یک صدای Text-to-speech را زیر voice.tts.openai.voice یا voice.tts.providers.openai.voice انتخاب کنید. cedar روی مدل فعلی TTS OpenAI گزینه خوبی با صدای مردانه است.
• بازنویسی‌های systemPrompt مخصوص هر کانال Discord روی نوبت‌های رونویسی صوتی آن کانال صوتی اعمال می‌شوند.
• نوبت‌های رونویسی صوتی وضعیت مالک را از allowFrom در Discord (یا dm.allowFrom) به‌دست می‌آورند؛ گویندگان غیرمالک نمی‌توانند به ابزارهای فقط مالک دسترسی داشته باشند (برای مثال gateway و cron).
• صدای Discord برای پیکربندی‌های فقط متنی اختیاری است؛ برای فعال کردن فرمان‌های /vc، زمان اجرای صوتی و intent مربوط به Gateway با نام GuildVoiceStates، مقدار channels.discord.voice.enabled=true را تنظیم کنید (یا یک بلوک موجود channels.discord.voice را نگه دارید).
• channels.discord.intents.voiceStates می‌تواند اشتراک intent وضعیت صوتی را صریحا بازنویسی کند. آن را تنظیم‌نشده بگذارید تا intent از فعال‌سازی موثر صوتی پیروی کند.
• اگر voice.autoJoin چند ورودی برای همان guild داشته باشد، OpenClaw به آخرین کانال پیکربندی‌شده برای آن guild می‌پیوندد.
• voice.allowedChannels یک فهرست مجاز اقامت اختیاری است. آن را تنظیم‌نشده بگذارید تا /vc join بتواند وارد هر کانال صوتی مجاز Discord شود. وقتی تنظیم شود، /vc join، پیوستن خودکار هنگام راه‌اندازی و جابه‌جایی‌های وضعیت صوتی ربات به ورودی‌های فهرست‌شده { guildId, channelId } محدود می‌شوند. برای رد کردن همه پیوستن‌های صوتی Discord، آن را روی آرایه خالی تنظیم کنید. اگر Discord ربات را به بیرون از فهرست مجاز منتقل کند، OpenClaw آن کانال را ترک می‌کند و وقتی هدف پیوستن خودکار پیکربندی‌شده‌ای موجود باشد، دوباره به آن می‌پیوندد.
• voice.daveEncryption و voice.decryptionFailureTolerance مستقیما به گزینه‌های join در @discordjs/voice منتقل می‌شوند.
• اگر تنظیم نشده باشند، پیش‌فرض‌های @discordjs/voice برابر daveEncryption=true و decryptionFailureTolerance=24 هستند.
• OpenClaw برای دریافت صدای Discord به‌صورت پیش‌فرض از رمزگشای pure-JS با نام opusscript استفاده می‌کند. بسته بومی اختیاری @discordjs/opus توسط سیاست نصب pnpm این مخزن نادیده گرفته می‌شود تا نصب‌های عادی، مسیرهای Docker و آزمون‌های نامرتبط یک افزونه بومی را کامپایل نکنند. میزبان‌های اختصاصی عملکرد صوتی می‌توانند پس از نصب افزونه بومی، با OPENCLAW_DISCORD_OPUS_DECODER=native آن را فعال کنند.
• voice.connectTimeoutMs انتظار اولیه Ready در @discordjs/voice را برای تلاش‌های /vc join و پیوستن خودکار کنترل می‌کند. پیش‌فرض: 30000.
• voice.reconnectGraceMs کنترل می‌کند OpenClaw چه مدت منتظر بماند تا یک نشست صوتی قطع‌شده شروع به اتصال دوباره کند، پیش از آنکه آن را از بین ببرد. پیش‌فرض: 15000.
• در حالت stt-tts، پخش صوتی فقط به این دلیل که کاربر دیگری شروع به صحبت می‌کند متوقف نمی‌شود. برای جلوگیری از حلقه‌های بازخورد، OpenClaw هنگام پخش TTS ضبط صوت جدید را نادیده می‌گیرد؛ برای نوبت بعدی پس از پایان پخش صحبت کنید. حالت‌های بلادرنگ شروع صحبت گوینده را به‌عنوان سیگنال‌های barge-in به ارائه‌دهنده بلادرنگ ارسال می‌کنند.
• در حالت‌های بلادرنگ، اکوی بلندگوها به میکروفون باز می‌تواند شبیه barge-in به نظر برسد و پخش را قطع کند. برای اتاق‌های Discord پر‌اکو، voice.realtime.providers.openai.interruptResponseOnInputAudio: false را تنظیم کنید تا OpenAI روی صوت ورودی به‌صورت خودکار وقفه ایجاد نکند. اگر همچنان می‌خواهید رویدادهای شروع صحبت گوینده در Discord پخش فعال را قطع کنند، voice.realtime.bargeIn: true را اضافه کنید. پل بلادرنگ OpenAI کوتاه‌سازی‌های پخش کوتاه‌تر از voice.realtime.minBargeInAudioEndMs را به‌عنوان اکوی/نویز محتمل نادیده می‌گیرد و به‌جای پاک کردن پخش Discord، آن‌ها را به‌عنوان skipped ثبت می‌کند.
• voice.captureSilenceGraceMs کنترل می‌کند OpenClaw پس از آنکه Discord گزارش می‌دهد گوینده صحبت را متوقف کرده است، چه مدت منتظر بماند پیش از نهایی کردن آن قطعه صوتی برای STT. پیش‌فرض: 2500؛ اگر 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، fallback مشورت اجباری قطعه‌های رونویسی احتمالا ناقص را رد می‌کند، مانند متنی که به ... یا یک اتصال‌دهنده پایانی مثل and ختم می‌شود، به‌علاوه پایان‌بندی‌های آشکارا غیرقابل‌اقدام مانند “be right back” یا “bye”. وقتی این کار مانع یک پاسخ صف‌شده قدیمی شود، لاگ‌ها forced agent consult skipped reason=... را نشان می‌دهند.

راه‌اندازی opus بومی برای checkoutهای سورس: OC_I18N_900032 وقتی افزونه بومی ازپیش‌ساخته macOS arm64 بالادستی را می‌خواهید، برای Gateway از Node 22 استفاده کنید. اگر از زمان اجرای Node دیگری استفاده می‌کنید، نصب‌کننده اختیاری ممکن است به یک toolchain ساخت از سورس محلی node-gyp نیاز داشته باشد.

پس از نصب افزونه بومی، Gateway را با این دستور شروع کنید: OC_I18N_900033 لاگ‌های پرجزئیات صوتی باید discord voice: opus decoder: @discordjs/opus را نشان دهند. بدون فعال‌سازی env، یا اگر افزونه بومی وجود نداشته باشد یا روی میزبان بارگذاری نشود، OpenClaw مقدار discord voice: opus decoder: opusscript را لاگ می‌کند و دریافت صوت را از طریق fallback pure-JS ادامه می‌دهد.

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

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

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

نمونه قدیمی STT به‌همراه TTS: OC_I18N_900035 نمونه bidi بلادرنگ: OC_I18N_900036 صوت به‌عنوان افزونه نشست یک کانال موجود Discord: OC_I18N_900037 در حالت agent-proxy، ربات به کانال صوتی پیکربندی‌شده می‌پیوندد، اما نوبت‌های عامل OpenClaw از نشست و عامل مسیریابی‌شده عادی کانال هدف استفاده می‌کنند. نشست صوتی بلادرنگ نتیجه بازگشتی را دوباره در کانال صوتی می‌خواند. عامل ناظر همچنان می‌تواند طبق سیاست ابزار خود از ابزارهای پیام عادی استفاده کند، از جمله ارسال یک پیام جداگانه Discord اگر اقدام درست همین باشد.

شکل‌های مفید هدف:

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

نمونه OpenAI Realtime برای محیط‌های پر‌اکو: OC_I18N_900038 از این زمانی استفاده کنید که مدل پخش صدای خودش در 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 کیلوهرتز که به صدای 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 یعنی Discord یا VAD ارائه‌دهنده گفتار را گزارش کرده، اما OpenClaw هیچ پخش فعالی برای قطع کردن نداشته است. این نباید صدا را قطع کند.

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

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

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

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

عیب‌یابی

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

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

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

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

مرتبط