computer-control

コンピューター操作スキル

Claude の Computer Use API を使用して、スクリーンショットやマウス／キーボード操作を通じてデスクトップ環境を表示・操作します。

使用する場面

• CLI による代替手段がない GUI ベースのワークフローを自動化する場合
• 視覚的な操作を通じてウェブアプリケーションをテストする場合
• フォームへの入力、メニューの操作、デスクトップアプリとのやり取りを行う場合
• 視覚的な検証が必要な自動化パイプラインを構築する場合

使用しない場面

• CLI または API で実行できるタスク（GUI が不要な場合）
• Playwright または CDP のほうが適しているブラウザー自動化

オプトインのままとする理由。
docs/inclusive-defaults.md（TRUE-exception カテゴリー 4）にあるように、Computer Use はスクリーンショットを撮影し、キーボード／マウス入力を生成します。これはプロセスをまたぐ副作用を伴うため、常に明示的に呼び出す必要があり、デフォルトで有効にしてはなりません。

アーキテクチャ

コンピューター操作システムは、次の 3 つのレイヤーで構成されます。

1. ディスプレイツールキット（phantom.display）- xdotool/scrot を使用して、実ディスプレイまたは仮想ディスプレイ上で OS レベルの操作を実行します
2. エージェントループ（phantom.loop）- Claude API とディスプレイツールキット間の会話サイクルを管理します
3. CLI（phantom.cli）- タスクの実行や環境の準備状況の確認を行うコマンドラインインターフェースです

User Task
    |
    v
Agent Loop  <---->  Claude API (beta)
    |                   |
    v                   v
Display Toolkit    tool_use responses
    |              (click, type, screenshot)
    v
OS Commands (xdotool, scrot)
    |
    v
Display (X11 / Xvfb / WSLg)

クイックスタート

環境を確認する

cd plugins/phantom
uv run python -m phantom.cli --check

タスクを実行する

export ANTHROPIC_API_KEY="sk-ant-..."
uv run python -m phantom.cli "Open Firefox and search for Claude AI"

Python で使用する

from phantom.display import DisplayConfig, DisplayToolkit
from phantom.loop import LoopConfig, run_loop

result = run_loop(
    task="Take a screenshot of the desktop",
    api_key="sk-ant-...",
    loop_config=LoopConfig(
        model="claude-sonnet-5",
        max_iterations=10,
    ),
    display_config=DisplayConfig(width=1920, height=1080),
)

print(f"Done in {result.iterations} iterations")
print(result.final_text)

API バージョン

モデル	ツールのバージョン	ベータフラグ
Opus 4.6、Sonnet 4.6、Opus 4.5	computer_20251124	computer-use-2025-11-24
Sonnet 4.5、Haiku 4.5、それ以前のモデル	computer_20250124	computer-use-2025-01-24

resolve_tool_version() 関数は、モデル名に基づいてこの対応付けを自動的に処理します。

使用可能なアクション

すべてのバージョン：

• screenshot - ディスプレイを撮影します
• left_click - [x, y] の位置をクリックします
• type - 文字列を入力します
• key - キーの組み合わせを押します（例：ctrl+s）
• mouse_move - カーソルを移動します

拡張機能（20250124 以降）：

• scroll - 方向と量を指定してスクロールします
• left_click_drag - 座標間をドラッグします
• right_click、middle_click、double_click、triple_click
• hold_key - 指定した時間キーを押し続けます
• wait - アクション間に一時停止します

最新（20251124）：

• zoom - 画面の領域をフル解像度で確認します

安全性

コンピューター操作にはリスクが伴います。次のガイドラインに従ってください。

1. サンドボックスを使用する：メインの OS ではなく、Docker または VM で実行します
2. アクセスを制限する：必要な場合を除き、ログイン認証情報を渡さないでください。また、銀行や機密性の高いサービスの認証情報は決して渡さないでください
3. 反復回数の上限を設定する：API コストが際限なく増加するのを防ぐため、常に max_iterations を使用します
4. 人による承認：現実世界に影響を与えるアクションには、on_action を介して確認コールバックを追加します
5. 機密性の高いアプリを閉じる：Claude はスクリーンショットを通じて画面全体を認識します。開始前にプライベートなものはすべて閉じてください

環境要件

Linux（ネイティブまたは WSLg を使用する WSL2）：

sudo apt install xdotool scrot xclip

ヘッドレス（Docker/CI）：

# Install Xvfb for virtual display
sudo apt install xvfb xdotool scrot xclip
Xvfb :1 -screen 0 1920x1080x24 &
export DISPLAY=:1

プロンプト作成のヒント

1. タスクの各手順を具体的に指定します
2. ミスを早期に発見できるよう、「各手順の後にスクリーンショットを撮影して確認する」を追加します
3. UI 要素をクリックしにくい場合は、キーボードショートカットを使用します
4. 繰り返し実行するワークフローには、例となるスクリーンショットを用意します
5. ドメイン固有の指示を含むシステムプロンプトを設定します

終了条件

• タスクを開始する前に uv run python -m phantom.cli --check が終了コード 0 で終了すること。失敗した場合は、続行前に必要な OS ツール（xdotool、scrot、xclip）をインストールするか、Xvfb を起動します
• すべての run_loop() 呼び出しで max_iterations を設定すること。API コストが際限なく増加するのを防ぐため、反復回数の上限を明示せずにタスクを開始しないでください
• 最終結果に result.iterations の回数と、タスクの結果を確認できる result.final_text が含まれていること。final_text が空の場合は、成功ではなく失敗として扱います
• タスク開始前に機密性の高いアプリケーション（パスワードマネージャー、銀行関連、プライベートファイル）を閉じ、タスクのプロンプトに認証情報をそのまま含めないこと