---
sidebar_position: 5
title: ローカルClaude Code + Playwright CLIでブラウザ自動化エージェントを作る
description: Claude Code + Playwright CLIで安定したブラウザ自動化環境を構築する方法
hide_table_of_contents: false
displayed_sidebar: null
image: ./banner.png
---

# ローカルClaude Code + Playwright CLIで「自分だけのブラウザ自動化エージェント」を作る

## はじめに

[前回の記事](/tech/dgx-spark-claude-code-local)で、Claude Codeをローカルで動かす方法を紹介しました。

今回はその続き。**Playwright CLI**を組み合わせて、ブラウザを自動操作できるエージェントを作ります。

### 何ができるようになる？

- ✅ 「このサイトの情報を集めて」→ 自動でスクレイピング
- ✅ 「ログインしてデータをダウンロード」→ 認証も自動
- ✅ 「このフォームに入力して送信」→ ブラウザ操作を自動化
- ✅ 「E2Eテストを書いて実行」→ テストコード生成＆実行

しかも**完全ローカル**。データはどこにも送られません。

## なぜMCPではなくCLI？

ブラウザ自動化には2つの方式があります：

| 方式 | 特徴 | 成功率 |
|------|------|--------|
| Playwright MCP | リアルタイム状態管理 | △ 不安定なことがある |
| **Playwright CLI + SKILLS** | トークン効率が良い | **◎ 安定して動く** |

:::tip CLI方式をおすすめする理由
1. **トークン効率が良い** - 巨大なツールスキーマやアクセシビリティツリーをコンテキストに読み込まない
2. **安定している** - シンプルなコマンド実行なので失敗しにくい
3. **デバッグしやすい** - 同じコマンドを手動でも実行できる
:::

## 前提条件

- [Claude Codeのローカル環境](/tech/dgx-spark-claude-code-local)が動作済み
- Node.js 18以上

## セットアップ

### Step 1: Playwright CLIをインストール

```bash
npm install -g @playwright/cli@latest
```

確認：

```bash
playwright-cli --help
```

### Step 2: SKILLSをインストール

```bash
playwright-cli install --skills
```

これでClaude Codeが自動的にPlaywright CLIのスキルを認識します。

### Step 3: 動作確認

```bash
claude-local  # ローカルモデルで起動
```

Claude Codeで：


## スキルを使わせるコツ

:::warning Claude Codeがplaywright-cliを使ってくれない？
デフォルトではClaude Codeは`playwright-cli`の存在を知りません。以下の方法で認識させましょう。
:::

### 方法1: 明示的に指示する

プロンプトで**明示的に**`playwright-cli`を指定します：

```text
playwright-cli を使って https://example.com のスクリーンショットを撮って
```

最初に「`playwright-cli --help` を確認して」と言うのも効果的：

```text
playwright-cli --help を確認して、そのコマンドを使ってブラウザ操作をして
```

### 方法2: CLAUDE.mdにスキルを記述

プロジェクトのルートに `CLAUDE.md` を作成し、スキルを記述します：

```markdown title="CLAUDE.md"
# プロジェクト設定

## ブラウザ操作

このプロジェクトではブラウザ操作に **playwright-cli** を使用してください。
Web検索やFetchではなく、必ず playwright-cli コマンドを使ってください。

利用可能なコマンド:
- playwright-cli open <url> - ブラウザを開く
- playwright-cli snapshot - ページ構造を取得
- playwright-cli click <ref> - 要素をクリック
- playwright-cli type <text> - テキスト入力
- playwright-cli screenshot - スクリーンショット
```

### 方法3: セッション開始時に宣言

Claude Codeを起動したら、最初にこう言います：

```text
このセッションではブラウザ操作に playwright-cli を使います。
playwright-cli --help で使い方を確認してください。
```

これでClaude Codeが`playwright-cli`の存在を認識し、以降のブラウザ操作で使ってくれます。

```text
> playwright-cli --help を確認して、https://example.com のスクリーンショットを撮って
```

## 公式SKILLSリファレンス

Playwright CLIには公式のSKILLSファイルがあります。以下は主要なコマンド：

### Quick Start

```bash
playwright-cli open                        # ブラウザを開く
playwright-cli goto https://playwright.dev # URLに移動
playwright-cli click e15                   # 要素refでクリック
playwright-cli type "page.click"           # テキスト入力
playwright-cli press Enter                 # Enterキー
playwright-cli screenshot                  # スクリーンショット
playwright-cli close                       # ブラウザを閉じる
```

### Core Commands

```bash
playwright-cli open https://example.com     # ページを開く
playwright-cli goto https://example.com     # URLに移動
playwright-cli type "検索キーワード"          # テキスト入力
playwright-cli click e3                      # 要素をクリック（refで指定）
playwright-cli fill e5 "user@example.com"   # 入力欄に値を設定
playwright-cli select e9 "option-value"     # セレクトボックス選択
playwright-cli check e12                     # チェックボックスON
playwright-cli uncheck e12                   # チェックボックスOFF
playwright-cli upload ./document.pdf        # ファイルアップロード
playwright-cli snapshot                      # ページ構造を取得
playwright-cli screenshot                    # スクリーンショット
```

### Navigation

```bash
playwright-cli go-back       # 戻る
playwright-cli go-forward    # 進む
playwright-cli reload        # リロード
```

### Keyboard

```bash
playwright-cli press Enter
playwright-cli press ArrowDown
playwright-cli keydown Shift
playwright-cli keyup Shift
```

### Tabs

```bash
playwright-cli tab-list       # タブ一覧
playwright-cli tab-new        # 新しいタブ
playwright-cli tab-new https://example.com  # URLを指定して新しいタブ
playwright-cli tab-select 0   # タブを選択
playwright-cli tab-close      # タブを閉じる
```

### Storage（Cookie/LocalStorage）

```bash
# 状態の保存・読み込み
playwright-cli state-save auth.json
playwright-cli state-load auth.json

# Cookie操作
playwright-cli cookie-list
playwright-cli cookie-get session_id
playwright-cli cookie-set session_id abc123
playwright-cli cookie-clear

# LocalStorage操作
playwright-cli localstorage-list
playwright-cli localstorage-get theme
playwright-cli localstorage-set theme dark
```

### Sessions

```bash
playwright-cli list                            # セッション一覧
playwright-cli -s=myproject open https://example.com  # 特定セッションで操作
playwright-cli open --persistent               # 永続セッション（Cookie保存）
playwright-cli close-all                       # 全セッション終了
playwright-cli kill-all                        # 強制終了
```

### DevTools

```bash
playwright-cli console       # コンソールログ
playwright-cli network       # ネットワークリクエスト
playwright-cli tracing-start # トレース開始
playwright-cli tracing-stop  # トレース終了
playwright-cli video-start   # 動画記録開始
playwright-cli video-stop video.webm  # 動画記録終了
```

## Snapshots

各コマンド実行後、Playwright CLIはページの**スナップショット**を返します：

```text
> playwright-cli goto https://example.com
Page URL: https://example.com/
Page Title: Example Domain
Snapshot: .playwright-cli/page-2026-02-19T13-30-00.yml
```

スナップショットには要素の**ref（e1, e2, e15など）** が含まれており、これを使ってクリックや入力を行います。

## 実践例

### 例1: フォーム入力

```bash
playwright-cli open https://example.com/form
playwright-cli snapshot
playwright-cli fill e1 "user@example.com"
playwright-cli fill e2 "password123"
playwright-cli click e3
playwright-cli snapshot
playwright-cli close
```

### 例2: 複数タブ操作

```bash
playwright-cli open https://example.com
playwright-cli tab-new https://example.com/other
playwright-cli tab-list
playwright-cli tab-select 0
playwright-cli snapshot
playwright-cli close
```

### 例3: 認証状態の保存

```bash
# ログイン後に状態を保存
playwright-cli state-save auth.json

# 次回は状態を読み込んでスキップ
playwright-cli open --persistent
playwright-cli state-load auth.json
```

## トラブルシューティング

### ブラウザが起動しない

```bash
npx playwright install chromium
```

### セッションが残っている

```bash
playwright-cli kill-all
```

### 要素が見つからない

```bash
playwright-cli snapshot
```

スナップショットで要素のrefを確認。

## まとめ

**ポイント**：

1. **CLI方式を使う** - MCPより安定している
2. **公式SKILLSを使う** - `playwright-cli install --skills`
3. **snapshotでref確認** - 要素はe1, e2などのrefで指定
4. **セッションを活用** - ログイン状態を保持

## 参考リンク

- [Playwright CLI（Microsoft）](https://github.com/microsoft/playwright-cli)
- [公式SKILLS](https://raw.githubusercontent.com/microsoft/playwright-cli/main/skills/playwright-cli/SKILL.md)
- [Playwright公式](https://playwright.dev/)
- [前回の記事: Claude Codeローカル化](/tech/dgx-spark-claude-code-local)

---

*この記事は2026年2月時点の情報です。*