エージェント接続のトラブルシューティング

まず Chorus に表示されている症状から確認します。診断中はできるだけデーモンをフォアグラウンドで実行してください。起動時のエラーを見つけやすくなります。

エージェントがオンラインにならない

chorus agents を実行し、エージェントがこのマシンに設定されていることを確認します（各エージェントの名前、UUID、バックエンドが一覧され、API キーは決して出力されません）。
意図した作業ディレクトリで chorus daemon を実行します。
選んだバックエンドの CLI がインストールされ、PATH で利用できることを確認します。
認証情報が欠けているか誤っている場合は、正しい Chorus の URL とエージェントの API キーを指定して chorus agents add（または chorus login）を実行します。
設定 → エージェント（Settings → Agents）を開き、新しいオンライン（Online）のハートビートを確認します。

HTTP 401 は通常、キーが無効か失効していることを意味します。HTTP 403 は、認証情報は有効だが、要求された操作の権限がないことを意味します。広範な管理者アクセスを付与するのではなく、認証情報または必要な権限を修正してください。

サービスが停止する、または再起動を繰り返す

次を実行します。

chorus daemon status
chorus daemon logs
chorus daemon restart

エージェントの CLI がサービスの PATH にない場合は、インストールを修正し、意図したバックエンドと作業ディレクトリを指定して chorus daemon install をもう一度実行します。Linux では、Chorus が生成したサービスを使い、デタッチの -d モードと組み合わせないでください。

Chorus が誤った作業ディレクトリを表示する

デーモンを停止し、意図したパスで起動し直します。

chorus daemon --cwd /path/to/your/project --chorus-only

複数のプロジェクトでは --cwd を繰り返します。インストール済みのサービスを変更した場合は、必要なディレクトリをすべて指定して再インストールします。そのうえで、期待するすべてのパスが設定 → エージェント（Settings → Agents）の接続の下に表示されることを確認します。

リモートで作業を開始しても何も起きない

次を確認します。

選んだ接続がまだオンライン（Online）であること。
プロジェクトや課題が、別のオフライン接続に固定されていないこと。
作業ディレクトリがデーモンに登録されていること。
エージェントがその項目を読み、要求されたアクションを実行する権限を持っていること。

固定された接続を復旧させるか、新しいターゲットを明示的に選びます。見つからないターゲットを表示させるためだけに、ファイルシステムへのアクセス範囲を広げないでください。

中断または再開が失敗する

会話を開き、要求した中断または再開を実行できる状態にあるかを確認します。そのセッションを所有するデーモンがオンラインでなければなりません。再開は常に元の接続と作業ディレクトリに戻ります。

プロセスがクラッシュした場合は、再開する前に途中までのファイルシステムの変更を確認します。復旧の全手順はセッションを中断して再開するをご覧ください。

返信の前にターンが失敗する

会話の失敗したターンでエージェントの起動・実行に失敗の要約を読み、可能ならエラーの詳細を表示を選びます。返信がなくても診断は記録される場合があります。再試行前に失敗したターンの診断を確認してください。

Linux デーモンが SSH のログアウトや再起動後にオフラインになる場合は、chorus daemon status と lingering 設定を確認します。設定後も Codex が旧認証情報を使う場合は、chorus daemon restart だけでなく App Server の安全な再起動に従います。

役に立つ診断情報を集める

制限付きのフォアグラウンドモードで、問題を一度再現します。

chorus daemon --verbose --chorus-only --cwd /path/to/your/project

失敗したステップ、時刻、バックエンド、ステータスメッセージ、関連するログ行を記録します。API キーは決して共有しないでください。プライベートな URL、ユーザー名、リポジトリのパス、および問題に無関係なプロンプトやコマンドの出力は削除してください。