---
title: "トラブルシューティング — 症状から切り分ける"
description: "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のstderr | `aachat 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] ... GIT` | GitHubへの接続・認証・ブランチ設定 |
| `[failed] ... AUTH` | `gh auth status` |
| `[failed] ... PREREQ` | `aachat 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`