免费开源AI桌宠AIRI上手：安装配置与二次元角色定制指南

最近在折腾桌面美化时发现了一个挺有趣的玩法把 AI 装进桌宠里养一只会聊天、会陪打游戏的二次元角色。AIRI 这个开源项目就在这段时间热度涨得很快简单说它把一个 AI 对话模型和桌面宠物整合到了一起不需要自己写复杂的代码下载安装就能用。这篇文章我会完整梳理 AIRI 桌宠从下载、安装、配置到日常使用的全过程。适合零基础的新手也适合想了解桌面端 AI 应用怎么做的开发者。如果你正好在找一款免费、可自定义的 AI 桌宠或者对桌宠开发有兴趣这篇应该能帮你省不少时间。1. 背景与核心概念1.1 什么是 AI 桌宠桌宠是桌面宠物Desktop Pet的简称很多人小时候可能用过 QQ 宠物或者是早期系统里的 Office 助手那就是最早的桌宠形态。桌宠的本质是一个常驻在桌面的小窗口角色可以拖动位置、播放动画、响应鼠标操作甚至执行一些系统功能。AI 桌宠是在传统桌宠的基础上接入了大语言模型LLM和语音能力。也就是说这个角色不再只是播放预设动画而是能理解你的输入、组织语言回复你甚至根据对话内容改变表情和动作。AIRI 就是这样一款项目角色形象是二次元风格内核通过大模型驱动日常状态可以当作桌面宠物聊天时可以当作 AI 陪伴角色。1.2 AIRI 项目解决什么问题传统桌宠最大的问题是“宠而不聊”角色只是动画循环播放无法对用户的话做出有意义的回应。而纯粹的 AI 聊天应用又缺少桌面陪伴感打开网页聊天关掉之后就消失了。AIRI 把两者做了结合主要解决三个痛点陪伴形式更自然角色一直待在桌面上用户随时能看到、能互动。聊天不再需要打开额外页面直接在桌宠窗口输入AI 回复同步显示。可定制性强因为是开源项目角色形象、对话风格、接入的模型都可以调整。1.3 应用场景有哪些从我自己的使用体验和社区反馈来看AIRI 常见的应用场景有这几类桌面陪伴写代码、办公、学习时放在屏幕角落缓解独处时的枯燥感。游戏互动游戏等待界面、游戏加载时聊天或者打完一局后和桌宠复盘几句。AI 助手角色扮演按自己的喜好设定角色性格比如温柔的、毒舌的、活泼的。技术学习对开发者来说这也是一个学习桌面端 AI 应用开发的参考项目。本文标题里提到的“AI 女友”实际是用户自定义角色性格后的一种用法。AIRI 本身是一个开源桌宠框架你完全可以把它配置成助手、伙伴或者其他任意角色不必局限于默认设定。2. 环境准备与版本说明2.1 支持平台根据项目仓库提供的信息AIRI 桌面端目前主要面向 Windows 和 macOS 用户仓库里可以看到对应的安装包文件标志为“ai小镇_macw”说明 Mac 和 Windows 都有构建产物。无论你使用哪个系统建议先满足下面的基础条件环境项建议要求说明操作系统Windows 10 及以上 / macOS 12 及以上低版本系统可能缺少必要的运行库网络可正常访问 AI 模型 API 服务需要网络连接才能完成对话硬件CPU 正常即可内存建议 8G 以上对话推理在云端完成对本地算力要求不高账号AI 模型服务商 API Key用于模型调用常见的如 DeepSeek、OpenAI 兼容接口等2.2 关于模型接口AIRI 这类桌宠应用通常并不会内置模型能力而是通过配置模型 API 的方式接入 AI 对话服务。也就是说你使用哪个大模型取决于你在配置文件里填写哪个服务的接口地址和 Key。国内用户比较方便的选择包括 DeepSeek、Kimi、智谱等平台它们大多提供 OpenAI 兼容接口配置时基本是同样的格式。如果你只是本地体验也可以关注项目仓库是否支持本地模型方案但默认推荐优先使用在线 API稳定性会更好。注意不同模型的 API 价格、速率限制、内容安全策略不同实际使用时请以服务商官方文档为准。不要把自己 API Key 写入公开分享的配置里避免造成额度损失。2.3 开源项目信息AIRI 对应的 GitHub 仓库是https://github.com/mewamew/my_ai_town仓库名称 my_ai_town 直译为“我的 AI 小镇”AIRI 是这个小城镇中的核心角色。README 中一般会给出最新版本的下载链接、运行说明和常见功能。建议在下载前先打开仓库确认一下版本状态因为开源项目更新迭代可能比较快以仓库里的最新说明为准最稳妥。3. 下载与安装3.1 从哪里下载因为这是一个开源项目优先推荐从 GitHub Releases 页面下载安装包避免从第三方渠道拿到被修改过的软件。在项目主页中找到 Releases 入口在里面选择匹配你系统的文件Windows 用户选择.exe或.msi安装包macOS 用户选择.dmg文件如果你的网络访问 GitHub 比较慢也可以在项目 README 中查看是否提供了国内镜像或其他下载方式。这里还是要提醒一下下载桌面软件一定要从官方或开源仓库给出的地址下载不要使用来源不明的安装包。3.2 Windows 安装步骤下载完成后双击安装包正常情况下会进入安装向导。流程大致是阅读并同意用户协议。选择安装目录默认路径即可。点击安装等待进度条完成。安装完成后桌面或开始菜单会出现 AIRI 的快捷方式。首次启动时Windows SmartScreen 可能会弹出蓝色提示窗口提示“已保护你的电脑”。这是因为项目还没有购买代码签名证书属于开源软件的常见情况。如果你确认安装包是从 GitHub 官方 Releases 下载的可以点击“更多信息” - “仍要运行”继续启动。3.3 macOS 安装步骤macOS 用户下载.dmg文件后双击打开把应用拖入 Applications 文件夹即可。首次打开时macOS 的 Gatekeeper 可能会拦截未签名应用提示“无法打开因为无法验证开发者”。此时可以右键点击应用图标选择“打开”在弹出的对话框中点击“打开”。或者在“系统设置” - “隐私与安全性”中找到被拦截的应用点击“仍要打开”。如果你在 macOS 上遇到应用图标显示“已损坏”通常是因为 macOS 验证策略比较严格和网络下载来源有关。需要确认下载文件是否完整必要时重新下载。这里不建议为了绕过系统限制而随意关闭 SIP除非你完全清楚自己的操作和风险。3.4 验证安装是否成功把安装流程模拟成命令行操作的话你可以这样理解# Windows 下启动假设安装在默认目录 cd C:\Users\你的用户名\AppData\Local\Programs\my_ai_town .\AIRI.exe # macOS 下启动 cd /Applications/my_ai_town.app/Contents/MacOS ./my_ai_town实际使用时你直接点击快捷方式启动就行不需要真的执行这些命令。这里只是帮助你找到应用的真实路径方便后续排查问题。启动成功后屏幕上应该出现一个二次元形象的小窗口此时应用主体已经正常运行。接下来的核心任务是配置 AI 模型接口否则桌宠只能展示动画没办法跟你聊天。4. 核心配置接入 AI 模型4.1 为什么需要配置模型AIRI 的角色动画是本地渲染的但对话能力依赖大语言模型。没有模型接口它就只能“看”不能“说”。所以要让它真正陪你聊天必须把模型 API 配置好。从架构上看AIRI 的对话流程是用户输入文字 - 调用模型 API - 模型返回文本 - 桌宠窗口显示回复 - 触发表情/动作这个流程决定了你需要准备两样东西一个可用的模型 API Key。服务商提供的接口地址Base URL。4.2 获取 API Key这里我们以 OpenAI 兼容接口为例演示获取 Key 的通用思路。不同平台的流程可能略有差异但核心逻辑是一样的注册并登录模型服务平台如 DeepSeek 开放平台。进入控制台或 API Keys 管理页面。创建一个新的 API Key创建后立即复制保存因为很多平台只在创建时展示一次。确认账户有余额或已开通免费额度。注意安全原则API Key 等同于你的账户凭证不要把它提交到公开仓库、不要分享到聊天群、不要截图发到社交网络。如果发现 Key 泄露第一时间到平台吊销并重新生成。4.3 配置文件说明AIRI 大部分配置都集中在应用目录下的配置文件中。具体文件名和路径根据版本不同可能略有差异常见的有config.json、settings.json或.env文件。一个典型的模型配置结构如下{ model: { provider: openai-compatible, base_url: https://api.deepseek.com/v1, api_key: sk-你的API密钥, model_name: deepseek-chat, temperature: 0.8 }, character: { name: AIRI, personality: 温柔、活泼、喜欢陪你聊天, greeting: 今天想聊点什么呀 } }字段含义说明provider模型服务商类型这里使用openai-compatible表示兼容 OpenAI 接口格式。base_url模型接口地址由服务商提供。api_key你自己的密钥。model_name要使用的具体模型名称。temperature回复随机性值越大越发散越小越稳定。character.name角色名称。character.personality角色性格描述大模型会参考这段描述组织回复。character.greeting桌宠启动后的第一句问候语。4.4 注意事项配置完成后通常需要重启应用才能生效。如果你修改了性格描述最好也重启一下或者查看应用是否提供“重新加载配置”的按钮。如果重启后聊天没有反应可以先检查这几个点API Key 是否填错了空格。base_url末尾是否带了/v1不同平台要求不同。模型名称是否和服务商支持的名称一致比如有些平台是deepseek-chat有些是gpt-4o。网络是否能正常访问到服务商接口。不同版本的项目配置字段可能会有变化。上面的 JSON 是一个通用示例实际字段名请以项目 README 或配置文件默认内容为准。不要在不确定的情况下强行套用否则可能出现“配置了但没生效”的情况。5. 进阶使用让它成为会陪你玩游戏的角色5.1 常驻桌面与窗口置顶AIRI 作为桌宠可以常驻桌面。建议在设置中开启以下选项开机自动启动每次开机后桌宠自动出现。窗口置顶让桌宠始终悬浮在其他窗口上方方便随时互动。鼠标穿透在不互动时鼠标点击会穿透桌宠区域不影响你操作下层窗口。这几个设置项可以极大提升日常使用体验。如果不开启“窗口置顶”打开游戏或浏览器全屏后可能看不到桌宠如果不开启“鼠标穿透”桌宠占用的那块区域可能会挡住你的游戏操作。5.2 玩游戏时怎么互动AIRI 能够陪你玩游戏主要体现在几个方面第一种等待阶段陪伴。很多游戏加载、排队、匹配需要等待这时候切到桌宠窗口聊几句比对着进度条发呆舒服很多。第二种语音/文字快速交互。如果 AIRI 支持语音输入你可以直接用语音喊话不必打字。如果没有语音支持就使用文字输入框但要注意打字会占用一小会儿时间适合游戏暂停或死亡等待恢复的时候。第三种自定义角色设定。你可以给桌宠设置一个“游戏搭子”人格比如{ character: { personality: 你是一个资深的游戏玩家熟悉主流的竞技游戏和单机游戏喜欢和用户讨论游戏攻略输了会安慰用户赢了会夸用户操作好。 } }这样聊起来更有场景感相当于给它增加了一个“游戏达人”的身份。5.3 自定义外观与动作AIRI 使用的角色模型和动画机制如果支持替换你可以尝试自己改外观素材。项目如果基于通用模型格式读取动画文件的目录通常会在项目文档里说明。需要注意替换素材前先备份原文件。图片、动画资源有格式和大小要求不要随意改后缀直接替换。如果项目支持社区模型可以去官方指定渠道找其他人分享的制作素材。如果你打算自己制作或修改模型还需要一点基本的动画资源处理知识建议先从官方文档给出的工具链入手。6. 常见问题与排查思路6.1 常见问题汇总根据社区反馈和个人实操经验我整理了下面这些常见问题问题现象常见原因解决思路应用启动后没有桌宠出现快捷方式启动失败或窗口被隐藏检查任务管理器/活动监视器是否有进程重新启动桌宠出现了但不回复消息未配置 API Key或配置错误打开配置文件检查模型配置项回复速度很慢模型接口响应慢或网络延迟高更换网络环境或换一个低延迟模型桌宠挡住游戏画面未开启鼠标穿透在设置中开启鼠标穿透模式启动时系统报病毒/未知开发者开源软件未签名确认下载来源按系统提示信任应用修改配置后没有变化未重启应用重启应用或调用重新加载配置功能角色不说话只有文案未开启语音功能或语音服务未配置查看项目文档按需配置 TTS 语音服务API Key 泄漏分享截图或误提交仓库立即到平台吊销并重新生成6.2 启动失败的排查流程如果你双击应用后什么反应都没有可以按下面的顺序排查去任务管理器Windows或活动监视器macOS看看进程是否存在。如果进程存在但没窗口可能是窗口被隐藏或渲染异常尝试在系统托盘区查找图标。如果进程不存在说明启动过程崩溃。去应用日志目录查看错误日志通常logs或error.log文件里会有线索。删除配置文件恢复默认设置后再试一次。如果这时能启动说明是配置问题。检查系统版本是否符合要求必要时升级系统或安装缺少的运行库。6.3 模型配置的常见坑模型配置是用户踩坑最多的地方。最常见的三个坑如下坑一base_url 填晚。有些平台需要以/v1结尾有些不需要。如果你发现配置正确但请求报错先检查这个路径。坑二模型名写错。不要自己猜模型名称去平台文档里确认。比如 DeepSeek 的接口不同时期模型名可能不同。坑三温度参数不生效。如果你想让角色回复更稳定但调了temperature没有变化可能是因为这个参数在代码里没有透传给 API或者被项目固定写死了。这时候只能改代码如果是开源项目或者接受默认值。7. 最佳实践与工程建议7.1 从用户角度日常使用建议如果你只是把 AIRI 当桌宠使用我建议关注这几点API Key 安全不要把 Key 写进分享的配置片段里定期更换。用量控制大模型 API 按 Token 计费如果每天长时间高频聊天需要注意余额变化。可以在设置里减少单次对话的最大 Token 数降低成本。性格设定越具体越好想让角色更符合预期性格描述尽量具体。可以给出角色经历、说话习惯、喜好甚至不允许它聊的话题而不是只写“活泼、可爱”。7.2 从开发者角度二次开发建议AIRI 是开源项目如果你和我一样有一定编程基础可以从这几个层面去学习和扩展了解桌面端应用的基础架构。打开项目源码看看它用了什么技术栈。这类应用通常包含一个桌面窗口层负责渲染角色和显示界面。一个逻辑层负责接收用户输入、组织对话请求、处理回复。一个配置管理层负责读取和保存用户设置。接入更多模型。OpenAI 兼容接口的好处是几乎市面上主流大模型都支持这种协议。你在代码里只需要改base_url、api_key、model_name三个字段就能切换不同的模型服务商。增加语音输出能力。如果你想让它“开口说话”可以考虑接入 TTS语音合成服务。流程一般如下# 下面是一个最小示例思路将模型回复文本传入 TTS 服务 # 实际实现需要根据你选择的 TTS 服务商调整 def text_to_speech(text: str, output_file: str): import requests # 伪代码真实实现需要按服务商文档写 tts_url https://api.tts.example.com/v1/synthesize payload { text: text, voice: female_01, format: mp3 } # 请求 TTS 接口并保存音频文件 # resp requests.post(tts_url, jsonpayload) # 将返回的音频数据写入 output_file pass做一个本地知识库增强。如果你希望桌宠“懂你”可以把你的聊天记录、笔记、个人资料整理成向量库在调用大模型之前先做检索增强RAG这样角色回复会更贴合你的实际情况。7.3 关于安全与合规最近 AI 桌宠这类应用非常火但火的同时也存在很多灰色地带。我的建议是只使用正规、开源、可审计的桌宠项目。不下载“破解版”“无限制版”等来源不明的改造包。不把 AI 角色用于发布违规内容、绕过内容过滤或从事不当行为。涉及 API Key、个人数据、聊天记录注意本地存储安全性。AI 陪伴应用本身是正常的娱乐和学习工具但我们要把它用在合理、安全的范围内。开源项目的价值在于透明这也是我优先推荐 AIRI 这类开源项目的原因。8. 总结AIRI 是一个把二次元桌宠和大模型能力结合起来的开源项目下载安装门槛很低重点是配置好模型 API。配置完成之后你就能拥有一个常驻桌面、可聊天、可定制性格的 AI 角色。对于想要进一步学习桌面端 AI 应用开发的开发者来说这个项目也是一个很好的学习样本。从窗口渲染、模型调用、配置管理到角色系统每个部分都可以拆开研究并根据自己的需要做二次开发。下一步你可以这样继续先下载安装跑通默认效果再根据自己的喜好调整角色性格接着尝试接入不同的模型服务最后再去阅读源码理解它底层的实现原理。桌宠看似只是一个小玩具但把它背后的 AI 接入、桌面交互、实时渲染串起来能学到的东西其实不少。如果这篇文章对你有帮助可以收藏备用也欢迎在评论区交流你的配置和使用问题。