CodeNomad/docs/help/ja/troubleshooting.md

トラブルシューティング

まず、失敗した操作の管理元がブラウザー、CodeNomad バックエンド、OpenCode サービス、プロバイダーのどれかを確認して復旧します。応答が失われても、変更操作の失敗は証明できません。繰り返す前に現在の状態を読み直してください。

デスクトップの起動問題

macOS の隔離属性

CodeNomad の macOS 版は Apple の公証を受けていないため、公式リポジトリからダウンロードして検証したコピーでも、初回起動が macOS によってブロックされる場合があります。"CodeNomad" Not Opened（Apple がマルウェアを含まないことを確認できなかった）と表示されるか、アプリが壊れていると表示されることがあります。

1. ダウンロード元と、インストール済みアプリのパスを確認します。
2. 次のパスにインストールされている場合は、隔離属性を削除します。

xattr -dr com.apple.quarantine /Applications/CodeNomad.app

3. 再度起動します。Not Opened のメッセージの場合は、起動がブロックされた後に System Settings → Privacy & Security で CodeNomad の Open Anyway を選び、管理者パスワードで確定する方法もあります。

これは、そのアプリの macOS 隔離属性を変更します。破損したダウンロードの修復や、未知のバイナリを信頼できるものにする操作ではありません。

Linux のグラフィックスと FUSE

Wayland/NVIDIA で Tauri AppImage が即座に終了する場合、WebKitGTK の DMA-BUF/GBM レンダラーの影響が考えられます。ダウンロードした AppImage を、対象を限定した環境上書きで実行します。

WEBKIT_DISABLE_DMABUF_RENDERER=1 ./CodeNomad-Tauri-linux-x64-<version>.AppImage

Electron は Chromium を使用するため、同じホストでの代替になります。FUSE がなく AppImage をマウントできない場合は、--appimage-extract-and-run を使います。Linux のインストールを参照してください。これらの対処に Electron のサンドボックス無効化は不要です。

Git とワークスペースの利用可否

1. エージェントのシェル内だけでなく、バックエンドアカウントの PATH に Git があるか確認します。
2. なければ、そのホスト／アカウントに Git をインストールし、更新された環境を継承するよう CodeNomad バックエンドを再起動します。
3. ワークスペースを開き直す／更新し、リポジトリの状態を確認します。

Git がなくてもディレクトリ専用の会話は使えますが、ワークツリーと Git 操作は使えません。Windows では、WSL 内だけにインストールした Git は Windows バックエンドに十分ではありません。既知のリポジトリでないフォルダーには Git を初期化 が表示される場合がありますが、Git 実行ファイルの欠落は別問題で、先に解決する必要があります。要件とファイルを参照してください。

所有するワークツリーや会話の配置を確認できない場合は、任意のパスを試したりネイティブストレージを編集したりせず、その物理フォルダーを明示的に開きます。不確かな移動／削除後は、更新して実際の配置を確認してください。ワークツリーの強制削除は未コミットファイルを破壊する場合があるため、接続修復に使わないでください。

OpenCode ランタイムと WSL

1. 設定 → OpenCode を開き、OpenCode バージョン カード（インストール済みバージョンと稼働中サービスの状態）、続いて OpenCode バイナリ で選択した実行ファイルを確認します。
2. 必要なランタイムがなければ、サポートされるインストール／更新操作を使用します。現在の最低要件は 2.2.3、推奨／検証済みバージョンは 2.2.5 です。
3. インストール済み CLI と稼働中サービスが異なる場合は、共有サービスを再起動するか明示的に判断します。

OpenCode サービスを再起動 は トラブルシューティング にあり、確認が必要です。接続中の全クライアントの作業を中断しますが、セッション履歴は保持します。設定の再読み込みは別操作であり、プロセスを保ちつつ、読み込み済み Location を再構築し、保留中の質問／権限をキャンセルします。どちらも無害な更新ではありません。

WSL 実行ファイルでは、目的のディストリビューションと Windows の localhost 転送を確認します。サービスのライフサイクルは Linux 内で動きますが、CodeNomad は Windows からそのループバックエンドポイントに到達できる必要があります。サービス登録／データベースを編集したり、推測した Linux プロセス ID に Windows からシグナルを送ったりしないでください。

カスタム／新しいバージョンは、非互換でなくても未検証の場合があります。バージョン変更前に、実際の契約エラーを読んでください。セッション環境の同期に失敗したら、実行ホストの環境／接続を修正します。同期なしでは CodeNomad はプロンプトを送りません。OpenCodeを参照してください。

ログイン、TLS、直接接続

症状	安全な確認と復旧
CodeNomad に再ログイン	ページを開いたまま、サーバーのユーザー名／パスワードを入力して ログイン を選びます。復旧はその場で再接続して下書きを保ち、失敗した操作は再実行しません。
サーバーに到達できない	バックエンドの稼働を確認し、表示されたアドレス／実際のポートを使用します。到達不能チェックだけではログインの期限切れは証明できません。
プロバイダーが認証を拒否	管理元でプロバイダーログインを修復します。プロバイダー OAuth の修復に CodeNomad サーバーパスワードを変えないでください。
証明書の名前／信頼エラー	実際のホスト名／IP と SAN を比較し、意図した CA の信頼または有効なサーバー証明書を設定します。TLS 検証は無効にしないでください。
直接接続が拒否される	実効の HTTP/HTTPS バインド、ファイアウォール、経路を確認します。デスクトップ／両リスナーモードの HTTP はループバックに留まり、スタンドアロン HTTP 専用では異なるバインド動作になります。

認証復旧後は、応答が不確かだった変更操作を手動再試行する前に状態を確認します。実行時パスワードは毎回のバックエンド起動で指定が必要ですが、設定画面で保存したパスワードは永続化されます。セキュリティ、TLS／バインド規則、サーバーリファレンスを参照してください。

リモートコントロールのペアリング

1. ホストで 設定 → リモートアクセス を開き、リモートコントロールの稼働を確認します。
2. 新しいペアリングリンクを作り、有効期限前に目的の端末で開きます。
3. クライアントに このデバイスを再ペアリング が表示されたら、ホストからペアリングし、クライアントで 接続を確認 を選びます。

ペアリングリンクは短期間有効の使い捨てであり、直接アクセスのパスワードは代わりになりません。取り消し済みや未使用による期限切れの端末認証情報には、再ペアリングが必要です。最後のデスクトップウィンドウを閉じるとバックエンドとリモートコントロールが停止し、有効なサービスは次回アプリ起動時に再開します。利用できないホスト専用画面と取り消しは、リモートコントロールを参照してください。

プロバイダー、プラグイン、拡張機能の状態

問題	復旧
プロバイダーのアカウント／割り当て量が違う	選択したネイティブアカウントと 使用量 を確認します。割り当て量表示はトークン／費用の合計ではありません。不確かなアカウント変更後は更新してください。選択は他のサービスクライアントにも影響する場合があります。
外部管理 OAuth の期限切れ	OpenCode、Claude Code、該当する認証管理元で再ログインします。CodeNomad はそれらの更新トークンを交換しません。
自動ローテーションが切り替えない	有効化の対象条件と、現在のアカウントが実際に上限に達しているか確認します。受け付け前のポリシーであり、実行途中のフェイルオーバーやプロンプトの再実行ではありません。
プラグイン状態が古く見える	プラグインコントロールを更新 を使い、ツールチップの範囲／対象を確認します。ランタイムの有効化はネイティブの更新待ちの場合があります。不確かな書き込みを何度も切り替えないでください。
追加したプラグインが失敗した、または 未確認 と表示される	OpenCode ホストからのパッケージ名、バージョン、レジストリへのアクセスを確認します。インストールに失敗した場合は、プラグインのツールチップにあるエラー参照で OpenCode のログを検索します。未確認 は無効になったプラグインにも表示されます。プラグインを削除しても、ダウンロードしたパッケージは OpenCode のキャッシュに残ります。
ミッションコントロールを利用できません	示された原因に従います。OpenCode がミッションプラグインを読み込んでいない場合は更新し、解決しなければ OpenCode の設定を再読み込み を使用します。プラグインの読み込みに失敗した場合は、プラグイン一覧でエラーを確認します。サーバーがミッション用のローカル接続を開けなかった場合は、サーバーログを確認します。OpenCode を再読み込みしても解決しないためです。ミッションはスタンドアロンサーバーでも動作します。
インストール済み拡張機能がない	パネルのカスタマイズにある唯一の有効化チェックボックスを確認します。インストール／置き換え後は、明示的に有効化して必要な同意を承認するまで無効です。
拡張機能の資産アクセスが拒否される	現在マウント中のセッションに対する API 2 の資産読み取りの同意を確認します。拡張機能のインストールは、任意のファイル／履歴を読む許可ではありません。

プロバイダー、連携、拡張機能を参照してください。

履歴、保留リクエスト、クリーンアップ

全履歴検索は、会話欄に現在読み込まれた行だけに限定されません。表示フィルターは内容を削除せず隠すものです。検索、コンパクト化、技術クリーンアップ、削除の違いは、履歴を参照してください。

保留リクエストの復旧が不完全な場合、CodeNomad は不足した確認範囲を空のキューとみなさず、既知のキューと回答下書きを保持します。不完全な復旧が 2 回連続すると、プロジェクト、原因、フォルダー、影響を受けるセッションを示して 1 回警告します。この警告は通知カテゴリー プロジェクトとタブ に属します（既定では画面と履歴に表示。設定 → 通知 を参照）。一時的な失敗は生存確認で再試行します。コンパクト化に伴う延期は、リクエストのキャンセルを意味しません。下書きを残し、サービス接続を確認し、再回答前にリクエストの現在の状態を確認してください。

キャンセル済み／部分的なクリーンアップでは、別の削除を始める前に進捗／記録を読みます。キャンセルしても送出済みのバッチは元に戻りません。ネイティブデータベースを編集して履歴を修復しないでください。ミッションの結果が不確かな場合は、新たな実行の作成や作業の自動再実行ではなく、状態を確認／更新による復旧を使います。再起動と寿命の制限は、ミッションで説明しています。

ログと安全な診断

1. インスタンス情報 で状態を確認します。サーバーログを表示 で利用可能な出力を開けます。
2. 設定 → OpenCode で、詳しい情報が必要な場合にのみ、目的の ログ出力の詳細度 を選びます。スタンドアロン CodeNomad のログには、サーバー CLI のログオプションを使用します。
3. 設定 → 情報 → 診断 を開き、バグを報告、クリップボードにコピー、.txt をダウンロード を使用します。

詳しいログは、パス、出力、アプリケーションデータを公開する場合があります。ログ／キャプチャの共有前に、認証情報、ペアリングリンク、ネットワークアドレス、私的なパス、会話内容を伏せてください。完全な診断レポートにはパス／アドレスが含まれますが、事前入力する不具合フォームでは意図的に除外しています。不具合を報告するを参照してください。