トラブルシューティング

このページでは、NemoClawのインストール、オンボード、実行時によく発生する問題とその解決方法を扱います。

ヒント： 問題がここに記載されていない場合は、NemoClaw Discordチャンネルでコミュニティに質問してください。GitHubでissueを作成することもできます。

インストール

インストール後に`nemoclaw`が見つからない

nvmやfnmでNode.jsを管理している場合、インストーラーが現在のシェルのPATHを更新しないことがあります。 nemoclawバイナリはインストール済みですが、シェルが場所を知りません。

source ~/.bashrc（zshの場合はsource ~/.zshrc）を実行するか、新しいターミナルウィンドウを開いてください。

サポートされていないプラットフォームでインストーラーが失敗

インストーラーは処理前にOSとアーキテクチャをチェックします。 NemoClawにはLinux Ubuntu 22.04 LTS以降が必要です。サポートされていないプラットフォームエラーが表示された場合は、対応するLinuxディストリビューション上で実行しているか確認してください。

Node.jsのバージョンが古い

NemoClawにはNode.js 20以降が必要です。 Node.jsバージョンエラーでインストーラーが終了した場合、現在のバージョンを確認してください：

$ node --version

バージョンが20未満の場合は、対応バージョンをインストールしてください。 nvmを使用している場合：

$ nvm install 20
$ nvm use 20

その後、インストーラーを再実行してください。

Dockerが起動していない

インストーラーとオンボードウィザードにはDockerの起動が必要です。 Docker接続エラーが表示された場合は、Dockerデーモンを起動します：

$ sudo systemctl start docker

macOSでDocker Desktopを使用している場合は、Docker Desktopアプリケーションを開き、起動完了を待ってからリトライしてください。

npm installで権限エラー

npm installがEACCES権限エラーで失敗した場合、sudoでnpmを実行しないでください。代わりに、自分が所有するディレクトリを使うようnpmを設定します：

$ mkdir -p ~/.npm-global
$ npm config set prefix ~/.npm-global
$ export PATH=~/.npm-global/bin:$PATH

export行を~/.bashrcか~/.zshrcに追加して永続化し、インストーラーを再実行してください。

ポートが使用中

NemoClaw gatewayはデフォルトでポート18789を使用します。別のプロセスがこのポートを占有している場合、オンボードが失敗します。競合プロセスを特定し、安全に停止できることを確認してから終了させてください：

$ lsof -i :18789
$ kill <PID>

プロセスが終了しない場合はkill -9 <PID>で強制終了してから、オンボードをリトライしてください。

オンボード

オンボード時のcgroup v2エラー

Ubuntu 24.04、DGX Spark、WSL2では、Dockerがcgroup v2 delegation用に設定されていない場合があります。オンボードのプリフライトチェックがこれを検出し、明確なエラーメッセージを出力します。

Sparkセットアップスクリプトを実行してDockerのcgroup設定を修正し、オンボードをリトライしてください：

$ sudo nemoclaw setup-spark
$ nemoclaw onboard

サンドボックス名が無効

サンドボックス名はRFC 1123サブドメインルールに従う必要があります：小文字英数字とハイフンのみ、英数字で始まり英数字で終わること。大文字は自動的に小文字に変換されます。

名前がルールに合わない場合、ウィザードがエラーで終了します。 my-assistantやdev1のような名前を選んでください。

DGXでサンドボックス作成が失敗

DGXマシンでは、gatewayのDNSがまだ伝播していない場合や、前回のオンボードで残ったポートフォワードがまだアクティブな場合、サンドボックス作成が失敗することがあります。

nemoclaw onboardを実行してリトライしてください。ウィザードが古いポートフォワードを自動的にクリーンアップし、gatewayの準備完了を待ちます。

Colimaソケットが検出されない（macOS）

新しいバージョンのColimaはXDGベースディレクトリ（~/.config/colima/default/docker.sock）を使用し、レガシーパス（~/.colima/default/docker.sock）は使いません。 NemoClawは両方のパスをチェックします。どちらも見つからない場合は、Colimaが起動しているか確認してください：

$ colima status

ランタイム

サンドボックスが停止と表示される

サンドボックスが停止または削除された可能性があります。 nemoclaw onboardを実行し、同じブループリントとポリシー定義からサンドボックスを再作成してください。

サンドボックス内でstatusが「not running」と表示される

これは想定された動作です。アクティブなサンドボックス内でopenclaw nemoclaw statusを実行すると、ホスト側のサンドボックス状態と推論設定は参照できません。 statusコマンドはサンドボックスコンテキストを検出し、代わりに「active (inside sandbox)」と報告します。

ホスト上でopenshell sandbox listを実行して確認してください。

推論リクエストがタイムアウト

推論プロバイダーのエンドポイントがホストから到達可能か確認してください。アクティブなプロバイダーとエンドポイントを確認：

$ openclaw nemoclaw status

エンドポイントが正しいのにリクエストが失敗する場合は、ネットワークポリシールールが接続をブロックしていないか確認し、NVIDIA API keyが有効か検証してください。

エージェントが外部ホストに接続できない

OpenShellはネットワークポリシーに未記載のホストへのアウトバウンド接続をブロックします。 TUIを開いてブロックされたリクエストを確認し、承認してください：

$ openshell term

エンドポイントを恒久的に許可するには、ネットワークポリシーに追加してください。詳細はネットワークポリシーのカスタマイズを参照。

ブループリント実行が失敗

失敗したブループリント実行のエラー出力を確認します：

$ openclaw nemoclaw logs --run-id <id>

実行IDが不明な場合は--run-idを省略すると最新の実行ログが表示されます。デバッグ時は--followでリアルタイムにログをストリームできます。