Project AIRI（0.12.0-beta.5）桌面端使用与配置完全指南：安装、界面操作、角色卡与机体模块实战

Project AIRI（0.12.0-beta.5）桌面端使用与配置完全指南：安装、界面操作、角色卡与机体模块实战

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

本篇指南以 Project AIRI 官方《说明书》（AIRI-0.12.0-beta.5 版）为主体，结合仓库源码与配套配置文档，系统讲解 AIRI 从下载安装、聊天服务商初始化、界面与系统托盘操作，到角色卡、机体模块、角色模型、服务来源与系统设置的完整使用链路。读完本文，你将能够独立完成 AIRI 桌面端的安装与首次配置，掌握主窗口、托盘、设置界面的每一项操作，并为角色配置意识、发声、听觉、视觉、绘图与 MCP 等能力。

版本说明：本文对应 AIRI-0.12.0-beta.5。仓库中桌面端应用 apps/stage-tamagotchi/package.json 的version字段即0.12.0-beta.5，与说明书一致。该说明书由社区团队（沐玖芸萱工作室）编写并提交至官方文档，主要覆盖 Windows 桌面端与部分网页端特性；版本更新可能改变部分界面与功能，实际体验请以你当前运行的版本为准。

第一章 · 安装：按平台选择正确的发行版

前往 Project AIRI 最新发行版的Assets区，下载与你的设备对应的文件后打开安装包按提示完成安装。下表中<版本号>会随最新发行版变化，请以实际为准。

发行版命名规则（源码佐证）

上述产物命名并非随手编写，而是由 electron-builder 配置模板决定。在 apps/stage-tamagotchi/electron-builder.config.ts 中：

• Windows 使用 NSIS 安装器，产物模板为${productName}-${version}-windows-${arch}-setup.${ext}，即AIRI-0.12.0-beta.5-windows-x64-setup.exe；
• macOS DMG 模板为${productName}-${version}-darwin-${arch}.${ext}，对应darwin-arm64（Apple 芯片）与darwin-x64（Intel）两个架构；
• Linux 同时产出deb与rpm两类包，模板为${productName}-${version}-linux-${arch}.${ext}。

也就是说，同一版本号下，各平台与 CPU 架构的产物文件名差异完全由${arch}模板展开决定，下载时只需按上表对号入座。

Windows 安装程序的两种方式

AIRI 的 Windows 安装程序提供两种安装方式：

• 为自己安装：不需要管理员权限，安装后仅当前用户可访问；
• 为所有人安装：需要管理员权限，此电脑上所有用户都可使用。

这与 apps/stage-tamagotchi/electron-builder.config.ts 中nsis段的oneClick: false、allowToChangeInstallationDirectory: true（允许自定义安装目录）、createDesktopShortcut: 'always'（总是创建桌面快捷方式）等配置相互印证——AIRI 使用非一键安装模式，安装路径与安装范围均可由用户选择。

iPhone、iPad 与鸿蒙注意事项

• iPhone / iPad：目前仅提供.ipa文件，需要手动签名后安装，暂不提供详细安装教程；项目组计划后续发布 TestFlight 测试链接。
• 华为鸿蒙：暂不提供原生鸿蒙软件。若你使用纯血鸿蒙系统，可通过卓易通（兼容层工具）安装安卓版软件。

第二章 · 初步配置：让 AIRI 先能「开口说话」

开始使用前，你至少要准备一个聊天服务商和可用模型。云端服务通常需要创建 API Key 或登录账号；本地服务则需要先启动模型服务（如 Ollama 等本地推理服务）。

初始化引导步骤

1. 打开 AIRI，进入初始化引导设置。
2. 选择你的语言。
3. 若想使用自己的 AI 模型，点击「配置您自己的 AI 服务来源」；若想使用官方提供的 AI 模型，点击「登录」。如果不确定选哪个提供商，建议从 AIRI 官方提供商、OpenRouter、OpenAI 兼容提供商 或本地的 Ollama 中选择一个进行配置。
4. 若使用自己的 AI 模型：
   1. 选中你准备的服务来源，点击「下一步」；
   2. 填入 API Key（必要时可更改 Base URL），点击「下一步」；
   3. 再点击一次「下一步」；
   4. 选择打算使用的模型，点击「保存并继续」。
5. 若使用官方 AI 模型，参考 AIRI 官方提供商 的说明。

不出意外的话，到这里你就完成了 AIRI 的初步配置。

只需先配置聊天即可开始

聊天服务商和模型配置成功后，AIRI 就能回复消息。之后可以逐步添加语音合成（TTS）、语音识别（ASR/STT）、视觉理解和艺术创作等能力，分别参考 语音输入与输出、视觉理解 与下文「绘图」一节。

API Key 安全红线

API Key、AccessKey Secret 和其他服务凭据只应保存在你的设备中。不要将它们提交到仓库、发到 Issue、截图或发送给他人。这一要求在说明书的多处（初步配置、服务来源、Discord、X/Twitter 等小节）被反复强调。

配置后的验证方法

参考 聊天模型配置指南，配置完成后可用以下方式自检：

• 在「设置 → 服务商 → 聊天」中点击Ping API，验证网络连通性与 Key 是否正确；
• 若验证通过但没有可选模型，说明该服务商不提供模型列表或该 Key 无相应权限，可在「意识」页面手动输入与服务商文档完全一致的模型 ID；
• 返回聊天界面发送一条简短消息（例如“你好”），收到回复即表示配置成功。AIRI 没有回复时，优先确认「意识」页面是否同时选中了服务商和模型——仅保存服务商凭据不会自动启用它。

第三章 · AIRI 界面介绍

本章以桌面端为主进行讲解；网页版/移动端可参考此部分，网页端独有功能在「网页版特性补充」一节介绍。

主窗口

主窗口是展示虚拟角色形象的窗口，共有五个选项：

• 「展开 ⌃」——点击可展开更多选项（见下文）。
• 「打开聊天」——点击可打开聊天窗口。
• 「听觉控制 🎤︎」——点击后可与 AIRI 说话。点击后打开“听力输入”面板：先启用麦克风输入并选择麦克风；若系统提示权限请求，请允许 AIRI 使用麦克风。配置语音识别服务后，所说内容会被转写并发送到当前聊天会话。AIRI 正在说话时会暂停收音，避免把自己的语音再次识别进去。
• 「扬声器」——暂略（具体功能暂未测试）。
• 「移动 ✥」——鼠标左键长按并拖动即可改变主窗口在桌面上的位置。

点击「展开 ⌃」后共有九个子选项，从上到下、从左到右依次为：

• 「登录」——登录你自己的 AIRI 账号。
• 「打开设置」——打开 AIRI 的设置界面。
• 「切换角色」——切换角色卡。
• 「刷新」——刷新主窗口。
• 「移至屏幕中央」——将窗口移到屏幕中央。
• 「切换到暗色模式」——切换 AIRI 的界面背景为「亮 / 暗」。
• 「取消置顶」——使 AIRI 人物模型不再保持置顶显示。
• 「总是显示」/「悬停时隐藏」——使 AIRI 主窗口不影响鼠标光标对窗口下内容的点击，从而不影响你的工作。
• 「关闭」——一键关闭 AIRI。

系统托盘其他选项

首先找到 AIRI 在任务栏（Windows）/菜单栏（macOS）的小图标。如果找不到：Windows 上可能需要在任务栏点击「显示隐藏的图标（⌃）」展开；macOS 上图标可能隐藏在刘海后面（尤其是 MacBook 内置显示屏），可打开系统设置 → 菜单栏，显示或隐藏菜单图标。

右键 AIRI 的小图标，可以看到以下选项：

• 「显示」——召唤主窗口，一般用不上。
• 「调整大小」——调整主窗口大小，同时使主窗口居中。包含四个子选项：
  • 「推荐（450x600）」——设置为推荐大小 450x600；
  • 「全高」——使主窗口的高占满桌面的高；
  • 「半高」——使主窗口的高为桌面的高的一半；
  • 「全屏」——使主窗口填满整个桌面。
• 「对齐到」——使主窗口对齐到桌面的特定位置。包含五个子选项：「居中」「左上」「右上」「左下」「右下」。
• 「设置」——打开设置界面。
• 「关于」——打开关于窗口，可查看版本号、访问项目主页、更新 AIRI 并选择更新通道。
• 「打开快速操作」——打开一个浮动输入框（Spotlight）。输入给 AIRI 的简短请求后按 Enter，窗口会隐藏并以通知显示处理结果；按 Esc 取消。
• 「打开小部件」——打开小部件窗口。地图、天气、艺术创作或扩展提供的小部件会在这里显示；未运行相关工具或扩展时窗口可能为空。
• 「打开字幕」——打开字幕。只有启用 TTS 服务才能在 AIRI 说话时显示文字，默认鼠标光标悬停时隐藏。
• 「字幕浮窗」——包含两个子选项：「跟随窗口」（默认选中，字幕位置跟随主窗口移动；取消选中则字幕位置独立）与「重置位置」。
• 「退出」——一键关闭 AIRI。

托盘菜单的源码实现

托盘菜单并非虚构功能，其完整实现位于 apps/stage-tamagotchi/src/main/tray/index.ts。源码中可以看到：

• 推荐尺寸常量RECOMMENDED_WIDTH = 450、RECOMMENDED_HEIGHT = 600（L30-L32），与「推荐（450x600）」完全一致；
• 「全高 / 半高 / 全屏」的宽高由当前显示器工作区（workArea）按 450:600 的宽高比动态计算；
• 「对齐到」的五个位置由 resolveAlignedWindowBounds 完成坐标计算，并通过 Animator 做窗口位移动画；
• 「打开快速操作」「打开小部件」「打开字幕」「字幕浮窗 → 跟随窗口/重置位置」分别对应setupInlayWindow、widgetsWindow、captionWindow.toggleVisibility、setFollowWindow与resetToSide调用；
• 菜单项文案全部经i18n.t()本地化，随语言切换动态重建（L255-L259）。

设置界面

设置界面可通过两种方式打开：

• 在主窗口点击「展开」，然后选择「打开设置」；
• 右键系统托盘中的 AIRI 小图标，选择「设置」。

设置界面包括九大内容：

• 「AIRI 角色卡」——选择和配置角色的人设。
• 「机体模块」——配置 AIRI 的各种功能，包括意识、发声、听觉、视觉、短期记忆、长期记忆、Discord、X / Twitter、网络搜索、我的世界、异星工厂、MCP 服务器、同步音律。
• 「场景」——配置 AIRI 的场景（背景）。
• 「角色模型」——选择和设置角色的模型。
• 「记忆体」——功能暂未发布。
• 「服务来源」——配置 LLM、TTS、STT、Artistry 服务的来源。
• 「Data」——译为「数据」，管理 AIRI 的各种数据。
• 「连接」——配置 WebSocket 服务器地址。
• 「系统」——包含四个子选项：通用、配色方案、窗口快捷方式、开发者。

聊天窗口

在主窗口点击「打开聊天」即可打开聊天窗口，在这里与 AIRI 对话。启用语音合成后，AIRI 正在朗读回复时，输入区会出现「停止朗读」按钮；点击它只会停止当前语音播放，不会取消已经生成的文字回复。

点击输入区左侧的「对话」按钮，或点击聊天窗口标题，可打开对话列表。列表按最近更新时间显示每段对话的预览与同步状态；你可以切换、删除对话，或为当前角色新建对话。删除后通常无法恢复，请先确认不再需要其中的内容。

第四章 · 设置详解

AIRI 角色卡

在这里可以上传、创建或直接修改默认角色卡。

关于导入与导出：角色卡可以导入或导出为 AIRI 角色卡包。卡包使用Character Card V3数据，并可选地附带 Live2D、Spine 或 VRM 显示模型。导入时 AIRI 会校验包内的清单和角色卡数据；格式不正确或缺少必需文件的包无法导入。

创建新角色卡，建议按下面的顺序配置：

1. 填写身份部分：名字、昵称、描述、创建者笔记；
2. 根据需要填写行为部分：角色性格、场景（周围环境/背景/情境）和问候语；
3. 根据需要调整模块部分，为角色配置特定的机体模块；
4. 根据需要配置Artistry部分，为角色配置生成图片的功能；
5. 最后检查设置部分：系统提示词、历史提示指令和版本；
6. 确认无误后点击「保存更改」或「保存并激活」完成创建（推荐直接点击后者，可省略第七步直接生效）；
7. 创建完成后，点击角色卡右下角的圈，或点击角色卡后再点击激活，正式启用这个角色卡。

身份部分最重要的是名字和描述：

• 名字即角色正式名称；如果设定了昵称，昵称会被优先使用。
• 描述即关于人设的具体细节，可自由发挥，也可参考默认角色卡。

补充说明：

• 若参考默认角色卡编写设定，其中后半部分关于 ACT 标签的内容可以不添加；
• 创建者笔记仅为卡片备注，不会影响 AIRI 回复结果；
• 行为部分补充性格、场景与问候语；模块部分可为该角色指定聊天、视觉、语音和显示模型；Artistry 部分设置该角色的图片生成偏好；设置部分包含系统提示词、历史提示指令和版本信息。

如需从零编写角色卡，可参考仓库内的 角色卡模板。

机体模块

在这里可以配置 AIRI 的各种功能。仓库中「机体模块」的页面源码位于 apps/stage-tamagotchi/src/renderer/pages/settings/modules 目录。

意识（Consciousness）

即 AIRI 的“大脑”——聊天模型。配置方法参考 聊天模型。完成服务商配置后，回到此处选择服务商和模型即可让 AIRI 回复消息。

发声（Speech / TTS）

语音合成。配置方法参考 语音输入与输出。若不想让 AIRI 发声，选择「无」。补充说明：

• 先选择服务商和模型，再选择该模型提供的音色；不同服务商显示的字段会不同；
• **Pitch（音调）**仅对支持该参数的服务商和模型生效。

听觉（Hearing / STT）

语音识别。配置方法参考 语音输入与输出。暂不使用语音输入时选择「无」。

名词解释：STT是「语音转文本」（Speech-to-Text）的缩写，也称自动语音识别（ASR）。它的目标是让计算机听懂人类的语音，并将其转换成对应的文字。

macOS 用户注意：第一次在 macOS 上使用语音输入功能时，需要进行一次性麦克风权限授权。看到系统提示时请选择「允许（Allow）」，否则该功能无法正常使用。

在听觉页面你还可以：

• 启用Auto-send transcribed text（自动发送转录文本）实现自动发送；
• 关闭该功能则可以先检查或修改转录结果再发送；
• 通过Auto-send delay（自动发送延迟）调整发送延迟。

测试麦克风：在界面中间部分点击「start monitoring」开启监听，必要时调整Sensitivity（灵敏度）。测试 STT：在界面最下方点击「start speech-to-text」，然后在Transcription Result下查看识别结果。

视觉（Vision）

配置方法参考 视觉理解。AIRI 不维护独立的视觉 API 凭据：视觉配置与聊天配置共用同一服务商凭据，但必须选择明确支持图像输入的模型。

⚠️使用屏幕视觉前，需要启动 Vision Capture仅配置视觉服务商和模型时，无需开启此工具。如需让 AIRI 分析屏幕或窗口，请前往「系统 → 开发者 → Vision Capture」：授予屏幕录制权限，选择要捕获的窗口或显示器，然后点击「Start ticker」；如需将识别结果提供给 AIRI 对话，再开启「Publish to character」。Vision Capture 是当前的桌面端调试/开发工作流，离开该页面会停止捕获循环。完整说明见 桌面端开发者工具。

网络搜索

阅读 网络搜索配置指南，配置Tavily API Key，并了解使用方式、隐私提示和常见问题。

绘图（Artistry）

为 AIRI 配置艺术创作（图片生成）的能力，可参考侧栏“配置 → 服务商 → 艺术创作服务商”了解如何配置不同的 AI 提供商。

⚠️请使用支持工具调用的聊天模型艺术创作不是由角色直接生成图片：AIRI 会向当前的聊天模型提供已配置图像服务的工具，再由模型调用该工具提交生成任务。因此，聊天模型和服务商必须支持Tool Calling / Function Calling（工具/函数调用）。 在「设置 → 意识」中选择服务商后，请选择该服务商明确标注支持工具调用的模型。仅支持普通文本对话，或服务商未透传工具调用的模型，可能只会文字回复、拒绝生成，或完全不会向所选图像服务提交任务。 配置后先让角色执行一次简单的图片请求，确认 AIRI 已发起工具调用；任务完成并返回图片后，AIRI 才会显示结果。各服务商的专属验证方式，参考侧栏「配置 → 服务商 → 艺术创作服务商」中的对应页面。

短期记忆

功能正在开发中，敬请期待。如你有实现该功能的想法，欢迎通过 issues 或 PR 提出建议。

长期记忆

功能正在开发中，敬请期待。同样欢迎通过 issues 或 PR 提出实现建议。

Discord

Discord 集成需要从源码运行机器人服务，才能让 AIRI 进入 Discord 服务器的消息和语音频道：

1. 在 Discord 机器人集成指南 中创建 Discord 应用、启用所需 Intent，并配置 Bot Token；
2. 在本地配置模型和语音服务凭据；
3. 从仓库根目录启动 Discord 机器人服务。

⚠️ Discord Bot Token、模型 API Key 和语音服务凭据只应保存在本地配置文件中，不要提交、截图或发送。

X / Twitter

阅读 X / Twitter 集成指南，创建并填写 X Developer Platform 应用凭据。不要公开 API Key、API Secret 或访问令牌。

我的世界 Minecraft

Minecraft 集成需要从源码运行本地智能体服务。按照 Minecraft 智能体集成指南 配置受信任的服务器、AIRI 和模型服务，然后启动智能体。该集成对应仓库中的 integrations/minecraft 目录。

⚠️ 不要将 Minecraft 智能体连接到不受信任的公共服务器。它会驱动本地 Minecraft 会话和网络连接，恶意服务器可能造成非预期行为。

异星工厂 Factorio

阅读 异星工厂集成指南，在 AIRI 中填写受信任服务器的地址、端口和游戏内用户名。注意：AIRI不随附可直接部署的 Factorio 服务端集成。

MCP 集成

MCP（Model Context Protocol）让 AIRI 通过本地进程使用外部工具。在桌面端，打开此页后可以添加服务器，填写其命令、参数和环境变量，先运行连接测试，再点击「应用并重启」启动或重启 MCP 服务。也可以打开配置文件或使用 JSON 编辑器批量维护配置。

⚠️ 仅运行你信任的 MCP 服务器：它们可在本机执行命令并访问你授予的环境变量。

同步音律（Beat Sync）

同步音律会从屏幕捕获的音频分析节拍，并将节拍信号发送给舞台效果。点击「开始屏幕捕获」后选择包含音频的屏幕或窗口；可用「停止」结束捕获。页面提供灵敏度、最小节拍间隔及高级滤波参数，并显示实时频谱和节拍可视化。首次使用可能需要授予系统屏幕录制权限。相关实现可参考 apps/stage-tamagotchi/src/renderer/beat-sync.main.ts；开发者工具中的「Beat Sync Visualizer」可绘制 V-motion 目标、轨迹及 Y/Z 标量变化，用于确认节拍驱动的角色运动是否连续稳定。

场景（Scenes）

在这里可以配置 AIRI 主界面的场景——简单理解为 AIRI 主界面的背景。包含两个预设，将鼠标光标移到预设中间，点击显现的对勾即可启用场景。也可以点击「上传到场景库」导入自己的图片场景；需要清除场景时点击「清除默认」。

角色模型

在这里可以选择和设置角色的模型。AIRI 支持Live2D、VRM 3D、Spine 2D、MMD 和 Tachie五种模型，对应仓库中的渲染包 packages/stage-ui-live2d、packages/stage-ui-three（VRM）、packages/stage-ui-spine、packages/stage-ui-mmd 与 packages/stage-ui-tachie。

如果只是想切换现有模型：

1. 点击「选择模型」打开模型选择界面；
2. 当前版本默认可以看到两个 Live2D 模型和两个 VRM 3D 模型；
3. 选中一个模型后点击「确认」完成切换。

如果想导入自己的模型，点击「导入」选择 Live2D、VRM、Spine、MMD 或 Tachie 格式。

⚠️ 导入模型前请注意：

• 旧版 Live2D 模型可能不被支持，请尽量选择包括*.moc3的文件；
• 导入 Live2D 模型前，需要先将「模型文件夹」压缩为*.zip文件；
• Spine 模型同样以*.zip导入；VRM 使用单个*.vrm文件。

Live2D 模型的调整

启用 Live2D 后可按顺序调整：

1. 展开「缩放与位置」：调整模型在主窗口中的大小和位置。x 为横轴（左右）位置，y 为纵轴（上下）位置。
2. 展开「动画」：可设置动作驱动器（通用和 MAGIC 两种）、鼠标跟踪、空闲眼部动作、眨眼及模式、空闲动画。若选择 MAGIC 驱动器，还可以选择配置（包括空闲/平静和说话/兴奋两种内置配置）、是否忽略生成的嘴部开合、强制视线朝前。注意：MAGIC 驱动在展示模型全身时表现会比较差，会出现整个模型上下晃动的情况——这是开发者参考 neuro 以及 vts 的工作逻辑后经过考虑设定的正常情况，推荐启用 MAGIC 驱动时仅展示模型的半身。对应实现可参考 packages/model-driver-magic-live2d。
3. 展开「模型参数」：可设置渲染缩放、帧率（FPS）、投影、重置为默认参数、清除模型缓存以及模型涉及的各种参数。
4. 若要设置待机动画，请确保模型压缩包中包含动画文件。
5. 如需表情功能，可再展开「表情」启用「表情系统」。

启用语音合成时，AIRI 会在朗读结束后自动恢复 Live2D 的嘴部状态（对应 packages/model-driver-lipsync 实现的嘴型同步能力）。

模型的可用参数、待机动画和表情由模型文件本身决定。启用表情系统后只显示该模型实际提供的表情；若没有表情或动画文件，对应选项不会产生效果。

Spine 2D 模型的调整

Spine 模型提供独立的设置面板：可以调整缩放、X/Y 位置、皮肤、变体、待机动画、动画混合时间和播放速度，也可以限制帧率与调整渲染比例。若模型包含可用的皮肤、变体或动画，它们会出现在对应下拉选项中；缺少的资源不会显示。

VRM 3D 模型的调整

先展开「场景」，然后设置Model Position（模型位置）、视角调整（度）、相机距离（画面缩放）、模型朝向（Y 轴旋转）、模型注视方向等内容。内置舞台中的位置、旋转、相机距离与注视方向会保存到当前设置。

Godot Stage（实验性）

「Switch to Godot Stage (Experimental)」会启动独立的 Godot 舞台渲染器；再次点击「Back to Built-in Stage」可切回内置舞台。Godot Stage 目前只支持 VRM 模型。启动并选定 VRM 后，可以在 Godot View 中调整相机X/Y/Z、偏航、俯仰和视野角；状态或模型加载错误会显示在该区域。

从工程角度看，Godot 舞台是独立的渲染引擎，其代码位于 engines/stage-tamagotchi-godot，并在打包时通过 electron-builder.config.ts 的extraResources将 Godot 输出目录作为godot-stage资源随应用分发。

记忆体

功能暂未发布。如你有实现该功能的想法，欢迎通过 issues 或 PR 提出建议。

服务来源

“服务来源”是 AIRI 连接模型和语音能力的入口。先在这里保存服务商凭据，再到对应功能页面选择服务商及模型。可按用途选择分类：

• 聊天：配置让 AIRI 回复消息的 LLM；这是开始使用 AIRI 的必要配置。
• 视觉：让 AIRI 能看见图片。
• 语音合成（TTS）：让 AIRI 朗读回复；随后在「机体模块 → 发声」中选择模型和音色。
• 语音识别（ASR/STT）：把麦克风语音转换为文字；随后在「机体模块 → 听觉」中选择模型。
• 艺术创作：配置图片生成服务；随后在「机体模块 → Artistry」中使用。

如果跳过了初始化配置引导，建议先完成聊天服务商的配置：选择服务商，填写 API Key 或登录账号；如服务商要求，再填写 Base URL、区域等高级字段；然后使用Ping API验证连通性。验证后进入「机体模块 → 意识」选择服务商和模型，发送一条消息确认 AIRI 能回复。

注意：切换聊天服务商后，原先选择的聊天模型会被清空，请回到「机体模块 → 意识」为新服务商重新选择模型。

常用配置指南：

• 不确定服务商的字段、验证方式或报错含义时，阅读 通用配置说明；
• 配置聊天模型，阅读 聊天模型；
• 配置语音输入输出，阅读 语音输入与输出；
• 视觉理解使用与聊天服务商相同的凭据，并须选择支持图像输入的聊天模型，详情见 视觉理解。

技术性建议：服务商列表以 AIRI 当前版本为准。若你的服务商不在列表里但支持 OpenAI 兼容接口，可使用OpenAI 兼容 API配置；Base URL 和模型 ID 必须按照该服务商官方文档填写。

数据（Data）

在这里可以管理 AIRI 的各种数据。

⚠️ 该部分可以删除或清理相关数据，而且无法恢复，请谨慎操作。在执行删除和重置操作前，建议先再确认一遍内容。

注意：「打开应用数据文件夹」和「重置桌面设置和状态」仅在桌面版可用，网页/移动版 App 不可用。

连接

“连接”用于配置 AIRI 的服务通道：

• 可以设置WebSocket 地址，并在需要加密传输时启用TLS；
• 桌面端还可选择仅本机访问、允许局域网访问或填写高级主机名（暂不可用），并设置访问令牌；
• 页面会提供二维码，方便其他设备连接。

仅在受信任的网络中开放局域网访问，并妥善保管访问令牌。macOS 用户注意：启用安全 WebSocket 时，AIRI 会将本地证书加入 macOS 登录钥匙串，系统可能要求使用 Touch ID 或输入 Mac 登录密码授权。

系统

通用

在这里设置程序主题、语言等内容：

• 主题：默认亮色，点击后面的按钮可切换到暗色模式；
• 语言：可设置界面语言，选择会在重启 AIRI 后保留；
• 控制岛图标大小：更改主窗口右下角三个按键的大小；
• 还可以设置是否允许收集使用数据及崩溃分析，或阅读隐私政策。

配色方案

• 启动RGB选项，主题颜色会像 RGB 灯带那样自动变化；
• 拖动下方的黑线或在彩色条中点击，可更改主题颜色；
• 下方为颜色效果预览；
• 也可直接选择下方的预设改变主题颜色。

提示：选择预设时应点击任意一个圆，而不是方框。

窗口快捷方式

在这里可以修改Spotlight全局快捷键。Spotlight 是「打开快速操作」所使用的浮动输入框：

1. 点击当前快捷键；
2. 按下想使用的新组合键；必须包含 Cmd、Ctrl、Alt 或 Super 中至少一个修饰键；
3. 若快捷键已被其他应用占用，AIRI 会提示冲突；按 Esc 取消录制；
4. 点击「重置」可恢复默认快捷键。

使用方式：按下已设置的快捷键打开快速操作输入框，输入请求后按 Enter 发送给 AIRI，按 Esc 关闭。

开发者

此页面用于开发、排障和验证实验功能，普通用户不需要操作。完整工具说明见 桌面端开发者工具。该页面按问题类型提供了工具选择矩阵，例如：页面报错用开发者工具，聊天上下文/WebSocket 用 Context Flow 与 WebSocket Inspector，屏幕共享/视觉输入用 Screen Capture 与 Vision Capture，更新问题用 Updater。

网页版特性补充

网页版主界面

网页版主界面分为三个部分：角色模型空间、聊天框和其他。

聊天框

聊天框分上下两部分：上半部分是显示和记录聊天记录的区域；下半部分是输入框，可打字与角色对话。输入框下方有两个按钮（文本内容仅供参考）：

• 发送方式——选择通过什么方式确认发送消息；
• 开启语音输入。

其他部分 · 上方区域

包括三个选项：关于、角色卡、账号及设置。第三个选项中包含三大块内容：账号信息、档案 / Flux / 设置、登出。

• 档案：登录 AIRI 后可管理账号信息。可以查看并修改显示名称，管理密码和已关联的登录方式（例如 GitHub、Google），也可以在危险操作区注销或删除账号。头像当前由账号资料显示，暂不支持在此上传新头像。
• Flux：AIRI 官方服务使用的余额单位。登录后可查看当前余额、使用统计和流水记录；在开放购买的地区或版本中，还可选择套餐并进入结算。使用官方聊天、视觉或语音服务时，相关请求可能消耗 Flux；第三方服务商的费用仍由该服务商单独结算。
• 设置：同桌面端设置。

其他部分 · 下方区域

包括六个选项（文本内容仅供参考）：

• 对话：管理对话。注意不同对话之间相互独立；
• 静音语音：暂略；
• 位置及大小：点击后出现 x、y、scale 三个参数（x 为模型 x 轴位置，y 为模型 y 轴位置，scale 为模型缩放/大小），可通过点击并拖动网页界面左边竖着的条调整；
• 删除聊天记录：一键清除全部聊天记录。点击删除无法恢复，请谨慎操作；
• 切换亮暗：切换界面亮色或暗色；
• 背景：更改主界面的背景。

历史特性与常见问题

常见问题

• 从早期版本升级后模型“消失”：如果你曾改动过模型的大小和位置，升级后模型可能“消失”。遇到该问题时，请在模型设置界面重置模型的缩放和位置。

历史特性

• 在过去的其中几个版本中，主窗口右上角还有一个「websocket 状态」选项，点击可打开连接设置，配置 WebSocket 服务器地址。
• 在更早的版本中，创建完角色卡后必须手动激活；当前版本已支持「保存并激活」一步到位。

附 · 关于本文档与项目源码的关系

本指南所依据的说明书由社区团队编写并提交至官方文档，属于“官方仓库内、由非官方人员主导维护”的文档。文中所有界面菜单、尺寸常量、产物命名等内容，均已与仓库源码交叉核对：

• 托盘菜单与 450x600 推荐尺寸：apps/stage-tamagotchi/src/main/tray/index.ts
• 安装包产物命名与平台配置：apps/stage-tamagotchi/electron-builder.config.ts
• 版本号与工程脚本：apps/stage-tamagotchi/package.json
• 配置类文档：聊天模型 llm.md、语音 audio.md、视觉 vision.md、网络搜索 web-search.md、通用配置 common.md

由于说明书由社区维护且可能滞后于版本更新，遇到与本文描述不一致的地方，请以你实际运行的版本为准；若使用过程中有疑问，也可以在 Project AIRI 的官方 Discord、微信群（仓库内 docs/wechat.md 提供入群方式）或 QQ 群中与社区交流。

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