トラブルシューティング
何かおかしいと感じたら、3 つのコマンドでほぼすべてを診断できます。順番に実行して ください。
| # | コマンド | わかること |
|---|---|---|
| 1 | waired doctor |
ゲートウェイトークン、一時停止状態、エンジンの準備状況、メッシュピア、コーディングエージェント統合について ✓/⚠/✗ を表示。ターミナルでは f を押すと修復可能なものを修復します（非対話的に修復するには --fix）。 |
| 2 | waired status --observability |
ライブスナップショット: エンジン、共有、一時停止、メッシュ（enrolled / reachable / ready）、および直近の推論の判断 + レイテンシ。マシン可読な出力には -o json を追加します。 |
| 3 | waired claude status |
Claude Code のマネージド設定連携が有効かどうか、そして managed-settings.json ファイルの場所。 |
症状 → 最初のコマンド
Section titled “症状 → 最初のコマンド”| 症状 | まず実行 | 何が起きているか |
|---|---|---|
| Claude Code がローカルモデルではなくクラウドを使う | waired doctor → waired claude status |
ゲートウェイトークン / 一時停止 / エンジン / メッシュピアが ✗ を示す場合、サービングは Anthropic へフェイルオープンしています。f を押してトークン + スキルを再構築してください。マネージド設定が未有効なら有効化します（下記参照）。 |
waired infer が 503 waired_paused を返す |
waired resume |
ルーティングが一時停止中です。再開してください。 |
waired infer が 503 waired_inference_disabled を返す |
waired inference share on |
共有がオフになっています。（ローカル専用利用ならオフのままで問題ありません — 自分の waired infer は引き続き動作します。） |
Engine: not ready |
waired runtimes status + waired models ls |
ランタイムがダウンしているか、モデルがまだプル中です。 |
メッシュピアが現れない / reachable=false |
waired status --observability -o json |
エンロール、コントロールプレーン同期、WireGuard の到達性を確認してください。 |
| システムトレイのアイコンが表示されない（Linux） | waired doctor |
GNOME ではトレイに AppIndicator ホスト拡張が必要です。system tray host の行で拡張が無いことがわかります（下記参照）。 |
waired status が「permission denied」と表示する / sudo を求める |
sudo waired status |
サービスインストールではデバイス状態が root 所有です（下記参照）。 |
| コマンドが「waired-agent is not running」と表示する | waired doctor |
ローカルデーモンに到達できません — サービスを再起動してください（さらに深く参照）。 |
よくある対処法
Section titled “よくある対処法”waired status が「permission denied」と表示する — 以前は「Not enrolled」だった
Section titled “waired status が「permission denied」と表示する — 以前は「Not enrolled」だった”サービスインストール(Linux/macOS で通常の sudo waired init を行ったケース)では、
デバイス状態は root だけが読めるシステムディレクトリ(Linux では
/var/lib/waired)に保存されます。一般ユーザーで waired status や
waired auth status を実行してもこれを読めないため、コマンドは対象ディレクトリと
対処(sudo waired status、Windows では管理者プロンプトで再実行)を示す
permission エラーで終了します。
代わりに Not enrolled. Run \waired init` to connect this device.が終了コード 0 で 表示される場合は、そのマシンは本当に未エンロールです —waired init` を実行してください。
Claude Code（または OpenCode）が自分のモデルを使っていない
Section titled “Claude Code（または OpenCode）が自分のモデルを使っていない”waired doctor を実行します。ゲートウェイトークンや統合についてフラグが立った場合は、
f を押す（または waired link all を実行する）と再構築されます。waired claude status
がマネージド設定連携が未有効であることを示している場合は有効化します: sudo waired claude enable
（Linux/macOS）、または管理者権限で waired claude enable（Windows）。
コーディングエージェント を参照してください。
waired claude status は、リクエストが自分のモデルではなく本物の Anthropic API に
送られた際の最後のフォールバックとその理由も表示します:
local_no_model— このデバイスでアクティブなローカルモデルがまだありません。waired statusを確認してモデルを選択/取得してください。local_status_<コード>— フォールバック直前にローカル配信がその HTTP ステータスで エラーになりました。詳細はwaired status --observabilityで確認できます。
Claude Code に waired のステータスラインが表示されない
Section titled “Claude Code に waired のステータスラインが表示されない”プロジェクトディレクトリの中で waired claude status を実行してください。
Claude Code のステータスラインは単一スロットで優先順位が厳格に決まっており、
プロジェクトの .claude/settings.local.json / .claude/settings.json は
Waired が入れるユーザーレベルの設定より優先されます。shadow されている場合、
status の出力が該当ファイル名と、そのステータスラインスクリプトに追記すれば
ルートを表示できる 1 行スニペットを表示します。また waired claude enable の
あとに Claude セッションを再起動したかも確認してください。
エンジンが「not ready」のまま
Section titled “エンジンが「not ready」のまま”サインイン中、waired init はエンジンの起動を段階的に表示します — 「Starting the
inference engine…」「Preparing to download <モデル>…」のあと、ライブの
「Downloading <モデル>: NN% X.X GB / Y.Y GB (Z MB/s)」バー、最後に「<モデル> ready」。
大きなモデルの初回ダウンロードは数 GB あるため、ダウンロード段階に時間がかかるのは
正常で、バーは進み続けます。
代わりに「Waiting for the inference engine to start…」のまま止まり、その後エンジンが
まだ起動していない旨が表示された場合は、ローカルエンジンが起動していません。
waired status で現在の状態を、waired doctor（Linux では
journalctl -u waired-agent -e）で詳細を確認してください。
モデルがまだダウンロード中の可能性もあります — waired models ls で進捗が表示されます。
ランタイム自体がダウンしている場合は、waired runtimes status に詳細が表示されます。
モデルの初回ロードは遅く（コールドな CUDA ロードは約 60 秒かかることがあり、ROCm も
同様です）、エンジンは自動的に再試行して回復します。
統合 GPU でモデルがロードできない
Section titled “統合 GPU でモデルがロードできない”最近の Ollama バージョンは、統合 GPU（AMD Strix Halo / Radeon、Intel iGPU）を
デフォルトで無効にし、静かに CPU へフォールバックします。これらには
OLLAMA_IGPU_ENABLE=1 が必要です。Windows インストーラは既知の iGPU についてこれを
設定します。その他のシステムでは、Ollama サービス向けにこの環境変数を設定して
再起動してください。また、モデルが収まるかどうかも確認してください —
モデルカタログ の RAM/VRAM の列を参照してください。
「このマシンはごく小さなモデルしか動かせません」— 有効化すべき?
Section titled “「このマシンはごく小さなモデルしか動かせません」— 有効化すべき?”RAM の少ないマシンでは、waired init が「ごく小さいモデルしか収まらない」と
表示し、それでもローカル推論を有効にするか確認することがあります（既定は
いいえ）。そのサイズではローカルのコーディング品質が極めて低く、壊れた出力に
なりがちで、通常は動かす価値がありません。断っても Waired は安全な
ゲートウェイ/リレーとして動作します（メッシュ上の能力あるピアへルーティング
可能）。同様に、init 末尾のベンチマークでモデルが遅すぎ、さらに軽い選択肢が
その極小モデルしか無い場合は、ローカル推論を無効化するか尋ねます。いずれの選択も
後から waired runtimes benchmark、あるいはより高性能なハードウェアで
waired init を再実行して見直せます。
システムトレイのアイコンが表示されない（Linux / GNOME）
Section titled “システムトレイのアイコンが表示されない（Linux / GNOME）”GNOME には組み込みのシステムトレイが無いため、waired-tray のアイコンは
AppIndicator ホスト拡張 がインストールされ有効になっているときだけ描画されます。
waired init は GNOME を検出すると拡張を自動でインストール・有効化し、
waired doctor は拡張が無いと system tray host の警告を表示します。手動で設定する
場合:
sudo apt install gnome-shell-extension-appindicatorgnome-extensions enable appindicatorsupport@rgcjonas.gmail.comその後、GNOME が拡張を読み込むよう ログアウトして再ログイン（Wayland では必須） してください。KDE Plasma はトレイホストを内蔵しているため何も不要です。MATE は アイコンをまったく表示できません — GNOME（拡張あり）か KDE で表示してください。
Windows: waired infer が 502 を返す（Ollama がインストールされていない）
Section titled “Windows: waired infer が 502 を返す（Ollama がインストールされていない）”素の Windows ワンライナーは Ollama をバンドルしていません。別途インストールして ください:
iwr -useb https://github.com/gen16k/waired-install/releases/latest/download/ollama-windows.ps1 | iex（install.ps1 に -Control/-Dev を渡すと、Ollama も併せてインストールされます。）
ピアに到達できない
Section titled “ピアに到達できない”waired status --observability -o json を実行し、各ピアの reachable と
last_check を確認してください。次に以下を確認します:
- 両方のデバイスが 同じ Google アカウント でエンロールされていること（同じ
ネットワーク）。各デバイスの
waired statusのaccount/network行を比較して ください。 - WireGuard が接続できること —
waired peers listでピアのエンドポイントが表示 されます。直接 UDP を開けない場合はファイアウォールや NAT を疑ってください。 Waired は自動的にリレーへフォールバックするため、直接の経路が機能しなくても接続性は 保たれるはずです。 - Network Map が最新であること —
waired statusが古いマップを示している場合は、 エージェントを再起動してください。
さらに深く（ログ）
Section titled “さらに深く（ログ）”waired doctor を実行した後でのみ:
- Linux:
journalctl -u waired-agent -e - Windows:
Get-WinEvent -ProviderName waired-agent -LogName Application -MaxEvents 50 - Ollama（同梱エンジン）: モデルロード中に 503 が繰り返される場合は、waired の
state ディレクトリ配下のエンジンログ
…/runtimes/ollama/logs/engine.log（Linux:/var/lib/waired/…、macOS:/Library/Application Support/waired/…）。自前の Ollama を使っている場合（--skip-ollama+ reuse）は~/.ollama/logs/server.log。
Restart-Service waired-agent（Windows）または systemctl restart waired-agent
（Linux）で、一時的な不整合のほとんどは解消します。