トラブルシューティング

遭遇する可能性が高い順の一般的な失敗モード。

まず最初に確認すべき箇所：

zeroclaw doctor

一連のチェックを実行し、要約を表示します。以下に示される詳細は、doctor コマンドがフラグとして出力する内容の詳細版です。

インストール時

cargoが見つかりません

curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh

Rustを完全にスキップするには、install.sh / setup.bat に --prebuilt を渡してください。

ビルド依存関係が不足しています (Linux)

ディストロのベースラインツールチェーンをインストールし、./install.sh を再実行してください：

sudo apt install build-essential pkg-config

sudo dnf group install development-tools && sudo dnf install pkg-config

sudo pacman -S base-devel

ディストロ別の完全なリスト: セットアップ → Linux。

低RAMホストでOOMをビルドする

ZeroClaw をソースからビルドする際は、特に最終リンク時に大量のメモリを消費します。install.sh は、ソースからビルドする際にこれを自動的に調整します:

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

まだメモリ不足になる場合、または install.sh を使ってビルドしていない場合：

1. ビルド済みを使用: ./install.sh --prebuilt はツールチェーンをスキップし、GitHub Releases からダウンロードします。
2. より大きなマシンでクロスコンパイルし、バイナリをコピーします。
3. より軽量なビルドプロファイルを選択する: cargo build --profile release-fast（コード生成の並列性が高く、リンクが軽量）または --profile ci（thin LTO、最速・最小メモリ）。
4. ビルドを直列化する: CARGO_BUILD_JOBS=1 cargo build --release --locked。
5. スワップを追加 (RAM の代わりになり、ディスクを消費します。両方に余裕があることを確認してください)。

Raspberry Pi 固有の内容については、Raspberry Pi setup → buildを参照してください。

ビルドが非常に遅い

Matrix E2EE スタック（matrix-sdk、ruma、vodozemac）および TLS/crypto ネイティブ依存関係（aws-lc-sys、ring）が主なコストです。これらが必要ない場合はオプトアウトしてください：

cargo build --release --locked --no-default-features --features デフォルトの軽量

または、何が起きているかを確認してください：

cargo check --timings
# report at target/cargo-timings/cargo-timing.html

インストール後、zeroclaw: コマンドが見つかりません

cargo install はバイナリを ~/.cargo/bin/ に配置します。PATH に追加してください：

export PATH="$HOME/.cargo/bin:$PATH"

シェルプロファイルに永続化してください。

クイックスタート

既存の設定はクイックスタートでは上書きされません

zeroclaw quickstart には --force フラグがなく、既存のインストールを意図的にそのまま残します。古いインストールに対して新規のクイックスタートを実行するには、ディレクトリを削除してやり直してください。

rm -rf ~/.zeroclaw
zeroclaw quickstart

または、すべてを消去する代わりに古いフィールドを 1 つだけ編集するには、zeroclaw config set <key> <value> を直接使用します。

Homebrew インストール: 設定パスの不一致

Homebrew でのインストールでは $HOMEBREW_PREFIX/var/zeroclaw/（これにより brew services が動作します）が推奨されますが、デフォルトの設定ディレクトリは ~/.zeroclaw/ です。2 つのパスを揃えるために、quickstart を実行する前に ZEROCLAW_WORKSPACE に Homebrew のパスを設定してください:

export ZEROCLAW_WORKSPACE="$HOMEBREW_PREFIX/var/zeroclaw"
zeroclaw quickstart

または、手動でシンボリックリンクを一度作成します:

ln -s "$HOMEBREW_PREFIX/var/zeroclaw" ~/.zeroclaw

ランタイム

OpenAI Codex のサブスクリプション認証で、config またはストリーミングに関する警告が表示される

症状:

• エージェントの model_provider = "openai.<alias>" が Codex エントリを指しているのに、実行時の設定が誤っているように感じられる
• 設定の読み込み時に、api_key / api_url のような不明なトップレベルフィールドについて警告します（これらはファイルのルートではなく、プロバイダーエントリに記述する必要があります）
• Agent が provider streaming failed, falling back to non-streaming chat をログに記録します

チェック（<alias> は [agents.<alias>] で設定されたエージェントのエイリアスに置き換えてください）：

OpenAI Codex のサブスクリプションを使用する場合は、プロバイダーエイリアスで requires_openai_auth = true を設定し、api_key は未設定のままにします。ランタイムは保存された Codex ログインを使用します。サブスクリプションの認証情報はベンダー独自のログインフローから取得してください。認証情報モデルの詳細については、Provider Configuration → OAuth and subscription auth を参照してください。その後、テストします:

zeroclaw agent -a <alias> -m "hello"

注:

• エイリアスで requires_openai_auth = true（かつ api_key を未設定）にすると、サブスクリプションパスが選択されます。これを最小限の動作例の正規エージェント + リスクプロファイルで囲んでください。
• エイリアスエントリの api_key / uri は、カスタムの OpenAI 互換ゲートウェイやその他の明示的なエンドポイントの上書きにのみ必要です。
• streaming-disabled の警告自体は認証エラーではありません。ZeroClaw は非ストリーミングモードでリクエストを再試行します。

デーモンが起動し、すぐに終了します

実際のエラーを確認するには、journald またはプラットフォームのログ（ログと観測性 を参照）を確認してください。一般的な原因:

• 無効な設定: 解決された値を表示するには zeroclaw config list、想定される形式を確認するには zeroclaw config schema を実行してください
• ポート競合: 別のプロセスが 42617 を使用しています。[gateway] port を変更するか、ポートを解放してください
• シークレットの欠落: キーファイルが失われているため、暗号化されたシークレットストアを復号できません。バックアップから復元するか、オンボーディングを再実行してください

デーモンが再起動を繰り返す

systemctl --user status zeroclaw は最後の終了コードを表示します。設定ファイルにエラーがある場合、サービスは再起動を停止し（終了コード 2）、設定ファイルを修正する必要があります。パニックが発生した場合は、ユニットは 10 秒ごとに再試行します。

デバッグログを有効にして、次の障害をキャッチします：

zeroclaw service stop
RUST_LOG=デバッグ zeroclaw daemon

ゲートウェイに到達できない

curl -sv http://localhost:42617/health

接続が拒否された場合：デーモンが実行されていないか、異なるインターフェースにバインドされています。設定ファイルの [gateway] host / port を確認してください。

403 / 401 の場合: ペアリングが完了していないか、トークンが期限切れです。ペアリングフローを再度実行してください。

チャンネル

Telegram: 他の getUpdates リクエストによって終了

2つのプロセスが同じボットトークンをポーリングしています。Telegramでは、一度に1つのポーラーしか許可されていません。

修正: そのトークンを使用している zeroclaw daemon / zeroclaw channel start を1つ以外すべて停止する。

Discord / Slack の認証失敗

Discordのトークンは、Developer Portalで再生成すると期限切れになります。Slackのボットトークンは期限切れにはなりませんが、取り消すことができます。ターゲットのワークスペース/ギルドにボットがまだインストールされていることを確認してください。

どちらかの場合:

zeroclaw channel doctor

SOP fan-in は channel doctor の対象ではありません

zeroclaw channel doctor は、デーモンの稼働中の SOP エンジンと監査ハンドルなしでトランスポートアダプターを構築します。通常のチャネルトランスポートは確認できますが、MQTT、ファイルシステム、または AMQP の SOP ディスパッチで実行を開始できることは証明しません。これらのソースについては、SOP ランタイムを有効にして zeroclaw daemon を起動し（sop.sops_dir に空でない値を設定します。デフォルトでは未設定で、これにより無効になります。ドキュメントに記載されている値は shared/sops です）、その後、ソース接続と SOP ingress ログイベントを調べます。dispatch = "sop" または "sop_and_agent_loop" を使用する AMQP チャネルは、SOP ハンドルを利用できない場合、デーモンの起動時にフェイルクローズします。その状態では、意図的に doctor の作業リストから除外されます。

Matrix: 「不明なデバイス」

デバイスキーを保持せずに再オンボーディングした場合、ホームサーバーは未検証の新しいデバイスとして認識されます。ログイン済みの別のクライアントから再検証するか、キーストアをリセットしてください。

rm -rf ~/.zeroclaw/workspace/matrix-crypto
# 次のチャンネル開始時にペアリングフローを再実行

IMAP ポーリングが停止しました

多くの場合は認証エラーで、プロバイダーがパスワードをローテーションしたか、アプリパスワードの有効期限が切れています。以下を確認してください:

journalctl --user -u zeroclaw -n 200 | grep -i imap

プロバイダー

「Ollama への接続がタイムアウトしました」

• Ollama デーモンが実行されていません: systemctl status ollama (Linux)、brew services list (macOS)
• 設定のURLが間違っています。コンテナ内からは localhost:11434 ではホストに到達できません。host.docker.internal またはホストのLAN IPを使用してください
• ファイアウォールがポート11434をブロックしています。ローカルでは稀ですが、共有LANではよく発生します

Anthropic / OpenAI 401

APIキーが無効または期限切れです。プロバイダーのダッシュボードで再生成し、[providers.models.<name>] api_key に更新して、サービスを再起動してください。

OAuth（sk-ant-oat*）を使用している場合、OAuthトークンの有効期限が切れている可能性があります。OAuthで発行されたトークンは長期間有効ですが、無期限ではありません。再認証してください。

ツール

ポリシーによってシェルコマンドがブロックされました

未知のコマンドに対する Supervised 自律モードでの期待される動作。いずれか：

• プロンプトが表示されたら、インラインで承認してください。
• コマンドを [autonomy] allowed_commands に追加する
• コンテキストを信頼できる場合は、自律性を Full に引き上げます。

セキュリティ → 自律レベル を参照してください。

Dockerサンドボックス内でツール呼び出しが失敗する

• コンテナイメージが取得されていません。[security.sandbox].image で設定しているイメージ（デフォルト: alpine:latest）に対して docker pull <image> を実行してください
• ZeroClaw ユーザーから Docker デーモンに到達できません。docker info を確認してください
• ツールにはパススルーされていないデバイスが必要です。allow_devices を拡張してください

ブラウザツールが最初の使用時にハングする

Playwright は初回起動時に Chromium（約150MB）をダウンロードします。ダウンロードが完了するまでお待ちください。もし処理が止まったままになる場合は、ディスク容量とプロキシ設定を確認してください。

サービスモード

サービスはインストールされていますが、非アクティブ状態です

zeroclaw service start
zeroclaw service status

zeroclaw service logs を使用して、インストールされたサービスログを追跡します。--follow を追加すると新しいエントリをストリーミングでき、--lines <count> で表示する履歴の量を変更できます。ラッパーが利用できない場合や、プラットフォームを直接調査する必要がある場合は、次を使用します。

• Linux: journalctl --user -u zeroclaw.service -f
• macOS: log stream --predicate 'process == "zeroclaw"'
• ターミナルで zeroclaw daemon を直接実行している場合は、サービスログコマンドの代わりにそのフォアグラウンド出力を使用してください。

対話的には成功するのにバックグラウンドでサービスが停止する場合、ほとんどの場合は設定または権限の問題です。ジャーナルを確認してください:

journalctl --user -u zeroclaw --since 5分前

サービスが設定ファイルを見つけられません

サービスとCLIは、異なるユーザーとして実行される場合や、異なる環境変数で実行される場合に、設定ファイルを異なる方法で解決する可能性があります。デーモンが認識するパスを強制的に出力します：

zeroclaw config list

zeroclaw config list（あなたとして）とサービス（そのユーザーとして）でパスが異なる場合、次のいずれかを行ってください：

• サービスユニットの Environment= に ZEROCLAW_CONFIG_DIR を設定する
• サービスを実行します（ lingering-enabled ユーザーサービスとして）
• 設定ファイルをサービスが期待するパスにコピーまたはシンボリックリンクしてください。

まだお困りですか？

診断情報を収集し、問題を報告してください：

zeroclaw --version
zeroclaw doctor
zeroclaw channel doctor
journalctl --user -u zeroclaw --since 1時間前 > zeroclaw-log.txt

zeroclaw-log.txt をサニタイズして（万が一チャンネルトークンが紛れ込んでいたら編集して伏せてください。本来含まれることはありませんが）、issue に添付してください。添付先については Contributing → Communication を参照してください。

関連項目も参照してください

• ログと観測性
• サービスとデーモン
• セットアップ → サービス管理
• 参照 → 設定