NanoClaw v2 のエージェントコンテナに GPU パススルーを設定する

はじめに
NanoClaw は、Telegram や WhatsApp などのメッセージングチャンネルに Claude を接続できる、セルフホスト型の AI エージェントフレームワークです。エージェントはそれぞれ Docker コンテナとして起動されますが、デフォルトでは GPU が利用できません。
この記事では、NanoClaw v2 のエージェントコンテナに NVIDIA GPU をパススルーし、コンテナ内から nvidia-smi や CUDA を使えるようにする手順を解説します。
環境
OS: Ubuntu 22.04 (GCP インスタンス)
GPU: NVIDIA L4 (VRAM 23GB)
NanoClaw: v2（GitHub クローン、~/nanoclaw-v2/ に配置）
起動方式: systemd ユーザーサービス
Docker: インストール済み
仕組みの理解
NanoClaw v2 はメッセージが届くたびにエージェントコンテナを docker run で起動します。この起動コマンドを組み立てているのが src/container-runner.ts（コンパイル後は dist/container-runner.js）です。

メッセージ受信
  → container-runner.js の buildContainerArgs() で docker run 引数を構築
  → docker run --rm --name ... [各種オプション] nanoclaw-agent-v2-xxx:latest

GPU を使うには docker run --gpus all を追加する必要があります。
手順

1. dist/config.js に CONTAINER_GPU の設定を追加
   NanoClaw は CONTAINER_CPU_LIMIT や CONTAINER_MEMORY_LIMIT と同じパターンで環境変数からコンテナ設定を読み込みます。同じパターンで CONTAINER_GPU を追加します。

# CONTAINER_MEMORY_LIMIT の行の直後に追加
sed -i '38a export const CONTAINER_GPU = process.env.CONTAINER_GPU || '"'"''"'"';' \
  ~/nanoclaw-v2/dist/config.js

確認:

grep -n "CONTAINER_GPU\|CONTAINER_MEMORY" ~/nanoclaw-v2/dist/config.js
# 37: export const CONTAINER_CPU_LIMIT = process.env.CONTAINER_CPU_LIMIT || '';
# 38: export const CONTAINER_MEMORY_LIMIT = process.env.CONTAINER_MEMORY_LIMIT || '';
# 39: export const CONTAINER_GPU = process.env.CONTAINER_GPU || '';

1. dist/container-runner.js に GPU フラグを追加
   ① import に CONTAINER_GPU を追加

sed -i 's/import { CONTAINER_CPU_LIMIT,/import { CONTAINER_CPU_LIMIT, CONTAINER_GPU,/' \
  ~/nanoclaw-v2/dist/container-runner.js

② buildContainerArgs() 内に --gpus フラグを追加

sed -i '/args.push.*--memory.*CONTAINER_MEMORY_LIMIT/a\    if (CONTAINER_GPU)\n        args.push('"'"'--gpus'"'"', CONTAINER_GPU);' \
  ~/nanoclaw-v2/dist/container-runner.js

確認:

grep -n "gpus\|CONTAINER_GPU" ~/nanoclaw-v2/dist/container-runner.js
# 10: import { CONTAINER_CPU_LIMIT, CONTAINER_GPU, CONTAINER_IMAGE, ...
# 352:     if (CONTAINER_GPU)
# 353:         args.push('--gpus', CONTAINER_GPU);

1. .env に CONTAINER_GPU=all を追加

echo 'CONTAINER_GPU=all' >> ~/nanoclaw-v2/.env

特定の GPU だけを渡したい場合は CONTAINER_GPU=device=0 のように指定できます。
4. systemd サービスファイルに EnvironmentFile を追加
デフォルトの systemd サービスファイルは .env を読み込まないため、EnvironmentFile ディレクティブを追加します。

# 現在のサービスファイルを確認
cat ~/.config/systemd/user/nanoclaw-v2-*.service

[Service]
Type=simple
ExecStart=/usr/bin/node /home/tclc_kaihatsu/nanoclaw-v2/dist/index.js
WorkingDirectory=/home/tclc_kaihatsu/nanoclaw-v2
# ... EnvironmentFile がない！

EnvironmentFile を追加:

sed -i '/Environment=HOME/i EnvironmentFile=/home/tclc_kaihatsu/nanoclaw-v2/.env' \
  ~/.config/systemd/user/nanoclaw-v2-*.service

確認:

grep "EnvironmentFile\|Environment" ~/.config/systemd/user/nanoclaw-v2-*.service
# EnvironmentFile=/home/tclc_kaihatsu/nanoclaw-v2/.env
# Environment=HOME=/home/tclc_kaihatsu
# Environment=PATH=...

1. daemon-reload して再起動

systemctl --user daemon-reload && systemctl --user restart nanoclaw-v2-*.service

動作確認
再起動後にチャンネルへメッセージを送るとコンテナが起動します。
ホスト側で確認 — --gpus all が付いているか:

ps aux | grep "docker run" | grep nanoclaw | grep -o "\-\-gpus[^ ]*"
# --gpus
# all

コンテナ内（エージェントに依頼）で確認 — nvidia-smi を実行してもらう:

+-----------------------------------------------------------------------------------------+
| NVIDIA-SMI 580.167.08             Driver Version: 580.167.08     CUDA Version: 13.0     |
+-----------------------------------------------------------------------------------------+
|   0  NVIDIA L4                      Off |   00000000:00:03.0 Off |                    0 |
|       0MiB /  23034MiB |      4%      Default                                          |
+-----------------------------------------------------------------------------------------+

GPU が見えていれば成功です。
注意事項
dist/ を直接編集しているため、NanoClaw を pnpm build で再ビルドすると変更が上書きされます。アップデート後は手順 1〜2 を再実行してください。
より恒久的に管理したい場合は src/config.ts と src/container-runner.ts を修正してビルドする方法が望ましいです。
ホストに nvidia-container-toolkit がインストールされていることが前提です。未インストールの場合は先に設定してください。

# nvidia-container-toolkit のインストール（未インストールの場合）
curl -fsSL https://nvidia.github.io/libnvidia-container/gpgkey | sudo gpg --dearmor -o /usr/share/keyrings/nvidia-container-toolkit-keyring.gpg
curl -s -L https://nvidia.github.io/libnvidia-container/stable/deb/nvidia-container-toolkit.list | \
  sed 's#deb https://#deb [signed-by=/usr/share/keyrings/nvidia-container-toolkit-keyring.gpg] https://#g' | \
  sudo tee /etc/apt/sources.list.d/nvidia-container-toolkit.list
sudo apt-get update && sudo apt-get install -y nvidia-container-toolkit
sudo nvidia-ctk runtime configure --runtime=docker
sudo systemctl restart docker

まとめ
変更点は以下の 4 箇所だけです:
ファイル 変更内容
dist/config.js CONTAINER_GPU 環境変数の export を追加
dist/container-runner.js import と --gpus フラグ追加
.env CONTAINER_GPU=all を追加
~/.config/systemd/user/*.service EnvironmentFile ディレクティブを追加
これにより、NanoClaw のエージェントコンテナから GPU を使った処理（CUDA、推論、画像生成など）が可能になります。