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

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

ローカルアカウントのサインインや招待が失敗する

• 管理対象のローカルアカウントは DEFAULT_USER / DEFAULT_PASSWORD のデモログインとは別です。スーパー管理者に専用ワークスペースと最初の管理者の招待を依頼し、以後のユーザー管理とリセットはその管理者が行います。環境変数やメールサービスでこの機能を有効にするわけではありません。
• ユーザー名またはメールを入力し、選択画面では目的のワークスペースやロールを選んでください。ローカルアカウントでは OIDC ワークスペースにサインインできません。共通の資格情報エラーは、パスワード違い、存在しないアカウント、招待未完了、無効化、削除のいずれでも発生し得ます。存在の判定には使わないでください。
• 招待を受け入れてからサインインします。招待・リセットリンクは 24 時間有効で一度だけ使え、再発行や関連するアカウント変更で無効になります。担当管理者に新しいリンクを依頼してください。Chorus は自動メールを送信しません。パスワード設定後は別途サインインします。パスワードは 8 文字以上、UTF-8 で 72 バイト以下です。
• パスワードリセットやアカウント変更後は、バージョンが古いローカルセッションが拒否される場合があります。無効化・削除や非互換のワークスペース方式も拒否され、現在のアカウント状態が読めない場合もアクセスは許可されません。検証を迂回せずデータベース接続を復旧してください。
• サインイン直後に失効する場合は公開オリジン、Cookie 設定、全レプリカで共有する永続的な NEXTAUTH_SECRET を確認します。HTTPS では COOKIE_SECURE=true を使い、false は信頼できる HTTP 専用の試用に限定します。Default Auth 変数を削除しても管理対象のローカルパスワードログインは無効になりません。

認証設定と運用ガイドを参照してください。診断情報には資格情報リンクの URL、トークン、パスワード、Cookie、署名鍵を含めないでください。

サインインが 429 を返す、またはレプリカ間で制限が異なる

HTTP 429 と RATE_LIMITED は認証制限の超過です。Retry-After の秒数を待ってから再試行してください。連続再試行は復旧手順ではありません。識別子照合は 60 秒あたり 30 回、ローカルパスワードログインと招待・リセットの確定は各 60 秒あたり 10 回です。信頼できるプロキシアドレスを使う場合、同じアドレスのユーザーは操作の制限を共有することがあります。

全レプリカが同じ Redis 設定を使うことを確認します。空でない REDIS_URL が host ベースの TLS 設定より優先されます。REDIS_URL と REDIS_HOST の両方がない場合はプロセス内制限です。Redis 障害時の予備カウンターもプロセス内の制限しか維持しません。auth-throttle と Redis のログで READONLY/OOM を含む接続・コマンドエラーを確認してください。SSE が正常でも独立した認証接続が正常とは限りません。予期しない制限バックエンドエラーは許可側に倒れることがあるため、エッジ制限も維持します。Redis 障害は全ログインを拒否する fail-closed 方針ではありません。

任意のクライアントヘッダーではなく、強制された実際のプロキシチェーンに合わせて AUTH_TRUST_PROXY と AUTH_TRUST_PROXY_HOPS を確認します。信頼できるアドレスが欠落・不正な場合も識別子制限は残ります。エラーを消すために信頼を有効にしたり、プロキシを迂回する直接アクセスを許可したりしないでください。既定値、タイムアウト、復旧の境界は共有認証レート制限を参照してください。収集するのは時刻と機密情報を除いたエラーコードであり、資格情報や生のリクエストヘッダーではありません。

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

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-only の違反（Claude Code、Chorus 0.22.2 以降）。 詳細に --chorus-only is not being enforced by this Claude Code build とあり、まだ使えるツールが列挙されている場合、デーモンは起動時に Chorus の許可リスト外のツールを検出しています。デーモンはプロセスツリーを強制終了してそれ以降を何も転送しなかったため、その Claude Code ビルドでは制限付きの起動を実行できません。デーモンが示す対処は --yolo です。エージェントにツールをすべて使わせるつもりの場合に限り切り替え、そうでなければ --chorus-only のまま別の Claude Code バージョンを試してください。--chorus-only で強制される内容を参照してください。

エラーの詳細に含まれる既知の認証情報は [redacted] に置き換えられます。それ以外のテキストは伏せられないため、共有する前に確認してください。

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

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

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

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

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