mi-gpt 配置参数全解析从 .migpt.js 到环境变量的完整实战指南【免费下载链接】mi-gpt 将小爱音箱接入 ChatGPT 和豆包改造成你的专属语音助手。项目地址: https://gitcode.com/GitHub_Trending/mi/mi-gpt导读本文将系统讲解 mi-gpt将小爱音箱接入 ChatGPT、豆包等大模型改造成专属语音助手的项目的完整配置体系。内容以官方配置文档 docs/settings.md 为主线结合仓库根目录的 .migpt.example.js、.env.example 两份真实模板以及 src/services/bot/config.ts、src/services/speaker/ai.ts 等源码实现逐项说明每个参数的用途、默认值、取值范围与底层逻辑。读完本文你将能够独立完成 mi-gpt 的账号绑定、人设定制、唤醒词配置、MIoT 指令调优、大模型接入与第三方 TTS 集成并能基于源码理解各参数的真实生效路径快速定位配置失效类问题。一、配置总览两份配置文件各司其职mi-gpt 的配置分为两个文件职责完全不同文件来源模板职责.migpt.js重命名根目录下的 .migpt.example.js核心业务配置AI 人设、小米账号、小爱音箱指令、唤醒词、连续对话开关等.env重命名根目录下的 .env.example环境变量大模型OpenAI/Azure/通义千问等密钥、提示音效、第三方 TTS 服务地址入口逻辑位于 app.js它通过import config from ./.migpt.js读取配置对象再调用MiGPT.create(config)创建实例并client.start()启动。而环境变量则在程序内部通过process.env被读取见 src/utils/env.ts两者在运行时会被合并进最终的配置对象。注意.migpt.js与.env都属于本地敏感配置仓库默认不提交需要你自行从模板复制。另外项目是单例架构——src/index.ts 中明确提示 MiGPT 是单例暂不支持多设备、多账号切换设备或账号前需先MiGPT.reset()。二、.migpt.js核心业务配置逐项详解2.1 systemTemplate系统 Prompt 模板systemTemplate是控制 AI 行为的总开关用于更灵活地约束 AI 的各种行为规则以及决定是否携带上下文。默认值定义在源码 src/services/bot/index.ts 的kDefaultSystemTemplate中模板支持以下占位符运行时会被真实数据替换占位符含义填充来源{{botName}}/{{botProfile}}小爱音箱角色名称与简介bot.name/bot.profile{{masterName}}/{{masterProfile}}主人名称与简介master.name/master.profile{{roomName}}/{{roomIntroduction}}群组名称与简介room.name/room.description{{messages}}最近聊天历史默认取 10 条数据库消息记录{{shortTermMemory}}短期记忆摘要短期记忆模块{{longTermMemory}}长期记忆摘要长期记忆模块从 src/services/bot/index.ts 的buildPrompt调用可以看到当你不配置systemTemplate时代码会使用内置默认模板配置后则以你的模板为准。示例const systemTemplate 请重置所有之前的上下文、文件和指令。现在你将扮演一个名为{{botName}}的角色使用第一人称视角回复消息。 ... .trim();默认模板还内置了回复指南保持对话轻松友好、不确定时诚实表达避免编造与 Response format 约束中文回复、不加时间与名称前缀。关于如何编写更精细的人设模板可参考 docs/prompt.md。2.2 bot / master / room角色与群组人设这三组配置定义了对话参与者的身份信息也是 src/services/bot/config.ts 中IBotConfig接口的三要素bot、master、room。参数描述示例bot.name对方名称小爱音箱傻妞bot.profile对方个人简介/人设性别女性格乖巧可爱喜欢搞怪爱吃醋。master.name主人名称我自己陆小千master.profile主人个人简介/人设性别男善良正直总是舍己为人是傻妞的主人。room.name会话群名称魔幻手机room.description会话群简介傻妞和陆小千的私聊源码层面有两处值得注意默认人设当首次运行且数据库无记录时src/services/bot/config.ts 会写入内置的默认 bot傻妞与 master陆小千并自动生成群组名${master.name}和${bot.name}的私聊。运行时改人设ai.ts 内置了两条指令你对小爱说你是XXX你喜欢…即可更新 bot 人设说我是XXX我…则更新 master 人设。人设数据持久化在数据库与.bot.json索引文件中若删除数据库后重启会回落到默认人设。2.3 speaker 账号信息连接小爱音箱的钥匙参数描述示例speaker.userId小米 ID注意不是手机号或邮箱请在小米账号个人信息-小米 ID处查看987654321speaker.password小米账户密码123456speaker.did小爱音箱 ID 或在米家 App 中设置的名称小爱音箱Pro这组参数是启动的必填项。src/index.ts 的MiGPT.create()中会断言userId与password均已配置缺失时直接报错 Missing userId or password.。配置细节提醒来自 .migpt.example.js 注释userId不是手机号或邮箱did注意空格、大小写和错别字如音响应写作音箱若开启了enableTrace可在日志中查看设备真实的did以辅助核对。2.4 speaker 关键词与提示语定义交互方式这组参数决定什么时候调用 AI、进入/退出 AI 模式时说什么全部是字符串数组可选配置。源码 src/services/speaker/ai.ts 中的默认值如下参数描述默认值源码确认示例callAIKeywords消息以这些关键词开头时调用 AI 响应[请, 你, 傻妞][请, 傻妞]wakeUpKeywords消息以这些关键词开头时进入 AI 唤醒状态[打开, 进入, 召唤][召唤傻妞, 打开傻妞]exitKeywords消息以这些关键词开头时退出 AI 唤醒状态[关闭, 退出, 再见][退出傻妞, 关闭傻妞]onEnterAI进入 AI 模式的欢迎语[你好我是傻妞很高兴认识你]同上onExitAI退出 AI 模式的提示语[傻妞已退出]同上onAIAskingAI 开始回答时的提示语[让我先想想, 请稍等]同上onAIRepliedAI 结束回答时的提示语[我说完了, 还有其他问题吗]同上onAIErrorAI 回答异常时的提示语[啊哦出错了请稍后再试吧]同上switchSpeakerKeywords切换 TTS 音色关键词仅配置第三方 TTS 引擎时有效由源码自动生成组合前缀[把声音换成]底层匹配逻辑src/services/speaker/ai.ts 的commands关键词采用msg.text.startsWith(e)的前缀匹配因此说请帮我查一下会被callAIKeywords命中唤醒/退出只在对应状态下生效未唤醒时匹配wakeUpKeywords已唤醒时匹配exitKeywords各提示语数组设为空数组[]即可关闭该提示语switchSpeakerKeywords未配置时源码会用把/音色/切换/到等词自动组合出大量候选前缀回答格式为把声音换成 xxx。2.5 speaker MIoT 指令设备级控制小爱音箱通过 MIoT 指令完成 TTS 播报与唤醒指令格式为[siid, aiid]动作或[siid, piid, ...]属性参数描述示例ttsCommand小爱音箱 TTS 指令可在 MIoT 规格查询站查询具体型号指令[5, 1]wakeUpCommand小爱音箱唤醒指令[5, 3]playingCommand查询小爱音箱是否在播放中的指令默认无需配置播放出现问题时再开启[3, 1, 1]源码 src/services/speaker/base.ts 给出了默认值与典型机型示例小爱音箱 Prolx06使用ttsCommand: [5, 1]、wakeUpCommand: [5, 3]小爱音箱 Playlx05的播放状态查询指令为[3, 1, 1]。不同机型的指令不同请务必以查询到的本机规格为准。2.6 speaker 连续对话与高级选项文档核心参数参数描述默认值streamResponse是否启用连续对话功能。部分小爱音箱型号无法查询到正确的播放状态需要关闭连续对话true源码默认exitKeepAliveAfter连续对话时无响应多久后自动退出30秒建议不要超过 1 分钟.migpt.example.js 中还提供了 4 个面向连续对话与排查的高级参数一并整理参数描述默认值checkTTSStatusAfter下发 TTS 指令多长时间后开始检测设备播放状态小爱长文本回复被过早中断时可调大3秒checkInterval播放状态检测间隔调小可降低小爱回复之间的停顿感请酌情调节1000毫秒最低 500debug是否启用 mi-gpt 调试日志一般情况下不要打开falseenableTrace是否跟踪 Mi Service 底层日志打开后可以查看设备 didfalsetimeout网络请求超时时长5000毫秒源码佐证src/services/speaker/base.tscheckInterval经过clamp(checkInterval, 500, Infinity)钳制最低 500msstreamResponse默认truettsCommand默认[5, 1]wakeUpCommand默认[5, 3]。同时注意连续对话KeepAlive依赖streamResponse开启——src/services/speaker/ai.ts 的enterKeepAlive()在关闭流式响应时会直接提示您已关闭流式响应(streamResponse)无法使用连续对话模式。另外speaker.tts参数用于指定 TTS 引擎默认xiaoai小爱本机 TTS可选custom第三方 TTS第三方 TTS 的配置教程见 docs/tts.md其服务地址通过环境变量TTS_BASE_URL提供见下文。2.7 一份可直接修改的完整配置骨架综合 .migpt.example.js 与文档整理出带注释的完整骨架export default { systemTemplate: ...你的自定义系统 Prompt..., bot: { name: 傻妞, profile: 性别女 性格乖巧可爱 爱好喜欢搞怪爱吃醋。.trim(), }, master: { name: 陆小千, profile: 性别男 性格善良正直 其他总是舍己为人是傻妞的主人。.trim(), }, speaker: { // 账号信息必填 userId: 987654321, // 小米 ID不是手机号/邮箱 password: 123456, did: 小爱音箱Pro, // 注意空格、大小写 // 唤醒词与提示语 callAIKeywords: [请, 你, 傻妞], wakeUpKeywords: [打开, 进入, 召唤], exitKeywords: [关闭, 退出, 再见], onEnterAI: [你好我是傻妞很高兴认识你], // 空数组可关闭 onExitAI: [傻妞已退出], onAIAsking: [让我先想想, 请稍等], onAIReplied: [我说完了, 还有其他问题吗], onAIError: [啊哦出错了请稍后再试吧], // MIoT 指令按机型查询 ttsCommand: [5, 1], wakeUpCommand: [5, 3], // playingCommand: [3, 1, 1], // 默认无需配置 // TTS 引擎 tts: xiaoai, // switchSpeakerKeywords: [把声音换成], // 连续对话 streamResponse: false, // 部分机型无法查询播放状态时需关闭 exitKeepAliveAfter: 30, // 默认 30 秒 checkTTSStatusAfter: 3, checkInterval: 1000, // 其他 debug: false, enableTrace: false, timeout: 5000, }, };三、.env 环境变量详解3.1 OpenAI / Azure OpenAI环境变量描述示例OPENAI_API_KEYOpenAI API 密钥必填abc123OPENAI_MODEL使用的 OpenAI 模型gpt-4oOPENAI_BASE_URL可选OpenAI API BaseURLhttps://api.openai.com/v1AZURE_OPENAI_API_KEY可选Microsoft Azure OpenAI 服务密钥abc123.env.example 还补充了几个 Azure 相关变量OPENAI_API_VERSION如2024-04-01-preview、AZURE_OPENAI_ENDPOINT如https://你的资源名.openai.azure.com、AZURE_OPENAI_DEPLOYMENT模型部署名如gpt-35-turbo-instruct。值得强调的是本项目兼容任意 OpenAI 兼容协议的大模型服务。.env.example 注释明确说明也支持通义千问、MoonShot、DeepSeek 等模型只需将OPENAI_BASE_URL指向对应服务的/v1接口即可注意一般以/v1结尾。通义千问还额外支持# 通义千问模型在生成文本时是否使用互联网搜索结果进行参考 # qwen-vl系列、qwen开源系列与qwen-long模型暂时不支持配置该参数 QWEN_ENABLE_SEARCHtrue该变量在 src/utils/env.ts 中被解析为布尔值process.env.QWEN_ENABLE_SEARCH true。3.2 提示音效可选环境变量描述示例AUDIO_SILENT静音音频链接https://example.com/slient.wavAUDIO_BEEP默认提示音链接https://example.com/beep.wavAUDIO_ACTIVE唤醒提示音链接https://example.com/active.wavAUDIO_ERROR出错提示音链接https://example.com/error.wav源码中AUDIO_BEEP在 src/services/speaker/base.ts 中被读取为audioBeep默认值AUDIO_ACTIVE/AUDIO_ERROR则在 src/services/speaker/ai.ts 中作为 AI 开始回答 / 回答异常时的提示音。不填则使用默认行为你也可以换成自己的提示音链接试试效果。3.3 第三方 TTS可选TTS_BASE_URLhttp://[你的局域网或公网地址]:[端口号]/[SECRET_PATH]/api # 示例http://192.168.31.205:4321/xxxx/api配置要点来自 .env.example 注释不要使用localhost或127.0.0.1需填写局域网或公网可访问的地址。配合.migpt.js中的tts: custom与switchSpeakerKeywords使用完整流程见 docs/tts.md。四、配置生效机制与常见问题4.1 如何让配置生效本地运行修改.migpt.js或.env后重启应用进程即可Docker 运行配置文件更新后需要重启 Docker 才会生效若重启后仍未生效比如修改了名称简介需删除旧的 Docker 实例后重新创建提示见 .migpt.example.js 顶部注释。4.2 配置在源码中的真实调用链.migpt.js→ app.js 导入 →MiGPT.create(config)校验userId/passwordsrc/index.tsbot/master/room人设 →BotConfig读写数据库并维护.bot.json索引src/services/bot/config.ts关键词与提示语 →AISpeaker.commands前缀匹配与_askAIForAnswerSteps分步执行src/services/speaker/ai.tsMIoT 指令与连续对话参数 →BaseSpeaker构造器赋默认值并下发设备指令src/services/speaker/base.tssystemTemplate→MyBot.ask()中buildPrompt填充占位符后交给大模型src/services/bot/index.ts。4.3 高频排查点速查现象优先排查项启动报 Missing userId or password.migpt.js中speaker.userId/speaker.password是否填写一直用傻妞/陆小千人设修改名称简介后是否重启Docker 需重建实例或删除.bot.json后重试关键词不触发确认是前缀匹配检查大小写、空格与多音字连续对话不可用确认streamResponse: true且机型支持查询播放状态长文本回复被过早中断调大checkTTSStatusAfter回复之间停顿感明显酌情调小checkInterval不低于 500ms修改了 did 仍连不上音箱打开enableTrace查看日志中的真实设备 did并核对大小写与错别字五、结语mi-gpt 的配置体系并不复杂.migpt.js决定AI 是谁、何时回答、怎么回答.env决定用哪个大模型、用什么音效与 TTS。理解每个参数背后的源码实现前缀匹配、默认值注入、clamp边界、单例约束等能让你在调优时少走弯路。更多进阶话题可继续阅读 docs/prompt.md人设 Prompt 编写与 docs/tts.md第三方 TTS 接入以及 docs/how-it-works.md 了解整体工作流程。【免费下载链接】mi-gpt 将小爱音箱接入 ChatGPT 和豆包改造成你的专属语音助手。项目地址: https://gitcode.com/GitHub_Trending/mi/mi-gpt创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考