Claude Code DesktopアプリプレビューでWebアプリを検証する

Claude Code DesktopのアプリプレビューはBrowserペインで動く

Claude Code DesktopのCodeタブは、コードを編集するたびに動作を自分で確認します。devサーバーを起動し、Browserペインでアプリを開き、スクリーンショットを撮ってDOM(ページの構造)を調べ、必要ならフォームに入力してボタンをクリックする。この一連の検証を、フロントエンドのWebアプリだけでなくバックエンドのAPIサーバーでも行います。APIエンドポイントを叩き、サーバーログを見て、見つかった問題をその場で直す動きまで組み込まれています。

多くの場合、ファイルを編集した時点でClaudeが自動的にサーバーを起動します。手動でプレビューを頼むこともできます。Browserペインからは、サーバーの起動・停止、設定の編集、全サーバーの一括停止も操作できます。

この仕組みの要点は、次の3つの設定に集約されます。

症状から探す — どの設定を触ればよいか

プレビューまわりの困りごとは、原因がほぼ設定の3か所に分かれます。症状を起点に、触る場所を引き当てるための対応表です。

プレビューの検証をスクリプトから自動で回したい場合は、設定では解決しません。DesktopのCodeタブには、CLIの --print やAgent SDKに当たるスクリプト実行の手段がないため、CIや定期処理にはCLI側の機能を使います。DesktopとCLIの機能差はClaude Code Desktopとはに表で整理しています。

devサーバーだけでなく静的ファイルも開ける

Browserペインが表示できるのはdevサーバーだけではありません。プロジェクト内の静的HTMLファイル、PDF、画像、動画も同じペインで開けます。チャット内でHTML・PDF・画像・動画のパスをクリックすると、そのままBrowserペインに表示されます。

ログイン状態を保ったまま開発を続けたいときは、サーバードロップダウンでPersist sessions(セッションを保持)を選びます。サーバーを再起動してもCookieとlocalStorageが引き継がれ、開発中に毎回ログインし直す手間がなくなります。保存したセッションデータを消したいとき、またはBrowser自体を無効にしたいときは、Settings → Claude Codeのトグルで操作します。

Browserペインはタブ切り替え式のブラウザーでもあり、実行中のアプリの隣でドキュメントやIssueトラッカーを開いておけます。macOSはCmd+Shift+B、WindowsはCtrl+Shift+Bで呼び出せます。メニューのViewsから選ぶこともできます。

チャット内の外部リンクをクリックすると、「Open in app」と「Default browser」を選ぶチューザーが出ます。前者はBrowserペイン、後者は普段使いのブラウザーで開きます。CmdキーまたはCtrlキーを押しながらクリックすると、システムのブラウザーで直接開きます。ペイン内ではGoogle OAuthのようなポップアップ型のサインインも行えます。

Browserペインか、Chrome拡張機能か

BrowserペインとChrome拡張機能は、どちらもブラウザー操作をClaudeに任せる手段です。違いは「誰の身元で動くか」に出ます。

なお、ブラウザー以外も含め、Claudeが使う手段には優先順位があります。コネクターがあればコネクター、シェルコマンドならBashです。ブラウザー作業でChrome拡張機能が設定済みならChrome拡張機能、iOSアプリならiOS Simulatorペインを使います。そのどれでもなければコンピューター操作(computer use)で、最も広く、最も遅い手段と位置づけられています。

computer useは既定でオフで、Settingsで有効にしたときだけ使われます。macOSとWindowsのリサーチプレビューで、ProまたはMaxプランが必要です。TeamとEnterpriseでは使えません。

外部サイトを開くときは個別に承認する

Browserペインでdevサーバー以外の外部サイトを開くと、Claudeが最初にそのページを操作する時点で承認カードが表示されます。選べるのは3つです。

• Allow once: その場限りで許可し、何も保存しない
• Always allow: その端末でそのサイトを常に許可する(Settingsから取り消し可能)
• Deny: 拒否する

承認はサイトごとに必要で、サブドメインが変わればそのつど別扱いになります。一方、ローカルのdevサーバーやプロジェクト内のファイルは承認の対象外です。Auto-verifyはプロンプトなしで動き続けます。

承認済みのサイトであっても、Claudeは購入操作・アカウント作成・CAPTCHA突破を利用者の指示なしには行いません。書き込み系の操作(クリックや入力)は、どの権限モードでもauto modeと同じ安全性分類器がチェックします。疑わしいと判定されれば、モードにかかわらず改めて許可を求められます。Auto modeとBypass permissions以外の権限モードでは、新しいサイトへ移動する前にドメインの許可リストも確認されます。

組織で外部サイトへのアクセスを制限したい場合は、管理設定を2つ使い分けます。

どちらもローカルのdevサーバーやファイルプレビューには影響しません。Chrome拡張機能向けにサイトの許可リスト・ブロックリストをすでに設定している組織では、Browserペインも同じリストに従います。

Auto-verify — Claudeが自分の変更を自動で検証する仕組み

autoVerify が有効な間、Claudeはファイルを編集するたびに変更を自動で検証します。スクリーンショットを撮り、エラーが出ていないかを確認し、動作を確かめてから応答を完了する流れです。既定でオンです。

無効にしたい場合はプロジェクトの .claude/launch.json に "autoVerify": false を追加するか、サーバードロップダウンメニューから切り替えます。

{
  "version": "0.0.1",
  "autoVerify": false,
  "configurations": [
    {
      "name": "my-app",
      "runtimeExecutable": "npm",
      "runtimeArgs": ["run", "dev"],
      "port": 3000
    }
  ]
}

無効化してもプレビュー用のツール自体は使えるままです。「編集のたびに自動で」という部分だけがオフになり、必要なタイミングでClaudeに検証を頼む使い方に切り替わります。

launch.jsonで起動コマンドをカスタマイズする

Claudeはセッション開始時に選んだフォルダーのdevサーバー構成を自動で検出し、フォルダー直下の .claude/launch.json に設定を保存します。プレビューはこのフォルダーを作業ディレクトリとします。親フォルダーを選んでセッションを始めた場合、サブフォルダー側のdevサーバーは自動検出されません。

サブフォルダーのサーバーを扱うには、そのフォルダーで直接セッションを始めるか、設定を手動で追加します。npm run dev の代わりに yarn dev を使いたい、ポート番号を変えたいといったカスタマイズも同じ要領です。ファイルを直接編集するか、サーバードロップダウンのEdit configurationからコードエディターで開きます。ファイルはコメント付きJSONに対応しています。

たとえばYarnで動くNext.jsなら、次の1項目で足ります。

{
  "version": "0.0.1",
  "configurations": [
    {
      "name": "web",
      "runtimeExecutable": "yarn",
      "runtimeArgs": ["dev"],
      "port": 3000
    }
  ]
}

configurations は配列なので、複数のサーバーを1つのプロジェクトで定義できます。

設定フィールドの一覧

configurations の各項目には次のフィールドを指定できます。

runtimeExecutable はパッケージマネージャー経由でサーバーを起動する場合に使います。単体のNode.jsスクリプトを node で直接動かしたいときは、代わりに program を使います。"program": "server.js" は node server.js として動き、args で追加のフラグを渡せます。

シークレットを渡す用途では、env ではなくローカルセッションの環境変数エディターを使います。設定ファイル自体がリポジトリにコミットされる前提のためです。

urlで開くアドレスを変える

既定では、プレビューは http://localhost:<port> を開きます。ローカルHTTPSが必要なサーバー、*.localhost サブドメインを使うアプリ、リダイレクト経由でサインインさせるアプリでは url を指定します。

{
  "version": "0.0.1",
  "configurations": [
    {
      "name": "my-app",
      "runtimeExecutable": "npm",
      "runtimeArgs": ["run", "dev"],
      "port": 8443,
      "url": "https://localhost:8443"
    }
  ]
}

localhost、任意の *.localhost サブドメイン、127.0.0.1、::1 はそのまま開きます。ただしローカルホスト向けの url は、サーバーのオリジンだけで書く決まりです。パスやクエリは含められず、ポート番号も port と一致させます。特定のページを見せたいときは、プレビューが開いたあとにClaudeへそのページへ移動するよう頼みます。この決まりに反する設定は、該当のURLと修正方法を示す設定エラーとして報告されます。

それ以外のアドレスは、初回に開くときに許可を求められ、パスを含められます。Always allowを選べば以降は聞かれません。組織が外部サイトを制限している場合は、その制限が優先されます。url は http か https で、ユーザー名とパスワードを含めることはできません。

すでに自分で起動しているサーバーにプレビューだけ接続したい場合は、コマンドを書かず url だけを設定します。Claudeは新しいサーバーを起動せず、動いているサーバーに接続します。

{
  "version": "0.0.1",
  "configurations": [
    {
      "name": "my-app",
      "url": "https://app.localhost:3000"
    }
  ]
}

ポートが競合したときの挙動

autoPort フィールドは、指定したポートがすでに使われていたときの挙動を決めます。

Claudeが別のポートを割り当てた場合、割り当てたポート番号は PORT 環境変数としてサーバーに渡されます。サーバーが PORT を読む作りでなければ、割り当てられたポートでは待ち受けません。

モノレポでフロントエンドとAPIサーバーを両方定義するなら、フロントエンドを autoPort: true で空きポートに逃がします。ポート固定が必要なAPIサーバー(OAuthコールバックなど)だけ autoPort: false にする、という使い分けが典型的です。

{
  "version": "0.0.1",
  "configurations": [
    {
      "name": "frontend",
      "runtimeExecutable": "npm",
      "runtimeArgs": ["run", "dev"],
      "cwd": "apps/web",
      "port": 3000,
      "autoPort": true
    },
    {
      "name": "api",
      "runtimeExecutable": "npm",
      "runtimeArgs": ["run", "start"],
      "cwd": "server",
      "port": 8080,
      "env": { "NODE_ENV": "development" },
      "autoPort": false
    }
  ]
}

まとめ

プレビューの設定は、launch.jsonで「どう起動するか」、autoVerifyで「いつ検証するか」、承認カードで「どこまで外へ出すか」の3つを分けて考えると迷いません。自動検出のまま動くプロジェクトでは、手を入れるのは症状が出てからで足ります。

Codeタブの基本操作はClaude Desktopとは、ネイティブデスクトップアプリをRustとフロントエンドで組む場合はClaude CodeでTauriアプリを開発するも参考になります。