​

Discord (Bot API)

​

Hızlı kurulum

export DISCORD_BOT_TOKEN="YOUR_BOT_TOKEN"
openclaw config set channels.discord.token --ref-provider default --ref-source env --ref-id DISCORD_BOT_TOKEN --dry-run
openclaw config set channels.discord.token --ref-provider default --ref-source env --ref-id DISCORD_BOT_TOKEN
openclaw config set channels.discord.enabled true --strict-json
openclaw gateway

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

DISCORD_BOT_TOKEN=...

openclaw pairing list discord
openclaw pairing approve discord <CODE>

​

Önerilen: Bir sunucu çalışma alanı kurun

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

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

​

Çalışma zamanı modeli

• Discord bağlantısının sahibi gateway’dir.
• Yanıt yönlendirmesi deterministiktir: Discord’dan gelen yanıtlar tekrar Discord’a gider.
• Varsayılan olarak (session.dmScope=main), doğrudan sohbetler ajanın ana oturumunu paylaşır (agent:main:main).
• Sunucu kanalları yalıtılmış oturum anahtarlarıdır (agent:<agentId>:discord:channel:<channelId>).
• Grup DM’leri varsayılan olarak yok sayılır (channels.discord.dm.groupEnabled=false).
• Yerel slash komutları yalıtılmış komut oturumlarında çalışır (agent:<agentId>:discord:slash:<userId>), ancak yine de CommandTargetSessionKey değerini yönlendirilen konuşma oturumuna taşır.

​

Forum kanalları

• Bir ileti dizisini otomatik oluşturmak için forum üst öğesine (channel:<forumId>) mesaj gönderin. İleti dizisi başlığı, mesajınızın ilk boş olmayan satırını kullanır.
• Doğrudan bir ileti dizisi oluşturmak için openclaw message thread create kullanın. Forum kanalları için --message-id geçmeyin.

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"

​

Etkileşimli bileşenler

• text, section, separator, actions, media-gallery, file
• Eylem satırları en fazla 5 düğmeye veya tek bir seçim menüsüne izin verir
• Seçim türleri: string, user, role, mentionable, channel

• file blokları bir ek başvurusuna işaret etmelidir (attachment://<filename>)
• Eki media/path/filePath ile sağlayın (tek dosya); birden çok dosya için media-gallery kullanın
• Yükleme adının ek başvurusu ile eşleşmesi gerektiğinde bunu geçersiz kılmak için filename kullanın

• En fazla 5 alanla components.modal ekleyin
• Alan türleri: text, checkbox, radio, select, role-select, user-select
• OpenClaw otomatik olarak bir tetikleyici düğme ekler

{
  channel: "discord",
  action: "send",
  to: "channel:123456789012345678",
  message: "İsteğe bağlı fallback metni",
  components: {
    reusable: true,
    text: "Bir yol seçin",
    blocks: [
      {
        type: "actions",
        buttons: [
          {
            label: "Onayla",
            style: "success",
            allowedUsers: ["123456789012345678"],
          },
          { label: "Reddet", style: "danger" },
        ],
      },
      {
        type: "actions",
        select: {
          type: "string",
          placeholder: "Bir seçenek seçin",
          options: [
            { label: "Seçenek A", value: "a" },
            { label: "Seçenek B", value: "b" },
          ],
        },
      },
    ],
    modal: {
      title: "Ayrıntılar",
      triggerLabel: "Formu aç",
      fields: [
        { type: "text", label: "Talep eden" },
        {
          type: "select",
          label: "Öncelik",
          options: [
            { label: "Düşük", value: "low" },
            { label: "Yüksek", value: "high" },
          ],
        },
      ],
    },
  },
}

​

Erişim denetimi ve yönlendirme

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

​

Role dayalı ajan yönlendirme

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

​

Developer Portal kurulumu

​

Yerel komutlar ve komut kimlik doğrulaması

• commands.native varsayılan olarak "auto" değerindedir ve Discord için etkindir.
• Kanal başına geçersiz kılma: channels.discord.commands.native.
• commands.native=false, önceden kaydedilmiş Discord yerel komutlarını açıkça temizler.
• Yerel komut kimlik doğrulaması, normal mesaj işlemeyle aynı Discord izin listelerini/ilkelerini kullanır.
• Komutlar, yetkili olmayan kullanıcılar için Discord arayüzünde yine de görünür olabilir; yürütme yine de OpenClaw kimlik doğrulamasını uygular ve “not authorized” döndürür.

• ephemeral: true

​

Özellik ayrıntıları

{
  channels: {
    discord: {
      streaming: "partial",
    },
  },
}

{
  channels: {
    discord: {
      streaming: "block",
      draftChunk: {
        minChars: 200,
        maxChars: 800,
        breakPreference: "paragraph",
      },
    },
  },
}

{
  session: {
    threadBindings: {
      enabled: true,
      idleHours: 24,
      maxAgeHours: 0,
    },
  },
  channels: {
    discord: {
      threadBindings: {
        enabled: true,
        idleHours: 24,
        maxAgeHours: 0,
        spawnSubagentSessions: false, // isteğe bağlı olarak açılır
      },
    },
  },
}

{
  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_...", // isteğe bağlı; özel sistemler için gereklidir
      },
    },
  },
}

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

{
  channels: {
    discord: {
      activity: "Odak zamanı",
      activityType: 4,
    },
  },
}

{
  channels: {
    discord: {
      activity: "Canlı kodlama",
      activityType: 1,
      activityUrl: "https://twitch.tv/openclaw",
    },
  },
}

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

​

Araçlar ve eylem kapıları

• mesajlaşma: sendMessage, readMessages, editMessage, deleteMessage, threadReply
• tepkiler: react, reactions, emojiList
• moderasyon: timeout, kick, ban
• presence: setPresence

​

Components v2 UI

• channels.discord.ui.components.accentColor, Discord bileşen kapsayıcılarında kullanılan vurgu rengini ayarlar (hex).
• Hesap başına channels.discord.accounts.<id>.ui.components.accentColor ile ayarlayın.
• components v2 mevcut olduğunda embeds yok sayılır.

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

​

Ses kanalları

• Yerel komutları etkinleştirin (commands.native veya channels.discord.commands.native).
• channels.discord.voice yapılandırın.
• Botun hedef ses kanalında Connect + Speak izinlerine ihtiyacı vardır.

{
  channels: {
    discord: {
      voice: {
        enabled: true,
        autoJoin: [
          {
            guildId: "123456789012345678",
            channelId: "234567890123456789",
          },
        ],
        daveEncryption: true,
        decryptionFailureTolerance: 24,
        tts: {
          provider: "openai",
          openai: { voice: "alloy" },
        },
      },
    },
  },
}

• voice.tts, yalnızca ses oynatımı için messages.tts değerini geçersiz kılar.
• Ses transkript turları, sahip durumunu Discord allowFrom (veya dm.allowFrom) üzerinden türetir; sahip olmayan konuşmacılar yalnızca sahibin kullanabildiği araçlara erişemez (örneğin gateway ve cron).
• Ses varsayılan olarak etkindir; devre dışı bırakmak için channels.discord.voice.enabled=false ayarlayın.
• voice.daveEncryption ve voice.decryptionFailureTolerance, @discordjs/voice katılma seçeneklerine olduğu gibi aktarılır.
• @discordjs/voice varsayılanları, ayarlanmamışsa daveEncryption=true ve decryptionFailureTolerance=24 değerleridir.
• OpenClaw ayrıca alma tarafındaki şifre çözme hatalarını izler ve kısa bir zaman penceresinde yinelenen hatalardan sonra ses kanalından ayrılıp yeniden katılarak otomatik kurtarma yapar.
• Alma günlükleri tekrar tekrar DecryptionFailed(UnencryptedWhenPassthroughDisabled) gösteriyorsa, bu discord.js #11419 içinde izlenen yukarı akış @discordjs/voice alma hatası olabilir.

​

Sesli mesajlar

• Bir yerel dosya yolu sağlayın (URL’ler reddedilir).
• Metin içeriğini atlayın (Discord aynı yükte metin + sesli mesaja izin vermez).
• Her türlü ses biçimi kabul edilir; gerektiğinde OpenClaw bunu OGG/Opus’a dönüştürür.

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

​

Sorun giderme

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

{
  channels: {
    discord: {
      accounts: {
        default: {
          eventQueue: {
            listenerTimeout: 120000,
          },
          inboundWorker: {
            runTimeoutMs: 1800000,
          },
        },
      },
    },
  },
}

​

Yapılandırma başvuru işaretçileri

• Configuration reference - Discord

• başlangıç/kimlik doğrulama: enabled, token, accounts.*, allowBots
• ilke: groupPolicy, dm.*, guilds.*, guilds.*.channels.*
• komut: commands.native, commands.useAccessGroups, configWrites, slashCommand.*
• olay kuyruğu: eventQueue.listenerTimeout (listener bütçesi), eventQueue.maxQueueSize, eventQueue.maxConcurrency
• inbound worker: inboundWorker.runTimeoutMs
• yanıt/geçmiş: replyToMode, historyLimit, dmHistoryLimit, dms.*.historyLimit
• teslimat: textChunkLimit, chunkMode, maxLinesPerMessage
• akış: streaming (eski takma ad: streamMode), draftChunk, blockStreaming, blockStreamingCoalesce
• medya/yeniden deneme: mediaMaxMb, retry
  • mediaMaxMb giden Discord yüklemelerini sınırlar (varsayılan: 100MB)
• eylemler: actions.*
• presence: activity, status, activityType, activityUrl
• UI: ui.components.accentColor
• özellikler: threadBindings, üst düzey bindings[] (type: "acp"), pluralkit, execApprovals, intents, agentComponents, heartbeat, responsePrefix

​

Güvenlik ve işlemler

• Bot token’larını gizli bilgiler olarak ele alın (denetimli ortamlarda DISCORD_BOT_TOKEN tercih edilir).
• En az ayrıcalık ilkesine göre Discord izinleri verin.
• Komut dağıtımı/durumu bayatsa, gateway’i yeniden başlatın ve openclaw channels status --probe ile tekrar kontrol edin.

​

İlgili

• Eşleştirme
• Gruplar
• Kanal yönlendirme
• Güvenlik
• Çoklu ajan yönlendirme
• Sorun giderme
• Slash commands