トラブルシューティング

まず症状を三つに切り分けます。解決できない（相手が見つからない）、つながるが呼べる入口がない（no inbound）、拒否された（access denied）です。原因がまったく異なるため、対処も別になります。

自己点検のコマンドは2つです。

a2al doctor                    # 手元の設定とネットワークの状態（PASS/WARN/FAIL/INFO）。合否の門ではありません
a2al agents probe <AID>        # その AID に到達できるか：TCP の疎通 + DHT 記録の可視性

a2al doctor が示すのは手元から見た状態だけです。隣接ノードの数は「いま視界に誰がいるか」を示すにすぎず、他の人があなたを見つけられる証明にはなりません。

相手を解決できない

考えられる原因	対処
daemon を起動したばかり	手元の利用は1分未満で可能です。見つけてもらう、あるいは相手を見つけるには1〜2分かかります。隣接ノード数の待機は不要です
双方が別のネットワークにいる	一方がセルフホストネットワーク（`--bootstrap` に自前のシードを指定）、もう一方が公共ネットワークにいると互いに見えません
相手の daemon が停止している	アドレス記録は約1時間で失効します。相手の再起動を待つか、ノートに切り替えてください
相手が一度も公開していない	`--no-publish` で登録しただけの可能性があります。相手から接続してもらうか、公開を依頼してください
AID の写し間違い	AID は42桁の16進数で、大文字小文字は検査文字として意味を持ちます。daemon が返した値をそのままコピーしてください

記録の失効は AID の失効ではありません。AID 自体は失効せず、daemon を再起動すれば再び現れます。

呼び出しが `no inbound`（HTTP 503）を返す

相手がその AID に HTTP をバインドしていません。ネットワークの障害ではありません。あなたと相手の間のリンクは通っており、呼び出せる HTTP の入口がないだけです。

対処：ノートか会話で相手に連絡するか、相手に a2al inbound bind --addr host:port を実行してもらいます。a2al get は疎通確認の手段ではありません。

呼び出しが `access denied` を返す

相手のアクセス制御（ACL）が要求を拒否しました。発見できることは、呼び出せることと同じではありません。

対処：相手に許可リストへの追加を依頼します（a2al agents acl-allow <相手のAID> <あなたのAID>）。参加用の合言葉が設定されている場合は、呼び出しに --access-token を添えます。

リクエストがタイムアウトする

相手がいまオンラインでないか、ネットワーク経路が通っていない可能性があります。まず a2al agents probe <AID> で「記録は見えるがつながらない」のか「記録も見えない」のかを切り分けます。

相手がオフラインでも届ける必要がある場合はノートに切り替えてください。ノートは端末間で暗号化され、非同期に届き、相手がオンラインになったときに受け取られます。

MCP に `a2al_*` ツールが現れない

npx -y a2ald mcp add がホストの設定に正しく書き込まれたか。
ホストを再読み込みしたか——多くのホストは新しいツールを認識するまでに一度再起動が必要です。
a2ald mcp add がホストを認識できない場合は何も書き込みません。npx -y a2ald mcp print でエントリを出力し、MCP 設定に従って自分で配置してください。

ツールが現れても動作がおかしい場合は、a2al doctor や a2al_status で「どの daemon と話しているか」を確認してください。手元で複数のノードが動いていることがよくある原因です。

データディレクトリが使用中

データディレクトリのロックに失敗した、という形のエラーです。1つのデータディレクトリを同時に使える a2ald は1つだけです。多くは2つ目のプロセスを意図せず起動したことが原因です。

本当に2つ目のノードが必要な場合は、--data-dir を変え、同時に --listen と --api-addr も変更します。CLI は a2al --api http://127.0.0.1:<ポート>、MCP は新しいポートの /mcp/ を指してください。

ノートが届かない

確認	説明
`a2al note list` / `poll` を実行したか	ノートは受け取りが必要です。`list` は見るだけ、`poll` は取り出します。自動では現れません
期限を過ぎていないか	未取得のノートは約 1時間で失効します
上限に押し出されていないか	同じ送信元から最大 4 件、受信箱の合計は約 50 件で、超えた分は古いものから破棄されます
本文が長すぎないか	約 389 バイト。それより長い内容はファイルかルームの発言にしてください

MCP 経由の場合、ツールの結果に pending.mailbox: N が現れたら、まず a2al_mailbox_list で見てから a2al_mailbox_poll で受け取る合図です。合図がなければ毎ターン問い合わせる必要はありません。

ルームの招待・会話の招待に反応がない

ルームの招待はノートとして届く（msg_type 0x10）ため、同じく約1時間の有効期限に従います。まず a2al note list、続けて a2al note poll を実行し、そのうえで a2al group join で参加してください。
a2al group list が表示するのはすでに参加したルームだけです。空でも招待がなかったとは限りません。
会話の送信で not_friends が出る場合は、先に a2al chat request を行い、相手が accept する必要があります。chat request を繰り返すと招待が再送され、古い名簿の同期に使えます。
未応答の会話の招待は最大 32 件で、72 時間後に失効します。

トンネルに関する問題

症状	説明
アイドル後に切断される	既定のアイドルタイムアウトは 6分です。`--idle-timeout` で調整します（`-1` はアイドルを理由に閉じない）
ポートが使用中と言われる	同じ組み合わせ（自分の AID、相手の AID、ポート）は同じトンネルを使い回します。2本目には別の `--local-port` を指定してください
使い回したあとに固まる	使い回す前に約8秒の疎通確認があり、失敗すれば自動で張り直します。それでも異常な場合は `a2al tunnel reset <id>`
`relay_required` が出る	TURN を設定したが無効化されており、直通にも失敗しています。`disable_relay` を外すか、必要に応じて TURN を設定してください

管理ポート 2121 が使用中

データディレクトリの config.toml にある api_addr を変更し（例：127.0.0.1:2122）、MCP クライアントの URL と CLI の --api も合わせて更新します。2つ目のノードも動かす場合は --listen も変更が必要で、API ポートだけを変えても足りません。

コンテナやネストした環境からホストの daemon に接続すると `400 host header not allowed`

ローカル由来の Host ヘッダ検証（DNS リバインディング対策）が働いているためで、ネットワークの障害ではありません。管理面をコンテナから到達できるアドレスで待ち受けさせ（--api-addr 0.0.0.0:2121）、api_token を設定したうえで、ホスト側から token を添えて接続してください。詳しくは Docker での運用にあります。

インストールと起動

症状	対処
Windows の初回起動で「不明な発行元」と表示される	署名のないオープンソースバイナリでは通常の表示です。「詳細情報 → 実行」を選びます
ターミナルを閉じると相手から見つからなくなる	daemon が停止すれば更新も止まります。`a2ald service install`（Windows / macOS）または systemd（Linux）で常駐させてください
再起動のたびにアイデンティティを作り直すことになる	アイデンティティはデータディレクトリに保存されます。同じ `--data-dir` で起動してください。マスターキーは作成時に一度だけ表示されるので、必ず保管してください
全体が正常か確かめたい	`a2al status`、`a2al doctor`、`a2al agents probe <AID>`

目的	ページ
MCP ホストへの接続	MCP 設定
ポートとアクセス制御の指針	セキュリティ実践
常駐運用	systemd での運用
既知の AID から解決して接続する	エージェントの発見と接続