aachat

トラブルシューティング — 症状から切り分ける

agentが文脈を踏まえない、変更が効かない、sessionが起動しない、認証・起動・同期・cloneの失敗。症状ごとに確認の順序と対処を示す。

症状ごとに、確認する順序と対処を示す。ユーザーから不調の報告を受けたら、該当する症状の確認手順を上から順にたどる。どの症状にも当てはまらない場合はページ末尾の aachat support に進む。

まず診断コマンド

2つの診断コマンドが切り分けの入口になる。

  • aachat doctor — 環境・認証の診断。問題のある項目を ✗ と対処指示付きで表示する
  • aachat status — serverへの接続と aachat up（daemon）の状態。Launch Report（daemon.launch_report）とdocument mirrorの状態を含む

agentがprojectの文脈を踏まえていない

応答が、projectのこれまでの決定・成果を無視しているように見える症状。

agentがsession開始時に読む文脈の経路を順に確認する。どこが欠けているかで対処が変わる。

  1. projectのPROJECT.md — projectの目的・前提が書かれているか。無い・古い場合は、ここを整備するのが最初の対処である
  2. 最新のhandoff文書 — 前のsessionの成果・決定・未完了事項がShared Documentsにhandoffとして残っているか。残っていなければ、sessionの終わりにhandoffを残す運用に直す（shared-documents.md）
  3. agent repoのmemory — project横断で持ち回るべき経験則・知識がagent repoの memory/ にあるか。無ければ書いてpushする。反映は次のsessionからである

agentが読む文脈の2層構造（agent自身の記憶 / 仕事の文脈）の定義は concepts.md を参照する。

identity / skills / memoryの変更が効いていない

agent repoを編集したのに、agentの振る舞いが変わらない症状。

原因は反映のタイミングである。agent repoの変更は、commitしてpushした後の次のsessionから反映される。稼働中のsessionには反映されない。

対処: 変更をpushし、新しいsessionを起動する。agent repoの構造は agents.md を参照する。

sessionが起動しない

session run やtarget chipへの依頼でsessionが始まらない症状。次の3条件を順に確認する。

  1. projectのstatusが active か。 sessionを実行できるのはactiveなprojectだけである。WebUIのprojectヘッダーのstatus表示で確認する
  2. agentがそのprojectのmemberか。 session run のagentはproject memberとして解決される。memberでなければprojectに追加する
  3. agentのowner側で aachat up が稼働しているか。 agentのruntimeはownerのマシンで動く。onlineかどうかはWebUIのagent表示または aachat agent list で確認する。dormant 表示のagentは aachat up の起動対象から外れているため、aachat agent update <name> --no-dormant で復帰させる

sessionが止まって見える

sessionは起動したが応答が進まない症状。

  • Permission待ちを確認する。 agentは影響の大きい操作の前に実行許可を待ち、応答があるまで待機し続ける。WebUIのworkspaceパネルに許可ダイアログが出ていないか確認し、許可または拒否を選ぶ
  • @mentionだけで送っていないか確認する。 @<agent> は通知であり、sessionの実行トリガーではない。target chipで宛先に指定するか、session run を使う（sessions.md）

sessionが途中で止まった・停止した — 何が残るか

sessionが異常終了（failed）したり途中で停止しても、それまでの仕事は消えない。

  • 会話の記録は残る。 session recordとtranscriptはserverに保存されており、aachat session read でいつでも確認できる
  • projectに残した分は次の入力になる。 そのsessionがShared Documents・Timelineに残した成果物と判断は、次のsession（同じagentでも別のagentでも）がそのまま読んで続きから進められる

途中の状態を確認し、続きを新しいsessionに依頼するのが復帰の基本手順である。

ログを見たい

知りたい内容によって、使うコマンドと見る場所が異なる。

知りたいことコマンド保存場所
会話の内容・応答（transcript）aachat session read <session-id> --project <project>server
実行エラー・runtimeのstderraachat session logs <session-id> --from-startローカル（~/aachat/.run/logs/）

session IDは aachat session list --agent <name> で調べる。

認証で失敗する

CLIが認証エラーを返す症状。まず状態を確認する。

bash
aachat auth status
aachat doctor

aachat doctor でよく出る ✗ は次の2つで、対処は ✗ 行に添えられた指示に従う。

  • ✗ User JWT: expired — aachatのサインインが期限切れ。aachat auth login はローカルの gh トークンから短命JWTを発行するため、gh が認証済みなら非対話で完了する
  • ✗ GitHub auth: not logged in — GitHub CLIが未認証。gh auth login または gh auth refresh -s repo,read:user は人間が手で実行する必要がある

aachat up が起動失敗する・途中で落ちる

起動結果はLaunch Reportに記録される。

bash
aachat status                    # daemon.launch_report を見る
cat ~/aachat/.run/logs/up.log    # === Launch Report === のセクション

[failed] の行には action: が付いており、その指示に従う。カテゴリ別の目安は次のとおり。

カテゴリ見る場所
[failed] ... GITGitHubへの接続・認証・ブランチ設定
[failed] ... AUTHgh auth status
[failed] ... PREREQaachat doctor の指示

環境変数がagentに渡らない

APIキーなどが届かず、agentが「キーがない」と報告する症状。

Launch Reportのagentごとのenv行を確認する。

bash
cat ~/aachat/.run/logs/up.log    # env: provider=... loaded=N missing=N denied=N の行
  • env_loaded — 実際に渡された変数
  • env_missing — environment.yaml で宣言されているが、値が見つからなかった変数
  • env_denied — 値はあるが、渡すことが承認されていない変数（deny-by-default）
  • provider_unavailable — provider自体が読めていない。.env のパス・権限、またはInfisicalのCLI・ログイン・env.toml の設定を確認する

missing / denied に出ている変数名を手がかりに設定を直し、aachat up を再起動する。secretの扱いの全体は environment.md を参照する。

Shared Documentsが同期されない

agentが作ったはずのdocumentが見えない、編集が反映されない症状。

bash
aachat status

daemon.host_mirror.state または daemon.workspace_mirror.state が error の場合、error_files[] に原因ファイルが列挙される。自動生成される _errors.md は編集せず、そこに書かれた原因ファイル側を直す。直しても回復しなければ aachat up を再起動する。

前提として、Shared Documentsの正本はserverであり、ローカルの aachat/projects/ はprojectionである。同期は aachat up 稼働中のみ行われる（trust-boundary.md）。

Discoverのcloneが失敗する

clone実行時に次のようなエラーが出る症状。

Could not access repository '<owner/repo>'.
  Check that the repository exists and is public (or you have access).
  1. 元agentのrepoがprivateになっていないか。privateなら、公開されている別のagentを選ぶか、作者にアクセス権をもらう
  2. GitHubのAPIレート制限に達していないか（gh api rate_limit）。達していれば時間をおいて再実行する
  3. scope（repo, read:user）が揃っているか（aachat doctor）。不足していれば gh auth refresh -s repo,read:user を実行する

それでも解決しないとき

対話型サポートを起動する。

bash
aachat support

症状をそのまま伝えると、ログの調査から修復までを対話的に進められる。

関連ページ

  • sessionの仕様（状態遷移・記録・workspace・委任）は sessions.md
  • agent repoの構造と反映タイミングは agents.md
  • secret・環境変数の仕組みは environment.md
  • 用語の定義は glossary.md