5分钟跑通自托管 AI 伴侣：AIRI 实时语音与游戏陪玩完整指南-育师

5分钟跑通自托管 AI 伴侣：AIRI 实时语音与游戏陪玩完整指南

【免费下载链接】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

如果你想要一个可以实时对话、能陪你打游戏、并且完全跑在自己设备上的 AI 伴侣，AIRI 是个值得动手试的项目。这是一个开源的自托管 AI 伴侣系统：你用自己的模型 API 密钥给它装上"大脑"，它就能以虚拟角色的形态活在浏览器、桌面或移动设备里，支持语音对话、Minecraft 与 Factorio 游戏互动。下面按"先选路、再上手、后调优"的顺序，带你从零走到能用。

🎮 它能陪你做什么

先看几个真实使用场景，判断它是否适合你。

游戏陪玩：AIRI 通过 Mineflayer 等库接入游戏服务器，能接收游戏内上下文、执行动作并回传状态。你打 Minecraft 时它可以在旁边"看局"并给出建议，玩 Factorio 时它可以协助你管理产线。相关能力在 integrations/ 目录下，Minecraft 与 Factorio 均有独立文档。适合喜欢单人游戏、想有"队友感"的玩家。

语音陪伴：它不只是文字聊天。配置语音合成（TTS，让角色能开口说）和语音识别（ASR，让角色能听懂你说话）后，交互从打字变成对话，还支持判断"你是否正在说话"，打断感更自然。适合习惯语音输入、或想把它当桌宠长期挂着的人。

多端随身：同一个角色可以同时有 Web 版、桌面版和移动端，网页、桌面、移动共享大量基础设施。你在办公室用浏览器聊两句，回家切到桌面端看 3D 模型，配置体验是连贯的。

🧭 按需求选部署路径

三条路径的区别，本质是"你想要的掌控度"和"愿意折腾的程度"。只体验选 Web 版，想要模型常驻和完整功能选桌面端，要完全自主（比如接本地模型、改代码）再上自托管。

浏览器里直接用

最快的方式：打开 AIRI 的 Web 版本，按提示填好模型 API 密钥，就能开始聊天。所有渲染和交互都在浏览器完成，零安装。缺点是深度功能（如部分游戏智能体）不在 Web 端。适合第一次接触、想验证"这东西到底什么体验"的人。

桌面客户端

功能最全的一条路：桌面端支持 Live2D（2D 纸片人模型）和 VRM（3D 模型）常驻屏幕，还有系统托盘、窗口穿透、悬停淡化这类桌宠式交互。Windows 直接下载安装包，macOS 可以走 Homebrew（brew install --cask airi），Linux 用 AppImage 或 Snap。需要长期陪伴、希望性能最好的用户选这条。

从源码自托管

要接 Ollama 本地模型、改角色逻辑或部署机器人时，从源码启动：

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

pnpm 是这个 monorepo 的包管理器，装完依赖用pnpm dev启动开发服务器即可。这条路自由度最高，但你也得自己处理升级和环境问题。

🚀 首次运行：从密钥到第一次对话

按顺序做四步，做完就能聊上。

1. 领一个模型 API 密钥。在 OpenAI、Claude、DeepSeek、Gemini 等服务商中挑一个（项目也支持 Ollama 和任何 OpenAI 兼容接口的站点），在它的控制台创建 API Key。如果你用的是 OpenAI 兼容接口，还会要一个 Base URL，也就是模型的"服务地址"——直接抄服务商文档里的默认值，别自己猜。

2. 填入设置。打开应用的设置页，进入服务商配置，选择聊天类服务商，粘贴密钥并完成验证。这一步的详细字段说明见服务商配置指南。

3. 指定大脑模型。在"意识"配置里选一个刚验证过的服务商和模型作为 AIRI 的大脑。小建议：带深度思考模式的模型回一条消息可能要等很久，日常对话选非思考模型会流畅得多。

4. 发起第一条对话。回到首页，输入框里说句话。正常的话，几秒后你就能收到角色风格的回复，第一次对话完成。

🕹️ 上手体验：把功能挂到场景里

让它开口、让它听见。进"设置 → 机体模块"，配置"发声"（语音合成）和"听觉"（语音转文字）。浏览器自带的转文字对中文支持不完整，通常要手动新增一个 TTS/ASR 服务商再回来选择。配完后在对话框点麦克风图标，选定麦克风并开启转文字，之后就可以直接跟它说话，嘈杂环境下的语音也有噪音过滤加持。

用角色卡定义它的性格。AIRI 内置了一张叫 ReLU 的角色卡，你也可以自己写。角色卡定义了角色的名字、性格、说话方式，甚至能为不同模块指定不同的模型——换个角色卡，相当于换个"人"，模型配置一起切换。想改语气、改偏好，从这里入手。

把它放进游戏。以 Minecraft 为例：在integrations/minecraft下把.env复制成.env.local，填好服务器地址和模型配置，然后启动：

pnpm -F @proj-airi/minecraft-bot dev

启动后智能体同时连上 AIRI 和你的 Minecraft 服务器，开始接收上下文、执行动作。接入步骤和注意事项在 Minecraft 集成文档里有完整说明。

把角色搬进 IM。仓库里还有 Discord 与 Telegram 机器人，流程一致：各自目录下配置.env.local填 Token 和模型凭据，用 pnpm 启动对应包。这样伴侣就从"你打开应用才在"变成"你随时找得到"。

📦 生产部署与调优

想把 Web 版长期挂在服务器上，项目里自带 Dockerfile，构建和运行各一条命令：

docker build -t airi-web -f apps/stage-web/Dockerfile .

docker run -d -p 3000:80 --name airi airi-web

构建阶段用 Node 24 编译前端，运行阶段是 nginx 容器，访问 3000 端口即可。需要区分环境时，可通过VITE_ENABLE_ANALYTICS等构建参数控制行为。

几条调优与安全经验：

性能：按设备选模型。Web 端 4GB 内存的现代设备可跑，桌面端建议 8GB 以上，游戏功能对显卡有要求。
记忆与上下文：上下文长度别拉满，够用就行，省资源也省 token 费用。
密钥管理：API Key、Bot Token、游戏凭据只放本地.env.local，不要提交、截图或发到 Issue 里——官方文档对每条集成都专门强调了这点。
版本：保持更新，安全修复和模型兼容都在跟进。