ZeroClaw on Arduino Uno Q: ステップバイステップガイド

Arduino Uno QのLinux側でZeroClawを実行します。Telegramはこれぞれのセットアップで機能します。WiFi経由のTelegram。GPIOコントロールはBridge(最小限のApp Labアプリが必要)を使用します。

含まれるもの(コード変更は不要)

ZeroClaw には Arduino Uno Q に必要なものがすべて含まれています。リポジトリをクローンしてこのガイドに従うだけで、パッチやカスタムコードは一切不要です。

コンポーネント	場所	目的
Bridge app	`firmware/uno-q-bridge/`	MCU sketch + Python socket server (port 9999) for GPIO
Bridge tools	`crates/zeroclaw-hardware/src/peripherals/uno_q_bridge.rs`	`gpio_read` / `gpio_write` tools that talk to the Bridge over TCP
セットアップコマンド	`crates/zeroclaw-hardware/src/peripherals/uno_q_setup.rs`	`zeroclaw peripheral setup-uno-q` deploys the Bridge via scp + arduino-app-cli
Config schema	`board = "arduino-uno-q"`, `transport = "bridge"`	ゲートウェイ、zerocode、または `zeroclaw config set` で設定可能

Build with --features hardware to include Uno Q support.

前提条件

Arduino Uno Q with WiFi configured
初期ボードセットアップ用に、お使いのコンピューターに Arduino App Lab がインストールされていること
arduino-app-cliは Uno Q で利用可能です（ボードの Debian イメージにプリインストールされており、Bridge のデプロイに使用されます）
API key for LLM (OpenRouter, etc.)

Phase 1: Initial Uno Q Setup (One-Time)

1.1 Configure Uno Q via App Lab

Download Arduino App Lab (tar.gz on Linux).
Connect Uno Q via USB, power it on.
Open App Lab, connect to the board.
Follow the setup wizard:
- Set username and password (for SSH)
- Configure WiFi (SSID, password)
- Apply any firmware updates
Note the IP address shown (e.g. arduino@192.168.1.42) or find it later via ip addr show in App Lab’s terminal.

1.2 Verify SSH Access

sh

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

Phase 2: Install ZeroClaw on Uno Q

オプション A: デバイス上でビルドする（より簡単）

sh

# SSH into 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

# Install build deps (Debian)
sudo apt-get update
sudo apt-get install -y pkg-config libssl-dev

# Clone zeroclaw (or scp your project)
git clone https://github.com/zeroclaw-labs/zeroclaw.git
cd zeroclaw

# ビルド（デバイス上でのビルドは遅いため、ビルド時間が重要な場合はより大きなマシンからクロスコンパイルしてください）
export CARGO_BUILD_JOBS=1 # これがないとビルドはリンク中に OOM で強制終了されます
cargo build --release --features hardware

# Install
sudo cp target/release/zeroclaw /usr/local/bin/

Option B: Cross-Compile on Mac (Faster)

sh

# On your Mac — add aarch64 target
rustup target add aarch64-unknown-linux-gnu

# Install cross-compiler (macOS; required for linking)
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

# Copy to 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/"

If cross-compile fails, use Option A and build on the device.

Phase 3: Configure ZeroClaw

3.1 クイックスタートを実行する（または手動で設定を作成する）

sh

ssh arduino@<UNO_Q_IP>

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

最低限、api_key / model を指定した [providers.models.<type>.<alias>] エントリを 1 つ、model_provider = "<type>.<alias>" でそれを参照する [agents.<alias>] を 1 つ、bot_token を指定した [channels.telegram.<alias>] を 1 つ設定してください。エージェント側の channels = ["telegram.<alias>"] でチャネルをエージェントにバインドします。以下のフェーズ 4 までは [peripherals] を無効のままにしておいてください。すべてのフィールドについては Config reference を参照してください。

フェーズ 4: ZeroClaw デーモンを実行

sh

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: Bridge 経由の GPIO (ZeroClaw が処理)

ZeroClaw には Bridge アプリとセットアップコマンドが含まれています。

5.1 Bridge アプリをデプロイ

お使いのコンピューターから（zeroclaw リポジトリを使用）:

sh

zeroclaw peripheral setup-uno-q --host 192.168.0.48

Uno Q から (SSH でログイン):

sh

zeroclaw peripheral setup-uno-q

これにより Bridge アプリが ~/ArduinoApps/uno-q-bridge にコピーされ、起動されます。

zeroclaw daemon --host 127.0.0.1 --port 42617

Telegram ボットに “Turn on the LED” または “Set pin 13 high” とメッセージを送ると、ZeroClaw は Bridge 経由で gpio_write を使用します。

概要: コマンドの開始から終了まで

ステップ	コマンド
1	App Lab で Uno Q を設定 (WiFi、SSH)
2	`ssh arduino@<IP>`
3	`curl -sSf https://sh.rustup.rs \| sh -s -- -y && source ~/.cargo/env`
4	`sudo apt-get install -y pkg-config libssl-dev`
5	`git clone https://github.com/zeroclaw-labs/zeroclaw.git && cd zeroclaw`
6	`export CARGO_BUILD_JOBS=1 && cargo build --release --features hardware`
7	`zeroclaw quickstart --api-key KEY --model-provider openrouter`
8	`zeroclaw config set channels.telegram.default.bot-token <token>`
9	`zeroclaw daemon --host 127.0.0.1 --port 42617`
10	Telegram ボットにメッセージを送信すると、応答が返ってきます
11	`zeroclaw peripheral setup-uno-q`（Bridgeをデプロイ）
12	ゲートウェイ、zerocode、または `zeroclaw config set` を使って、`board = "arduino-uno-q"` を指定した `peripherals` ボードを追加します
13	デーモンを再起動（`zeroclaw daemon …`）すると、GPIO コマンドが動作するようになりました

トラブルシューティング

“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): [providers.models.glm.<alias>] を環境変数または設定の GLM_API_KEY で構成します（レガシーの zhipu という同義語は glm に統合されます）。ZeroClaw は正しい v4 エンドポイントを使用します。

ZeroClaw Docs