Raspberry Pi のセットアップ

このガイドでは、Raspberry Pi での ZeroClaw のインストールと実行について説明します。

ランタイムは十分に小さく、どの Pi でも快適に動作します。唯一の制約はデバイス上でソースからビルドする場合です。Rust のリンカはメモリを大量に消費するため（fat LTO は RAM の少ないボードで OOM を引き起こす可能性があります）、デバイス上でのビルドパスにはスワップと軽量なプロファイルが必要です。ほとんどのユーザーはビルド済みバイナリを使用し、これらすべてをスキップすべきです。

ハードウェア互換性

64ビット（aarch64）または32ビット（armv7）のRaspberry Pi OSを実行できるPiであればビルド済みバイナリをそのまますべて実行でき、ランタイムに実質的なメモリ下限はありません。ビルド済みのPi向けバイナリは、これらのリリースターゲット（64ビットRaspberry Pi OS向けの64ビットaarch64、32ビットOS向けの32ビットarmv7/arm）から提供されています。

• aarch64-unknown-linux-gnu (64ビット)
• arm-unknown-linux-gnueabihf（32ビット）
• armv7-unknown-linux-gnueabihf（32ビット）

オプション1: ビルド済みバイナリ（推奨）

最速の方法です。コンパイラ不要、スワップ不要、OOMのリスクもありません。

インストールスクリプトの使用

Unix の高速パス

curl -fsSL https://raw.githubusercontent.com/zeroclaw-labs/zeroclaw/master/install.sh | sh

このルートは非対話型で、ピッカーを開きません。

一致するビルド済みバイナリを優先し、必要に応じてソースからのビルドにフォールバックします。

ビルド済みアーカイブには zerocode が含まれている場合があります。非対話型のソースフォールバックでは、ピッカーを開かずにデフォルトアプリがインストールされます。

このコマンドでは固定の機能セットが使用されます。

ソースからのビルドが必要な場合、インストーラーは Rust がインストールされていなければ Rust をブートストラップできます。

Unix では、許可されている場合、インストーラーがシェルプロファイルを更新します。新しい PATH を利用する前に、親シェルを再読み込みしてください。

インストーラーはセットアップをスキップし、次の手順として zeroclaw quickstart を表示します。

Unix ガイド付きパス

git clone https://github.com/zeroclaw-labs/zeroclaw.git
cd zeroclaw
./install.sh

このルートはガイド付きで、サポートされている選択肢が提示される場合があります。

サポート対象のターゲットでは、ビルド済み版またはソースからのインストールを利用できます。

ビルド済みアーカイブには zerocode が含まれている場合があります。ソースを選択すると、zerocode がデフォルトで選択され、アプリを選択できます。

ソースパスでは、オプションの Cargo フィーチャーも選択できます。

ソースからのビルドが必要な場合、インストーラーは Rust がインストールされていなければ Rust をブートストラップできます。

Unix では、許可されている場合、インストーラーがシェルプロファイルを更新します。新しい PATH を利用する前に、親シェルを再読み込みしてください。

未設定のインストールでは、zeroclaw quickstart またはブラウザーベースのクイックスタートを利用できます。

このスクリプトはお使いのアーキテクチャ（aarch64、armv7、または armv6）を自動検出し、対応するリリースバイナリを $CARGO_HOME/bin/zeroclaw（デフォルトは ~/.cargo/bin/zeroclaw）にインストールします。そのディレクトリが PATH に含まれていることを確認してください。

スクリプトが事前ビルド済みのバイナリを使用せずにソースからビルドする場合、ボードの利用可能なメモリに合わせてビルドを調整します:

install.sh が Linux 上でソースからビルドする際、/proc/meminfo から MemTotal を読み取り、RAM が 12 GiB 未満 のホストでは、ビルド前に CARGO_PROFILE_RELEASE_LTO=thin をエクスポートします。Fat LTO（[profile.release] のデフォルト）は、クレート間の型解決パス中に RSS が 7 GB を超えてピークに達することがあり、RAM の少ないボードでは OOM を引き起こす可能性があります。thin LTO は、バイナリサイズのわずかな増加と引き換えに、ビルド時のメモリピークを大幅に低減します。

スイッチは、変数をまだ固定していない場合にのみ適用されます。どちらの方向でも明示的に上書きできます:

# 低RAMホストでも強制的にfat LTOを使用（バイナリは小さくなるがビルド時のRAM消費が増加）
export CARGO_PROFILE_RELEASE_LTO=fat

# 高RAMホストでthin LTOを強制（ビルドRAMを削減）
export CARGO_PROFILE_RELEASE_LTO=thin

手動ダウンロード

最新リリースから該当する tarball を選択してください。

# 64ビット（64ビット版Raspberry Pi OSを使用したPi 4/5）
curl -LO https://github.com/zeroclaw-labs/zeroclaw/releases/latest/download/zeroclaw-aarch64-unknown-linux-gnu.tar.gz
tar xzf zeroclaw-aarch64-unknown-linux-gnu.tar.gz
sudo install -m 0755 zeroclaw /usr/local/bin/

# 32ビット（Pi Zero 2 W、32ビットOSを搭載した旧型Pi 3）
curl -LO https://github.com/zeroclaw-labs/zeroclaw/releases/latest/download/zeroclaw-armv7-unknown-linux-gnueabihf.tar.gz
tar xzf zeroclaw-armv7-unknown-linux-gnueabihf.tar.gz
sudo install -m 0755 zeroclaw /usr/local/bin/

アーキテクチャを確認してください

uname -m
# aarch64 → 64-bit（aarch64-unknown-linux-gnu バイナリを使用）
# armv7l  → 32-bit (use the armv7-unknown-linux-gnueabihf binary)
# armv6l → Pi 1 / Zero / Zero W（arm-unknown-linux-gnueabihf バイナリを使用）

オプション 2: 別のマシンからクロスコンパイルする

より高性能なマシンをすでにお持ちの場合、クロスコンパイルはPi上でビルドするよりも高速です。

# クロスコンパイルターゲットをインストールする
rustup target add aarch64-unknown-linux-gnu

# Linux GNU クロスツールチェーンをインストールする — Arduino Uno Q ガイドで使用されているのと同じパターン
brew tap messense/macos-cross-toolchains
brew install aarch64-unknown-linux-gnu

# ビルド
CC_aarch64_unknown_linux_gnu=aarch64-unknown-linux-gnu-gcc \
CARGO_TARGET_AARCH64_UNKNOWN_LINUX_GNU_LINKER=aarch64-unknown-linux-gnu-gcc \
cargo build --release --target aarch64-unknown-linux-gnu

# Copy to your Pi
scp target/aarch64-unknown-linux-gnu/release/zeroclaw pi@raspberrypi:~/

# クロスコンパイルツールチェーンをインストールする
sudo apt-get install -y gcc-aarch64-linux-gnu

# ターゲットを追加
rustup target add aarch64-unknown-linux-gnu

# リンカーの設定
# [target.aarch64-unknown-linux-gnu]
# linker = "aarch64-linux-gnu-gcc"

# ビルド
cargo build --release --target aarch64-unknown-linux-gnu

# Pi にコピー
scp target/aarch64-unknown-linux-gnu/release/zeroclaw pi@raspberrypi:~/

オプション3: Piでビルドする

デバイス上でエージェントが自分自身をコンパイルします。スワップと適切なビルドプロファイルがあればどの Pi でも動作しますが、RAM の少ないボードでは遅くなります。

ステップ 1: Rust ツールチェインをインストールする

curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
source $HOME/.cargo/env

ステップ 2: スワップを追加する

ファットLTOは最終リンク時にピークに達するため、スワップがないと低RAMのボードではリンク中にOOMで強制終了されます。

# 4 GB のスワップファイルを作成する
sudo fallocate -l 4G /swapfile
sudo chmod 600 /swapfile
sudo mkswap /swapfile
sudo swapon /swapfile

# 検証
free -h

# 再起動後も永続化する
echo /swapfile none swap sw 0 0 | sudo tee -a /etc/fstab

ステップ3: ビルド

利用可能なRAMに応じてプロファイルを選択します。release はfat LTO（最良のバイナリ、最も重いリンク）、release-fast はcodegen-unitsを増やして軽量なリンクにします。ci はthin LTOを使用して最も少ないメモリでリンクします。（install.sh はこれを自動的に選択します。インストールスクリプトの使用を参照してください。）

git clone https://github.com/zeroclaw-labs/zeroclaw.git
cd zeroclaw

cargo build --release           # 高RAM搭載ボード
cargo build --profile release-fast   # 中容量RAMボード
cargo build --profile ci        # 低RAM / 制約のあるボード

# ビルドしたバイナリをインストールします:
sudo install -m 0755 target/release/zeroclaw /usr/local/bin/
# (または target/release-fast/zeroclaw、または target/ci/zeroclaw)

GPIO サポート

スキルから Pi GPIO を制御するには、関連する peripherals 機能フラグを有効にしてビルドします。ほとんどのエージェントワークロードでは不要です。Peripherals design を参照してください。

コンテナ化されたデプロイ（DockerよりPodmanを推奨）

メモリが制限された Pi では、コンテナランタイムの選択が重要です。ZeroClaw と並べてスタックするものすべてが同じ固定プールを奪い合うため、コンテナインフラに使われないメモリは、そのままエージェントが利用できるメモリになります。

Pi で Docker ではなく Podman を選ぶ理由:

1. デフォルトでルートレス。 ルートデーモンが存在せず、コンテナは自分のユーザー権限で実行されます。これは公開されたエッジデバイスにおいて重要です。
2. Quadlet 経由の systemd ネイティブ。 systemd が直接管理する .container ユニットファイルで、別途の docker.service やロギングレイヤーは不要です。
3. 永続的なデーモンがありません。 Docker は dockerd を常駐させますが、Podman はそうしないため、分離性を損なうことなく最大のメモリ消費要因を解消できます。

トレードオフ: Podman のルートレスネットワーク（slirp4netns/pasta）は Docker のブリッジよりも低速です。ZeroClaw の「1つか2つの長時間稼働するエージェントコンテナ」というパターンではこれは無視できる程度であり、制約のあるハードウェアではデーモンの節約効果が支配的になります。

クイックインストール（Raspberry Pi OS Bookworm/Trixie）

sudo apt-get install -y podman
# オプション: 短いエイリアス — 多くの docker-compose フローは podman-compose でそのまま動作します
sudo apt-get install -y podman-compose

Podman での ZeroClaw の実行

公開されている OCI イメージは、変更なしで Podman 上で動作します:

podman pull ghcr.io/zeroclaw-labs/zeroclaw:latest

podman run --rm -d \
  --name zeroclaw \
  -p 42617:42617 \
  -v ~/.zeroclaw:/root/.zeroclaw \
  ghcr.io/zeroclaw-labs/zeroclaw:latest \
  daemon --host 0.0.0.0 --port 42617

バインドの落とし穴: ZeroClaw はゲートウェイのデフォルトを 127.0.0.1 にします。コンテナ内ではこれはホストからゲートウェイに到達できないことを意味します。コンテナ内で実行する場合は、必ず --host 0.0.0.0 を渡してください（または ZEROCLAW_BIND=0.0.0.0 を設定してください）。

Quadlet を介して systemd ユニットとして実行する

/etc/containers/systemd/（システム）または ~/.config/containers/systemd/（rootless ユーザー）に .container ファイルを配置します：

# ~/.config/containers/systemd/zeroclaw.container
[Unit]
Description=ZeroClaw gateway
After=network-online.target
Wants=network-online.target

[Container]
Image=ghcr.io/zeroclaw-labs/zeroclaw:latest
ContainerName=zeroclaw
PublishPort=42617:42617
Environment=ZEROCLAW_BIND=0.0.0.0
Exec=daemon --host 0.0.0.0 --port 42617
Volume=zeroclaw-data:/root/.zeroclaw

[Service]
Restart=always
RestartSec=10

[Install]
WantedBy=multi-user.target default.target

systemctl --user daemon-reload
systemctl --user start zeroclaw.service

ルートレス構成の場合は、ログイン前にサービスが起動するように loginctl enable-linger $USER も実行してください。

インストール後: ネイティブ（非コンテナ）セットアップ

1. ZeroClaw を初期化する

zeroclaw quickstart

プロバイダー認証、ゲートウェイ設定を順を追って説明し、ZeroClaw 設定を作成します。

2. 動作することを確認する

zeroclaw doctor
zeroclaw agent -a assistant -m 2+2は何ですか？

3. 永続的なサービスとして実行する

# systemd ユーザーサービスのインストールと起動
zeroclaw service install
systemctl --user enable --now zeroclaw

# ログアウト／再起動後も維持されるように:
loginctl enable-linger $USER

4. フォアグラウンドデーモンとして実行する

開発／デバッグ用：

zeroclaw daemon --host 0.0.0.0 --port 42617

5. チャンネルを有効にする

ZeroClawはチャットプラットフォーム（Matrix、Mattermost、Discord、Telegramなど）に接続できます。チャンネル → 概要を参照してください。ほとんどのチャンネルトランスポートはPi上で問題なく動作します。最も負荷が高いのは一部のボイスチャンネルで使用されるWebRTCスタックで、通話のセットアップ中にCPU使用率が急上昇する可能性があります。

GPIOとハードウェア周辺機器

スキルでGPIOピン（LED、ボタン、センサーなど）を制御したい場合：

1. ユーザーを gpio グループに追加します:

   sh

   sudo usermod -aG gpio $USER
   グループの変更を有効にするには、一度ログアウトして再度ログインしてください
   

2. スキルの peripherals クレートの GPIO バインディングを使用します。抽象化モデルについては Hardware → Peripherals design を参照してください。

トラブルシューティング

• ビルド中の OOM kill: スワップを追加する（オプション 3 のステップ 2）か、より軽量なプロファイル（release-fast または ci）に切り替えるか、ビルド済みバイナリの使用 / クロスコンパイルを行ってください。
• ビルドが極端に遅い: RAM容量の少ないボードでは想定される動作です。問題になる場合はクロスコンパイル（オプション2）を使用してください。
• ビルド済みバイナリの “Exec format error”: アーキテクチャの不一致です。uname -m を実行し、一致するバイナリを取得してください（aarch64 = 64ビット、armv7l = 32ビット）。
• GPIO のアクセスが拒否されました: gpio グループに所属していません。sudo usermod -aG gpio $USER を実行してから、再ログインしてください。
• 再起動後にサービスが起動しない場合: loginctl enable-linger $USER を実行すると、ログアウト後もユーザーサービスが維持されます。
• コンテナからホストのゲートウェイに接続できない場合: ゲートウェイは 127.0.0.1 にバインドされています。--host 0.0.0.0（または ZEROCLAW_BIND=0.0.0.0）を指定してください。

パフォーマンスのヒント

• SSDまたは高速なSDカードを使用してください。 コンパイルはI/Oバウンドであり、Pi 4/5でUSB 3.0 SSDを使用するとビルド時間が大幅に短縮されます。
• ヘッドレスで実行する: sudo systemctl set-default multi-user.target。
• ビルド成果物用の tmpfs（RAM + swap に余裕がある場合）: export CARGO_TARGET_DIR=/tmp/zeroclaw-target。
• カスタムイメージを使用する場合は、カーネルの cmdline に clk_ignore_unused が設定されていないか確認してください。これはクロックゲーティングを抑制し、アイドル時の消費電力を増加させます。標準の Raspberry Pi OS では設定されていません。

関連

• Linux のセットアップ: Pi 固有ではない Linux のセットアップ。バイナリのインストール後はここでも適用できます
• サービス管理: systemd のパターン、上記よりも詳しく
• ハードウェア → ペリフェラル設計: GPIOとペリフェラルクレート
• ハードウェア → ボードとツールの追加: ハードウェアサポートの拡張