Discord

​

الإعداد السريع

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" },
    },
  },
}
JSON5
openclaw config patch --file ./discord.patch.json5 --dry-run
openclaw config patch --file ./discord.patch.json5
openclaw 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 discord
openclaw 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,
        },
      },
    },
  },
}

​

نموذج وقت التشغيل

• يملك 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 إلى الإجابة النهائية المرئية من المساعد، وتُرسل مرة واحدة. أما حمولات الوسائط والمكوّنات المنظمة فتظل متعددة الرسائل عندما يصدر الوكيل عدة حمولات قابلة للتسليم.

​

قنوات المنتديات

• أرسل رسالة إلى أصل المنتدى (channel:<forumId>) لإنشاء سلسلة نقاش تلقائيًا. يكون عنوان سلسلة النقاش هو أول سطر غير فارغ من الرسالة (مع اقتطاعه وفق حد Discord البالغ 100 محرف لأسماء سلاسل النقاش).
• استخدم openclaw message thread create لإنشاء سلسلة نقاش مباشرةً. لا تمرّر --message-id لقنوات المنتدى.

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

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

​

المكوّنات التفاعلية

• text وsection وseparator وactions وmedia-gallery وfile
• تسمح صفوف الإجراءات بما يصل إلى 5 أزرار أو قائمة تحديد واحدة
• أنواع التحديد: string وuser وrole وmentionable وchannel

• يجب أن تشير كتل 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: "Optional fallback text",
  components: {
    reusable: true,
    text: "Choose a path",
    blocks: [
      {
        type: "actions",
        buttons: [
          {
            label: "Approve",
            style: "success",
            allowedUsers: ["123456789012345678"],
          },
          { label: "Decline", style: "danger" },
        ],
      },
      {
        type: "actions",
        select: {
          type: "string",
          placeholder: "Pick an option",
          options: [
            { label: "Option A", value: "a" },
            { label: "Option B", value: "b" },
          ],
        },
      },
    ],
    modal: {
      title: "Details",
      triggerLabel: "Open form",
      fields: [
        { type: "text", label: "Requester" },
        {
          type: "select",
          label: "Priority",
          options: [
            { label: "Low", value: "low" },
            { label: "High", 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 },
          },
        },
      },
    },
  },
}

​

توجيه الوكلاء المستند إلى الأدوار

{
  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: {
          label: "auto",
          maxLines: 8,
          maxLineChars: 120,
          toolProgress: true,
          commentary: false,
        },
      },
    },
  },
}

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

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

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

{
  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: "نفد الرمز المميز",
      },
    },
  },
}

​

الأدوات وبوابات الإجراءات

• المراسلة: sendMessage، وreadMessages، وeditMessage، وdeleteMessage، وthreadReply
• التفاعلات: react، وreactions، وemojiList
• الإشراف: timeout، وkick، وban
• الحضور: setPresence

​

واجهة مستخدم المكونات بالإصدار الثاني

• يعيّن 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 عند وجود مكونات الإصدار الثاني.
• تُمنع معاينات عناوين URL العادية افتراضيًا. عيّن suppressEmbeds: false في إجراء رسالة عندما ينبغي توسيع رابط صادر واحد.

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

​

الصوت

​

القنوات الصوتية

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 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 ميزة اختيارية في إعدادات النص فقط؛ اضبط channels.discord.voice.enabled=true (أو احتفظ بكتلة channels.discord.voice موجودة) لتمكين أوامر /vc، وبيئة تشغيل الصوت، وهدف Gateway المسمى GuildVoiceStates. يمكن لـ channels.discord.intents.voiceStates تجاوز الاشتراك في الهدف صراحةً؛ اتركه من دون ضبط ليتبع حالة التمكين الفعلية للصوت.
• يتحكم voice.mode في مسار المحادثة. الوضع الافتراضي هو agent-proxy: تتولى واجهة صوتية أمامية في الوقت الفعلي توقيت الأدوار، والمقاطعة، والتشغيل، وتفوّض العمل الجوهري إلى وكيل OpenClaw الموجّه عبر openclaw_agent_consult، وتتعامل مع النتيجة كموجّه Discord مكتوب صادر عن ذلك المتحدث. يحتفظ 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، يستخدم التحويل من الكلام إلى نص 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 عند تنفيذ أعمال مساحة العمل، أو جلب الحقائق الحالية، أو البحث في الذاكرة، أو تنفيذ الإجراءات المدعومة بالأدوات.
• في وضع الوقت الفعلي agent-proxy لدى OpenAI، اضبط voice.realtime.requireWakeName: true لإبقاء صوت Discord في الوقت الفعلي صامتًا حتى يبدأ النسخ النصي أو ينتهي باسم تنبيه. يجب أن تتكون أسماء التنبيه المضبوطة من كلمة أو كلمتين. إذا لم يُضبط voice.realtime.wakeNames، يستخدم OpenClaw قيمة name للوكيل الموجّه إضافةً إلى OpenClaw، مع الرجوع إلى معرّف الوكيل إضافةً إلى OpenClaw عند التعذر. يؤدي التقييد باسم التنبيه إلى تعطيل الاستجابة التلقائية لمزوّد الوقت الفعلي، وتوجيه الأدوار المقبولة عبر مسار استشارة وكيل OpenClaw، وتقديم إقرار صوتي قصير عند التعرّف على اسم تنبيه في البداية من النسخ الجزئي قبل وصول النسخ النهائي.
• يقبل مزوّد OpenAI للوقت الفعلي أسماء أحداث Realtime 2 الحالية والأسماء البديلة القديمة المتوافقة مع Codex لأحداث إخراج الصوت والنسخ النصي، بحيث يمكن أن تنحرف لقطات المزوّد المتوافقة من دون إسقاط صوت المساعد.
• يتحكم voice.realtime.bargeIn في ما إذا كانت أحداث بدء المتحدث في Discord تقاطع التشغيل النشط في الوقت الفعلي. إذا لم يُضبط، فإنه يتبع إعداد مقاطعة صوت الإدخال لدى مزوّد الوقت الفعلي.
• يتحكم voice.realtime.minBargeInAudioEndMs في الحد الأدنى لمدة تشغيل المساعد قبل أن تؤدي مقاطعة في الوقت الفعلي من OpenAI إلى اقتطاع الصوت. القيمة الافتراضية: 250. اضبطه على 0 للمقاطعة الفورية في الغرف منخفضة الصدى، أو ارفعه لإعدادات مكبرات الصوت ذات الصدى الشديد.
• يتجاوز voice.tts قيمة messages.tts لتشغيل الصوت في وضع stt-tts فقط؛ وتستخدم أوضاع الوقت الفعلي voice.realtime.speakerVoice بدلًا منه. لاستخدام صوت من OpenAI في تشغيل Discord، اضبط voice.tts.provider: "openai" واختر صوتًا لتحويل النص إلى كلام ضمن voice.tts.providers.openai.speakerVoice. يُعد cedar خيارًا جيدًا ذا طابع صوتي ذكوري في نموذج OpenAI الحالي لتحويل النص إلى كلام.
• تنطبق تجاوزات systemPrompt الخاصة بكل قناة في 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 برنامج الترميز المضمّن libopus-wasm لاستقبال صوت Discord وتشغيل PCM الخام في الوقت الفعلي. وهو يتضمن إصدارًا مثبتًا من libopus المبني باستخدام WebAssembly ولا يتطلب إضافات opus أصلية.
• يتحكم voice.connectTimeoutMs في مدة الانتظار الأولية لحالة @discordjs/voice المسماة Ready لمحاولات /vc join والانضمام التلقائي. القيمة الافتراضية: 30000.
• يتحكم voice.reconnectGraceMs في المدة التي ينتظرها OpenClaw حتى تبدأ جلسة صوتية منقطعة الاتصال بإعادة الاتصال قبل إتلافها. القيمة الافتراضية: 15000.
• في وضع stt-tts، لا يتوقف تشغيل الصوت لمجرد أن مستخدمًا آخر بدأ الكلام. لتجنب حلقات التغذية الراجعة، يتجاهل OpenClaw التقاط صوت جديد أثناء تشغيل تحويل النص إلى كلام؛ تحدث بعد انتهاء التشغيل لبدء الدور التالي. تمرر أوضاع الوقت الفعلي بدايات المتحدثين كإشارات مقاطعة إلى مزوّد الوقت الفعلي.
• في أوضاع الوقت الفعلي، قد يبدو صدى مكبرات الصوت الداخل إلى ميكروفون مفتوح كمقاطعة ويوقف التشغيل. في غرف Discord شديدة الصدى، اضبط voice.realtime.providers.openai.interruptResponseOnInputAudio: false لمنع OpenAI من المقاطعة التلقائية عند وجود صوت إدخال. أضف voice.realtime.bargeIn: true إذا كنت لا تزال تريد أن تقاطع أحداث بدء المتحدث في Discord التشغيل النشط. يتجاهل جسر OpenAI للوقت الفعلي اقتطاعات التشغيل الأقصر من voice.realtime.minBargeInAudioEndMs باعتبارها على الأرجح صدى/ضوضاء، ويسجلها كمتخطاة بدلًا من مسح تشغيل Discord.
• يتحكم voice.captureSilenceGraceMs في المدة التي ينتظرها OpenClaw بعد أن يبلغ Discord عن توقف متحدث، قبل إنهاء ذلك المقطع الصوتي لتحويل الكلام إلى نص. القيمة الافتراضية: 2000؛ ارفعها إذا كان Discord يقسم فترات التوقف الطبيعية إلى نسخ جزئية متقطعة.
• عندما يكون ElevenLabs هو مزوّد تحويل النص إلى كلام المحدد، يستخدم تشغيل صوت Discord تحويل النص إلى كلام بالتدفق ويبدأ من تدفق استجابة المزوّد. أما المزوّدون الذين لا يدعمون التدفق فيرجعون إلى مسار الملف المؤقت المُركّب.
• يراقب OpenClaw حالات فشل فك تشفير الاستقبال ويتعافى تلقائيًا عبر مغادرة القناة الصوتية وإعادة الانضمام إليها بعد تكرر حالات الفشل ضمن فترة قصيرة.
• إذا أظهرت سجلات الاستقبال مرارًا DecryptionFailed(UnencryptedWhenPassthroughDisabled) بعد التحديث، فاجمع تقريرًا عن الاعتماديات والسجلات. يتضمن إصدار @discordjs/voice المضمّن إصلاح الحشو من طلب السحب رقم #11449 في discord.js، الذي أغلق المشكلة رقم #11419 في discord.js.
• تُعد أحداث الاستقبال The operation was aborted متوقعة عندما ينهي OpenClaw مقطعًا ملتقطًا للمتحدث؛ وهي تشخيصات تفصيلية وليست تحذيرات.
• تتضمن سجلات صوت Discord التفصيلية معاينة محدودة من سطر واحد لنسخ التحويل من الكلام إلى نص لكل مقطع متحدث مقبول، بحيث يُظهر تصحيح الأخطاء جانب المستخدم وجانب رد الوكيل من دون تفريغ نص نسخ غير محدود.
• في وضع agent-proxy، يتخطى الرجوع إلى الاستشارة الإلزامية أجزاء النسخ التي يُرجّح أنها غير مكتملة، مثل النص المنتهي بـ ... أو بأداة ربط ختامية مثل “و”، إضافةً إلى العبارات الختامية الواضحة التي لا تتطلب إجراءً مثل “سأعود حالًا” أو “وداعًا”. تعرض السجلات forced agent consult skipped reason=... عندما يمنع ذلك إجابة قديمة في الطابور.

​

متابعة المستخدمين في الصوت

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

• يقبل followUsers معرّفات مستخدمي Discord الخام وقيم discord:<id>. يوحّد OpenClaw كلا الشكلين قبل مطابقة أحداث الحالة الصوتية.
• تكون القيمة الافتراضية لـ followUsersEnabled هي true عند ضبط followUsers. اضبطها على false للاحتفاظ بالقائمة المحفوظة مع إيقاف المتابعة الصوتية التلقائية.
• عندما ينضم مستخدم متابَع إلى قناة صوتية مسموح بها، ينضم OpenClaw إلى تلك القناة. وعندما ينتقل المستخدم، ينتقل OpenClaw معه. وعندما ينقطع اتصال المستخدم المتابَع النشط، يغادر OpenClaw.
• إذا كان عدة مستخدمين متابَعين في الخادم نفسه وغادر المستخدم المتابَع النشط، ينتقل OpenClaw إلى قناة مستخدم متابَع آخر يجري تتبعه قبل مغادرة الخادم. وإذا انتقل عدة مستخدمين متابَعين في الوقت نفسه، يفوز آخر حدث حالة صوتية تمت ملاحظته.
• تظل allowedChannels سارية. يُتجاهل المستخدم المتابَع الموجود في قناة غير مسموح بها، وتنتقل الجلسة المملوكة للمتابعة إلى مستخدم متابَع آخر أو تغادر.
• يوفّق OpenClaw أحداث الحالة الصوتية الفائتة عند بدء التشغيل وعلى فاصل زمني محدود. تأخذ عملية التوفيق عينات من الخوادم المضبوطة وتضع حدًا لعمليات بحث REST في كل تشغيل، لذا قد تحتاج قوائم followUsers الكبيرة جدًا إلى أكثر من فاصل زمني واحد للوصول إلى الحالة المتسقة.
• إذا نقل Discord أو مسؤول البوت أثناء متابعته لمستخدم، يعيد OpenClaw بناء الجلسة الصوتية ويحافظ على ملكية المتابعة عندما تكون الوجهة مسموحًا بها. وإذا نُقل البوت خارج allowedChannels، يغادر OpenClaw ويعيد الانضمام إلى الهدف المضبوط عند وجوده.
• قد يغادر تعافي استقبال DAVE القناة نفسها ويعيد الانضمام إليها بعد تكرر حالات فشل فك التشفير. تحتفظ الجلسات المملوكة للمتابعة بملكية المتابعة عبر مسار التعافي هذا، ولذلك يؤدي انقطاع مستخدم متابَع لاحقًا إلى مغادرة القناة.

• استخدم followUsers للإعدادات الشخصية أو إعدادات المشغّلين التي ينبغي أن يوجد فيها البوت تلقائيًا في الصوت عندما تكون موجودًا.
• استخدم autoJoin لبوتات الغرف الثابتة التي ينبغي أن تبقى حاضرة حتى عندما لا يكون أي مستخدم متتبَّع في الصوت.
• استخدم /vc join لعمليات الانضمام لمرة واحدة أو للغرف التي سيكون فيها الوجود الصوتي التلقائي مفاجئًا.

• تعرض سجلات استقبال الصوت discord voice: opus decoder: libopus-wasm.
• يرمّز التشغيل في الوقت الفعلي PCM ستيريو خامًا بتردد 48 كيلوهرتز إلى Opus باستخدام حزمة libopus-wasm المضمّنة نفسها قبل تسليم الحزم إلى @discordjs/voice.
• يحوّل تشغيل الملفات وتدفقات المزوّد إلى PCM ستيريو خام بتردد 48 كيلوهرتز باستخدام ffmpeg، ثم يستخدم libopus-wasm لتدفق حزم Opus المرسلة إلى Discord.

• يُحوَّل التقاط PCM من Discord إلى ملف WAV مؤقت.
• تتولى tools.media.audio تحويل الكلام إلى نص (STT)، مثل openai/gpt-4o-mini-transcribe.
• تُرسل النسخة النصية عبر مسار الإدخال والتوجيه في Discord، بينما يعمل نموذج اللغة الكبير للاستجابة وفق سياسة إخراج صوتي تُخفي أداة الوكيل tts وتطلب إرجاع النص، لأن صوت Discord يتولى تشغيل تحويل النص إلى كلام (TTS) النهائي.
• عند تعيين voice.model، فإنه يتجاوز نموذج اللغة الكبير للاستجابة لهذه الجولة في القناة الصوتية فقط.
• يُدمج voice.tts فوق messages.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",
        },
      },
    },
  },
}

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

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

• يوجّه target: "channel:123456789012345678" عبر جلسة قناة نصية في Discord.
• يُعامل target: "123456789012345678" بوصفه هدف قناة.
• يوجّه target: "dm:123456789012345678" أو target: "user:123456789012345678" عبر جلسة الرسائل المباشرة تلك.

{
  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 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 أو لدى الجهة الموفرة أبلغ عن كلام، لكن لم يكن لدى OpenClaw تشغيل نشط لمقاطعته. لا ينبغي أن يؤدي ذلك إلى قطع الصوت.

​

الرسائل الصوتية

• وفّر مسار ملف محليًا (تُرفض عناوين URL).
• احذف المحتوى النصي (يرفض Discord النص والرسالة الصوتية في الحمولة نفسها).
• يُقبل أي تنسيق صوتي؛ ويحوّله OpenClaw إلى OGG/Opus عند الحاجة.

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

​

استكشاف الأخطاء وإصلاحها

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

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

{
  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_BOT_TOKEN في البيئات الخاضعة للإشراف).
• امنح أذونات Discord وفق مبدأ أقل قدر من الامتيازات.
• إذا كانت حالة نشر الأوامر/حالَتها قديمة، فأعد تشغيل Gateway ثم أعد التحقق باستخدام openclaw channels status --probe.

​

مواضيع ذات صلة