AIRI Discord Bot 集成指南将 AIRI 接入 Discord 实现文字与语音对话【免费下载链接】airi Self hosted, you-owned Grok Companion, a container of souls of waifu, cyber livings to bring them into our worlds, wishing to achieve Neuro-samas altitude. Capable of realtime voice chat, Minecraft, Factorio playing. Web / macOS / Windows supported.项目地址: https://gitcode.com/GitHub_Trending/ai/airi导读本指南基于 AIRI 仓库中的 integrations/discord-bot 集成服务与官方文档 docs/content/en/docs/integrations/discord.md完整讲解如何把 AIRI 作为语音与消息机器人接入 Discord 服务器。读完本文你将掌握在 Discord Developer Portal 创建应用与 Bot、配置 Bot Token 与 AIRI Auth Token、通过 AIRI 桌面端的Settings → Modules → Discord面板下发配置、使用/ping与/summon命令完成文字回复与语音对话以及语音转写STT与文本回复背后依赖 AIRI 自身聊天配置的原理。架构总览一个独立的 Discord 适配服务AIRI 的 Discord 集成不是一个直接嵌入 AIRI 客户端的插件而是一个独立的 Node.js 服务通过 WebSocket 与 AIRI 主程序通信。整体调用链如下Discord 侧使用 discord.js 建立 Gateway 连接监听消息MessageCreate、斜杠命令交互InteractionCreate与语音状态GuildVoiceStates。AIRI 侧通过proj-airi/server-sdk的ServerChannel客户端建立 WebSocket 通道订阅input:text、input:text:voice、input:voice、module:configure、output:gen-ai:chat:message等事件见 airi-adapter.ts。配置下发AIRI 桌面端把 Bot Token 与启用状态经module:configure事件推送给服务服务收到后动态登录或重连 Discord 客户端。回复回传AIRI 生成回复后经output:gen-ai:chat:message事件回传服务按 channelId 找到对应频道并发送文本。因此Discord 文本回复使用的是 AIRI 当前激活的聊天提供方与模型chat provider 和 model而不是 Discord Bot 自身的任何模型配置。前置条件在开始之前请确认以下条件在仓库根目录执行pnpm i安装依赖。在 Discord Developer Portal 创建 Application 与 Bot。在 Bot 设置中启用Message Content Intent消息内容意图。在 AIRI 中配置一个可用的聊天提供方chat provider与模型。::: warning 凭据安全 Bot Token 与 AIRI Auth Token 只能存放在 AIRI 本地设置或 Bot 服务本地的.env.local文件中切勿提交到版本库、截图或分享这些凭据。 :::配置 Bot 服务1. 创建本地环境变量文件cp integrations/discord-bot/.env integrations/discord-bot/.env.local2. 获取并填写 AIRI 凭据在桌面版 AIRI 中打开Settings → Connection显示并复制Auth Token然后写入integrations/discord-bot/.env.localAIRI_URLws://localhost:6121/ws AIRI_TOKENAuth Token from Settings → ConnectionAIRI_URLAIRI WebSocket 服务地址默认ws://localhost:6121/ws端口 6121 是 AIRI 本地服务的默认端口。AIRI_TOKEN用于向 AIRI 服务鉴权的 Auth Token。3. 关于其他环境变量的说明DISCORD_TOKEN是可选的启动回退startup fallback可以留空服务连接后由 AIRI 通过配置通道下发 Bot Token。以下变量虽然出现在模板.env中但不会被服务使用DISCORD_BOT_CLIENT_IDOPENAI_MODEL、OPENAI_API_KEY、OPENAI_API_BASE_URLELEVENLABS_API_KEY、ELEVENLABS_API_BASE_URL原因在于 Discord 文本回复直接使用 AIRI 的激活聊天配置。不过如果要用语音输入则必须配置一个 OpenAI 兼容的转写端点OPENAI_STT_API_BASE_URLyour transcription endpoint base url OPENAI_STT_API_KEYyour api key OPENAI_STT_MODELmodel name, e.g. whisper-1这三项对于文本频道不是必需的但没有它们语音转写无法完成。从源码看语音转写通过openaiTranscribe调用createOpenAI(env.OPENAI_STT_API_KEY, env.OPENAI_STT_API_BASE_URL)并使用generateTranscription生成文本见 tts.ts。启动服务pnpm -F proj-airi/discord-bot start该命令在integrations/discord-bot包中定义tsx --env-file.env --env-file-if-exists.env.local src/index.ts见 package.json。tsx负责直接运行 TypeScript 源码--env-file-if-exists.env.local让.env.local中的值覆盖.env。入口文件 src/index.ts 创建DiscordAdapter并启动同时注册SIGINT/SIGTERM优雅关闭钩子。start()会先尝试用环境变量中的DISCORD_TOKEN登录若没有 Token则进入“等待 UI 下发配置”状态见 airi-adapter.ts。在 AIRI 中配置 Discord打开Settings → Modules → Discord。将 Bot Token 粘贴到Bot Token字段。打开Enable Discord Integration。点击Save。保存后AIRI 会通过配置通道module:configure事件把启用状态与 Token 下发给已认证的 Bot 服务。源码中的isDiscordConfig类型守卫会校验tokenstring与enabledboolean字段并据此执行三种分支见 airi-adapter.tsenabled false销毁当前 Discord 客户端。enabled但无 Token记录警告并停止 Bot。有 Token 且与当前不同或客户端未就绪销毁旧客户端并重新login。注意如果服务没有运行或服务的 AIRI Auth Token 缺失/错误仅保存这些字段不会启动 Discord Bot。此外配置处理期间设有isReconnecting锁正在重连时会忽略新的配置事件避免并发重连。在 Discord 中安装与使用 Bot安装与权限在 Discord Developer Portal 配置Guild Install使用botscope 将 Bot 安装到服务器。botscope 默认包含applications.commands。只授予功能所需的最小权限文字回复View Channels与Send Messages。语音输入View Channels与Connect。语音播放Speak。文字聊天向 Bot 发送私信DM或在服务器频道中 提及 Bot。Bot 不会响应服务器中的每一条消息——源码中的MessageCreate处理器明确判断isMentioned || isDM才响应见 airi-adapter.ts。提及时的处理细节值得注意Bot 会把提及从消息中剥离/!?\d/g正则只把纯文本内容发送给 AIRI。同时构建包含channelId、guildId、guildName、guildMember的 Discord 上下文并计算会话 ID服务器内消息 →discord-guild-guildId私信 →discord-dm-memberId这样同一个服务器频道的多轮对话可以共享同一会话见 airi-adapter.ts。AIRI 的回复经output:gen-ai:chat:message事件回传后服务按channelId取频道并发送文本超过 Discord 单条消息 2000 字符上限时会按换行、空格边界分块发送见 airi-adapter.ts。语音对话加入一个语音频道。运行/summonBot 会加入你所在的语音频道。服务在 Bot 登录后自动注册/ping与/summon两个斜杠命令见 commands/index.ts。/ping简单回复 Pong!/summon由VoiceManager.handleJoinChannelCommand处理先检查调用者是否在语音频道不在则回复 Please join a voice channel first.否则调用joinChannel加入频道见 summon.ts。语音转写与播放的实现原理从源码看语音处理链路相当完整见 summon.ts加入与状态管理joinVoiceChannel建立连接通过entersState等待Ready/Signalling状态20 秒超时断线时尝试 5 秒内重连否则销毁连接并清理见 [summon.ts](https://link.gitcode.com/i/fd2e40741cfa1cf7511f355c9717923c#L96-L128, L165-L221)。说话检测connection.receiver.speaking监听start/end事件对非 Bot 用户启动音频监控monitorMember。音频解码OpusDecoder以 16 kHz 单声道解码DECODE_SAMPLE_RATE 16000见 constants/audio.ts随后convertOpusToWav生成 44 字节 WAV 头并拼接 PCM 数据见 utils/audio.ts。防重叠barge-inmonitorMember在播放期间持续监测用户音量30 帧滑动窗口平均音量超过 0.05 阈值时立即停止当前播放实现用户说话打断 AI见 summon.ts。转写去抖语音数据按用户缓存进userStates说话结束后等待 1.5 秒静默DEBOUNCE_TRANSCRIPTION_THRESHOLD 1500才触发转写减少碎片转写见 summon.ts。转写结果处理有效转写不含[BLANK_AUDIO]标记通过input:text:voice与input:text两个事件发送给 AIRI实现听与说的闭环见 summon.ts。语音播放createAudioPlayerNoSubscriberBehavior.PausecreateAudioResourceStreamType.Arbitrary播放 AIRI 返回的音频流见 summon.ts。常见问题排查部分频道可用、部分不可用检查频道级权限覆盖channel-level permission overrides确保目标频道授予了所需权限。服务已运行但 Bot 不响应确认 AIRI 侧Enable Discord Integration已开启、Auth Token 正确保存配置时留意服务日志中的module:configure处理记录。语音转写无结果检查OPENAI_STT_API_BASE_URL、OPENAI_STT_API_KEY、OPENAI_STT_MODEL三项是否配置完整转写端点是否 OpenAI 兼容。多频道会话混乱会话按 guild 隔离同一服务器的文本对话共享上下文跨服务器互不干扰。安全注意事项将 Bot 的访问范围限制在其所需频道与能力上遵循最小权限原则。若 Bot Token 丢失或泄露立即在 Discord Developer Portal 重置并同步更新 AIRISettings → Modules → Discord中的 Bot Token。Bot Token 与 AIRI Auth Token 仅存放于.env.local与 AIRI 本地设置避免提交、截图或分享。总结AIRI 的 Discord 集成由 integrations/discord-bot 这个独立服务承载它在 AIRI 与 Discord 之间充当桥梁文本回复复用 AIRI 的聊天配置与模型语音侧则依靠 OpenAI 兼容 STT 端点完成转写再通过discordjs/voice完成解码、播放与打断barge-in。整个体系的核心配置只有寥寥几个环境变量与一个 UI 开关但底层涵盖了语音流式处理、会话隔离、断线重连等工程细节可以作为二次开发与自托管部署的直接参考。【免费下载链接】airi Self hosted, you-owned Grok Companion, a container of souls of waifu, cyber livings to bring them into our worlds, wishing to achieve Neuro-samas altitude. Capable of realtime voice chat, Minecraft, Factorio playing. Web / macOS / Windows supported.项目地址: https://gitcode.com/GitHub_Trending/ai/airi创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考