トラブルシューティング

症状から問題を探してください。各項目では症状 / 考えられる原因 / 診断方法 / 解決方法を提供します。お使いの状況が一覧にない場合は、GitHub にイシューを登録するか、サポートにお問い合わせください。

デーモンがサーバーに接続できない

症状: aacworkflow daemon の status コマンドが offline または connection refused を表示します。AACWorkflow Cloud 側にもこのランタイムの最近のアクティビティが見当たりません。デーモンの仕組みについてはデーモンとランタイムを参照してください。

考えられる原因:

1. AACWORKFLOW_SERVER_URL が誤ったアドレスを指している — 未設定のままか、デフォルトの wss://api.aacworkflow.com/ws と一致している必要があります
2. ネットワーク / ファイアウォールによるブロック — お使いのマシンからのアウトバウンド WebSocket 通信がブロックされている
3. トークンが期限切れまたは無効 — aacworkflow login を一度も実行していない、または PAT が取り消された
4. 対象のワークスペースのメンバーではない — ログインしたアカウントが、デーモンを登録しようとしているワークスペースに所属していない（register が 403 を返す）
5. DNS 解決の失敗 — デーモンのマシンで api.aacworkflow.com が解決されない

診断方法:

aacworkflow daemon logs --lines 100    # look for daemon-side errors
echo $AACWORKFLOW_SERVER_URL          # confirm the address, if you set one
cat ~/.aacworkflow/config.json        # verify api_token exists
aacworkflow workspace list            # confirm you're a member of the target workspace

解決方法: 上記の各原因を 1 つずつ対処してください。最もよくある 2 つの解決策は、カスタムの AACWORKFLOW_SERVER_URL を解除してデーモンを再起動すること(aacworkflow daemon restart)と、ログインし直すこと(aacworkflow logout && aacworkflow login)です。

タスクが queued で止まる

症状: エージェントにイシューを割り当てた後、イシューの状態はすぐに in_progress に変わりますが、長時間経ってもページにエージェント実行の兆候が見えません。aacworkflow daemon status はデーモンを online と表示しています。

考えられる原因(頻度順):

1. エージェントの同時実行上限に到達 — このエージェントの max_concurrent_tasks(デフォルト 6)が、他の実行中タスクですでに埋まっている
2. 同じイシューで同じエージェントの別タスクがまだ実行中 — 同じエージェント × 同じイシューは順次実行が強制されます(重複実行の防止)
3. エージェントがアーカイブされている — アーカイブ後も新しいタスクはキューに入りますが、クレームできず、5 分後にタイムアウトします
4. デーモンが現在のワークスペースにこのランタイムを登録していない — デーモンを再起動するか、UI でランタイムを選択し直してください
5. デーモンの接続が切れた — 直近 45 秒間ハートビートがありません。daemon status が online と表示されるのは、ごく最近切断された状態を反映している可能性があります

診断方法:

aacworkflow daemon status --output json       # runtime list + last_seen_at
aacworkflow agent list                         # check agent archived state
aacworkflow issue show <issue-id>             # inspect task history

解決方法:

• 同時実行が満杯 → 実行中のタスクが終わるのを待つか、aacworkflow agent update <id> --max-concurrent-tasks 10 で上限を引き上げてください
• 同一イシューの順次実行 → 前のタスクが終わるのを待つか、別のエージェントに割り当て直してください
• エージェントがアーカイブされている → aacworkflow agent restore <id>
• ランタイム未登録 → aacworkflow daemon restart するとデーモンが再登録します

WebSocket が接続できない

症状: ブラウザのコンソールに WebSocket is closed が記録されます。ページにリアルタイム更新(タスクの進捗、コメント、インボックス)が表示されず、再読み込みしないと見えません。エージェントのタスクはバックグラウンドで引き続き実行されます。

考えられる原因:

1. 企業プロキシやファイアウォールが WebSocket アップグレードをブロックしている — 通常の HTTPS は通すが、Upgrade ヘッダーを取り除くネットワークもあります
2. JWT クッキーの期限切れまたは欠落 — 30 日の有効期限後にログインし直していない
3. ブラウザ拡張機能の干渉 — 一部のプライバシー / 広告ブロック系拡張機能が wss:// 接続だけを選択的にブロックすることがあります

診断方法:

• ブラウザの DevTools → Network → 「WS」でフィルタリングし、接続状態とステータスコードを確認してください
• 別のネットワーク(モバイルのテザリングなど)で試して、企業プロキシが原因かどうか切り分けてください

解決方法:

• クッキーの期限切れ → ページを再読み込みしてログインし直してください
• プロキシ / ファイアウォールがブロックしている → 別のネットワークで試すか、ネットワーク管理者に wss://api.aacworkflow.com を許可してもらってください
• それでも解決しない → DevTools の Network タブのスクリーンショットを添えてサポートにお問い合わせください

メールが届かない

症状: ログインまたは招待の受諾中にメールアドレスを送信したのに、インボックスにもスパムフォルダにも認証コードがありません。

考えられる原因:

1. 配信の遅延 — まれに 1 分ほどかかることがあります
2. スパム / プロモーションフォルダ — 認証メールがフィルタリングされることがあります
3. 社内メールのフィルタリング — 一部の企業メールゲートウェイが自動送信メールを隔離することがあります
4. メールアドレスの入力ミス — サインインページで入力した内容を再確認してください

解決方法:

• 1 分ほど待ってから、スパム / プロモーションフォルダを確認してください
• サインインページのコードを再送信をクリックしてください
• 組織で受信メールをフィルタリングしている場合は、noreply@aacworkflow.com を許可リストに追加するよう IT 部門に依頼してください
• 数分経っても届かない場合はサポートにお問い合わせください

ポートの競合(デーモン)

症状: aacworkflow daemon start が address already in use で失敗します。

考えられる原因:

1. デーモンの health ポートが使用中(デフォルト 19514、プロファイルごとにハッシュでオフセット)
2. 別のデーモンプロファイルがすでに同じポートにバインドしている

診断方法:

lsof -i :19514        # macOS / Linux
netstat -ano | findstr :19514    # Windows

解決方法: 競合しているプロセスを停止するか、aacworkflow daemon start --profile <name> で別のプロファイルとして追加のデーモンを実行してください。プロファイルごとに異なる health ポートが自動的に選ばれます。

ログの場所

バックグラウンドモードでは daemon.log はサイズでローテーションされ(デフォルトは 20MB × gzip バックアップ 5 世代。AACWORKFLOW_DAEMON_LOG_MAX_SIZE_MB / _MAX_BACKUPS / _MAX_AGE_DAYS で調整可能)、開けないほど大きくなることはありません。

より詳細なデーモンログが必要な場合は、デーモンをバックグラウンドからフォアグラウンドに移してください: aacworkflow daemon stop && aacworkflow daemon start --foreground。フォアグラウンドで実行すると、ログはローテーションファイルではなくターミナルにリアルタイムで出力されます。