問題を特定する
Panolayer に表示されるメッセージから始めます。表を使って該当する修正に移動し、次の手順を試す前に結果を確認してください。
| 何が問題ですか？ | ここから開始 |
|---|---|
| インストールまたはシステムチェックが完了しない | インストールとシステムチェック |
| ブラウザではサインインできるが、アプリがまだ待機している | サインインを完了する |
| repository が開かない、または不完全に見える | 正しい repository を開く |
| agent が見つからない、起動しない、またはエンジンエラーを報告する | agent を開始する |
| agent がファイルを読み取れない、または変更できない | ファイルアクセスを確認する |
| 検証が中断された、利用できない、または未決定である | 検証を復旧する |
| ルールが誤った動作を記述している | ルールとその根拠を確認する |
| agent が停止した、またはその変更が見つからない | agent の作業を確認する |
| グラフが失敗する、または不完全な回答を返す | グラフのステップを確認する |
| マージが競合する、またはプッシュが失敗する | マージとプッシュの問題を解決する |
| さらにヘルプが必要 | 再現可能なバグを報告する |
エラーと作業内容を保持してください。 正確なメッセージと、それが表示された場所を記録します。別のタスクを開始する前に、既存の実行または worktree を確認してください。このガイドに従うために、repository、agent の worktree、設定を削除する必要はありません。
セットアップのヘルプ
ブラウザでのサインインをまだ待っていますか？
Panolayer でブラウザを再度開くを選択し、サインインの承認を完了してください。リクエストの有効期限が切れている場合は、再試行を選択して新しいリクエストを開始します。
ブラウザが間違ったアカウントを使用していますか？
ブラウザの承認ページでアカウントを切り替えるを選択し、使用するアカウントでサインインしてください。
システムインストーラが開いていませんか？
Panolayer のシステムチェック画面でインストーラを再度開くを選択し、Apple Command Line Tools のインストールを完了してください。インストーラの実行中、Panolayer は自動的に確認します。
インストール、検証、agent の問題については、トラブルシューティング を参照してください。
インストールまたはシステムチェックが完了しない
まず Mac を確認してください。 Panolayer デスクトップアプリには、macOS 15 Sequoia 以降を実行する Apple silicon Mac が必要です。チップと macOS のバージョンは Apple メニュー → この Mac について で確認してください。Intel Mac はサポートされていません。
Panolayer をダウンロードしたがインストールされていない場合: .dmg を開き、Panolayer を Applications にドラッグしてから、Applications から開きます。完全な手順については、Panolayer のインストールとセットアップ に従ってください。
「簡単なシステムチェック」で行き詰まっている場合:
- Git — Apple Command Line Tools の横にある インストール を選択し、Apple のインストーラを完了します。
- インストーラを閉じた場合は、Panolayer で インストーラを再度開く を選択します。
- インストール後に Panolayer に戻ります。ツールは自動的に検出されます。チェックの準備ができたら プロジェクトを選択 を選択します。
Panolayer でプロジェクトを選択できるようになれば、続行する準備は完了です。Apple のインストーラがエラーを報告する場合は、サポートを求める際にその正確なエラーを含めてください。
サインインが完了しない
サインインは 2 つの部分で構成されます。ブラウザで認証し、その後、その Mac を Panolayer アプリに対して承認します。Web サイトでサインインしただけでは、アプリの承認は完了しません。
| 表示内容 | 対処方法 |
|---|---|
| アプリが待機中で、ブラウザのページが開いていない | Panolayer で ブラウザを再度開く を選択します。 |
| ブラウザに別のアカウントが表示される | アカウントを切り替える を選択し、アプリで使用するアカウントでサインインします。 |
| ブラウザからこのコンピュータの承認を求められる | ブラウザのコードをアプリの あなたのコード と比較します。一致したら、はい、このコンピュータでサインインする を選択します。 |
| リクエストの有効期限が切れた | Panolayer で 再試行 を選択し、新しいブラウザリクエストを完了します。 |
| ブラウザで承認が確認される | Panolayer に戻り、セットアップを続行します。 |
アプリと Web サイトで同じアカウントを使用してください。詳細な手順は サインイン を参照してください。
サードパーティの agent から別途サインインを求められますか? それは agent ベンダーのサインインです。Panolayer アカウントで代用することはできません。その agent の指示に従い、サポート対象の agent を参照してください。
repository が開かない、または不完全に表示される
プロジェクトが開きませんか？
ローカル Git repository のルートフォルダーを選択したことを確認してください。repository がオンラインでホストされている場合は、まず Mac にクローンし、そのフォルダーを Panolayer で開いてください。
Panolayer の起動画面で プロジェクトを開く… を選択し、ローカル Git repository のルートフォルダーを選択してください。GitHub URL はローカルフォルダーではありません。通常使用している Git ツールで repository を Mac にクローンしてから開いてください。
マップが不完全に見える場合:
- 個別のファイルや誤ったサブフォルダーではなく、目的の repository ルートを開いたことを確認してください。
- Panolayer がまだコードを分析中か、インデックス作成エラーを報告しているかを確認してください。検証の復旧 を参照してください。
- コードベースで 対応言語 を確認してください。特に monorepo では、アーキテクチャ に表示されるアプリと関係を確認してください。
フレームワークが検出されたことやファイルが表示されていることは、すべての動的な関係を解決できることを意味しません。アーキテクチャと依存関係を確認する を参照してください。
ワークフローを比較するにはサンプルを使用してください。 ドキュメントでは Twitter Clone を使用しており、これは twitter-starter として開きます。自分の repository では、ファイル、イシュー数、依存関係が異なります。Panolayer を使用するためにサンプルへ切り替える必要はありません。
agent が起動しない
Panolayer Agent は組み込みです。 My Agents を開き、Monitor Agents の横にある + ボタンを選択してから、Panolayer Agent を選択します。別途ベンダーのサインインは必要ありません。repository で agent を実行する を参照してください。
別の agent の場合: マーケットプレイスからインストールし、My Agents に戻り、同じメニューから選択します。求められたらベンダーのサインインを完了してください。そのモデルアクセスと請求はそのベンダーに属します。関連する設定については サポート対象の agent を確認してください。
agent の失敗カードが表示された場合:
- 技術的な詳細を開き、起動エラーを確認してください。
- コンテナエンジンを起動できなかった場合は、上記の Mac 要件を確認してから、失敗カードの 再試行 を使用してください。
- メッセージに認証情報の不足やアカウントの問題が示されている場合は、再試行する前にその agent のサインインを完了してください。
- 同じメッセージで再度失敗する場合は、失敗カードの バグを報告 を選択してください。この経路には agent の診断情報が含まれます。送信する前にレポートを確認してください。
起動に成功すると agent の会話が開き、リクエストを送信できます。新しいセッションを繰り返し開始しても、インストールやアカウントのエラーが変わっていなければ解決しません。
リクエストが拒否される、または使用量を使い切っている
Panolayer が 今月の使用量を使い切りました と報告した場合は、設定 → プランと使用状況 を開いて、アカウントの使用量とリセット日を確認してください。同じリクエストを再試行しても、使い切った使用量は回復しません。
サードパーティの agent の場合は、エラーに示されたベンダーアカウントを確認してください。Panolayer にサインインしても、そのベンダーのクォータや請求は変わりません。再試行する前に、報告されたアカウントの問題を解決してください。
agent がファイルを読み取れない、または変更できない
アーキテクチャでファイルのコントロールを確認します。ファイルのソースを開き、詳細パネルを下にスクロールします。
| コントロール | 変更内容 |
|---|---|
| 実装ロックのファイルをロック | AI agent がファイルを変更するのを防ぎます。 |
| コンテナ agent アクセスのagent から隠す | 新しいコンテナ agent がファイルを読み取るのを防ぎます。既存の agent セッションは変更されません。 |
制限が意図的なものであれば、そのままにして、agent にその範囲内で作業するよう依頼します。agent にこのファイルへアクセスさせたい場合は、該当するコントロールを意図的に変更します。可視性の変更は新しいコンテナ agent セッションに適用されます。既存のセッションのアクセスは変更されません。
どちらのコントロールでも問題を説明できない場合は、agent のエラーと、agent が使用しているワークスペースを確認します。agent の作業を確認するを参照してください。
検証に使用可能な結果がない
イシューを開き、検証ステータスを読んでから対処を決めます。完了できなかったチェックは合格結果ではありません。また、コードに対して失敗したルールとは異なります。
| ステータスまたはメッセージ | 次に行うこと |
|---|---|
| コードを分析中またはルールを確認中 | 現在の段階に従います。結果を解釈する前に、完了するまで待ちます。 |
| まだインデックスされていませんまたはこのプロジェクトをインデックスできませんでした | カードのアクションに従ってインデックスを開始するか、再試行します。Panolayer は検証する前にソースを読み取る必要があります。 |
| 検証が中断されましたまたは検証に対処が必要です | 付随するエラーを読み、原因に対処してから、ステータスカードの再試行を選択します。 |
| 検証ステータスを読み取れませんでした | 再試行を選択してステータスを再度読み取ります。このメッセージは、コードが合格したか失敗したかを示すものではありません。 |
| 未確定の結果 | 各項目に記録された理由を開きます。これらのチェックは合格でも失敗でもありません。 |
| 入力が大きすぎます | 変更されていない入力で再試行しても解決しません。影響を受けるファイルと表示されているメッセージをレポートに含めて、チームが調査できるようにします。 |
| 評価を完了できませんでした | 記録された原因に対処してから、提供されている場合はチェックを再試行を使用します。 |
| 検証対象なし — まだ変更はありません | agent には確認する変更がありません。マージ結果を期待する前に、そのタスクとワークスペースを確認します。 |
アプリが、agent ワークスペースが削除された、または追跡されていないと報告した場合は、メインに戻るを選択してメインワークスペースで作業を続けます。古い結果は、チェックされなくなったファイルのステータスを示すものではありません。
再試行後は、新しいステータスを読み取ります。消えたエラー、空のイシュー一覧、未完了のチェックを、コードが合格した証拠として扱わないでください。検証結果を理解するを参照してください。
ルールが誤っているように見える
イシューの横にある詳細を開き、期待内容、説明、ソースを比較します。Twitter の例では、clearSaved はブックマークの削除が完了した後にのみ終了することが期待されています。詳細には、現在のコードが早すぎるタイミングで戻る理由が示されています。
- 期待内容が正しく、コードがそれに違反している場合: 修正を選択し、Panolayer Agent または別のインストール済み agent を選びます。最初のバグを修正するに従ってください。
- 期待内容が誤った動作を記述している場合: ルールを修正して関数が行うべき動作に一致させ、検証を再実行して新しい結果を確認します。
- 期待内容は正しいが、報告された失敗が不正確に見える場合: ルール、表示されている説明、およびそれを再現する最小例を報告します。
期待内容を変更することは、コードを修正することとは異なります。失敗を合格に変えるためだけに、正確なルールを弱めないでください。
agent が停止する、またはその変更が見つからない
Open My Agents and return to the conversation for that task. Choose Open on its run card. In Stream, select the relevant activity to inspect the command and its output in the right-hand panel. Read the error before sending another task.
A command or test failed? Check what the output actually says. A missing dependency, a rejected credential, and a failing application test need different fixes. Give the agent the failing command and the result you expect, keeping the follow-up tied to the same task. If the app shows a failure card, use its Technical details, Retry, or Report a bug controls.
The agent finished, but your checkout looks unchanged? Coding work happens in the agent’s worktree, separate from your main workspace. Open Changes and select that agent’s worktree on the right-hand side to see its uncommitted code. You can review worktrees, inspect changes by risk, and commit from Changes.
The run says Done, but the work is not merged? Completion and merge approval are separate. Review the verification summary and changed files, then decide whether to merge. A merge into your branch records the change locally; pushing to your remote is a separate step.
See Follow the agent’s work and Review changes and commit.
A graph step fails or the answer is incomplete
Inspect the step that failed and its output before changing the whole graph.
| What you see | What to check |
|---|---|
| The graph is read-only | Duplicate the built-in graph to edit your own copy. |
| An agent step needs a classification | Select the step and choose its agent classification in the right-hand panel. |
| A script fails immediately | Check Program, one argument per line, and Success exit code. The program must be available where the step runs. |
| The agent doesn’t use the question from this run | Check that Custom instructions includes the Goal variable inserted with @. |
| A failure has nowhere to go | Inspect the red failure route and connect an explicit handler or Failed destination. |
| The graph succeeds but the answer is incomplete | Read the agent step’s output, clarify its instructions, and test the same goal again. |
A successful script step means it met its configured success exit code. Check the actual output and the result you intended, too. After editing a failure route, test that path deliberately.
Follow Build your first AI agent graph for the working example and configuration screenshots.
A merge conflicts, or a push fails
Start in Changes. Select the relevant worktree and inspect what is waiting to be committed or merged. If you already approved an agent merge, find its commit in History before trying to commit the same work again.
If the merge reports conflicts:
- Read the conflict dialog. The agent’s work has not been merged yet, and its worktree remains available.
- Resolve each conflicted file in the agent’s worktree, save it, and stage that resolution with
git addin that worktree. You can also use the dialog’s action to ask the agent to resolve the conflicts, then review its edits. - Choose Refresh status. If the rebase is paused and the conflicts are staged, choose Continue rebase.
- Review the resulting changes, then use Review & retry merge when offered.
Do not resolve a conflict in a different checkout and expect the agent’s worktree to change with it.
If a push fails: read the Git error and check the configured remote and your permission to write to it. If the remote branch has moved on, reconcile the changes using your normal Git workflow before retrying. A local merge or commit remains local until a push succeeds. The Twitter sample may have no remote configured; a local commit is enough to complete its walkthrough.
See Review changes and commit for commit, History, and push controls.
Report a bug
If the problem persists, choose Report a bug in Panolayer, or contact the team. When an agent fails, use Report a bug on its failure card so the report includes that agent’s diagnostics.
You can use this template:
What I was trying to do:
Steps to reproduce:
1.
2.
3.
Expected result:
Actual result:
Exact error or status:
Panolayer version:
Mac chip and macOS version:
Agent name, if relevant:
Does it also happen in the Twitter Clone sample?
Include the file or function name when it helps locate the problem, and note whether it happened in the main workspace or an agent worktree. A small example you can share is more useful than an entire private repository. You don’t need to test the sample if it would interrupt your current work.
The report dialog includes diagnostics and logs, and can attach the current screen. Review the Screenshot attached control and any files you add before sending. Leave out credentials, API keys, and private source code you do not intend to share.
After sending, keep the tracking reference shown in the confirmation so you can refer to the same report when following up.