ZeroClaw 在 Arduino Uno Q 上的运行：分步指南

在 Arduino Uno Q 的 Linux 端运行 ZeroClaw。Telegram 通过 WiFi 工作；GPIO 控制使用 Bridge（需要最小化的 App Lab 应用）。

包含内容（无需更改代码）

ZeroClaw 包含 Arduino Uno Q 所需的一切。克隆该仓库并按照本指南操作，无需补丁或自定义代码。

使用 --features hardware 构建以包含 Uno Q 支持。

前置条件

• 已配置 WiFi 的 Arduino Uno Q
• 已在计算机上安装 Arduino App Lab（用于初始开发板设置）
• arduino-app-cli 在 Uno Q 上可用（已随开发板的 Debian 镜像预装，用于 Bridge 部署）
• 用于 LLM 的 API 密钥（OpenRouter 等）

阶段 1：初始 Uno Q 设置（一次性）

1.1 通过 App Lab 配置 Uno Q

1. 下载 Arduino App Lab（Linux 系统为 tar.gz 格式）。
2. 通过 USB 连接 Uno Q，并为其供电。
3. 打开 App Lab，连接到开发板。
4. 按照设置向导操作：
   • 设置用户名和密码（用于 SSH）
   • 配置 WiFi（SSID、密码）
   • 应用任何固件更新
5. 记下显示的 IP 地址（例如 arduino@192.168.1.42），或者稍后通过 App Lab 终端中的 ip addr show 命令查找。

1.2 验证 SSH 访问

ssh arduino@<UNO_Q_IP>
# Enter the password you set

阶段 2：在 Uno Q 上安装 ZeroClaw

选项 A：在设备上构建（更简单）

# SSH 登录 Uno Q
ssh arduino@<UNO_Q_IP>

# Install Rust
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh -s -- -y
source ~/.cargo/env

# 安装构建依赖项（Debian）
sudo apt-get update
sudo apt-get install -y pkg-config libssl-dev

# 克隆 zeroclaw（或 scp 你的项目）
git clone https://github.com/zeroclaw-labs/zeroclaw.git
cd zeroclaw

# 构建（设备端构建较慢；如果在意构建时间，请从性能更强的机器交叉编译）
export CARGO_BUILD_JOBS=1 # 没有这个配置，构建会在链接过程中因内存不足被终止
cargo build --release --features hardware

# 安装
sudo cp target/release/zeroclaw /usr/local/bin/

选项 B：在 Mac 上进行交叉编译（更快）

# 在您的 Mac 上 — 添加 aarch64 目标
rustup target add aarch64-unknown-linux-gnu

# 安装交叉编译器（macOS；用于链接）
brew tap messense/macos-cross-toolchains
brew install aarch64-unknown-linux-gnu

# 构建
CC_aarch64_unknown_linux_gnu=aarch64-unknown-linux-gnu-gcc cargo build --release --target aarch64-unknown-linux-gnu --features hardware

# 复制到 Uno Q
scp target/aarch64-unknown-linux-gnu/release/zeroclaw arduino@<UNO_Q_IP>:~/
ssh arduino@<UNO_Q_IP> `sudo mv ~/zeroclaw /usr/local/bin/`

如果交叉编译失败，请使用选项 A 并在设备上构建。

阶段 3：配置 ZeroClaw

3.1 运行快速入门（或手动创建配置）

ssh arduino@<UNO_Q_IP>

# Quick config
zeroclaw quickstart --api-key YOUR_OPENROUTER_KEY --model-provider openrouter

3.2 最小配置

至少需要配置一个带有 api_key / model 的 [providers.models.<type>.<alias>] 条目、一个通过 model_provider = "<type>.<alias>" 引用它的 [agents.<alias>]，以及一个带有 bot_token 的 [channels.telegram.<alias>]。通过在 agent 上设置 channels = ["telegram.<alias>"] 将频道绑定到 agent。在下方的第 4 阶段之前，请将 [peripherals] 保持禁用状态。所有字段请参阅配置参考。

阶段 4：运行 ZeroClaw 守护进程

ssh arduino@<UNO_Q_IP>

# Run daemon (Telegram polling works over WiFi)
zeroclaw daemon --host 127.0.0.1 --port 42617

到这一步： Telegram 聊天已经可用。向你的机器人发送消息，ZeroClaw 会做出响应。还没有 GPIO 功能。

阶段 5：通过桥接器访问 GPIO（ZeroClaw 负责处理）

ZeroClaw 包含桥接应用和设置命令。

5.1 部署桥接应用

从您的计算机（使用 zeroclaw 仓库）：

zeroclaw peripheral setup-uno-q --host 192.168.0.48

来自 Uno Q（通过 SSH 连接）：

zeroclaw peripheral setup-uno-q

这将把 Bridge 应用复制到 ~/ArduinoApps/uno-q-bridge 并启动它。

5.2 添加到配置

启用 [peripherals] 并添加一个 [[peripherals.boards]] 条目，其中 board = "arduino-uno-q" 且 transport = "bridge"。

5.3 运行 ZeroClaw

zeroclaw daemon --host 127.0.0.1 --port 42617

现在，当您向 Telegram 机器人发送消息 “Turn on the LED” 或 “Set pin 13 high” 时，ZeroClaw 会通过 Bridge 使用 gpio_write。

摘要：从开始到结束的命令

故障排除

• “command not found: zeroclaw”：使用完整路径：/usr/local/bin/zeroclaw，或确保 ~/.cargo/bin 已包含在 PATH 中。
• Telegram 无响应：检查 bot_token、allowed_users，以及 Uno Q 是否已联网（WiFi）。
• 内存不足：保持功能精简（Uno Q 使用 --features hardware）；考虑设置 compact_context = true。
• GPIO 命令被忽略：请确保 Bridge 应用正在运行（zeroclaw peripheral setup-uno-q 会部署并启动它）。配置中必须包含 board = "arduino-uno-q" 和 transport = "bridge"。
• LLM 提供方 (GLM/Zhipu)：在环境变量或配置中通过 GLM_API_KEY 配置 [providers.models.glm.<alias>]（旧的 zhipu 同义词已合并到 glm）。ZeroClaw 使用正确的 v4 端点。