トラブルシューティング
まず証拠を保全します。現在のビルド ID、安全なエラーテキスト、影響を受けたセッション／ワークフロー、容量状態、最近のログ、Git ステータスです。永続的な操作がすでに成功したかを把握するまで、クリーンアップ、削除、やみくもな再試行を避けてください。
Web UI が起動しない
チェック: サーバーをフォアグラウンドで実行し、curl -fsS http://127.0.0.1:9889/health を呼び出し、ポートがループバックで待ち受けていることを確認し、可能であれば Settings → About を確認します。
解決: 報告された依存関係／設定エラーまたはポート競合を解消します。ヘルスは動作するが静的ファイルが動作しない場合、候補を検証し、Python コードとパッケージ化された Web アセットが同じビルド由来であることを確認します。
別のマシンのブラウザーが接続できない
ThreadCells が正しくループバックで待ち受けている場合、これは想定どおりです。パブリックバインドに変更してはいけません。リモートアクセスの SSH トンネルまたは認証済みプロキシを使ってください。
プロバイダーで CLI が未インストールと表示される
チェック: Settings → Providers と Spawn Agent を比較し、ThreadCells ランタイムユーザーとして command -v PROVIDER_COMMAND を実行します。
解決: そのアカウント向けにプロバイダーの正規 CLI をインストールするか、サービスの PATH を修正するか、準備済みの別プロバイダーを選びます。アダプターの登録だけではインストールになりません。
プロバイダーはインストール済みだが認証されていない
チェック: ランタイムユーザーとして、プロバイダーがサポートする認証状態コマンドを実行します。
解決: プロバイダー固有のログインフローを完了します。ThreadCells は他ユーザーの認証情報をコピーせず、事前検査中にログインしません。
プロバイダーが readiness unverified と表示する
コマンドは存在しますが、安全な非対話式認証の事実を公開できません。バージョンを確認し、小さなネイティブテストを実行します。起動可能なままの場合があります。プロバイダーのログインプロンプトについて、結果の端末を確認してください。
エージェントが起動しない
チェック: プロバイダーの準備状態、選択したプロファイルの解決済みプレビュー、プロジェクトパス／権限、常駐／Provider／Work 容量、tmux の可用性、端末起動出力を確認します。
解決: 最初に失敗した受け入れまたはプロバイダー前提条件を修正します。最初のセッションがまだ起動中に、重複を繰り返し起動しないでください。
容量不足
Orchestration Capacity を開き、正確にどのカテゴリが満杯かを確認します。安全に完了した作業を退役するか、対応するプロバイダー／重いタスクを待ちます。ホストとクォータに測定済みの余裕がある場合にのみ、その制限を引き上げます。
Heavy 実行スロットを利用できない
ビルド、ブラウザーテスト、スキャン、または復旧ジョブが Heavy スロットを保持しています。待機するか、正規の状態を通じて古いリースを調査します。キューを回避するためだけに、受け入れ外で高負荷コマンドを実行してはいけません。
ワークフローがオーナーを待っている
ゲート理由を読みます。本当の公開、信頼、破壊的操作、コスト、またはプロダクト意味論の境界である場合にのみ、要求された判断を与えます。通常のプロバイダー最終応答は、対象の自律作業をオープンのままにするべきです。自動クローズはワークフローの不具合として報告してください。
結果が取り込まれていない
子が永続的結果を記録し、それが正しい親に配信されたことを確認します。親は不変の結果を読み取り／使用してから、取り込みを確認応答する必要があります。再起動リプレイにより、未確認応答の結果が再度配信されることがあります。同じ内容を二度適用しないでください。
新しいオーナー入力が閉じたワークフローの背後でキューに残る
サポート対象ランタイムを一度再起動し、正確なワークフローと Inbox ID を確認します。現在のビルドでは、バインド先ワークフローがすでにオープンでなくなった保留中の通常 Inbox 転送を照合してから、新しいオープンなオーナーターンの継続を許可します。Inbox 行を再バインドまたは手動編集してはいけません。古い転送が保留のまま、またはペイロードがワークフロー ID をまたぐ場合は、データベースを保持して不具合を報告してください。
オペレーター認可が設定されていない
THREADCELLS_OPERATOR_VERIFIER_FILE が実際のサーバープロセスに届いていることを確認し、再起動します。設定が無効なら、スキーマ、絶対／正規パス、ファイルの所有者／モード、読み取り可能性、すべての親ディレクトリを確認します。サービスアカウントは検証ファイルを所有したり置き換えたりできてはいけません。
正しいオペレーターシークレットが失敗する
サーバーが CLI で生成した同じ検証ファイルを読み込んだことを確認します。最小長はちょうど 5 文字です。古いサーバープロセスまたは最近置き換えた検証ファイルを確認します。入力したシークレットをログに残さないでください。
Telegram が設定されていない、またはテストに失敗する
オペレーター変更のロックを解除後、Settings → Telegram を開きます。Not configured は有効なボットトークンとチャット ID の両方を必要とします。Invalid は、非公開トークンファイルが所有権、通常ファイル、またはモードのチェックに失敗したことを示します。接続チェックの成功はボット認証情報を検証します。チャットと任意のトピック ID を検証するには、明示的なテスト通知を送ります。いずれかの操作が失敗した場合、送信 HTTPS/DNS を確認します。安全なエラーは Telegram の応答本文とトークンを意図的に省きます。Telegram 通知を参照してください。
Statistics に現在のセッションがない
使用量／状態を更新し、プロバイダーがテレメトリーをサポートすること、永続的なロールアウト証拠が読み取り可能なままであることを確認します。セッションはカウント前に削除する必要はありません。欠落したプロバイダーフィールドはゼロではなく Not reported と表示されるべきです。
Statistics の合計が重複して見える
グローバル、セッション、端末の各ディメンションを比較し、データベースを保全します。プロバイダーの累積スナップショットは、ポーリング／再起動／リプレイを通じて一つの安定したチェックポイントを更新する必要があります。診断前に行を手動削除してはいけません。
Docs／ビルド ID の不一致
Settings → About、Docs フッター、候補マニフェスト、静的アセットリビジョンは一致する必要があります。一つの不変候補を再ビルドして検証してください。一つのチェックアウトの Web 出力と別のものの Python コードを混在させてはいけません。
ディスク圧迫または Housekeeping が回収できない
Housekeeping のドライラン計画を確認します。保護済み、アクティブ、未知、バックアップ、現在、ロールバックの項目は意図的に保持されます。報告された所有者／参照に対処するか、安全にディスクを拡張してください。ランタイムルートを再帰削除してはいけません。
最大限の証明済み安全な回収には、別の Full Cleanup プレビューを確認します。全エージェントが権威ある事実でアイドルと判定され、プロバイダー、Heavy、キュー内変更、ランタイム操作が一つもアクティブでなくなるまで、実行はブロックされたままです。Ready エージェントを閉じたり、このゲートを弱めたりしてはいけません。継続状態は保護されます。Full Cleanup は証明済みの非アクティブなローカルリリースをすべて削除するため、ローカルロールバックを失ってよいことを確認してください。保護された曖昧なツール、バックアップ、ソース権限、dirty または未公開の worktree、不明なパスは、手動削除の理由ではなく、想定されるレポート項目です。
Full Output に出力がクリーンアップ済みと表示される
Full Cleanup が終了済み履歴エージェントの古い永続ログを削除した後も、そのエージェントは SQLite に残る場合があります。これは、保持メタデータを正しく表す状態です。Sessions と Agents は引き続き利用でき、Full Output は DURABLE_OUTPUT_UNAVAILABLE を報告します。現在および Ready エージェントの出力は保護されます。履歴テキストが必要な場合は保持済みバックアップから復元し、別のログを作り上げたり関連付けたりしないでください。
再起動後にブラウザー端末が再接続しない
一度更新し、サーバーと tmux セッションが正常であることを確認し、リバースプロキシを経由するブラウザーの WebSocket 接続を調べます。Caddy などのプロキシが upgrade ヘッダーを削除していないことを確認します。インストール済み PWA は端末または WebSocket 状態をキャッシュしません。
まだ解決しない場合
最小限の再現可能な証拠を保持し、広範なスイートの前に対象コンポーネントのチェックを実行します。Issue レポートには公開して安全なパスとメッセージだけを含めます。レポート要件についてはコントリビューティングを参照してください。