エージェントの診断
このガイドでは、エージェントが実行を生み出さない理由を突き止める方法を説明します。
上から順にたどります。まずエージェント自身の実行、次にそのバックエンド、次にサーバー、最後にホストです。
1. エージェントの実行履歴を確認する
「1. エージェントの実行履歴を確認する」というセクション設定 → ワークスペース → エージェント → エージェントを選択 → ログ。
各実行には、ステータスバッジ、所要時間（進行中は「Running…」）、開始時刻と完了時刻、PID、使用したアダプターが表示されます。表示を押すと、その実行の生のイベントストリームが開きます。停止は実行中のプロセスを強制終了し、その実行を「Killed by user」として記録します。ヘッダーの実行中を強制終了は、そのエージェントの進行中のすべての実行に対して同じことを行います。
次のように読み解きます:
- 実行がまったくない — ディスパッチが発生していません。メッセージ入力欄でのメンションは、
@と単語文字（英字、数字、アンダースコア）です。解決はエージェント名に対する完全一致または前方一致なので、@code-reviewerはcodeとして解析され、code-reviewerという名前のエージェントを依然として起動できます。名前に空白が含まれる場合、それを 1 つのトークンとしてメンションすることはできません。その場合は手順 2 に進みます。 - すぐにエラーで終了した実行 — 表示を開きます。バックエンドの起動失敗は、ここにプロセスエラーとして現れます。
- 「Running…」のまま止まっている実行 — 停止してから、設定タブでそのエージェントの無応答タイムアウトを確認します。タイムアウトが未設定の場合、モードごとのデフォルトが使われます。
- 完了したが役立つ出力がない実行 — 宣言された成果物を出さずに終了した実行では、実行ログのステータスは
completedのままです。正直なシグナルはバッジではなく、要約テキストです。
ログタブにはコストが表示されません。支出については、オブザーバビリティ → インサイトにあるエージェントごとの表を使用します。
2. エージェントのバックエンドを確認する
「2. エージェントのバックエンドを確認する」というセクション設定 → サーバー → モデルプロバイダー（/settings/server/providers）。
検出されたランナーの一覧には、各アダプターとそのプローブ結果 — インストール済みのバージョン、「確認中…」、「見つかりません」のいずれか — に加えて、解決されたパスと、見つかった CLI のケイパビリティチップが表示されます。再プローブするには、ページヘッダーの更新をクリックします。
プローブは、今見ているマシンではなく、cc_server をホストしているマシン上で実行されます。Web クライアントやペアリング済みデバイスを使っている場合、「見つかりません」はサーバーホストにその CLI がないことを意味します。
確認すべきことは 2 つあります:
- エージェントにアダプターが設定されているか。 アダプターが空のエージェントは Control Center (built-in) にディスパッチされ、実行ログには
cc-harnessが記録されるため、トランスクリプトに何が実行されたかが示されます。モデルもない場合、組み込みループは Anthropic にデフォルトを問い合わせます — Anthropic アカウントを接続していなければ、これはNo credential for provider "anthropic"で失敗します。シードされるスペシャリストはアダプターなしで出荷されます。 - 組み込みアダプターにモデルがあるか。 そのモデル一覧は、同じページの下方で接続されているプロバイダーからリアルタイムに取得されるため、資格情報が保存されていないプロバイダーはモデルを 1 つも提供しません。
アダプターのカタログ自体は固定です — 新しいアダプターを登録する方法はありません。ここでアダプターごとに変更できるのは、その起動引数と環境変数です。資格情報が解決されるとき、アダプターごとの環境変数の上書きが、接続済みのプロバイダーアカウントを黙って打ち負かす点に注意してください。
3. サーバーを確認する
「3. サーバーを確認する」というセクション設定 → サーバー → 接続とステータス（/settings/server/connection）には、このクライアントがどのサーバーと通信しているか、そしてそのサーバーが何を報告しているかが表示されます。
ヘッドレスサーバーの場合、GET /healthz はクライアントなしで同じ情報を提供します。これは設計上、認証不要で CORS もオープンです:
curl http://localhost:9030/healthz返されるのは、サーバーのステータス、稼働時間（秒）、ライブ接続数、バインドされたポート、ビルドバージョンと git SHA、ワークスペーススキーマバージョン、RPC カタログバージョン、サーバー ID、名前とアイデンティティフィンガープリント、バインドが安全でないかどうか、そして watching / indexing / pending のカウントを持つ codeGraph ブロックです。キャッシュがトラフィックを受けたことがある場合は caches ブロックも含まれ、デモサーバーは demo: true を追加します。
変更が「テストでは動くがアプリでは動かない」ときに知っておくべきことが 2 つあります:
- デスクトップは、ソースよりもビルド済みの
cc_serverバイナリを優先して起動します。新しい RPC オペレーションや MCP ツールは、バイナリを再ビルドするまで現れず、子プロセスの git SHA がアプリのものと異なる場合、起動時に警告がログに記録されます。 - デスクトップは、20 秒以内に準備完了のバナーを出力しなかった起動済みサーバーを強制終了し、エラー画面に移行します。
4. ホストを確認する
「4. ホストを確認する」というセクション設定 → サーバー → 診断とプライバシー（/settings/server/diagnostics）はホストレベルのページです。ここには次のものがあります:
- サンドボックス化 — マスタートグル、検出されたバックエンド、インストールのヒントです。サーバーから取得するのは検出されたバックエンドだけです。後述の注意を参照してください。リセット用のコントロールはありません。
- セマンティック検索 — オンデバイスの埋め込みモデルのライフサイクル（インストール済み、パーセント付きでダウンロード中、未インストール、インストールエラー）です。インストールされるまで、メモリとコード検索はキーワードのみのままです。
- システムの動作 — エージェントの実行中にコンピューターをスリープさせないようにします。
- ログレベル — 障害を再現する前に引き上げます。
- プライバシー — 生の diff 内容をエージェントのモデルへ転送してよいかどうか、およびクラッシュレポートを送信するかどうかです。
よくある失敗
「よくある失敗」というセクション実行が始まらず、アダプターが「見つかりません」と表示する
「実行が始まらず、アダプターが「見つかりません」と表示する」というセクションCLI をサーバーホストにインストールし、モデルプロバイダーページで更新をクリックします。または、CLI を必要としない組み込みアダプターにエージェントを切り替え、同じページでプロバイダーを接続します。
エージェントがプッシュもプルリクエストの作成もできない
「エージェントがプッシュもプルリクエストの作成もできない」というセクションgit またはエージェントが表示した内容を読んでください。Control Center policy: … は、アクションのルールが拒否したか、承認に応答がなかったことを意味します: 設定 → ワークスペース → エージェントの権限 で リモートへプッシュ と プルリクエストを作成 を確認してください。プッシュできる GitHub の資格情報が Control Center にないと git が表示する場合は、そのリポジトリに GitHub App をインストールするか、GitHub を接続してください。
セマンティック検索が役立つ結果を返さない
「セマンティック検索が役立つ結果を返さない」というセクション設定 → サーバー → 診断とプライバシー → セマンティック検索を確認します。埋め込みモデルがインストールされるまで、検索はキーワードのみです。モデルのインストール前に書き込まれた行はバックフィルされないため、その後もキーワードのみのままです。
サーバーがまったく起動しない
「サーバーがまったく起動しない」というセクションネイティブライブラリは必須で、劣化モードはありません。dylib が見つからないと、cc_server は起動を拒否し、エラーの中で問題のファイルを名指しします。scripts/natives/build_natives.sh でネイティブをステージし、サーバーバイナリを再ビルドします。
アクションが黙って拒否される
「アクションが黙って拒否される」というセクション承認者が接続されていない prompt のガードレール判定は、設計上拒否されます。設定 → ワークスペース → エージェントの権限でワークスペースのルールを確認します。