构建个人语音AI助手：从LLM到本地执行的完整架构解析

1. 项目概述：一个真正能用的个人语音AI助手

如果你和我一样，对手机内置的语音助手（比如Siri）的“人工智障”表现感到失望，总在幻想一个能真正理解复杂指令、帮你处理日常事务的智能伙伴，那么Vox-Voice这个项目绝对值得你花时间研究。它不是一个简单的语音转文本玩具，而是一个运行在你个人设备上的、功能强大的语音优先AI助手。它的核心思路非常清晰：将你手机上的语音指令，通过一个运行在你个人Mac电脑上的“网关”（OpenClaw），转化为实际的操作——发送邮件、创建日历事件、播放音乐、控制智能家居，甚至执行Mac上的脚本命令。简单说，它把大语言模型（LLM）的理解能力和你设备的本地执行能力结合了起来，创造了一个属于你个人的、可深度定制的“贾维斯”。

与那些将你的语音数据上传到未知云端的商业服务不同，Vox-Voice的设计哲学强调个人化和隐私。AI的“思考”（由Claude模型完成）和语音的转录（由Whisper完成）虽然依赖云API，但具体的操作执行完全发生在你的本地网络环境中，通过你控制的OpenClaw网关进行。这意味着，像“打开这个文档”、“锁屏”这类涉及本地资源的敏感操作，其指令流转完全在你的掌控之内。项目采用React Native + Expo构建，这意味着你可以同时拥有iOS和Android版本，用一套代码管理你的跨平台智能助手。

2. 核心架构与工作流深度解析

要玩转Vox，必须理解它的数据流，这能帮你定位未来可能出现的任何问题。整个系统可以看作一个精心设计的管道，每个环节都有其特定的技术选型和考量。

2.1 三层架构：移动端、网关与云服务

Vox的架构清晰地分为三层，这种分离带来了灵活性和可控性。

第一层：移动端应用（React Native）。这是你直接交互的界面。它的职责非常专注：捕获音频、管理用户界面（如那个会变色的交互球体Orb和各类信息卡片）、处理文本到语音（TTS）的播放，并通过WebSocket与网关通信。选择React Native和Expo，对于这样一个需要调用大量原生模块（音频、存储、网络）的项目来说是明智的，它平衡了开发效率和原生性能。Expo SDK 55提供了对expo-av（音频录制）、expo-speech（TTS）等模块的良好支持，简化了开发流程。

第二层：OpenClaw网关（运行在Mac上的本地服务）。这是整个系统的“中枢神经”和“执行臂”。它不是一个简单的转发服务器，而是一个具备执行能力的AI Agent框架。当它收到从手机发来的、经过LLM扩展的文本指令时，会解析其中的“动作标记”（例如[ACTION: CALENDAR_CREATE]），然后调用对应的本地执行器。这些执行器可以是：

• AppleScript：用于操作macOS上的原生应用，如日历、邮件、音乐。
• Shell命令：执行任何你可以在终端里运行的命令。
• 快捷指令（Shortcuts）：调用macOS/iOS的快捷指令，实现复杂自动化。
• HTTP请求：与外部API（如智能家居的本地API）交互。 网关的存在，将危险的或需要高权限的系统级调用隔离在了你的电脑上，手机应用只负责“请求”，不负责“执行”，提升了安全性。

第三层：云端AI服务（API调用）。这是系统的“大脑”。包括：

• Anthropic Claude API：负责理解用户意图、进行逻辑推理和生成结构化的响应与动作指令。选择Claude通常是出于其出色的指令遵循和结构化输出能力。
• OpenAI Whisper API：将语音转换为文本。虽然也有本地Whisper模型，但使用API在准确性和速度上通常是更好的选择，尤其是对于非英语语音。
• （可选）OpenAI TTS API：提供高质量的语音合成。你也可以选择本地或其它TTS服务。

注意：项目的隐私边界就在这里。你的语音转录文本和对话内容会发送给Anthropic和OpenAI。因此，请务必阅读这些服务商的隐私政策。对于高度敏感的信息，你可以考虑在指令中要求AI不要记录或用于训练，但这取决于服务商是否遵守。

2.2 端到端语音交互流水线

让我们跟随一次“播放周杰伦的《晴天》”的指令，走完整个流程：

1. 语音捕获与端点检测：你点击屏幕上的Orb或说出唤醒词，应用启动expo-av录制音频。这里有个关键细节：静音检测。录音不会无限进行，当检测到音频电平持续低于-40dB约1.5秒时，会自动停止并发送数据。这个阈值和时长在嘈杂环境中可能需要调整，我们会在后续“避坑”部分详谈。

2. 语音转文本（STT）：录制的音频文件（通常是高质量的CAF或WAV格式）被发送到OpenAI的Whisper API进行转录。项目默认配置language=en，如果你主要使用中文，务必在代码或设置中将其改为language=zh，这能显著提升识别准确率。verbose_json参数确保了返回结果包含时间戳等丰富信息，为未来的功能扩展（如高亮正在朗读的文本）留有余地。

3. 智能提示词扩展：这是Vox的“魔法”所在。原始的“播放周杰伦的《晴天》”可能直接丢给AI，效果并不稳定。Vox内建了一个提示词扩展器。它会匹配一系列预定义的正则表达式模式，将简短指令扩展为富含上下文和明确要求的详细提示。例如，音乐播放指令可能被扩展为：“用户想听音乐。请调用Apple Music应用，播放歌手周杰伦的歌曲《晴天》。如果找不到确切匹配，请播放周杰伦最热门的歌曲。请以[MUSIC_PLAY: ...]的格式回复确认。” 这个步骤极大地提升了AI执行动作的准确率和可靠性。

4. 网关处理与动作执行：扩展后的提示词通过WebSocket发送到OpenClaw网关。网关中的Claude模型“看到”这个详细的提示，理解其意图是“执行音乐播放动作”，并生成一个结构化的响应，其中包含类似[ACTION: MUSIC_PLAY]的标记和必要的参数（如歌曲名、艺术家）。网关的“动作执行器”模块捕获到这个标记，便会调用macOS的AppleScript，命令Apple Music执行播放操作。

5. 响应解析与卡片渲染：网关执行完毕后，会将结果（例如“正在Apple Music中播放周杰伦的《晴天》”）流式传回手机应用。手机的card-parser（卡片解析器）会扫描响应文本，寻找25种预定义的卡片类型标记（如[NOW_PLAYING_CARD]）。一旦匹配，对应的React组件（如NowPlayingCard）就会被渲染，展示专辑封面、播放控件等信息。这种设计将AI的自由格式文本与UI的强结构化完美结合。

6. 文本转语音（TTS）反馈：最后，响应文本会被送入TTS引擎。这里提供了多个选项：高质量的OpenAI TTS、可自托管的Kokoro TTS、Google Cloud TTS或设备内置的离线TTS。一个重要的处理细节是，在发送给TTS前，响应文本会经过stripMarkdown()函数的处理，移除AI可能返回的Markdown格式符号（如粗体），确保朗读的自然性。

3. 从零开始的详细搭建与配置指南

理论讲完，我们进入实战。以下是我从零搭建Vox并使其稳定运行的全过程记录，包含了每一步的意图和可能遇到的坑。

3.1 基础环境准备：避坑第一步

在克隆代码之前，请确保你的环境达标，这能避免80%的后续问题。

对于macOS（网关宿主及开发机）：

• Node.js 18+: 建议使用nvm管理Node版本。nvm install 18 && nvm use 18。直接安装的Node可能会遇到权限问题。
• Xcode Command Line Tools: 在终端运行xcode-select --install。这是编译原生依赖所必需的。
• Python 3.8+: macOS通常自带，但建议用brew install python安装新版。确保python3 --version可用。
• Watchman (推荐):brew install watchman。Expo开发服务器用它来监听文件变化，没有它热重载可能不灵敏。

对于目标手机：

• iOS: 需要Apple Developer账号（每年99美元）用于真机调试和构建。免费的Apple ID仅支持模拟器。
• Android: 需要开启“开发者选项”和“USB调试”。不同品牌手机开启方式不同，通常是在“关于手机”里连点7次“版本号”。

实操心得：在开始前，先用npm run doctor（项目提供的）或自行检查：node --version,npm --version,expo --version。我曾经在Node版本不匹配的问题上浪费了半天时间，系统自带的Node是v16，而项目需要v18。

3.2 OpenClaw网关部署：系统的基石

Vox本身只是个“指挥官”，OpenClaw才是“执行官”。必须先在Mac上把它跑起来。

1. 克隆与安装：

   git clone https://github.com/openclaw/openclaw.git cd openclaw npm install

   这个过程会安装网关所需的所有Node依赖。

2. 配置与运行： 通常OpenClaw会有一个配置文件（如config.json或openclaw.json）。你需要关注两个关键信息：

   • WebSocket服务器地址：默认可能是ws://localhost:18789或ws://0.0.0.0:18789。为了让同一网络下的手机能访问，你需要将其改为你Mac的局域网IP，例如ws://192.168.1.100:18789。在终端输入ifconfig | grep "inet " | grep -v 127.0.0.1可以找到你的IP。
   • 认证令牌：网关可能会生成一个初始令牌（token）用于客户端连接。记下它。

3. 启动网关：

   npm start # 或 node index.js

   看到类似“WebSocket server listening on port 18789”的日志，说明网关已就绪。保持这个终端窗口打开。

3.3 Vox-Voice应用安装与配置

现在来设置手机上的“指挥官”。

1. 获取项目代码并安装依赖：

   git clone https://github.com/PrisacariuRobert/Vox-Voice.git cd Vox-Voice npm install

   这一步如果遇到网络问题，可以尝试设置npm镜像：npm config set registry https://registry.npmmirror.com。

2. 运行交互式设置向导（强烈推荐）：

   npm run setup

   这个向导是项目的一大亮点，它自动化了最繁琐的配置部分。它会依次引导你：

   • 检查系统环境（Node, Xcode等）。
   • 输入Anthropic API Key：去 Anthropic控制台 创建。这是驱动Claude模型的燃料。
   • 输入OpenAI API Key：去 OpenAI平台 创建。用于Whisper语音识别和可选的TTS。
   • 配置OpenClaw网关连接：输入上一步获取的WebSocket URL和Auth Token。
   • 设置用户档案：你的名字、邮箱、时区。这很重要，AI在创建日历事件或发送邮件时会用到。
   • 选择TTS语音：提供多个选项。我个人的选择逻辑是：追求质量选OpenAI的Nova或Shimmer；追求零延迟和免费选Device（设备内置）；想自托管选Kokoro。
   • 配置可选集成：如Zoom、Microsoft 365。初次搭建可以跳过，后续再补。

3. 部署到手机： 向导结束后，运行：

   npm run deploy

   脚本会交互式地询问你要构建iOS还是Android，并引导你完成后续步骤。对于iOS，你需要用Xcode打开生成的.xcworkspace文件，在“Signing & Capabilities”中选择你的开发者团队，然后用数据线连接iPhone进行构建。对于Android，连接手机后通常一条adb命令即可。

3.4 关键配置项详解

安装完成后，进入手机上的Vox应用，点击右上角的齿轮进入设置界面。以下几个配置关乎核心体验：

• OpenClaw Gateway：确认连接状态显示为绿色圆点。如果显示红色，检查：1) Mac和手机是否在同一Wi-Fi；2) Mac的防火墙是否阻止了18789端口；3) 网关地址是否填写了正确的局域网IP而非localhost。
• Speech-to-Text：确认已填入OpenAI API Key。你可以在这里测试语音识别，说句话看能否正确转成文字。
• Voice (TTS)：在这里切换不同的语音提供者和声音试听。一个常见问题是：如果选择OpenAI TTS但没有声音，请检查你的OpenAI账户余额是否充足，以及该API Key是否有tts-1模型的权限。
• Wake Word：可以设置自定义的唤醒词，如“你好小V”。注意，目前的唤醒词检测是基于周期性的Whisper识别，并非专业的离线唤醒引擎（如Porcupine），因此在省电和响应速度上需要权衡。在安静环境下效果尚可。

4. 核心功能实战与个性化定制

Vox开箱即用，但理解其功能边界和扩展方法，才能让它真正成为你的得力助手。

4.1 内置语音命令库的使用技巧

项目文档列出了庞大的命令列表，但在实际使用中，掌握“如何说”比“能说什么”更重要。基于Claude模型的特性，我总结出几个高效交互的原则：

• 具体化：不要说“发邮件”，而要说“发一封邮件给张三，主题是项目更新，内容是会议推迟到明天下午三点”。
• 包含上下文：AI会利用对话历史。你可以先说“查一下特斯拉的股价”，然后接着说“把它加到我的观察列表里”，AI能理解“它”指的是特斯拉。
• 使用自然动作短语：像“把这条记下来”、“提醒我到家后拿快递”、“把屏幕调亮一点”这样的口语化指令，效果很好。

一些高级用法示例：

• 复合指令：“帮我查查明天北京的天气，如果下雨就提醒我带伞，并把明天上午十点的会议发邮件通知所有参会者。” AI有能力分解并顺序执行多个子任务。
• 基于位置的服务：确保你已授予App位置权限。可以说“导航到最近的加油站”或“我家附近的咖啡厅”，AI会结合你的GPS数据返回结果。
• 系统控制：通过OpenClaw网关执行AppleScript，你可以实现“锁屏”、“静音”、“打开某个应用”等操作。这需要你在OpenClaw侧配置好对应的脚本。

4.2 动作卡片系统解析

Vox的UI反馈精髓在于这25+种动作卡片。它们不仅仅是美观，更是交互的入口。

• CalendarCard：展示日程事件。点击事件可以快速编辑或删除（如果网关配置了相应权限）。
• NowPlayingCard：显示正在播放的媒体。可以直接在卡片上暂停、切歌、调整音量，甚至切换AirPlay设备。
• PlacesCard / NavigationCard：展示地点列表或导航路线。点击即可跳转到Apple Maps或Google Maps开始导航。
• PhotosCard：这是结合了本地AI视觉搜索的强力功能。当你搜索“有狗的照片”时，它会展示一个照片网格。长按某张照片，有时会触发更详细的AI描述。

卡片系统的扩展潜力：这套卡片机制本质上是一个渲染管道。AI的响应文本中的特定标记（如[WEATHER]）触发对应的卡片组件。这意味着你可以为自己常用的服务（如智能家居的特定设备状态、加密货币价格、待办事项列表）创建自定义卡片类型，只需修改card-parser.ts和增加对应的React组件即可。

4.3 可选功能：AI照片搜索服务器搭建

这是Vox项目中最酷也最复杂的可选功能之一。它允许你用自然语言搜索手机相册。搭建它需要一些额外的步骤，但绝对物超所值。

为什么需要独立的服务器？因为直接在手机上进行实时的物体检测（YOLO）和语义理解（CLIP）计算量太大，耗电且发热。将这部分工作卸载到性能更强的Mac上是合理的设计。

分步搭建指南：

1. 进入服务器目录并创建Python虚拟环境：

   cd Vox-Voice/yolo-server python3 -m venv venv source venv/bin/activate # Windows系统使用 `venv\Scripts\activate`

   使用虚拟环境可以避免污染系统级的Python包。

2. 安装依赖：确保在虚拟环境激活状态下。

   pip install -r requirements.txt

   这个过程会下载torch、ultralytics（YOLO）、clip等大型库。如果下载慢，可以考虑使用国内镜像源，如pip install -r requirements.txt -i https://pypi.tuna.tsinghua.edu.cn/simple。

3. 配置环境变量：在yolo-server目录下创建.env文件。

   OPENAI_API_KEY=sk-your-key-here

   OpenAI API Key在这里是可选的。如果提供，服务器会使用GPT-4.1-mini对YOLO+CLIP筛选出的候选照片进行二次验证，精度极高。如果不提供，则只运行YOLO+CLIP，速度更快且完全免费，但可能会有一些误报（例如把玩具车识别成真车）。

4. 启动服务器：

   python server.py

   首次运行会自动下载YOLO11n模型文件（约6MB）。CLIP模型（ViT-B/32，约350MB）也会被下载。如果使用的是Apple Silicon Mac（M1/M2/M3），PyTorch应该会自动使用MPS后端加速，你会看到日志显示Using MPS backend。

5. 测试连接：服务器默认运行在http://你的MacIP:18790。在浏览器或终端中访问http://localhost:18790/health，应返回{"status":"ok", ...}。

工作原理与性能调优： 当你在Vox中说“找一下有猫的照片”：

1. App会分页读取手机相册（例如每次100张），生成256px的小图（Base64格式），批量发送到你的yolo-server。
2. 服务器对每张图运行YOLO，识别出图中的物体（如“cat: 0.95”）。
3. 同时，用CLIP模型计算图片特征与搜索词“cat”的语义相似度。
4. 结合物体检测置信度和语义相似度打分，超过阈值（默认0.2）的图片成为候选。
5. （如果配置了OpenAI Key）将候选图片发送给GPT-4.1-mini进行最终验证，GPT会严格判断图片内容是否匹配描述，过滤掉误报。
6. 将确认的图片索引传回App，App加载并显示原图。

注意事项：首次搜索可能会比较慢，因为需要加载模型和扫描大量图片。后续搜索会快很多。你可以根据你的照片数量和服务器性能，在lib/vision-photo-search.ts中调整batchSize（每批发送的图片数）和threshold（相似度阈值）。阈值调高（如0.3）会更精确但可能漏掉一些相关照片；调低（如0.15）则更宽松。

5. 高级调试、问题排查与经验分享

即使按照指南操作，也难免会遇到问题。以下是我在长期使用和搭建过程中遇到的典型问题及解决方案。

5.1 连接类问题

问题：App顶部的状态点一直是红色（未连接）。

• 排查步骤：
  1. 检查网关运行状态：回到Mac的终端，确认运行OpenClaw的窗口没有报错，且显示正在监听端口。
  2. 验证IP地址：在Mac上打开“系统设置”->“网络”，查看Wi-Fi的IP地址。确保App中填写的网关URL是这个IP，且端口正确（默认18789）。常见陷阱：Mac有时会有多个IP（如虚拟机网卡的），务必使用en0或en1这类主要无线网卡的IP。
  3. 网络互通性：在手机的浏览器中，尝试访问http://<你的MacIP>:18789（如果网关提供HTTP状态页）。如果打不开，说明手机和Mac不在同一子网，或者Mac的防火墙（系统设置->网络->防火墙选项）阻止了该端口。可以临时关闭防火墙测试。
  4. 检查认证令牌：确认App中填写的Auth Token与OpenClaw网关配置文件（如openclaw.json）中的一致。

问题：连接时断时续，状态点频繁在绿/红之间切换。

• 这通常是网络不稳定或手机进入休眠模式导致Wi-Fi节能策略生效。尝试在手机的Wi-Fi设置中，为该网络关闭“自动切换移动数据”或“低数据模式”。在iOS的“设置”->“开发者”中（需要先启用开发者模式），可以尝试关闭“Wi-Fi性能优化”。

5.2 语音识别与合成问题

问题：说话后没反应，或者转写的文字完全错误。

• 检查麦克风权限：进入手机系统设置，找到Vox应用，确保麦克风权限已开启。
• 测试Whisper API：在App的设置->Speech-to-Text页面，通常有测试按钮。录一段简单的英文（如“Hello world”）看能否正确识别。如果不能，问题可能在：
  • API Key无效或欠费：登录OpenAI平台检查。
  • 网络问题：手机可能无法直接访问OpenAI API。考虑网络环境。
  • 音频格式：检查lib/whisper-stt.ts中发送给API的音频格式参数。Whisper对采样率（16kHz或以上）、格式（如webm、wav）有要求。Expo的expo-av录制格式通常是兼容的。
• 环境噪音：在嘈杂环境中，静音检测（-40dB, 1.5s）可能过早结束录音。可以尝试在useVoiceInput钩子中调整silenceThreshold和silenceDurationMs参数。

问题：TTS没有声音，或者声音卡顿。

• 检查音量与播放设备：首先确认手机不是静音状态，媒体音量已调高。
• 切换TTS提供商测试：在设置中切换到“Device”语音。如果设备语音正常，而OpenAI/Kokoro/Google语音无声，问题出在云端TTS服务。
  • OpenAI TTS：检查API Key的余额和权限（需要tts-1访问权限）。
  • 网络延迟：云端TTS需要先下载音频数据再播放。网络慢会导致播放延迟或中断。查看lib/openai-tts.ts中是否有超时设置，可以适当增加。
• 音频会话冲突：在React Native中，多个音频模块（如录音和播放）可能冲突。确保在开始TTS前，录音模块已完全释放。检查useVoiceInput和useTTS钩子中关于Audio.Sound对象生命周期的管理。

5.3 动作执行失败问题

问题：命令被识别，也显示了“思考中”，但最终没有执行任何操作，或返回通用错误卡片。

• 这是最需要查看日志的地方。问题通常不在Vox App本身，而在OpenClaw网关或AI模型。
  1. 查看OpenClaw网关日志：这是最重要的调试信息源。日志会显示收到的指令、Claude的回复、以及执行动作时的具体错误。例如，可能显示“AppleScript error: Mail.app is not running”，那么你就需要确保邮件应用在Mac上是打开的。
  2. 检查AI响应格式：Vox依赖AI返回特定的动作标记（如[ACTION: CALENDAR_CREATE]）。如果Claude的回复是纯文本而没有这些标记，卡片解析器就无法触发动作。这通常意味着提示词扩展不够精确，或者Claude的回复格式不稳定。你需要去app/(tabs)/index.tsx中的expandSpecialPhrase函数，强化对应指令的提示词，明确要求AI以特定格式回复。
  3. 权限问题：许多操作（如发送邮件、创建日历事件、执行AppleScript）需要Mac上的应用授权。首次执行时，系统可能会弹出“xxx想要控制yyy应用”的权限请求，你必须点击“允许”。可以在“系统设置”->“隐私与安全性”->“自动化”中管理这些权限。

5.4 性能优化与个性化建议

• 唤醒词响应延迟：目前的唤醒词检测是基于间隔录音+Whisper识别，功耗和延迟较高。对于追求极致体验的用户，可以考虑集成Picovoice Porcupine这样的专业离线唤醒引擎。项目架构是支持的，你需要在useWakeWord钩子中替换检测逻辑，并引入Porcupine的React Native绑定库。
• 省电模式：长时间在后台保持WebSocket连接和音频监听可能耗电。可以考虑实现一个“按需连接”策略：当App从后台唤醒或用户主动打开时再建立WebSocket连接，一段时间无操作后自动断开。
• 自定义命令扩展：这是Vox最大的乐趣所在。假设你想增加一个“记录喝水”的命令，并同步到健康App：
  1. 在app/(tabs)/index.tsx的expandSpecialPhrase函数里，添加一个正则表达式匹配“记录喝水”、“喝了一杯水”等短语。
  2. 编写扩展提示词，明确告诉AI：“用户想记录一次饮水。请生成一个动作，调用HealthKit API（如果网关支持）或执行一个记录到本地文件的AppleScript。回复格式为[ACTION: LOG_WATER]。”
  3. 在OpenClaw网关侧，你需要编写一个对应的“动作处理器”，当收到LOG_WATER动作时，执行记录饮水的逻辑（可以是调用AppleScript操作健康数据，或写入一个CSV文件）。
  4. （可选）在Vox中创建一个WaterLogCard组件来美观地显示这次记录。
• 数据持久化与同步：Vox使用AsyncStorage存储对话历史。如果你在多台设备上使用，可以考虑将对话历史同步到iCloud或你自己的服务器，只需修改lib/conversation-store.ts中的存储逻辑即可。

搭建和定制Vox-Voice的过程，就像在精心调试一个属于你自己的数字生命体。从最初的连接调试，到后来的功能扩展，每一步的解决都带来巨大的成就感。它可能不会像商业产品那样开箱即用、完美无瑕，但正是这种可窥探、可修改、可掌控的特性，让它从一个工具变成了一个充满可能性的项目。当你第一次用语音成功创建了一个复杂的日历事件，或者快速从几千张照片中找出想要的那一张时，你会觉得所有的折腾都是值得的。这个项目最大的价值在于它提供了一个完整的、生产级的语音AI助手实现蓝图，你可以以此为起点，打造出独一无二的、真正懂你的个人AI伴侣。