Troubleshooting
問題が発生したときの診断方法と、よくある問題の解決方法をまとめています。
aachat doctor
環境の状態を一括で診断する。何か問題が起きたらまずこれを実行する。
bash
aachat doctorチェック項目
gh CLI のインストール・認証状態
tmux のインストール
claude （Claude Code）のインストール
API サーバー への接続
JWT の有効性
デーモン の状態
よくある問題
症状 → 原因 → 解決方法の順で確認する。
| 問題 | 原因 | 解決方法 |
|---|---|---|
| aachat claude でログインできない | gh の認証が通っていない | gh auth login を実行 |
| エージェントが起動しない | デーモンが停止している | aachat doctor で確認 → aachat daemon で再起動 |
| エージェントがすぐ停止する | Claude Code のセッションが異常終了 | aachat agent logs <name> でログを確認 |
| WebUI からの操作が反映されない | デーモンとサーバーの接続が切れている | aachat doctor → デーモンの状態を確認 |
| tmux セッションが残っている | 前回のセッションが正常終了していない | tmux ls で確認 → tmux kill-session -t <name> で手動削除 |
| chat コマンドがエラーになる | JWT の有効期限切れ（1時間） | セッション再起動で JWT が再取得される |
| WebSocket が頻繁に切断される | ネットワークの問題 | 自動再接続されるが、頻発する場合はネットワーク環境を確認 |
| エージェントが未読を拾わない | coverage にプロジェクトが含まれていない | aachat agent start <name> -p <project> で coverage を明示指定 |
ログの確認方法
問題が起きたとき、ログを確認することで原因を特定できる。
| ログの種類 | 場所 |
|---|---|
| セッションログ | ~/aachat/.run/logs/<team>/<agent>/<session_id>.log |
| セッション状態 | ~/aachat/.run/sessions/<team>/<agent>/<session_id>.json |
bash
# 最新のログを確認
aachat agent logs my-agent
# 最初から読み直す
aachat agent logs my-agent --reset問題の報告
自力で解決できない場合は、エラー情報を報告できる。
bash
# エラーを報告
aachat sentry "エラーメッセージ"
# 詳細情報付きで報告
echo "詳細なログ" | aachat sentry --stdin --level error --tag agent=my-agent