本指南适用于 macOS 系统，小白友好，跟着步骤操作即可成功启动！
📋 前置检查
在开始之前，请确认您的系统：
- ✅ macOS 10.15 或更高版本
- ✅ 有网络连接（需要下载依赖）
- ✅ 至少 4GB 可用硬盘空间
第一步：安装 Homebrew（如已安装可跳过）
1.1 检查是否已安装 Homebrew
打开「终端」应用（在「启动台」或「应用程序」→「实用工具」中找到），输入：
brew --version
- 如果显示版本号（如
Homebrew 4.x.x），说明已安装，跳到第二步 - 如果提示「未找到命令」，继续以下步骤安装
1.2 安装 Homebrew
在终端中复制粘贴以下命令，按回车键：
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"
⏱️ 安装过程需要 10-20 分钟，请耐心等待。安装完成后关闭终端重新打开。
第二步：安装系统依赖
在终端中复制粘贴以下命令，一次性安装所有需要的系统依赖：
brew install portaudio opus ffmpeg gfortran
⏱️ 首次安装需要 5-10 分钟（会自动下载很多依赖包）。
验证安装
安装完成后，输入以下命令验证：
brew list portaudio opus ffmpeg
如果显示文件列表而没有报错，说明安装成功！✅
第三步：安装 Conda（Python 环境管理器）
3.1 检查是否已安装 Conda
在终端中输入：
conda --version
- 如果显示版本号，说明已安装，跳到第四步
- 如果提示「未找到命令」，继续以下步骤
3.2 下载并安装 Miniconda
对于 Apple Silicon（M1/M2/M3）芯片的 Mac：
curl -O https://repo.anaconda.com/miniconda/Miniconda3-latest-MacOSX-arm64.sh
bash Miniconda3-latest-MacOSX-arm64.sh
对于 Intel 芯片的 Mac：
curl -O https://repo.anaconda.com/miniconda/Miniconda3-latest-MacOSX-x86_64.sh
bash Miniconda3-latest-MacOSX-x86_64.sh
3.3 安装过程操作说明
安装过程中会有几次提示：
- 许可协议：按
空格键快速翻页，最后输入yes并回车 - 安装路径：直接按
回车键（使用默认路径） - 初始化：输入
yes并回车
3.4 重新加载终端配置
source ~/.zshrc
如果使用 bash，则执行：
source ~/.bashrc
3.5 验证安装
conda --version
显示版本号即表示安装成功！✅
第四步：进入项目目录
在终端中输入（根据您的实际路径调整）：
cd /Users/你的用户名/Desktop/py-xiaozhi
💡 提示：可以直接把项目文件夹拖到终端窗口，会自动填入完整路径！
验证是否在正确目录：
pwd
应该显示包含 py-xiaozhi 的路径。
第五步：创建 Python 环境
5.1 创建专用环境
在终端中执行：
conda create -n py-xiaozhi python=3.10 -y
⏱️ 需要 2-3 分钟，会下载 Python 3.10 及相关包。
5.2 激活环境
conda activate py-xiaozhi
成功后，终端提示符前面会显示 (py-xiaozhi)，像这样：
(py-xiaozhi) ➜ py-xiaozhi
第六步：安装项目依赖
6.1 安装 Python 依赖包
确保已激活 py-xiaozhi 环境（提示符前有 (py-xiaozhi)），然后执行：
pip install -r requirements_mac.txt
⏱️ 这是最耗时的步骤，需要 10-20 分钟，会下载 70+ 个 Python 包。
6.2 等待安装完成
当看到类似以下信息时，表示安装成功：
Successfully installed PyQt5-5.15.11 numpy-1.26.4 ...
第七步：启动项目 🎉
7.1 首次启动（GUI 模式）
在终端中确保：
- 当前目录在
py-xiaozhi文件夹 - 已激活
py-xiaozhi环境
然后执行：
python main.py
7.2 看到激活窗口
首次启动会弹出设备激活窗口，这是正常的！
第八步：激活设备
8.1 获取激活信息
激活窗口会显示：
- 设备序列号（如：SN-xxxxxxxx-xxxxxxxxxxxx）
- 二维码或激活码
8.2 前往激活网站
- 打开浏览器访问：xiaozhi.me/
- 登录您的账号（如果没有账号，需要先注册）
- 找到「设备激活」或「添加设备」选项
8.3 完成激活
根据网站提示：
- 扫描二维码，或
- 手动输入设备序列号
激活成功后，客户端会自动连接！🎊
第九步：授予权限
macOS 会弹出权限请求，请全部允许：
- ✅ 麦克风权限（必需）：用于语音输入
- ✅ 摄像头权限（可选）：如果需要使用视觉功能
- ✅ 网络权限（必需）：连接小智 AI 服务
🎮 使用说明
默认快捷键
激活成功后，可以使用以下快捷键：
| 快捷键 | 功能 | 说明 |
|---|---|---|
Ctrl + J | 按住说话 | 按下说话，松开结束 |
Ctrl + K | 自动对话 | 开启/关闭连续对话模式 |
Ctrl + Q | 中断对话 | 立即停止当前对话 |
Ctrl + M | 切换模式 | 切换交互模式 |
Ctrl + W | 隐藏窗口 | 最小化/显示窗口 |
语音唤醒（可选）
如果启用了语音唤醒功能，可以说「小智小智」或其他配置的唤醒词来激活对话。
🔄 后续使用（第二次及以后）
每次使用只需要简单三步：
方法一：终端启动
# 1. 进入项目目录
cd /Users/你的用户名/Desktop/py-xiaozhi
# 2. 激活环境
conda activate py-xiaozhi
# 3. 启动程序
python main.py
方法二：创建启动脚本（推荐）
创建一个启动脚本，以后双击就能启动！
- 在项目文件夹创建文件
启动小智.command - 用文本编辑器打开，粘贴以下内容：
#!/bin/bash
cd "$(dirname "$0")"
source ~/.zshrc
conda activate py-xiaozhi
python main.py
- 在终端中给脚本添加执行权限：
chmod +x 启动小智.command
- 以后直接双击
启动小智.command即可启动！
🎯 其他运行模式
CLI 模式（命令行模式）
适合没有 GUI 或服务器环境：
python main.py --mode cli
MQTT 协议模式
python main.py --protocol mqtt
跳过激活（调试用）
python main.py --skip-activation
❓ 常见问题
Q1: 提示「opus 库加载失败」
解决方案：
# 重新安装 opus
brew reinstall opus
# 设置环境变量
export DYLD_LIBRARY_PATH=/opt/homebrew/lib:$DYLD_LIBRARY_PATH
Q2: 提示「麦克风权限被拒绝」
解决方案：
- 打开「系统设置」→「隐私与安全性」→「麦克风」
- 找到「终端」或「Python」，勾选允许
Q3: 激活窗口无法打开
解决方案：
# 检查是否安装了 PyQt5
pip show PyQt5
# 如果未安装，执行
pip install PyQt5==5.15.11
Q4: 网络连接失败
解决方案：
- 检查网络连接是否正常
- 确认可以访问 xiaozhi.me/
- 如果使用代理，请检查代理设置
Q5: 依赖安装失败
解决方案：
# 更换 pip 源为国内镜像
pip config set global.index-url https://mirrors.aliyun.com/pypi/simple/
# 重新安装
pip install -r requirements_mac.txt
Q6: Conda 命令找不到
解决方案：
# 重新初始化 Conda
~/miniconda3/bin/conda init zsh
# 重新加载配置
source ~/.zshrc
📚 进阶配置
修改配置文件
配置文件位置：config/config.json
可以修改的内容：
- 唤醒词设置
- 快捷键绑定
- 音频设备选择
- MCP 工具开关
注意：修改前请备份原文件！
查看日志
如遇问题，可查看日志文件：
# 查看最新日志
tail -f logs/app.log
# 查看完整日志
cat logs/app.log
🆘 获取帮助
如果遇到无法解决的问题：
- 查看完整文档：huangjunsen0406.github.io/py-xiaozhi/
- GitHub Issues：github.com/huangjunsen…
- B 站视频教程：www.bilibili.com/video/BV1dW…
✅ 完成检查清单
在首次启动前，确认以下步骤都已完成：
- 已安装 Homebrew
- 已安装系统依赖（portaudio, opus, ffmpeg, gfortran）
- 已安装 Conda
- 已创建并激活 py-xiaozhi 环境
- 已安装 Python 依赖包
- 已启动程序并看到激活窗口
- 已在 xiaozhi.me 完成设备激活
- 已授予麦克风权限
- 可以正常使用语音交互
全部打勾 ✅ 说明您已成功启动 py-xiaozhi！🎉
🎓 使用技巧
提高语音识别准确率
- 确保环境安静
- 说话清晰，语速适中
- 距离麦克风 20-30cm
- 避免背景噪音
优化性能
- 关闭不需要的 MCP 工具
- 调整音频采样率（在配置文件中）
- 使用有线网络而非 WiFi
数据安全
- 定期备份
config/目录 - 不要分享您的设备序列号和密钥
- 定期更新到最新版本
祝您使用愉快！ 🎊
有问题随时查阅文档或寻求社区帮助。享受与小智 AI 的对话吧！💬✨
