browserwing-admin

BrowserWing 管理スキル

概要

BrowserWing は、次の機能を備えたインテリジェントなブラウザー自動化プラットフォームです。

• ブラウザー自動化スクリプトの記録、作成、再生
• AI を使用してウェブサイトを自律的に探索し、再生可能なスクリプトを生成
• HTTP API または MCP プロトコル経由でスクリプトを実行
• AI 搭載機能向けの LLM 設定を管理

API ベース URL： http://localhost:8080/api/v1

認証： X-BrowserWing-Key: <api-key> ヘッダーまたは Authorization: Bearer <token> を使用します。

---

1. Google Chrome のインストール（前提条件）

BrowserWing を使用するには、ホストマシンに Google Chrome がインストールされている必要があります。

Linux（Debian/Ubuntu）

wget -q -O - https://dl-ssl.google.com/linux/linux_signing_key.pub | sudo apt-key add -
echo "deb [arch=amd64] http://dl.google.com/linux/chrome/deb/ stable main" | sudo tee /etc/apt/sources.list.d/google-chrome.list
sudo apt-get update
sudo apt-get install -y google-chrome-stable

macOS

brew install --cask google-chrome

Windows

https://www.google.com/chrome/ からダウンロードしてインストールします。

インストールの確認

google-chrome --version
# or on macOS:
# /Applications/Google\ Chrome.app/Contents/MacOS/Google\ Chrome --version

リモート Chrome の使用（代替方法）

Chrome がリモートマシン上でデバッグを有効にして実行されている場合：

google-chrome --remote-debugging-port=9222 --remote-debugging-address=0.0.0.0 --no-sandbox

次に、BrowserWing の config.toml を設定します。

[browser]
control_url = 'http://<remote-host>:9222'

---

2. LLM の設定

AI 機能（AI Explorer、エージェントチャット、スマート抽出）を使用するには、LLM の設定が必要です。

LLM 設定の一覧表示

curl -X GET 'http://localhost:8080/api/v1/llm-configs'

LLM 設定の追加

curl -X POST 'http://localhost:8080/api/v1/llm-configs' \
  -H 'Content-Type: application/json' \
  -d '{
    "name": "my-openai",
    "provider": "openai",
    "api_key": "sk-xxx",
    "model": "gpt-4o",
    "base_url": "https://api.openai.com/v1",
    "is_active": true,
    "is_default": true
  }'

対応プロバイダー： openai、anthropic、deepseek、または OpenAI 互換のエンドポイント。

LLM 設定のテスト

curl -X POST 'http://localhost:8080/api/v1/llm-configs/test' \
  -H 'Content-Type: application/json' \
  -d '{"name": "my-openai"}'

LLM 設定の更新

curl -X PUT 'http://localhost:8080/api/v1/llm-configs/<config-id>' \
  -H 'Content-Type: application/json' \
  -d '{"api_key": "sk-new-key", "model": "gpt-4o-mini"}'

LLM 設定の削除

curl -X DELETE 'http://localhost:8080/api/v1/llm-configs/<config-id>'

---

3. AI による自律探索（スクリプトの自動生成）

AI を使用してウェブサイトを閲覧し、タスクを実行して、再生可能なスクリプトを自動生成します。

探索の開始

curl -X POST 'http://localhost:8080/api/v1/ai-explore/start' \
  -H 'Content-Type: application/json' \
  -d '{
    "task_desc": "Go to bilibili.com, search for 'AI', and get the first page of video results",
    "start_url": "https://www.bilibili.com",
    "llm_config_id": "my-openai"
  }'

レスポンス： 追跡用のセッション id が返されます。

探索イベントのストリーミング（SSE）

curl -N 'http://localhost:8080/api/v1/ai-explore/<session-id>/stream'

リアルタイムの Server-Sent Events が返されます：thinking、tool_call、progress、error、script_ready、done。

探索の停止

curl -X POST 'http://localhost:8080/api/v1/ai-explore/<session-id>/stop'

生成されたスクリプトの取得

curl -X GET 'http://localhost:8080/api/v1/ai-explore/<session-id>/script'

生成されたスクリプトの保存

curl -X POST 'http://localhost:8080/api/v1/ai-explore/<session-id>/save'

生成されたスクリプトをローカルのスクリプトライブラリに保存して、後で再生できるようにします。

---

4. スクリプト管理

すべてのスクリプトを一覧表示

curl -X GET 'http://localhost:8080/api/v1/scripts'

id、name、description、actions、tags、group などを含む、すべてのローカルスクリプトが返されます。

スクリプトの詳細を取得

curl -X GET 'http://localhost:8080/api/v1/scripts/<script-id>'

スクリプトのスキーマ／概要を取得

curl -X GET 'http://localhost:8080/api/v1/scripts/summary'

名前、説明、入力パラメーター（変数）、アクション数を含む、すべてのスクリプトの簡潔な概要が返されます。プログラムからの検索に便利です。

新しいスクリプトの作成

curl -X POST 'http://localhost:8080/api/v1/scripts' \
  -H 'Content-Type: application/json' \
  -d '{
    "name": "Search Bilibili",
    "description": "Search for a keyword on Bilibili",
    "url": "https://www.bilibili.com",
    "actions": [
      {"type": "navigate", "url": "https://www.bilibili.com"},
      {"type": "click", "identifier": ".nav-search-input"},
      {"type": "type", "identifier": ".nav-search-input", "value": "${keyword}"},
      {"type": "press_key", "key": "Enter"},
      {"type": "wait", "timeout": 3}
    ]
  }'

変数： アクションの値には ${variable_name} 形式を使用します。スクリプトの実行時に、これらが入力パラメーターになります。

スクリプトの更新

curl -X PUT 'http://localhost:8080/api/v1/scripts/<script-id>' \
  -H 'Content-Type: application/json' \
  -d '{"name": "Updated Name", "description": "Updated description"}'

スクリプトの削除

curl -X DELETE 'http://localhost:8080/api/v1/scripts/<script-id>'

スクリプトをスキルとしてエクスポート（SKILL.md に変換）

1 つ以上のスクリプトを SKILL.md ファイルに変換し、AI エージェント（Claude、Cursor など）にインポートできるようにします。これにより、ほかの AI エージェントが BrowserWing のスクリプトを検出して実行できるようになります。

選択したスクリプトをエクスポート

curl -X POST 'http://localhost:8080/api/v1/scripts/export/skill' \
  -H 'Content-Type: application/json' \
  -d '{
    "script_ids": ["script-id-1", "script-id-2", "script-id-3"]
  }'

複数のスクリプトを、それらすべてのアクション、変数、説明を含む単一の SKILL.md にまとめます。

すべてのスクリプトをエクスポート

curl -X POST 'http://localhost:8080/api/v1/scripts/export/skill' \
  -H 'Content-Type: application/json' \
  -d '{"script_ids": []}'

空の script_ids 配列を渡すと、すべてのスクリプトを 1 つの SKILL.md にエクスポートします。

Executor スキルをエクスポート（ブラウザー制御 API）

curl -X GET 'http://localhost:8080/api/v1/executor/export/skill'

低レベルのブラウザー自動化 API をスキルとしてエクスポートし、AI エージェントがブラウザーを直接制御（移動、クリック、入力、抽出など）できるようにします。

ワークフロー：スクリプト → スキル → AI エージェント

1. Create scripts (manually, by recording, or via AI exploration)
2. Export them as SKILL.md: POST /scripts/export/skill
3. Place the SKILL.md in your AI agent's skill directory
4. The AI agent can now discover and call your scripts via POST /scripts/<id>/play

---

5. スクリプトの実行

ID を指定してスクリプトを実行

curl -X POST 'http://localhost:8080/api/v1/scripts/<script-id>/play' \
  -H 'Content-Type: application/json' \
  -d '{
    "variables": {
      "keyword": "deepseek"
    }
  }'

変数： スクリプトのアクションで定義されている ${variable_name} プレースホルダーに値を渡します。

再生結果（抽出データ）の取得

curl -X GET 'http://localhost:8080/api/v1/scripts/play/result'

最後にスクリプトを実行した際に抽出されたデータが返されます（例：execute_js アクションでスクレイピングされたコンテンツ）。

スクリプト実行履歴の一覧表示

curl -X GET 'http://localhost:8080/api/v1/script-executions?page=1&page_size=20'

---

6. スクリプトマーケットプレイス（リモートスクリプト）

注：リモートスクリプトのマーケットプレイス機能は開発中です。次の API はまだ利用できない場合があります。

マーケットプレイスを閲覧

# TODO: curl -X GET 'http://localhost:8080/api/v1/marketplace/scripts?category=search&page=1'

マーケットプレイスからスクリプトをインストール

# TODO: curl -X POST 'http://localhost:8080/api/v1/marketplace/scripts/<remote-id>/install'

---

7. MCP（Model Context Protocol）連携

BrowserWing は、AI エージェント連携用の MCP 互換エンドポイントを提供します。

MCP SSE エンドポイント

SSE:     http://localhost:8080/api/v1/mcp/sse
Message: http://localhost:8080/api/v1/mcp/sse_message

MCP のステータスを確認する

curl -X GET 'http://localhost:8080/api/v1/mcp/status'

MCP コマンドを一覧表示する

curl -X GET 'http://localhost:8080/api/v1/mcp/commands'

登録されているすべての MCP ツール（ブラウザーツールとスクリプトベースのカスタムコマンド）が表示されます。

---

8. プロンプト管理

システムプロンプトは AI の動作を制御します。ユーザーはカスタマイズできます。

すべてのプロンプトを一覧表示する

curl -X GET 'http://localhost:8080/api/v1/prompts'

特定のプロンプトを取得する

curl -X GET 'http://localhost:8080/api/v1/prompts/<prompt-id>'

システムプロンプト ID： system-extractor、system-formfiller、system-aiagent、system-get-mcp-info、system-ai-explorer

プロンプトを更新する

curl -X PUT 'http://localhost:8080/api/v1/prompts/<prompt-id>' \
  -H 'Content-Type: application/json' \
  -d '{"content": "Your custom prompt content here..."}'

---

9. ブラウザーインスタンス管理

ブラウザーインスタンスを一覧表示する

curl -X GET 'http://localhost:8080/api/v1/browser/instances'

ブラウザーインスタンスを起動する

curl -X POST 'http://localhost:8080/api/v1/browser/instances/<id>/start'

ブラウザーインスタンスを停止する

curl -X POST 'http://localhost:8080/api/v1/browser/instances/<id>/stop'

---

10. Cookie 管理

ブラウザーの Cookie を管理します。保存された Cookie の表示、Cookie のインポート（認証済みセッションなど）、Cookie の削除ができます。

保存済み Cookie を表示する

curl -X GET 'http://localhost:8080/api/v1/cookies/browser'

browser ストア ID（デフォルトのストア）に保存されているすべての Cookie を返します。必要に応じて、browser をカスタムストア ID に置き換えてください。

現在のブラウザー Cookie を保存する

curl -X POST 'http://localhost:8080/api/v1/browser/cookies/save'

現在のブラウザーセッションのすべての Cookie をデータベースに保存します。ブラウザーが起動している必要があります。

Cookie をインポートする

curl -X POST 'http://localhost:8080/api/v1/browser/cookies/import' \
  -H 'Content-Type: application/json' \
  -d '{
    "url": "https://example.com",
    "cookies": [
      {
        "name": "session_id",
        "value": "abc123",
        "domain": ".example.com",
        "path": "/",
        "secure": true,
        "httpOnly": true,
        "sameSite": "Lax",
        "expires": 1735689600
      }
    ]
  }'

フィールド： name と value は必須です。domain、path、secure、httpOnly、sameSite、expires は任意です（path のデフォルト値は / です）。

単一の Cookie を削除する

curl -X POST 'http://localhost:8080/api/v1/browser/cookies/delete' \
  -H 'Content-Type: application/json' \
  -d '{
    "id": "browser",
    "name": "session_id",
    "domain": ".example.com",
    "path": "/"
  }'

指定された Cookie ストアから、name + domain + path で識別される特定の Cookie を削除します。

Cookie を一括削除する

curl -X POST 'http://localhost:8080/api/v1/browser/cookies/batch/delete' \
  -H 'Content-Type: application/json' \
  -d '{
    "id": "browser",
    "cookies": [
      {"name": "session_id", "domain": ".example.com", "path": "/"},
      {"name": "tracking", "domain": ".example.com", "path": "/"}
    ]
  }'

複数の Cookie を一度に削除します。各 Cookie は name + domain + path で識別されます。

---

11. トラブルシューティング

問題が発生した場合は、次の手順で原因を特定してください。

サービスの状態を確認する

curl -X GET 'http://localhost:8080/health'

ログを表示する

BrowserWing のログは、config.toml の [log] file で設定されているパスに保存されます。 デフォルトの場所：./log/browserwing.log

# View last 100 lines of logs
tail -n 100 ./log/browserwing.log

# Follow logs in real-time
tail -f ./log/browserwing.log

# Search for errors
grep -i 'error\|fail\|panic' ./log/browserwing.log | tail -20

よくある問題

1. ブラウザーが起動しない

• Google Chrome がインストールされていることを確認します：google-chrome --version
• Linux では、--no-sandbox フラグを指定するか、root 以外のユーザーとして実行してください
• ユーザーデータディレクトリに Chrome のロックファイル（SingletonLock、lockfile）が残っていないか確認します
• リモート Chrome を使用している場合は、config.toml の control_url を確認します
• 実行中の Chrome プロセスを終了してみてください：pkill -f chrome

2. AI 機能が動作しない

• LLM の設定が完了し、有効になっていることを確認します：GET /api/v1/llm-configs
• LLM の接続をテストします：POST /api/v1/llm-configs/test
• API キーが有効で、モデルが利用可能であることを確認します
• LLM 関連のエラーがないかログを確認します

3. スクリプトの実行に失敗する

• スクリプトが存在することを確認します：GET /api/v1/scripts/<id>
• ブラウザーが起動していることを確認します：GET /api/v1/browser/instances
• 実行履歴を確認します：GET /api/v1/script-executions
• 再生リクエストで、必須の ${variables} がすべて指定されていることを確認します
• 対象のウェブサイトが変更されている可能性があります。スクリプトを再記録するか、更新してみてください

4. ページ要素が見つからない

• GET /api/v1/executor/snapshot を使用して、現在のページ要素を確認します
• 要素のセレクターが動的な場合があります。スナップショットの RefID を優先してください
• ページの読み込みが完了していない可能性があります。待機アクションを使用してください

5. ポートの競合

• BrowserWing のデフォルトポート：8080（config.toml の [server] port で変更可能）
• Chrome のデバッグポート：9222（または control_url で設定したポート）
• ポートの使用状況を確認します：lsof -i :<port> または netstat -tlnp | grep <port>

---

クイックスタートのワークフロー

以下の手順で利用を開始できます：

1. Install Chrome (see Section 1)
2. Start BrowserWing: ./browserwing --port 8080
3. Add an LLM config (see Section 2)
4. Choose your approach:
   a) AI Exploration: POST /ai-explore/start with a task description
   b) Manual Creation: POST /scripts with actions array
   c) Web UI: Open http://<host>:8080 in browser to use the visual editor
5. Execute scripts: POST /scripts/<id>/play
6. View results: GET /scripts/play/result

API クイックリファレンス

カテゴリー	メソッド	エンドポイント	説明
ヘルスチェック	GET	/health	サービスの状態を確認
LLM	GET	/api/v1/llm-configs	LLM 設定の一覧を取得
LLM	POST	/api/v1/llm-configs	LLM 設定を追加
LLM	POST	/api/v1/llm-configs/test	LLM 接続をテスト
探索	POST	/api/v1/ai-explore/start	AI 探索を開始
探索	GET	/api/v1/ai-explore/:id/stream	探索イベントをストリーミング
探索	POST	/api/v1/ai-explore/:id/stop	探索を停止
探索	POST	/api/v1/ai-explore/:id/save	生成したスクリプトを保存
スクリプト	GET	/api/v1/scripts	すべてのスクリプトの一覧を取得
スクリプト	GET	/api/v1/scripts/:id	スクリプトの詳細を取得
スクリプト	POST	/api/v1/scripts	新しいスクリプトを作成
スクリプト	PUT	/api/v1/scripts/:id	スクリプトを更新
スクリプト	DELETE	/api/v1/scripts/:id	スクリプトを削除
スクリプト	GET	/api/v1/scripts/summary	スクリプトのスキーマ／概要を取得
スクリプト	POST	/api/v1/scripts/export/skill	スクリプトを SKILL.md としてエクスポート
実行	POST	/api/v1/scripts/:id/play	スクリプトを実行
実行	GET	/api/v1/scripts/play/result	実行結果データを取得
実行	GET	/api/v1/script-executions	実行履歴の一覧を取得
プロンプト	GET	/api/v1/prompts	すべてのプロンプトの一覧を取得
プロンプト	PUT	/api/v1/prompts/:id	プロンプトを更新
ブラウザー	GET	/api/v1/browser/instances	ブラウザーインスタンスの一覧を取得
Cookie	GET	/api/v1/cookies/:id	保存済み Cookie を表示
Cookie	POST	/api/v1/browser/cookies/save	現在のブラウザー Cookie を保存
Cookie	POST	/api/v1/browser/cookies/import	Cookie をインポート
Cookie	POST	/api/v1/browser/cookies/delete	単一の Cookie を削除
Cookie	POST	/api/v1/browser/cookies/batch/delete	Cookie を一括削除
MCP	GET	/api/v1/mcp/status	MCP サーバーの状態
MCP	GET	/api/v1/mcp/commands	MCP コマンドの一覧を取得
エグゼキューター	GET	/api/v1/executor/help	エグゼキューター API のヘルプ
エグゼキューター	GET	/api/v1/executor/snapshot	ページのアクセシビリティスナップショット
スキル	GET	/api/v1/executor/export/skill	エグゼキューターのスキルをエクスポート
スキル	GET	/api/v1/admin/export/skill	この管理者スキルをエクスポート