AIRI：自托管 AI 虚拟伴侣的部署与配置指南

【免费下载链接】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-sama's altitude. Capable of realtime voice chat, Minecraft, Factorio playing. Web / macOS / Windows supported. 项目地址: https://gitcode.com/GitHub_Trending/ai/airi

AIRI 是一个开源的自托管 AI 虚拟伴侣项目：给它接入一个大模型 API，它就能以 VRM/Live2D 形象和你实时语音对话、在 Minecraft 里陪你打游戏，还能接进 Telegram、Discord。适合想把虚拟角色跑在自己机器上、数据完全自己掌控的开发者。

💖 功能全景

• 实时语音交互：客户端做语音识别和说话检测，多厂商 TTS 合成语音（ElevenLabs、Azure、OpenAI 兼容、本地 Kokoro）。对着麦克风说话，它会转成文字再作答，整条链路在你本机完成。
• 多模态形象驱动：支持 VRM 和 Live2D 模型，带自动眨眼、视线跟随、待机眼神游移。模型不是"贴图"，而是会看你、会眨眼的。
• 游戏 Agent：内置 Minecraft 机器人（四层认知架构：感知-反射-推理-执行），Factorio 也有 PoC demo。它是真的进游戏操作，不是查攻略。
• 跨平台入口：Web、桌面（Windows/macOS/Linux）、移动 PWA（Stage Pocket）多端可用，桌面版可直接调 NVIDIA CUDA 或 Apple Metal 做本地推理。
• 多平台聊天：通过 integrations 目录下的 Telegram / Discord bot 模块，把它拉进群聊。

🚀 上手路径

路径 A：浏览器直接体验

打开官方 Web 版 airi.moeru.ai，按引导填一个模型提供商的 API Key 就能开始对话。所有识别和推理都在浏览器侧跑，零安装。适合先花 5 分钟确认这个交互方式是不是你要的。

路径 B：桌面应用安装

macOS 和 Windows 都有包管理器一键装法：

# macOS（Homebrew Cask）
brew install --cask airi

# Windows（winget）
winget install MoeruAI.AIRI

装完首次启动会弹 onboarding 向导，按提示配好模型即可。桌面版是功能最全的形态，托盘常驻、窗口可拖动到屏幕任意位置。

路径 C：源码运行或 Docker 自托管

需要 pnpm 环境，pnpm dev 默认启动 Web 版开发服务器，桌面版用 pnpm dev:tamagotchi：

git clone https://gitcode.com/GitHub_Trending/ai/airi
cd airi
pnpm install
pnpm dev

apps/stage-web/Dockerfile 是现成的两阶段构建（Node 构建 + nginx 运行），自建镜像：

docker build -t airi-web -f apps/stage-web/Dockerfile .
docker run -d -p 3000:80 airi-web

注意这是纯前端部署，模型 API 仍在客户端配置，服务端不经过你的 Key。适合想自己发一份 Web 入口、控制静态资源的情况。

🎮 核心体验

实时语音对话

在首页对话框点麦克风图标，选择麦克风并打开转写开关即可开聊。效果上：你说完一句，角色嘴型随 TTS 播报同步驱动，整轮"听到→思考→说出口"的延迟基本在 2 秒内。文档明确提示浏览器自带 STT 对中文支持不完整，中文场景建议按 配置语音合成 另加一个 TTS/ASR 来源，内置 Kokoro TTS 本身不支持中文。

桌面宠物模式

桌面版可以脱离主窗口，把角色单独悬浮在桌面上，右键托盘菜单能调整位置、大小、淡入淡出。实际效果：你可以把它钉在屏幕角落，写代码时抬头就能跟它说一句，它还能通过视觉模块"看到"你的屏幕。

游戏里的 Agent

Minecraft 模块跑一个 Mineflayer 机器人，架构分四层：原始事件进感知层，反射层做状态机，推理层由 LLM 负责规划和对话，执行层落地成动作。把它接进你自己的服务器，它能在你旁边跑图、建东西、聊天。README 里有一句安全提醒很实在：别连不信任的公开服务器，因为它执行的是真实进程操作。目前该服务在计划迁移到 Fabric mod 方案。

进阶配置

• 模型提供商 — 设置里选厂商、填 Key 和 Base URL — 支持 OpenAI、Claude、DeepSeek、Gemini、Ollama、LM Studio 等 30+ 家，换模型不用换架构
• 角色卡 — 编辑名称、性格、行为描述，且每张卡可绑定独立的模型配置 — 切换角色卡 = 一键换人设 + 换模型
• 听觉/发声 — 分别配 ASR 和 TTS 来源 — 中文体验的关键项，务必配第三方
• 视觉 — 开启屏幕捕获让角色"看"你的屏幕 — 占用会上升，按需开

安全上三件事：API Key 只存在你本机（浏览器 localStorage 或应用配置），不要把自托管页面暴露到公网后裸奔 Key；桌面版麦克风权限走系统弹窗，macOS 拒绝后要去"系统设置-隐私"里重新放行；数据目录在本地，卸载前自己备份角色卡和对话记录。

踩坑与排障

• 现象：配好模型后回复很慢，有时几十秒 原因：选了带思考（thinking）功能的模型 解决：在模型列表里换成非思考模型，对话流畅度立刻上来

• 现象：中文语音转写经常断句错误或缺字 原因：用了浏览器内置 STT，中文支持不完整 解决：听觉设置里新增一个第三方 ASR 来源并选为默认

• 现象：语音是英文腔，读中文很怪 原因：默认 Kokoro TTS 不支持中文 解决：发声设置里 + 新增一个支持中文的 TTS 来源

• 现象：macOS 桌面版点了麦克风没反应 原因：首次启动时拒绝了麦克风权限 解决：系统设置 → 隐私与安全性 → 麦克风，给 AIRI 打勾后重启应用

生态与资源

• packages/core-agent/ — AI 核心循环，Agent 主逻辑所在
• integrations/minecraft/ — Minecraft bot 的接入配置与四层认知架构文档
• integrations/telegram-bot/ — Telegram 机器人，带 docker-compose 和 drizzle 数据库迁移
• apps/stage-web/ — Web 端应用，含 Dockerfile
• docs/content/zh-Hans/docs/ — 中文文档，提供商配置一页一家

社区走 Discord 和 Telegram 群（README 顶部有入口），翻译在 Crowdin 上开放。近期 DevLog 的方向集中在移动端性能、VRM 场景生命周期，以及 Factorio/KSP 更多游戏的接入。

下一步建议

先跑通路径 A 确认语音对话体验符合预期，再装桌面版配中文 TTS/ASR；想要数据全控或定制角色卡时，再走路径 C 的源码构建。Minecraft 这类重依赖模块留到你有一台稳定机器时再开。

【免费下载链接】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-sama's altitude. Capable of realtime voice chat, Minecraft, Factorio playing. Web / macOS / Windows supported. 项目地址: https://gitcode.com/GitHub_Trending/ai/airi