電腦使用工具

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

概述

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

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

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

模型相容性

電腦使用適用於以下 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,  # 新增迭代限制以防止無限迴圈
):
    """
    Claude 電腦使用互動的簡單代理迴圈。

    此函數處理以下之間的來回：
    1. 將使用者訊息發送給 Claude
    2. Claude 請求使用工具
    3. 您的應用程式執行這些工具
    4. 將工具結果發送回 Claude
    """
    # 設定工具和 API 參數
    client = Anthropic(api_key=api_key)
    beta_flag = "computer-use-2025-01-24" if "20250124" in tool_version else "computer-use-2024-10-22"

    # 配置工具 - 您應該已在其他地方初始化這些工具
    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"}
    ]

    # 主代理迴圈（具有迭代限制以防止失控的 API 成本）
    iterations = 0
    while True and iterations < max_iterations:
        iterations += 1
        # 設定可選的思考參數（適用於 Claude Sonnet 3.7）
        thinking = None
        if thinking_budget:
            thinking = {"type": "enabled", "budget_tokens": thinking_budget}

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

        # 將 Claude 的回應新增到對話歷史記錄
        response_content = response.content
        messages.append({"role": "assistant", "content": response_content})

        # 檢查 Claude 是否使用了任何工具
        tool_results = []
        for block in response_content:
            if block.type == "tool_use":
                # 在實際應用程式中，您會在此執行工具
                # 例如：result = run_tool(block.name, block.input)
                result = {"result": "Tool executed successfully"}

                # 為 Claude 格式化結果
                tool_results.append({
                    "type": "tool_result",
                    "tool_use_id": block.id,
                    "content": result
                })

        # 如果未使用任何工具，Claude 已完成 - 返回最終訊息
        if not tool_results:
            return messages

        # 將工具結果新增到訊息中，以供下一次 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.5 中可用：

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

工具參數

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

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

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

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

budget_tokens 參數指定 Claude 可以用於思考的令牌數。這從您的整體 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. 漏洞：越獄或提示注入等漏洞可能會在包括測試版電腦使用 API 在內的前沿 AI 系統中持續存在。在某些情況下，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

後續步驟