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

Chorus で見える症状から始めます。可能な限り診断中はデーモンをフォアグラウンドで実行してください。起動時のエラーがそこでは見つけやすいためです。

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

1. chorus agents を実行し、エージェントがこのマシンに設定されていることを確認します（各エージェントの名前、UUID、バックエンドが一覧され、API キーは決して出力されません）。
2. 意図した作業ディレクトリで chorus daemon を実行します。
3. 選んだバックエンドの CLI がインストールされ、PATH で利用できることを確認します。
4. 認証情報が欠けているか誤っている場合は、正しい Chorus の URL とエージェントの API キーを指定して chorus agents add（または chorus login）を実行します。
5. 設定 → エージェント（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）であること。
• プロジェクトや課題が、別のオフライン接続にピン留めされていないこと。
• 作業ディレクトリがデーモンに登録されていること。
• エージェントがその項目を読み、要求されたアクションを実行する権限を持っていること。

ピン留めされた接続を復旧させるか、新しいターゲットを明示的に選びます。欠けているターゲットを現れさせるためだけに、ファイルシステムのアクセスを広げないでください。

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

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

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

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

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

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

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