Computer use tool

一行要約

computer_toolset_20260801 を1つ宣言すると 17 個のメンバーツールが生え、実行するのは自分の環境。 座標は自分が返したスクリーンショットの画素空間で、そこの取り違えが誤クリックの主因になる。

要点

サーバツールではない —— 動かすのは自分

tools に {"type": "computer_toolset_20260801"} を1つ入れると、screenshot / left_click / type / zoom など 17 のメンバーツールが使えるようになる。Claude が返すのは "toolset_name": "computer" を持つ tool_use ブロックで、それを自分の環境で実行して tool_result を返すのは自分の仕事。ベータヘッダは要らない。

Claude API と Google Cloud では、Claude 5.5 以降のモデルは computer_toolset_20260801 でしか computer use を使えず、旧 computer_20251124 を渡すとエラーになる。 例外は Amazon Bedrock の Opus 5.5 と Sonnet 5.5 で、Opus 5 / Sonnet 5 と同じく旧版を受け付ける。Claude API と Google Cloud 以外のプラットフォームは、旧 beta 版（computer_20251124 / computer_20250124、毎リクエストに beta header が要る）しか提供していない。Opus 4.7 / 4.6 / Sonnet 4.6 / Opus 4.5 も旧 computer_20251124 だけ。

原典が挙げる環境の構成は、Xvfb の仮想ディスプレイ / Mutter + Tint2 の軽量デスクトップ / Firefox・LibreOffice などの同梱アプリ / ツール実装 / エージェントループ。Anthropic は Docker のリファレンス実装を公開している。

ページの中で完結する作業なら browser use ツールの方が近い、と原典自身が最初に言っている。デスクトップ一式が要らないため。

セキュリティ —— 画面の中の文字が命令になる

In some circumstances, Claude will follow commands found in content even when they conflict with your instructions.

状況によっては、Claude はコンテンツの中に見つけた命令に従う。それが自分の指示と衝突していてもである。

If you use the computer use tools, classifiers will automatically scan what the tools return, such as screenshots, to flag potential prompt injections. When these classifiers identify a potential prompt injection, they will automatically steer the model to check whether the instruction really came from you before acting on it.

computer use のツールを使うと、分類器がスクリーンショットなど、ツールが返すものを自動で走査し、prompt injection の可能性に印を付ける。分類器が注入の可能性を見つけると、その指示が本当に自分（開発者）から来たものかを、行動する前に確かめるようモデルを自動的に誘導する。

以前の取得では「スクリーンショットの中の注入を見つけたら、次の行動の前にユーザーの確認を求める」だった。走査の対象がツールの返すもの全般に広がり、誘導先も「ユーザーに確認を求める」から「指示の出所を確かめる」に変わった。

この分類器は computer use を使うと自動で走る。オプトアウトできることと、その理由まで原典が書いている。

This extra protection won’t be ideal for every use case (for example, use cases without a human in the loop), so if you’d like to opt out and turn it off, contact support.

この追加の保護はすべての用途に適しているわけではない（たとえば人が介在しない用途）。切りたい場合はサポートに連絡すること。原典の予防策は、専用の VM かコンテナ・認証情報を渡さない・ドメインの許可リスト・意味のある結果を伴う決定は人が確認の4点。

バッチアクションは「並列」ではなく「順番」

This is called a batch action; it uses the same response shape as parallel tool use with one difference: you run the blocks in order rather than concurrently.

これをバッチアクションと呼ぶ。parallel tool use と同じ応答の形だが、1点だけ違う。同時にではなく、順番に実行する。

途中で失敗したら、そのブロックに is_error: true を返し、残りは実行せずに停止用のテキストで答える。1ターン1アクションしか回せないループなら tool_choice の disable_parallel_tool_use を立てる。

座標はすべて「自分が返した画像」の画素空間

Every coordinate, start_coordinate, and region value, and the position that cursor_position reports, is in the pixel space of the full-display screenshots you return, with the origin at the top left. Zoom images don’t change this: after a zoom, Claude still expresses coordinates in the full screenshot’s space, never relative to the zoomed image.

coordinate / start_coordinate / region の値も、cursor_position が報告する位置も、すべて自分が返した全画面スクリーンショットの画素空間（原点は左上）。zoom はこれを変えない。 ズーム後も Claude は全画面の座標系で答える。ズーム画像を基準にすることは無い。

the toolset takes no display dimensions and the API doesn’t downscale for you, so an oversized tool_result image is rejected with a validation error

このツールセットはディスプレイの寸法を受け取らず、API が縮小してくれることも無い。大きすぎる tool_result の画像は検証エラーで弾かれる。

つまり縮小と座標の逆変換はアプリ側の責任。display_width_px などの旧パラメータは渡すと invalid_request_error になる。クリックがずれる原因の筆頭がこのスケール漏れで、原典は「一方向に一定してずれる」症状として表にしている（macOS の Retina なら 2倍を勘定に入れる）。

スクリーンショットの履歴が context とキャッシュを壊す

1枚あたりおおよそ 1,000〜1,800 入力トークン。1リクエストに 20 枚を超えると、その中の全画像に厳しい辺長制限がかかる。

Prune old screenshots in batches, not one each turn. Dropping a screenshot every turn changes the prefix every turn and invalidates the cache.

古いスクリーンショットはまとめて捨てる。毎ターン1枚ずつではない。 毎ターン捨てると毎ターン前置が変わり、キャッシュが無効になる。

原典の既定案は直近3枚を残し、25ターンごとに間引く。そして Fable 5.1・Opus 5.5・Sonnet 5.5 では話が変わる。

On Claude Fable 5.1, Claude Opus 5.5, and Claude Sonnet 5.5, avoid pruning on the client: removing an earlier screenshot invalidates every later thinking block in every request that still carries those turns.

Fable 5.1・Opus 5.5・Sonnet 5.5 ではクライアント側で間引かないこと。前の方のスクリーンショットを取り除くと、それ以降の thinking ブロックが全部無効になる —— そのターンを含むすべてのリクエストでである。

代わりに各辺 2000px 以下に縮小し、サーバ側の context-editing で古い結果を落とす。どうしても間引くなら prefix_mismatch_behavior: "drop_block" を以後ずっと立てておく。Sonnet 5.5 では block_binding は thinking: {"type": "adaptive"} のときしか効かないので、between_tools のときは履歴を append-only に保つか、編集したターン以降の thinking ブロックを剥がす。間引くたびに、間引いたスクリーンショット以降に生まれた thinking 無しで Claude は続ける（そのリクエストでも、以降のすべてでも）。症状の側は thinking-troubleshooting。

プロンプトの並べ方でクリック精度が変わる

When constructing a user turn’s content array, place the instruction text before the screenshot image. Providing the target description before the image is processed improves click accuracy.

user ターンの content 配列を組むとき、指示テキストをスクリーンショット画像より前に置く。 画像が処理される前に対象の説明を与えると、クリックの精度が上がる。

他に原典が挙げるもの: 1手ごとにスクリーンショットで結果を確かめさせる、ドロップダウンやスクロールバーはキーボードショートカットに逃がす、小さい文字は zoom を使わせる（使ってくれないときは画面全体でなく領域や要素を名指しで訊く）、繰り返す作業は成功例のスクリーンショットとツール呼び出しをプロンプトに入れる。

課金はトークンだけ。ただし定義が重い

Declaring computer_toolset_20260801 with its default members adds about 4,500 input tokens to a request

既定のメンバーのまま computer_toolset_20260801 を宣言すると、リクエストにおよそ 4,500 入力トークンが足される。

configs で zoom を切ると約 410 トークン減る（実装が無いなら切る。有効のままエラーを返すのは原典が否定している）。旧 computer_20251124 系は system プロンプトに 466〜499、ツール定義に約 735。これにスクリーンショットの画像入力が乗る。

限界（原典が明言しているもの）

遅いので速度が要る用途には向かない、座標を幻覚することがある、ニッチなアプリや複数アプリの同時操作で信頼性が落ちる、スクロールが効かないアプリがある（Page Down に逃がす）、表計算のセル選択は left_mouse_down / left_mouse_up で細かく、SNS でのアカウント作成や人物のなりすましは制限されている。

推論を見たいときは display: "summarized" を明示する。このツールセットを使えるモデルは既定で thinking テキストを返さないため。

そのまま使える具体例

1手ごとに検証させるプロンプト（原典そのまま。以前の取得で「思考を明示的に見せよ（“I have evaluated step X…”）」が「スクリーンショットに何が写り、その手が成功したかを1文で述べよ」に変わった）:

After each step, take a screenshot and carefully evaluate if you have achieved the right outcome. State in one sentence what the screenshot shows and whether the step succeeded. If it didn't, try again. Only when you confirm a step was executed correctly should you move on to the next one.

バッチの最後を必ずスクリーンショットで締めさせる:

End each group of actions with a screenshot so you can verify the result before continuing.

zoom を持たない環境の宣言:

{
  "type": "computer_toolset_20260801",
  "configs": {
    "zoom": { "enabled": false }
  },
  "cache_control": { "type": "ephemeral" }
}

失敗の返し方（toolset_name を付けるのを忘れない）:

{
  "type": "tool_result",
  "tool_use_id": "toolu_01A09q90qw90lq917835lq9",
  "toolset_name": "computer",
  "content": "Error: Failed to capture screenshot. Display may be locked or unavailable.",
  "is_error": true
}

ログイン情報を渡すなら XML タグで囲む（<robot_credentials>）。ただしログインを伴う操作は prompt injection の被害が大きくなると原典は釘を刺している。

原典で言及されている関連文書

mitigate-jailbreaks — 認証情報を渡す前に読めと名指しされている
effective-harnesses-for-long-running-agents — 複数セッションに跨るなら、各セッションの冒頭で端から端まで検証する
define-tools — 生成される system プロンプトの土台。computer use 版はここに一文足したもの
tool-search-tool — configs の defer_loading の行き先
prompt-caching — cache_control の置き方。4つの上限とバッチの扱い
thinking — thinking との併用。既定で thinking テキストが返らない件
context-editing — サーバ側で古い tool result を落とす。Fable 5.1・Opus 5.5・Sonnet 5.5 ではこちらを使う
thinking-troubleshooting — 原典が指すのは thinking の該当節。署名エラーとして現れた側はこちら

ai-docs

エクスプローラー