電腦使用工具

Claude 可以透過電腦使用工具與電腦環境互動，該工具提供螢幕截圖功能以及滑鼠/鍵盤控制，實現自主桌面互動。

概述

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

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

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

模型相容性

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

安全注意事項

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

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

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

我們仍然建議採取預防措施，將 Claude 與敏感資料和操作隔離，以避免與提示注入相關的風險。

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

快速開始

以下是如何開始使用電腦使用：

電腦使用的運作方式

我們將步驟 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-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。接受帶有座標 [x1, y1, x2, y2] 的 region 參數，定義要檢視區域的左上角和右下角。

工具參數

在 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 或服務整合（自訂工具）

建構自訂電腦使用環境

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

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

實作電腦使用工具

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

處理錯誤

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

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

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

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

要修正此問題，請自行調整螢幕截圖大小並將 Claude 的座標按比例放大：

遵循實作最佳實踐

了解電腦使用的限制

電腦使用功能目前處於測試版。雖然 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 會造訪網站，但我們限制了它在社交媒體網站和平台上建立帳號或生成和分享內容或以其他方式進行人類冒充的能力。我們未來可能會更新此功能。
7. 漏洞：越獄或提示注入等漏洞可能存在於前沿 AI 系統中，包括測試版電腦使用 API。在某些情況下，Claude 會遵循內容中發現的指令，有時甚至與使用者的指示相衝突。例如，網頁上的 Claude 指令或圖片中包含的指令可能會覆蓋指示或導致 Claude 犯錯。我們建議： a. 將電腦使用限制在可信環境中，例如具有最小權限的虛擬機器或容器 b. 避免在沒有嚴格監督的情況下讓電腦使用存取敏感帳號或資料 c. 告知終端使用者相關風險，並在啟用或請求應用程式中電腦使用功能所需的權限之前獲得他們的同意
8. ：根據 Anthropic 的服務條款，您不得使用電腦使用功能來違反任何法律或我們的可接受使用政策。

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

定價

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

後續步驟