openbrowser-ai

OpenBrowser

コードで動かす、AI によるブラウザー自動化。

---

**保存済み Cookie やスケジュールタスクを管理できるクラウドダッシュボードは、ホスト版で利用できます。先行アクセスのウェイトリストに登録してください：https://openbrowser.me**：

https://github.com/user-attachments/assets/b17f97f3-f9f8-4707-8e39-abbbbe1a693b

Walmart の商品情報を自動スクレイピング：

https://github.com/user-attachments/assets/c517c739-9199-47b0-bac7-c2c642a21094

OpenBrowserAI による航空券の自動予約：

https://github.com/user-attachments/assets/632128f6-3d09-497f-9e7d-e29b9cb65e0f

OpenBrowserAI によるフォームの自動入力：

https://github.com/user-attachments/assets/16f7ef1a-beb1-45e2-a733-9592536e0ef7

CodeAgent と CDP（Chrome DevTools Protocol）を使用した、AI によるブラウザー自動化

OpenBrowser は、インテリジェントなブラウザー自動化のためのフレームワークです。CDP との直接通信と CodeAgent アーキテクチャを組み合わせており、LLM が永続的な名前空間で実行される Python コードを記述することで、ウェブページを自律的に移動、操作し、情報を抽出します。

目次

• ドキュメント
• 主な機能
• インストール
• クイックスタート
• 設定
• 対応 LLM プロバイダー
• Claude Code プラグイン
• Codex
• OpenCode
• OpenClaw
• MCP サーバー
• ベンチマーク：トークン効率
• CLI の使い方
• プロジェクト構成
• バックエンドとフロントエンドのデプロイ
• テスト
• 研究：ブラウザーエージェント向け強化学習ファインチューニング
• コントリビューション
• ライセンス
• お問い合わせ

ドキュメント

詳細なドキュメント：https://docs.openbrowser.me

主な機能

• CodeAgent アーキテクチャ - LLM が、ブラウザー自動化のために永続的な Jupyter のような名前空間で Python コードを記述します
• 生の CDP 通信 - 最大限の制御性と速度を実現する、Chrome DevTools Protocol との直接通信
• ビジョン対応 - ページを視覚的に理解するためのスクリーンショット分析
• 15 種類の LLM プロバイダー - OpenAI、Anthropic、Google、Groq、AWS Bedrock、Azure、Ollama、DeepSeek、Cerebras、OpenRouter、OCI など
• MCP サーバー - Claude Desktop、Claude Code、Codex、OpenCode、その他の AI アシスタント向けの Model Context Protocol。再利用可能な保存済みログインセッションにも対応します
• CLI デーモン - Bash からコードを直接実行する -c フラグ、保存済みログイン状態、10 分後の自動シャットダウンに対応した永続的なブラウザーデーモン
• ワークフローの記録 - ブラウザーセッションを記録、再生し、Jupyter ノートブックまたは API クローラーコードとしてエクスポートします
• 動画の記録 - ffmpeg を使用してブラウザーセッションを動画ファイルとして記録します
• クラウドプラットフォーム - リアルタイム VNC ストリーミング、保存済みログイン（KMS 暗号化）、スケジュールされたワークフロー（EventBridge + SQS）、メール通知（SES）を備えたフルスタック Web UI
• プラグインシステム - 7 つのガイド付きスキル（詳細調査、Web スクレイピング、フォーム入力、E2E テスト、ページ分析、アクセシビリティ監査、ファイルダウンロード）を備えた Claude Code プラグイン

インストール

クイックインストール（macOS / Linux）

curl -fsSL https://raw.githubusercontent.com/billy-enrizky/openbrowser-ai/main/install.sh | sh

クイックインストール（Windows PowerShell）

irm https://raw.githubusercontent.com/billy-enrizky/openbrowser-ai/main/install.ps1 | iex

uv、pipx、または pip を検出し、OpenBrowser を自動的にインストールします。

sudo を使わずに ~/.local/bin にインストールする場合：

curl -fsSL https://raw.githubusercontent.com/billy-enrizky/openbrowser-ai/main/install.sh | sh -s -- --local

Homebrew（macOS / Linux）

brew tap billy-enrizky/openbrowser
brew install openbrowser-ai

pip

pip install openbrowser-ai

uv（推奨）

uv pip install openbrowser-ai

uvx（インストール不要）

インストールせずに直接実行できます。uvx がパッケージを自動的にダウンロードしてキャッシュします：

# MCP server mode
uvx openbrowser-ai --mcp

# CLI daemon mode
uvx openbrowser-ai -c "await navigate('https://example.com')"

pipx

pipx install openbrowser-ai

ソースからインストール

git clone https://github.com/billy-enrizky/openbrowser-ai.git
cd openbrowser-ai
uv pip install -e ".[agent]"

オプションの依存関係

pip install openbrowser-ai[agent]      # LLM agent support (langgraph, langchain, litellm)
pip install openbrowser-ai[all]        # All LLM providers
pip install openbrowser-ai[anthropic]  # Anthropic Claude
pip install openbrowser-ai[groq]       # Groq
pip install openbrowser-ai[ollama]     # Ollama (local models)
pip install openbrowser-ai[aws]        # AWS Bedrock
pip install openbrowser-ai[azure]      # Azure OpenAI
pip install openbrowser-ai[video]      # Video recording support

ブラウザーを別途インストールする必要はありません。 OpenBrowser は、インストール済みの Chromium ベースのブラウザー（Chrome、Edge、Brave、Chromium）を自動検出し、そのまま使用します。見つからず、uvx を利用できる場合は、初回実行時に Chromium が自動的にインストールされます。手動で事前にインストールする場合（uvx が必要）：openbrowser-ai install

クイックスタート

基本的な使い方

import asyncio
from openbrowser import CodeAgent, ChatGoogle

async def main():
    agent = CodeAgent(
        task="Go to google.com and search for 'Python tutorials'",
        llm=ChatGoogle(model="gemini-3-flash"),
    )

    result = await agent.run()
    print(f"Result: {result}")

asyncio.run(main())

さまざまな LLM プロバイダーを使う

from openbrowser import CodeAgent, ChatOpenAI, ChatAnthropic, ChatGoogle

# OpenAI
agent = CodeAgent(task="...", llm=ChatOpenAI(model="gpt-5.2"))

# Anthropic
agent = CodeAgent(task="...", llm=ChatAnthropic(model="claude-sonnet-4-6"))

# Google Gemini
agent = CodeAgent(task="...", llm=ChatGoogle(model="gemini-3-flash"))

ブラウザーセッションを直接使う

import asyncio
from openbrowser import BrowserSession, BrowserProfile

async def main():
    profile = BrowserProfile(
        headless=True,
        viewport_width=1920,
        viewport_height=1080,
    )
    
    session = BrowserSession(browser_profile=profile)
    await session.start()
    
    await session.navigate_to("https://example.com")
    screenshot = await session.screenshot()
    
    await session.stop()

asyncio.run(main())

設定

環境変数

# Google (recommended)
export GOOGLE_API_KEY="..."

# OpenAI
export OPENAI_API_KEY="sk-..."

# Anthropic
export ANTHROPIC_API_KEY="sk-ant-..."

# Groq
export GROQ_API_KEY="gsk_..."

# AWS Bedrock
export AWS_ACCESS_KEY_ID="..."
export AWS_SECRET_ACCESS_KEY="..."
export AWS_DEFAULT_REGION="us-west-2"

# Azure OpenAI
export AZURE_OPENAI_API_KEY="..."
export AZURE_OPENAI_ENDPOINT="https://your-resource.openai.azure.com/"

BrowserProfile のオプション

from openbrowser import BrowserProfile

profile = BrowserProfile(
    headless=True,
    viewport_width=1280,
    viewport_height=720,
    disable_security=False,
    extra_chromium_args=["--disable-gpu"],
    record_video_dir="./recordings",
    proxy={
        "server": "http://proxy.example.com:8080",
        "username": "user",
        "password": "pass",
    },
)

対応する LLM プロバイダー

プロバイダー	クラス	モデル
Google	ChatGoogle	gemini-3-flash, gemini-3-pro
OpenAI	ChatOpenAI	gpt-5.2, o4-mini, o3
Anthropic	ChatAnthropic	claude-sonnet-4-6, claude-opus-4-6
Groq	ChatGroq	llama-4-scout, qwen3-32b
AWS Bedrock	ChatAWSBedrock	anthropic.claude-sonnet-4-6, amazon.nova-pro
AWS Bedrock（Anthropic）	ChatAnthropicBedrock	Anthropic Bedrock SDK 経由の Claude モデル
Azure OpenAI	ChatAzureOpenAI	Azure にデプロイされた任意のモデル
OpenRouter	ChatOpenRouter	openrouter.ai 上の任意のモデル
DeepSeek	ChatDeepSeek	deepseek-chat, deepseek-r1
Cerebras	ChatCerebras	llama-4-scout, qwen-3-235b
Ollama	ChatOllama	llama-4-scout, deepseek-r1（ローカル）
OCI	ChatOCIRaw	Oracle Cloud GenAI モデル
Browser-Use	ChatBrowserUse	外部 LLM サービス

Claude Code Plugin

OpenBrowser を Claude Code プラグインとしてインストールします：

# Add the marketplace (one-time)
claude plugin marketplace add billy-enrizky/openbrowser-ai

# Install the plugin
claude plugin install openbrowser@openbrowser-ai

これにより、MCP サーバーと組み込みスキル 7 個がインストールされます：

スキル	説明
deep-research	出典を明記した複数のソースに基づくウェブ調査を行い、Markdown と JSON のレポートを作成します
web-scraping	構造化データを抽出し、ページネーションに対応します
form-filling	フォーム、ログインフロー、複数ステップのウィザードに入力します
e2e-testing	ユーザー操作をシミュレートしてウェブアプリをテストします
page-analysis	ページのコンテンツ、構造、メタデータを分析します
accessibility-audit	WCAG 準拠状況を確認するため、ページを監査します
file-download	ブラウザーセッションを使用してファイル（PDF、CSV）をダウンロードします

ツールのパラメーターに関する詳細なドキュメントは、plugin/README.md を参照してください。

Codex

OpenBrowser は、ネイティブのスキル検出機能を通じて OpenAI Codex で動作します。

クイックインストール

Codex に次のように伝えます：

Fetch and follow instructions from https://raw.githubusercontent.com/billy-enrizky/openbrowser-ai/refs/heads/main/.codex/INSTALL.md

手動インストール

# Clone the repository
git clone https://github.com/billy-enrizky/openbrowser-ai.git ~/.codex/openbrowser

# Symlink skills for native discovery
mkdir -p ~/.agents/skills
ln -s ~/.codex/openbrowser/plugin/skills ~/.agents/skills/openbrowser

# Restart Codex

次に、プロジェクトで MCP サーバーを設定します（下記の MCP サーバー を参照）。

詳細なドキュメント：.codex/INSTALL.md

OpenCode

OpenBrowser は、プラグインとスキルのシンボリックリンクを通じて OpenCode.ai で動作します。

クイックインストール

OpenCode に次のように伝えます：

Fetch and follow instructions from https://raw.githubusercontent.com/billy-enrizky/openbrowser-ai/refs/heads/main/.opencode/INSTALL.md

手動インストール

# Clone the repository
git clone https://github.com/billy-enrizky/openbrowser-ai.git ~/.config/opencode/openbrowser

# Create directories
mkdir -p ~/.config/opencode/plugins ~/.config/opencode/skills

# Symlink plugin and skills
ln -s ~/.config/opencode/openbrowser/.opencode/plugins/openbrowser.js ~/.config/opencode/plugins/openbrowser.js
ln -s ~/.config/opencode/openbrowser/plugin/skills ~/.config/opencode/skills/openbrowser

# Restart OpenCode

次に、プロジェクトで MCP サーバーを設定します（下記の MCP サーバー を参照）。

詳細なドキュメント：.opencode/INSTALL.md

OpenClaw

OpenClaw は CLI デーモンを通じて OpenBrowser をサポートします。OpenBrowser をインストールしてから、Bash ツールで openbrowser-ai -c を使用します：

openbrowser-ai -c "await navigate('https://example.com')"
openbrowser-ai -c "print(await evaluate('document.title'))"

デーモンは初回使用時に自動的に起動し、呼び出し間で変数を保持します。

OpenClaw プラグインのドキュメントについては、docs.openclaw.ai/tools/plugin を参照してください。

MCP サーバー

OpenBrowser には、ブラウザー自動化を Claude などの AI アシスタント向けのツールとして公開する MCP（Model Context Protocol）サーバーが含まれています。MCP Registry には me.openbrowser/openbrowser-ai として登録されています。外部の LLM API キーは不要です。インテリジェンスは MCP クライアントが提供します。

デフォルトでは、各 MCP サーバープロセスは ~/.config/openbrowser/profiles/mcp-<instance-id> の下に分離されたプロファイルを使用します。その storage_state.json は ~/.config/openbrowser/profiles/default/storage_state.json から一度だけシードされるため、既存のログイン状態を利用できる一方、同時実行中の MCP サーバーが互いのブラウザーを終了させたり破損させたりすることはありません。プロセスごとのプロファイルはディスク上に保持されますが、後続の MCP プロセスで自動的に再利用されることはありません。再起動後も維持されるプロファイルを使うには、OPENBROWSER_USER_DATA_DIR を設定してください。OPENBROWSER_STORAGE_STATE は管理対象プロファイルへの一度限りのシードであり、その後の変更はアクティブなプロセスごとのコピーに保存され、自動的にコピー元へ戻されることはありません。OpenBrowser は管理対象プロファイル内の一時的な Chromium キャッシュも自動でクリーンアップするため、Cookie やログイン状態を削除せずにディスク使用量を抑えられます。複数のサーバーに同じ OPENBROWSER_USER_DATA_DIR を明示的に設定した場合、プロファイルのリース機能により、2 つ目の所有者は明確なエラーとともに拒否されます。

クイックセットアップ

Claude Code：プロジェクトの .mcp.json に追加します：

{
  "mcpServers": {
    "openbrowser": {
      "command": "uvx",
      "args": ["openbrowser-ai", "--mcp"]
    }
  }
}

Claude Desktop：~/Library/Application Support/Claude/claude_desktop_config.json に追加します：

{
  "mcpServers": {
    "openbrowser": {
      "command": "uvx",
      "args": ["openbrowser-ai", "--mcp"],
      "env": {
        "OPENBROWSER_HEADLESS": "true"
      }
    }
  }
}

直接実行：

uvx openbrowser-ai --mcp

ツール

MCP サーバーは、ブラウザー自動化関数を使って永続的な名前空間で Python コードを実行する、単一の execute_code ツールを公開します。LLM は移動、操作、データ抽出を行う Python コードを記述し、明示的に要求された内容だけを返します。

利用可能な関数（特に記載がない限り、await を使用します）：

カテゴリ	関数
ナビゲーション	navigate(url, new_tab)、go_back()、wait(seconds)
操作	click(index)、input_text(index, text, clear)、scroll(down, pages, index)、send_keys(keys)、upload_file(index, path)
座標による操作	インデックスのないキャンバス、PDF、埋め込みコンテンツ、ネイティブ描画された対象に対する click_xy(x, y, button, click_count)、hover_xy(x, y)、scroll_xy(x, y, delta_x, delta_y)
ドロップダウン	select_dropdown(index, text)、dropdown_options(index)
タブ	switch(tab_id)、close(tab_id)
JavaScript	evaluate(code)：ページのコンテキストで JS を実行し、Python オブジェクトを返します
ダウンロード	download_file(url, filename)：ブラウザーの Cookie を使用してファイルをダウンロードします。list_downloads()：ダウンロードしたファイルを一覧表示します（同期処理のため、await は不要です）
状態	browser.get_browser_state_summary()：ページのメタデータと操作可能な要素を取得します
CSS	get_selector_from_index(index)：要素の CSS セレクターを取得します
完了	done(text, success)：タスクの完了を通知します

要素にインデックスがある場合は、インデックス指定の操作を優先してください。座標による操作では、スクリーンショットのピクセルではなく、CSS ビューポートのピクセルを使用します。スクリーンショットの devicePixelRatio が 1 以外の場合は、*_xy 関数を呼び出す前に、座標を window.devicePixelRatio で割ってください。

事前にインポート済みのライブラリ：json、csv、re、datetime、asyncio、Path、requests、numpy、pandas、matplotlib、BeautifulSoup

設定

環境変数	説明	デフォルト
OPENBROWSER_HEADLESS	GUI なしでブラウザーを実行します	true
OPENBROWSER_ALLOWED_DOMAINS	カンマ区切りの許可ドメインリスト	（なし）
OPENBROWSER_USER_DATA_DIR	任意の明示的な Chrome プロファイルディレクトリです。省略すると、MCP サーバーのインスタンスごとに分離されたプロファイルを使用します	（自動：~/.config/openbrowser/profiles/mcp-<instance-id>）
OPENBROWSER_STORAGE_STATE	管理対象の MCP プロファイルで Cookie と localStorage の初期データとして一度だけ使用する、任意の JSON ファイルです	（自動：profiles/default を元にプロセスごとにコピー）
OPENBROWSER_COMPACT_DESCRIPTION	最小限のツール説明（約 500 トークン）	false
OPENBROWSER_MAX_OUTPUT	実行ごとの最大出力文字数	10000

ベンチマーク：トークン効率

CLI ベンチマーク：4 種比較（6 タスク、N=3 回実行）

4 つの CLI ツールを、それぞれ単一の Bash ツールと組み合わせて比較します。Bedrock 上の Claude Sonnet 4.6 を使用しています。順序はランダム化しています。すべて 100% の精度を達成しています。

CLI ツール	所要時間（平均 +/- 標準偏差）	ツール呼び出し回数	Bedrock API トークン数	応答文字数
openbrowser-ai	84.8 +/- 10.9s	15.3 +/- 2.3	36,010 +/- 6,063	9,452 +/- 472
browser-use	106.0 +/- 9.5s	20.7 +/- 6.4	77,123 +/- 33,354	36,241 +/- 12,940
agent-browser	99.0 +/- 6.8s	25.0 +/- 4.0	90,107 +/- 3,698	56,009 +/- 39,733
playwright-cli	118.3 +/- 21.4s	25.7 +/- 8.1	94,130 +/- 35,982	84,065 +/- 49,713

openbrowser-ai は、Python コードのバッチ処理とコンパクトな DOM 表現により、すべての競合ツールより 2.1～2.6 倍少ないトークン数で処理します。

#### タスクごとのトークン使用量

タスク	openbrowser-ai	browser-use	playwright-cli	agent-browser
fact_lookup	2,504	4,710	16,857	9,676
form_fill	7,887	15,811	31,757	19,226
multi_page_extract	2,354	2,405	8,886	8,117
search_navigate	16,539	47,936	27,779	44,367
deep_navigation	2,178	3,747	4,705	5,534
content_analysis	4,548	2,515	4,147	3,189

openbrowser-ai は 6 タスク中 5 タスクで優れています。複雑なページで最も大きな優位性を示しており（search_navigate：browser-use よりトークンが 2.9 倍少ない）、コードのバッチ処理によってページ状態のダンプを繰り返さずに済みます。

ベンチマーク実行あたりのコスト（6 タスク）

モデル	openbrowser-ai	browser-use	playwright-cli	agent-browser
Claude Sonnet 4.6（100 万トークンあたり $3/$15）	$0.12	$0.24	$0.29	$0.27
Claude Opus 4.6（100 万トークンあたり $5/$25）	$0.24	$0.45	$0.56	$0.51

生の結果は benchmarks/e2e_4way_cli_results.json にあります。手法を含む 4-way 比較の全容。

E2E LLM ベンチマーク：MCP サーバー比較（6 タスク、N=5 回実行）

MCP サーバー	合格率	所要時間（平均 +/- 標準偏差）	ツール呼び出し数	Bedrock API トークン数
Playwright MCP（Microsoft）	100%	62.7 +/- 4.8s	9.4 +/- 0.9	158,787
Chrome DevTools MCP（Google）	100%	103.4 +/- 2.7s	19.4 +/- 0.5	299,486
OpenBrowser MCP	100%	77.0 +/- 6.7s	13.8 +/- 2.0	50,195

OpenBrowser のトークン数は Playwright より 3.2 倍少なく、Chrome DevTools より 6.0 倍少なくなっています。MCP の応答サイズは、Playwright が 1,132,173 文字、Chrome DevTools が 1,147,244 文字、OpenBrowser が 7,853 文字で、144 倍の差があります。

手法を含む MCP 比較の全容

CLI の使い方

# Run a browser automation task with an LLM agent
uvx openbrowser-ai -p "Search for Python tutorials on Google"

# Execute code directly via persistent daemon
uvx openbrowser-ai -c "await navigate('https://example.com')"
uvx openbrowser-ai -c "print(await evaluate('document.title'))"

# Daemon management
uvx openbrowser-ai daemon start     # Start daemon (auto-starts on first -c call)
uvx openbrowser-ai daemon stop      # Stop daemon and browser
uvx openbrowser-ai daemon status    # Show daemon info
uvx openbrowser-ai daemon restart   # Restart daemon

# Install browser
uvx openbrowser-ai install

# Run MCP server
uvx openbrowser-ai --mcp

-c フラグを指定すると、Unix ソケット経由で永続的なブラウザデーモンに接続します（Windows では localhost TCP）。デーモンの実行中は、呼び出し間で変数が保持されます。初回使用時にデーモンが自動的に起動し、10 分間操作がないと終了します。

CLI デーモンはブラウザプロファイルを ~/.config/openbrowser/profiles/daemon に保存し、同じ場所に storage_state.json も書き込むため、デーモンを再起動しても Cookie とログインセッションが保持されます。単発の -p 実行では ~/.config/openbrowser/profiles/cli を使用し、同様にストレージ状態を保持します。管理対象プロファイルでは、認証状態を維持したまま、起動時と終了時に一時的なブラウザーキャッシュが自動的に消去されます。

プロジェクト構成

openbrowser-ai/
├── .claude-plugin/            # Claude Code marketplace config
├── .codex/                    # Codex integration
│   └── INSTALL.md
├── .opencode/                 # OpenCode integration
│   ├── INSTALL.md
│   └── plugins/openbrowser.js
├── plugin/                    # Plugin package (skills + MCP config)
│   ├── .claude-plugin/
│   ├── .mcp.json
│   └── skills/                # 7 browser automation skills
├── src/openbrowser/
│   ├── __init__.py            # Main exports
│   ├── cli.py                 # CLI commands
│   ├── config.py              # Configuration
│   ├── actor/                 # Element interaction
│   ├── agent/                 # LangGraph agent
│   ├── browser/               # CDP browser control
│   ├── code_use/              # Code agent + shared executor
│   ├── daemon/                # Persistent browser daemon (Unix socket)
│   ├── dom/                   # DOM extraction
│   ├── llm/                   # LLM providers
│   ├── mcp/                   # MCP server
│   └── tools/                 # Action registry
├── benchmarks/                # MCP benchmarks and E2E tests
│   ├── playwright_benchmark.py
│   ├── cdp_benchmark.py
│   ├── openbrowser_benchmark.py
│   └── e2e_published_test.py
└── tests/                     # Test suite

テスト

# Run unit tests
pytest tests/

# Run with verbose output
pytest tests/ -v

# E2E test the MCP server against the published PyPI package
uv run python benchmarks/e2e_published_test.py

ベンチマーク

個々の MCP サーバーのベンチマークを実行します（JSON-RPC stdio、Wikipedia での 5 ステップのワークフロー）。

uv run python benchmarks/openbrowser_benchmark.py   # OpenBrowser MCP
uv run python benchmarks/playwright_benchmark.py     # Playwright MCP
uv run python benchmarks/cdp_benchmark.py            # Chrome DevTools MCP

生の結果は benchmarks/e2e_4way_cli_results.json にあります。手法については比較の全容をご覧ください。

バックエンドとフロントエンドのデプロイ

このプロジェクトには、Docker でコンテナ化された FastAPI バックエンドと Next.js フロントエンドが含まれています。

前提条件

• Docker と Docker Compose
• プロジェクトのルートにある、POSTGRES_PASSWORD と任意の LLM API キーを含む .env ファイル（backend/env.example を参照）

ローカル開発（Docker Compose）

# Start backend + PostgreSQL (frontend runs locally)
docker-compose -f docker-compose.dev.yml up --build

# In a separate terminal, start the frontend
cd frontend && npm install && npm run dev

サービス	URL	説明
バックエンド	http://localhost:8000	FastAPI + WebSocket + VNC
フロントエンド	http://localhost:3000	Next.js 開発サーバー
PostgreSQL	localhost:5432	チャットの永続化
VNC	ws://localhost:6080	ブラウザーのライブ表示

開発用 Compose では、backend/app/ と src/ をホットリロード用のボリュームとしてマウントします。API キーは env_file を介して backend/.env から読み込まれます。POSTGRES_PASSWORD はルートの .env ファイルから読み込まれます。

フルスタック（Docker Compose）

# Start all services (backend + frontend + PostgreSQL)
docker-compose up --build

バックエンドとフロントエンドの両方のコンテナーを PostgreSQL とともにビルドして実行します。

バックエンド

バックエンドは backend/ にある FastAPI アプリケーションで、backend/Dockerfile に Dockerfile があります。以下が含まれます。

• ポート 8000 の REST API
• リアルタイムのエージェント通信に使用する /ws の WebSocket エンドポイント
• ポート 6080-6090 でブラウザーをライブ表示するための VNC サポート（Xvfb + x11vnc + websockify）
• キオスクセキュリティ：Openbox ウィンドウマネージャー、Chromium エンタープライズポリシー、X11 キーグラバー・デーモン
• /health のヘルスチェック

# Build the backend image
docker build -f backend/Dockerfile -t openbrowser-backend .

# Run standalone
docker run -p 8000:8000 -p 6080:6080 \
  --env-file backend/.env \
  -e VNC_ENABLED=true \
  -e AUTH_ENABLED=false \
  --shm-size=2g \
  openbrowser-backend

フロントエンド

フロントエンドは frontend/ にある Next.js アプリケーションで、frontend/Dockerfile に Dockerfile があります。

# Build the frontend image
cd frontend && docker build -t openbrowser-frontend .

# Run standalone
docker run -p 3000:3000 \
  -e NEXT_PUBLIC_API_URL=http://localhost:8000 \
  -e NEXT_PUBLIC_WS_URL=ws://localhost:8000/ws \
  openbrowser-frontend

環境変数

バックエンドの主要な環境変数（一覧については backend/env.example を参照してください）：

変数	説明	デフォルト
GOOGLE_API_KEY	Google/Gemini API キー	（必須）
DEFAULT_LLM_MODEL	エージェントのデフォルトモデル	gemini-3-flash-preview
AUTH_ENABLED	Cognito JWT 認証を有効化	false
VNC_ENABLED	VNC ブラウザー表示を有効化	true
DATABASE_URL	PostgreSQL 接続文字列	（任意）
POSTGRES_PASSWORD	PostgreSQL パスワード（ルートの .env）	（Compose で必須）

研究：ブラウザーエージェントのための強化学習によるファインチューニング

フレームワークに加えて、強化学習を通じてブラウザーエージェントを改善するための独立した研究を 2 件実施しました。どちらも FormFactory ベンチマーク（8 つのドメインにまたがる 1,250 件のフォーム入力タスク）と OpenBrowser のブラウザー実行環境を使用しています。

研究 1：ブラウザー・イン・ザ・ループ（自己回帰型 RL）

教師あり学習で達成できる水準を超えて、強化学習によって言語モデルの Web フォーム入力能力を向上させられるかを調査しました。

• 手法：2 段階のパイプライン――QLoRA を使用して Qwen3-8B を SFT（デモ 992 件）で学習し、その後、ライブブラウザー実行報酬（複合報酬：送信成功率 40% + フィールド精度 40% + 実行完了率 20%）を用いてオンライン GRPO を実施
• 結果：保留した検証データで、GRPO は SFT のみの場合より平均報酬が 9.1%高くなりました（p=0.007、Wilcoxon 符号順位検定）。改善は特にフォーム送信の向上によるもので、フィールド入力の向上によるものではありません。
• 主な発見：SFT は前提条件です。SFT を行わないと、ベースモデルは構造化されていないテキストを生成し、すべての試行で報酬がゼロになります。
• 論文：Browser-in-the-Loop: Reinforcement Fine-Tuning LLM Agents for Web Form Filling
• モデル：Qwen3-8B-FormFactory-SFT-LoRA、Qwen3-8B-FormFactory-GRPO-LoRA

研究 2：Web アクション計画のための拡散言語モデル

拡散言語モデル（左から右へテキストを生成するのではなく、シーケンス全体を並列で反復的にノイズ除去して生成するモデル）が、Web アクション計画を学習できるかどうかを調査しました。

• テストしたモデル：ReFusion 8B（因果 LM バックボーンを備えたマスク拡散）と FS-DFM 1.3B（純粋な離散フローマッチング）
• 結果：SFT 後、拡散モデルはタスクの 60～69％を解決しましたが、AR ベースラインは 100％でした。トークンレベルの RL は一貫して不安定でした（16 件の比較のうち改善したのは 2 件で、いずれも有意差なし）。シーケンスレベルの RL は成功しました。MDPO により ReFusion は 91.9％（+31.4pp）に、ESPO により FS-DFM は 87.1％（+18.6pp）になりました。
• 主な知見：適切な RL の定式化はアーキテクチャに依存します。ELBO ベースの最適化（ESPO）はアーキテクチャを問わず集中した分布を生成する一方、ステップごとの軌跡手法はマルチモーダルな分布を生成します。
• 論文：集中か崩壊か：強化学習と拡散言語モデルがWeb計画で出会うとき
• モデル：ReFusion-8B-MDPO、FS-DFM-1.3B-ESPO-mu8 など、HuggingFace で学習済みの 10 個のモデル

RL 実験の再現

すべての学習コードは infra/training/ にあります。学習は Anyscale 経由で、単一の NVIDIA A10G GPU（24GB VRAM）上で実行できます。

# Study 1: Autoregressive RL (Qwen3-8B)
# SFT phase -- QLoRA fine-tuning on 992 FormFactory demonstrations (2-4 hours)
python infra/training/finetuning/sft_trainer.py

# Online GRPO phase -- browser-in-the-loop reward (4-8 hours per epoch)
# Requires headless Chromium + FormFactory forms server
python infra/training/shared/formfactory_server.py &   # Start form server
python infra/training/finetuning/online_grpo_trainer.py

# Evaluate SFT and GRPO checkpoints on val/test splits
python infra/training/finetuning/eval_sft.py

# Study 2: Diffusion LM RL (ReFusion 8B, FS-DFM 1.3B)
# SFT phase
python infra/training/flow_matching/fsdfm_sft_trainer.py    # FS-DFM SFT
python infra/training/flow_matching/flow_sft_trainer.py      # ReFusion SFT

# Sequence-level RL (best results)
python infra/training/flow_matching/espo_fsdfm_trainer.py    # ESPO on FS-DFM
python infra/training/flow_matching/espo_refusion_trainer.py # ESPO on ReFusion
python infra/training/flow_matching/mdpo_fsdfm_trainer.py    # MDPO on FS-DFM
python infra/training/flow_matching/mdpo_refusion_trainer.py # MDPO on ReFusion

# Submit jobs to Anyscale cloud
python infra/training/anyscale/submit_job.py --config infra/training/anyscale/online_grpo_job.yaml

# Push trained checkpoints to HuggingFace
python infra/training/anyscale/push_checkpoints_to_hf.py

# Serve trained model locally via vLLM or Ollama
python infra/training/serving/serve_vllm.py
python infra/training/serving/export_gguf.py   # Export to GGUF for Ollama

報酬関数（infra/training/shared/reward_functions.py 内）：複合スコア = 0.4 * タスク完了度 + 0.4 * フィールド正確度 + 0.2 * 実行完全度。オンライン報酬（online_reward.py）はヘッドレス Chromium を起動し、モデルのアクション計画を実行して、ライブブラウザーの状態からスコアを算出します。

貢献

貢献を歓迎します。以下の手順に従ってください。

1. リポジトリをフォークします
2. 機能ブランチを作成します（git checkout -b feature/amazing-feature）
3. 変更をコミットします（git commit -m 'Add amazing feature'）
4. ブランチにプッシュします（git push origin feature/amazing-feature）
5. プルリクエストを作成します

ライセンス

このプロジェクトは MIT License のもとでライセンスされています。詳細は LICENSE ファイルをご覧ください。

お問い合わせ

• メール：[email protected]
• GitHub：@billy-enrizky
• リポジトリ：github.com/billy-enrizky/openbrowser-ai
• ドキュメント：https://docs.openbrowser.me

---

AI 自動化コミュニティへの愛を込めて開発