难度：⭐⭐⭐☆☆ | 时长：45 分钟 | 收获：掌握嵌入式 AI 语音助手的完整搭建方案

我们今天来玩点硬核的——用树莓派做一个可以语音对话的 AI 助手。

按一下按钮，说出你的问题，LCD 屏幕上会实时流式显示 AI 的回复。如果你想让它说话，还能开启 TTS 语音播报。

这就是 pizero-openclaw，一个运行在树莓派上的开源语音 AI 助手。我们一步步把它跑起来。

---

目标读者画像

• 1-5 年开发经验，对嵌入式 + AI 感兴趣的开发者
• 想动手做 AI 硬件的玩家
• 有一定 Linux 命令行基础的同学

---

核心依赖与环境

在开始之前，确保你手头有这些：

---

项目结构

pizero-openclaw/
├── main.py                 # 入口文件，主循环
├── display.py              # LCD 渲染（状态、回复、时钟）
├── openclaw_client.py      # OpenClaw 网关 HTTP 客户端
├── transcribe_openai.py    # 语音转文字（OpenAI）
├── tts_openai.py           # 文字转语音（OpenAI）
├── record_audio.py         # 录音（ALSA）
├── button_ptt.py           # 按键状态机（按下录音、松开发送）
├── config.py               # 配置管理（.env 加载）
├── sync.sh                 # 部署脚本（rsync + systemd）
├── .env.example            # 配置示例
└── requirements.txt        # Python 依赖

---

硬件准备

我们先准备好所有硬件。

必选硬件

可选硬件

• PiSugar 电池 —— 锂电池模块，可以脱电使用
• 外壳 —— 3D 打印或亚克力切割

---

系统烧录与初始化

烧录 Raspberry Pi OS

1. 下载 Raspberry Pi Imager
2. 选择 Raspberry Pi OS (Bookworm) 32-bit 或 64-bit
3. 在高级设置里开启：
   • 启用 SSH
   • 配置 Wi-Fi SSID 和密码
   • 设置用户名 pi 和密码

烧录完成后，把 TF 卡插到树莓派上，通电开机。

首次连接

# 在电脑上查找树莓派 IP
arp -a | grep raspberry

# SSH 连接（默认密码是 raspberry）
ssh [email protected]

第一次登录后，建议更新系统：

sudo raspi-config

设置以下选项：

• 扩展文件系统到整个 TF 卡
• 设置时区（Localization → Timezone）
• 启用 SPI 接口（Interface Options → SPI）

---

安装依赖

Python 环境确认

# 检查 Python 版本
python3 --version
# 输出应该是 Python 3.11+

# 如果版本太低，需要升级
sudo apt update
sudo apt install python3.11 python3.11-venv

安装系统依赖

sudo apt install python3-numpy python3-pil python3-pip

安装 Python 包

# 克隆项目
git clone https://github.com/your-repo/pizero-openclaw.git
cd pizero-openclaw

# 安装依赖
pip install -r requirements.txt

requirements.txt 大概长这样：

requests
python-dotenv
numpy
Pillow

---

安装 WhisPlay 驱动

这一步很关键，LCD 和按键都需要驱动才能工作。

按照 PiSugar 官方文档安装驱动：

# 驱动应该安装到 /home/pi/Whisplay/Driver/
# 具体步骤参考：https://github.com/PiSugar/whisplay-ai-chatbot

安装完成后，测试一下 LCD 能否正常显示：

cd /home/pi/Whisplay/Driver/
python3 test_display.py

如果屏幕亮起并显示内容，说明驱动安装成功。

---

配置环境变量

复制配置模板

cd ~/pizero-openclaw
cp .env.example .env
nano .env

填写必要配置

# 必填：OpenAI API Key（用于语音转文字和 TTS）
export OPENAI_API_KEY="sk-your-openai-api-key"

# 必填：OpenClaw Gateway Token
export OPENCLAW_TOKEN="your-openclaw-gateway-token"

# 可选：OpenClaw Gateway 地址
export OPENCLAW_BASE_URL="http://192.168.1.100:18789"

其他常用配置

---

搭建 OpenClaw 网关

语音助手需要连接到 OpenClaw 网关才能和 AI对话。

在树莓派上运行网关（推荐）

# 安装 OpenClaw
npm install -g openclaw@latest
openclaw onboard --install-daemon

在其他机器上运行网关

如果你的其他机器上运行树莓派性能有限，可以把网关跑在另一台电脑上：

# 在 Mac/服务器上运行
npm install -g openclaw@latest
openclaw onboard --install-daemon

配置网关

编辑 ~/.openclaw/openclaw.json：

{
  "gateway": {
    "bind": "0.0.0.0",
    "port": 18789,
    "auth": {
      "mode": "token",
      "token": "你的-token"
    }
  }
}

# 重启网关
openclaw gateway restart

# 获取 Token
openclaw config get gateway.auth.token

把获取到的 Token 填到前面配置的 .env 文件里。

---

测试运行

本地启动

一切配置就绪，现在可以测试了：

cd ~/pizero-openclaw
python3 main.py

正常情况下，你会看到：

1. LCD 显示时钟、日期、电量、WiFi 状态
2. 屏幕显示 "Ready" 等待指令

语音对话测试

1. 长按 WhisPlay 上的按钮 —— 开始录音
2. 松开 按钮 —— 发送录音
3. 等待几秒，屏幕会显示：
   • 识别到的文字
   • AI 的流式回复
4. 如果开启了 TTS，还会听到语音播报

---

systemd 服务化部署

我们希望树莓派开机后自动运行语音助手，这就需要把程序注册为 systemd 服务。

使用 sync.sh 一键部署（推荐）

项目里自带了一个部署脚本：

./sync.sh

这个脚本会：

1. 通过 rsync 把代码同步到树莓派
2. 安装 systemd unit 文件
3. 启动服务

手动部署（可选）

如果 sync.sh 不适合你的场景，可以手动创建服务：

# 创建 service 文件
sudo nano /etc/systemd/system/pizero-openclaw.service

内容如下：

[Unit]
Description=OpenClaw Voice Assistant
After=network.target

[Service]
Type=simple
User=pi
WorkingDirectory=/home/pi/pizero-openclaw
ExecStart=/usr/bin/python3 /home/pi/pizero-openclaw/main.py
Restart=always
RestartSec=10

[Install]
WantedBy=multi-user.target

然后启动服务：

sudo systemctl daemon-reload
sudo systemctl enable pizero-openclaw
sudo systemctl start pizero-openclaw

日志查看

# 查看服务日志
sudo journalctl -u pizero-openclaw -f

# 查看调试日志
cat /tmp/openclaw.log

---

核心实现原理

我们来聊聊这个项目是怎么工作的。这部分适合想深入了解的同学。

整体架构

按钮按下 → 录音 (ALSA) → 语音识别 (OpenAI Whisper) →
→ 发送到 OpenClaw 网关 → 流式接收 AI 回复 →
→ LCD 显示 + 可选 TTS 语音播报

按键状态机

# button_ptt.py 核心逻辑
class ButtonPTT:
    def __init__(self):
        self.is_pressed = False

    def on_press(self):
        self.is_pressed = True
        start_recording()  # 开始录音

    def on_release(self):
        self.is_pressed = False
        stop_recording()   # 停止录音，发送到 AI

关键点：

• 按下 时开始持续录音
• 松开 时结束录音并发送
• 录音数据保存为 WAV 格式

语音识别

# transcribe_openai.py
def transcribe(audio_path: str) -> str:
    with open(audio_path, 'rb') as f:
        response = openai.audio.transcriptions.create(
            model="gpt-4o-mini-transcribe",
            file=f
        )
    return response.text

流式响应

# openclaw_client.py
def stream_chat(prompt: str, history: list) -> Generator[str]:
    # 发送消息给 OpenClaw 网关
    response = requests.post(
        f"{BASE_URL}/chat",
        json={"message": prompt, "history": history},
        stream=True
    )

    # 逐字 yield 实现流式效果
    for line in response.iter_lines():
        if line:
            yield parse_token(line)

LCD 渲染

# display.py
def render_response(text: str):
    # 像素级精确的字 wraps
    words = text.split()
    lines = []
    current_line = ""

    for word in words:
        if len(current_line + word) < 20:
            current_line += word + " "
        else:
            lines.append(current_line)
            current_line = word + " "

    # 逐行渲染到 LCD
    for i, line in enumerate(lines):
        draw.text((0, i * 16), line, fill=WHITE)

---

常见问题排查

这里列举几个最常见的问题及解决方案。

问题 1：麦克风无声音

症状：按钮松开后没有反应，或者识别结果为空

排查步骤：

1. 检查 ALSA 设备：arecord -l
2. 测试录音：arecord -d 3 -f cd /tmp/test.wav && aplay /tmp/test.wav
3. 调整 AUDIO_DEVICE 配置（通常是 plughw:1,0）
4. 检查 SILENCE_RMS_THRESHOLD 是否太高

问题 2：无法连接 OpenClaw 网关

症状：识别成功但 AI 不回复

排查步骤：

1. 检查 Token 是否正确：echo $OPENCLAW_TOKEN
2. 测试网关是否可达：curl http://your-gateway-ip:18789/health
3. 查看服务日志：sudo journalctl -u pizero-openclaw -f
4. 确认网关和树莓派在同一网络

问题 3：LCD 无显示

症状：屏幕不亮或显示乱码

排查步骤：

1. 检查驱动是否正确安装
2. 确认 SPI 接口已启用：raspi-config → Interface Options → SPI
3. 测试驱动：python3 /home/pi/Whisplay/Driver/test_display.py
4. 检查 LCD 排线是否松动

问题 4：TTS 无声音

症状：文字显示正常但喇叭没声音

排查步骤：

1. 确认 ENABLE_TTS=true 已设置
2. 测试喇叭：aplay /usr/share/sounds/alsa/Noise.wav
3. 调整 OPENAI_TTS_GAIN_DB 增加音量
4. 检查 AUDIO_OUTPUT_DEVICE 配置

问题 5：识别结果错误率高

症状：AI 回复的答非所问

排查步骤：

1. 检查麦克风是否正对嘴巴
2. 尝试在安静环境下测试
3. 调整 SILENCE_RMS_THRESHOLD 参数
4. 考虑更换更好的麦克风

问题 6：程序启动失败

症状：systemd 服务无法启动

排查步骤：

1. 检查 Python 路径：which python3
2. 查看错误日志：sudo journalctl -u pizero-openclaw -xe
3. 手动运行测试：cd /home/pi/pizero-openclaw && python3 main.py

---

进阶方向

玩转基础功能后，可以探索这些进阶玩法：

1. 自定义唤醒词

默认是按键唤醒，如果想改成语音唤醒（类似"小爱同学"），可以集成 Porcupine：

pip install pvporcupine

2. 添加传感器

可以接入温湿度传感器、人体感应模块等：

• DHT22 —— 温湿度显示
• HC-SR501 —— 人体感应，自动亮屏

3. 对接其他大模型

OpenClaw 支持多种模型 provider，可以切换到 Claude 或 Gemini：

{
  "providers": {
    "anthropic": {
      "apiKey": "sk-ant-..."
    }
  },
  "defaultProvider": "anthropic"
}

4. 离线语音识别

OpenAI API 需要网络，如果想做完全离线的方案，可以考虑：

• Whisper.cpp —— 本地运行的 Whisper
• Coqui TTS —— 本地 TTS

5. 自定义外观

• 3D 打印外壳
• 替换 LCD 壁纸
• 添加 LED 灯效

---

总结

我们今天搭建了一套完整的嵌入式 AI 语音助手：

1. 树莓派 Zero W —— 运行 Python 程序
2. PiSugar WhisPlay —— LCD 显示、按键、麦克风、喇叭
3. OpenClaw 网关 —— 连接 AI 大模型
4. systemd 服务 —— 开机自启

这套方案的亮点在于：

• 体积小巧，可以随身携带
• 离线运行，保护隐私
• 可扩展性强，方便接传感器
• 成本可控，200-300 元搞定

如果你想把这个项目搬到生产环境，还有几个点可以优化：

• 更好的麦克风阵列
• 添加降噪算法
• 支持多轮对话

好了，现在去试试吧！有任何问题随时来聊。

祝玩得开心！ 🎉

---

参考链接

• pizero-openclaw GitHub
• PiSugar WhisPlay 官方文档
• OpenClaw 官方文档
• Raspberry Pi OS 下载
• OpenAI API Keys