電腦使用工具

Claude 可以透過電腦使用工具與電腦環境互動，該工具提供截圖功能以及滑鼠/鍵盤控制，用於自主桌面互動。在 WebArena（一個跨真實網站的自主網頁導航基準測試）中，Claude 在單一代理系統中達到了最先進的成果，展現出端對端完成多步驟瀏覽器任務的強大能力。

概覽

電腦使用是一項測試版功能，可讓 Claude 與桌面環境互動。此工具提供：

• 截圖擷取：查看螢幕上目前顯示的內容
• 滑鼠控制：點擊、拖曳及移動游標
• 鍵盤輸入：輸入文字及使用鍵盤快捷鍵
• 桌面自動化：與任何應用程式或介面互動

雖然電腦使用可以與其他工具（如 bash 和文字編輯器）結合，以實現更全面的自動化工作流程，但電腦使用特指電腦使用工具查看和控制桌面環境的能力。

模型相容性

電腦使用功能適用於以下 Claude 模型：

安全考量

電腦使用是一項測試版功能，具有與標準 API 功能不同的獨特風險。與網際網路互動時，這些風險會更高。

在某些情況下，Claude 會遵循內容中找到的指令，即使這些指令與使用者的指示相衝突。例如，網頁上或圖片中的 Claude 指令可能會覆蓋指示或導致 Claude 犯錯。請採取預防措施，將 Claude 與敏感資料和操作隔離，以避免與提示注入相關的風險。

該模型已經過訓練以抵抗這些提示注入，並增加了額外的防禦層。如果您使用電腦使用工具，分類器將自動對您的提示執行，以標記潛在的提示注入實例。當這些分類器在截圖中識別出潛在的提示注入時，它們將自動引導模型在繼續下一個動作之前請求使用者確認。這種額外保護並不適合所有使用案例（例如，沒有人工參與的使用案例），因此如果您想退出並關閉它，請聯絡支援。

即使有分類器防禦層，這些預防措施仍然很重要。

在您自己的產品中啟用電腦使用功能之前，請告知終端使用者相關風險並取得其同意。

快速入門

以下是開始使用電腦使用功能的方法：

curl https://api.anthropic.com/v1/messages \
  -H "content-type: application/json" \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "anthropic-beta: computer-use-2025-11-24" \
  -d '{
    "model": "claude-opus-4-6",
    "max_tokens": 1024,
    "tools": [
      {
        "type": "computer_20251124",
        "name": "computer",
        "display_width_px": 1024,
        "display_height_px": 768,
        "display_number": 1
      },
      {
        "type": "text_editor_20250728",
        "name": "str_replace_based_edit_tool"
      },
      {
        "type": "bash_20250124",
        "name": "bash"
      }
    ],
    "messages": [
      {
        "role": "user",
        "content": "Save a picture of a cat to my desktop."
      }
    ]
  }'

電腦使用的運作方式

在沒有使用者輸入的情況下重複步驟 3 和 4 被稱為「代理迴圈」（即 Claude 以工具使用請求回應，而您的應用程式以評估該請求的結果回應 Claude）。

運算環境

電腦使用需要一個沙盒運算環境，Claude 可以在其中安全地與應用程式和網路互動。此環境包括：

1. 虛擬顯示器：虛擬 X11 顯示伺服器（使用 Xvfb），渲染 Claude 將透過截圖看到並用滑鼠/鍵盤動作控制的桌面介面。

2. 桌面環境：在 Linux 上執行的輕量級 UI，帶有視窗管理器（Mutter）和面板（Tint2），為 Claude 提供一致的圖形介面進行互動。

3. 應用程式：預先安裝的 Linux 應用程式，如 Firefox、LibreOffice、文字編輯器和檔案管理器，Claude 可以使用這些應用程式完成任務。

4. 工具實作：將 Claude 的抽象工具請求（如「移動滑鼠」或「截圖」）轉換為虛擬環境中實際操作的整合程式碼。

5. 代理迴圈：處理 Claude 與環境之間通訊的程式，將 Claude 的動作發送到環境並將結果（截圖、命令輸出）返回給 Claude。

當您使用電腦使用功能時，Claude 不會直接連接到此環境。相反，您的應用程式：

1. 接收 Claude 的工具使用請求
2. 將其轉換為您的運算環境中的動作
3. 擷取結果（截圖、命令輸出等）
4. 將這些結果返回給 Claude

為了安全性和隔離，參考實作在 Docker 容器內執行所有這些操作，並具有適當的連接埠映射，以便查看和與環境互動。

如何實作電腦使用

從參考實作開始

提供了一個參考實作，其中包含快速開始使用電腦使用所需的一切：

• 適合與 Claude 一起使用電腦的容器化環境
• 電腦使用工具的實作
• 與 Claude API 互動並執行電腦使用工具的代理迴圈
• 用於與容器、代理迴圈和工具互動的網頁介面。

了解多代理迴圈

電腦使用的核心是「代理迴圈」——Claude 請求工具動作、您的應用程式執行這些動作並將結果返回給 Claude 的循環。以下是一個簡化範例：

async def sampling_loop(
    *,
    model: str,
    messages: list[dict],
    api_key: str,
    max_tokens: int = 4096,
    tool_version: str,
    thinking_budget: int | None = None,
    max_iterations: int = 10,  # Add iteration limit to prevent infinite loops
):
    """
    A simple agent loop for Claude computer use interactions.

    This function handles the back-and-forth between:
    1. Sending user messages to Claude
    2. Claude requesting to use tools
    3. Your app executing those tools
    4. Sending tool results back to Claude
    """
    # Set up tools and API parameters
    client = Anthropic(api_key=api_key)
    beta_flag = (
        "computer-use-2025-11-24"
        if "20251124" in tool_version
        else "computer-use-2025-01-24"
        if "20250124" in tool_version
        else "computer-use-2024-10-22"
    )

    # Configure tools - you should already have these initialized elsewhere
    tools = [
        {
            "type": f"computer_{tool_version}",
            "name": "computer",
            "display_width_px": 1024,
            "display_height_px": 768,
        },
        {"type": f"text_editor_{tool_version}", "name": "str_replace_editor"},
        {"type": f"bash_{tool_version}", "name": "bash"},
    ]

    # Main agent loop (with iteration limit to prevent runaway API costs)
    iterations = 0
    while True and iterations < max_iterations:
        iterations += 1
        # Set up optional thinking parameter (for Claude Sonnet 3.7)
        thinking = None
        if thinking_budget:
            thinking = {"type": "enabled", "budget_tokens": thinking_budget}

        # Call the Claude API
        response = client.beta.messages.create(
            model=model,
            max_tokens=max_tokens,
            messages=messages,
            tools=tools,
            betas=[beta_flag],
            thinking=thinking,
        )

        # Add Claude's response to the conversation history
        response_content = response.content
        messages.append({"role": "assistant", "content": response_content})

        # Check if Claude used any tools
        tool_results = []
        for block in response_content:
            if block.type == "tool_use":
                # In a real app, you would execute the tool here
                # For example: result = run_tool(block.name, block.input)
                result = {"result": "Tool executed successfully"}

                # Format the result for Claude
                tool_results.append(
                    {"type": "tool_result", "tool_use_id": block.id, "content": result}
                )

        # If no tools were used, Claude is done - return the final messages
        if not tool_results:
            return messages

        # Add tool results to messages for the next iteration with Claude
        messages.append({"role": "user", "content": tool_results})

迴圈持續進行，直到 Claude 在不請求任何工具的情況下回應（任務完成）或達到最大迭代限制。此保護措施可防止可能導致意外 API 費用的潛在無限迴圈。

在閱讀本文件的其餘部分之前，請先試用參考實作。

透過提示優化模型效能

以下是一些獲得最佳品質輸出的技巧：

1. 指定簡單、定義明確的任務，並為每個步驟提供明確的指示。
2. Claude 有時會在未明確檢查結果的情況下假設其動作的結果。為了防止這種情況，您可以提示 Claude：After each step, take a screenshot and carefully evaluate if you have achieved the right outcome. Explicitly show your thinking: "I have evaluated step X..." If not correct, try again. Only when you confirm a step was executed correctly should you move on to the next one.
3. 某些 UI 元素（如下拉選單和捲軸）可能對 Claude 使用滑鼠移動來操作有些困難。如果您遇到這種情況，請嘗試提示模型使用鍵盤快捷鍵。
4. 對於可重複的任務或 UI 互動，請在提示中包含成功結果的範例截圖和工具呼叫。
5. 如果您需要模型登入，請在提示中使用 xml 標籤（如 <robot_credentials>）提供使用者名稱和密碼。在需要登入的應用程式中使用電腦使用功能會增加因提示注入而導致不良結果的風險。在向模型提供登入憑證之前，請查閱緩解提示注入的指南。

系統提示

當透過 Claude API 請求 Anthropic 定義的工具之一時，會生成特定於電腦使用的系統提示。它類似於工具使用系統提示，但以以下內容開頭：

You have access to a set of functions you can use to answer the user's question. This includes access to a sandboxed computing environment. You do NOT currently have the ability to inspect files or interact with external resources, except by invoking the below functions.

與一般工具使用一樣，使用者提供的 system_prompt 欄位仍然受到尊重，並用於建構組合系統提示。

可用動作

電腦使用工具支援以下動作：

基本動作（所有版本）

• screenshot - 擷取當前顯示畫面
• left_click - 在座標 [x, y] 處點擊
• type - 輸入文字字串
• key - 按下按鍵或按鍵組合（例如，"ctrl+s"）
• mouse_move - 將游標移動到座標

增強動作（computer_20250124） 適用於 Claude 4 模型和 Claude Sonnet 3.7：

• scroll - 以任意方向捲動，並控制捲動量
• left_click_drag - 在座標之間點擊並拖曳
• right_click、middle_click - 額外的滑鼠按鈕
• double_click、triple_click - 多次點擊
• left_mouse_down、left_mouse_up - 精細的點擊控制
• hold_key - 按住按鍵持續指定時間（以秒為單位）
• wait - 在動作之間暫停

增強動作（computer_20251124） 適用於 Claude Opus 4.6 和 Claude Opus 4.5：

• computer_20250124 的所有動作
• zoom - 以全解析度查看螢幕的特定區域。需要在工具定義中設定 enable_zoom: true。接受 region 參數，座標為 [x1, y1, x2, y2]，定義要檢查區域的左上角和右下角。

工具參數

在 Claude 4 模型和 Claude Sonnet 3.7 中啟用思考能力

Claude Sonnet 3.7 引入了一種新的「思考」能力，讓您可以在模型處理複雜任務時看到其推理過程。此功能幫助您了解 Claude 如何處理問題，對於除錯或教育目的特別有價值。

若要啟用思考，請在您的 API 請求中新增 thinking 參數：

"thinking": {
  "type": "enabled",
  "budget_tokens": 1024
}

budget_tokens 參數指定 Claude 可以用於思考的 token 數量。這將從您的整體 max_tokens 預算中扣除。

啟用思考後，Claude 將在回應中返回其推理過程，這可以幫助您：

1. 了解模型的決策過程
2. 識別潛在問題或誤解
3. 從 Claude 解決問題的方法中學習
4. 更清楚地了解複雜的多步驟操作

以下是思考輸出可能的樣子：

[Thinking]
I need to save a picture of a cat to the desktop. Let me break this down into steps:

1. First, I'll take a screenshot to see what's on the desktop
2. Then I'll look for a web browser to search for cat images
3. After finding a suitable image, I'll need to save it to the desktop

Let me start by taking a screenshot to see what's available...

使用其他工具擴充電腦使用功能

電腦使用工具可以與其他工具結合，創建更強大的自動化工作流程。這在以下情況特別有用：

• 執行系統命令（bash 工具）
• 編輯設定檔或腳本（文字編輯器工具）
• 與自訂 API 或服務整合（自訂工具）

curl https://api.anthropic.com/v1/messages \
  -H "content-type: application/json" \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "anthropic-beta: computer-use-2025-11-24" \
  -d '{
    "model": "claude-opus-4-6",
    "max_tokens": 2000,
    "tools": [
      {
        "type": "computer_20251124",
        "name": "computer",
        "display_width_px": 1024,
        "display_height_px": 768,
        "display_number": 1
      },
      {
        "type": "text_editor_20250728",
        "name": "str_replace_based_edit_tool"
      },
      {
        "type": "bash_20250124",
        "name": "bash"
      },
      {
        "name": "get_weather",
        "description": "Get the current weather in a given location",
        "input_schema": {
          "type": "object",
          "properties": {
            "location": {
              "type": "string",
              "description": "The city and state, e.g. San Francisco, CA"
            },
            "unit": {
              "type": "string",
              "enum": ["celsius", "fahrenheit"],
              "description": "The unit of temperature, either 'celsius' or 'fahrenheit'"
            }
          },
          "required": ["location"]
        }
      }
    ],
    "messages": [
      {
        "role": "user",
        "content": "Find flights from San Francisco to a place with warmer weather."
      }
    ],
    "thinking": {
      "type": "enabled",
      "budget_tokens": 1024
    }
  }'

建立自訂電腦使用環境

參考實作旨在幫助您快速開始使用電腦使用功能。它包含讓 Claude 使用電腦所需的所有元件。但是，您可以根據自身需求建立自己的電腦使用環境。您需要：

• 適合 Claude 電腦使用的虛擬化或容器化環境
• 至少一個 Anthropic 定義的電腦使用工具的實作
• 與 Claude API 互動並使用您的工具實作執行 tool_use 結果的代理迴圈
• 允許使用者輸入以啟動代理迴圈的 API 或 UI

實作電腦使用工具

電腦使用工具以無結構描述工具的形式實作。使用此工具時，您不需要像其他工具一樣提供輸入結構描述；結構描述已內建於 Claude 的模型中，無法修改。

處理錯誤

實作電腦使用工具時，可能會發生各種錯誤。以下是處理方式：

處理較高解析度的座標縮放

API 將圖像限制為最長邊最多 1568 像素，總計約 1.15 百萬像素（詳見圖像調整大小）。例如，1512x982 的螢幕會被降採樣至約 1330x864。Claude 分析這個較小的圖像並在該空間中返回座標，但您的工具在原始螢幕空間中執行點擊。

除非您處理座標轉換，否則這可能導致 Claude 的點擊座標偏離目標。

要解決此問題，請自行調整截圖大小並將 Claude 的座標縮放回原始大小：

import math


def get_scale_factor(width, height):
    """Calculate scale factor to meet API constraints."""
    long_edge = max(width, height)
    total_pixels = width * height

    long_edge_scale = 1568 / long_edge
    total_pixels_scale = math.sqrt(1_150_000 / total_pixels)

    return min(1.0, long_edge_scale, total_pixels_scale)


# When capturing screenshot
scale = get_scale_factor(screen_width, screen_height)
scaled_width = int(screen_width * scale)
scaled_height = int(screen_height * scale)

# Resize image to scaled dimensions before sending to Claude
screenshot = capture_and_resize(scaled_width, scaled_height)


# When handling Claude's coordinates, scale them back up
def execute_click(x, y):
    screen_x = x / scale
    screen_y = y / scale
    perform_click(screen_x, screen_y)

遵循實作最佳實踐

了解電腦使用的限制

電腦使用功能目前處於測試版。雖然 Claude 的能力處於前沿水準，但開發人員應了解其限制：

1. 延遲：目前電腦使用在人機互動方面的延遲可能比一般人工操作電腦的速度慢。請專注於速度不是關鍵的使用情境（例如，在受信任環境中進行背景資訊收集、自動化軟體測試）。
2. 電腦視覺準確性和可靠性：Claude 在生成動作時輸出特定座標時可能會出錯或產生幻覺。Claude Sonnet 3.7 引入了思考能力，可以幫助您了解模型的推理過程並識別潛在問題。
3. 工具選擇準確性和可靠性：Claude 在生成動作時選擇工具時可能會出錯或產生幻覺，或採取意外的動作來解決問題。此外，與小眾應用程式或同時與多個應用程式互動時，可靠性可能較低。在請求複雜任務時，請仔細提示模型。
4. 滾動可靠性：Claude Sonnet 3.7 引入了帶有方向控制的專用滾動動作，提升了可靠性。模型現在可以明確地按指定量向任意方向（上/下/左/右）滾動。
5. 試算表互動：Claude Sonnet 3.7 透過新增更精確的滑鼠控制動作（如 left_mouse_down、left_mouse_up）和新的修飾鍵支援，改善了試算表互動的滑鼠點擊。透過使用這些細粒度控制並將修飾鍵與點擊結合，儲存格選擇可以更加可靠。
6. 在社交和通訊平台上建立帳戶和生成內容：雖然 Claude 會造訪網站，但 Claude 在社交媒體網站和平台上建立帳戶、生成和分享內容或以其他方式進行人員模擬的能力是有限的。此功能可能在未來更新。
7. 漏洞：越獄或提示注入等漏洞可能在前沿 AI 系統中持續存在，包括測試版電腦使用 API。在某些情況下，Claude 會遵循內容中找到的命令，有時甚至與使用者的指示相衝突。例如，網頁上或圖像中包含的 Claude 指示可能會覆蓋指示或導致 Claude 出錯。請考慮以下事項： a. 將電腦使用限制在受信任的環境中，例如具有最低權限的虛擬機器或容器 b. 避免在沒有嚴格監督的情況下讓電腦使用存取敏感帳戶或資料 c. 在啟用或請求應用程式中電腦使用功能所需的權限之前，告知終端使用者相關風險並獲得其同意
8. 不當或非法行為：根據 Anthropic 的服務條款，您不得使用電腦使用功能違反任何法律或可接受使用政策。

請務必仔細審查和驗證 Claude 的電腦使用動作和日誌。在沒有人工監督的情況下，請勿將 Claude 用於需要完美精確度或涉及敏感使用者資訊的任務。

資料保留

電腦使用是一種客戶端工具。工作階段中涉及的所有截圖、滑鼠動作、鍵盤輸入和任何檔案都在您的環境中擷取和儲存，而非由 Anthropic 儲存。Anthropic 在 API 呼叫過程中即時處理截圖圖像和動作請求，但在返回回應後不會保留它們。

由於您的應用程式控制電腦使用資料的儲存位置和方式，電腦使用符合 ZDR 資格。有關所有功能的 ZDR 資格，請參閱 API 和資料保留。

定價

Computer use follows the standard tool use pricing. When using the computer use tool:

System prompt overhead: The computer use beta adds 466-499 tokens to the system prompt

Computer use tool token usage:

Additional token consumption:

• Screenshot images (see Vision pricing)
• Tool execution results returned to Claude

後續步驟