電腦使用工具

建構工具

電腦使用工具

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

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

電腦使用處於測試版，需要測試版標頭：

"computer-use-2025-11-24" 適用於 Claude Opus 4.7、Claude Opus 4.6、Claude Sonnet 4.6、Claude Opus 4.5
"computer-use-2025-01-24" 適用於 Sonnet 4.5、Haiku 4.5、Opus 4.1、Sonnet 4、Opus 4 和 Sonnet 3.7（已棄用）

請通過回饋表單分享您對此功能的回饋。

This feature is eligible for Zero Data Retention (ZDR). When your organization has a ZDR arrangement, data sent through this feature is not stored after the API response is returned.

概述

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

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

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

有關模型支援，請參閱工具參考。

安全考慮

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

為了最小化風險，請考慮採取以下預防措施：

使用具有最小權限的專用虛擬機器或容器，以防止直接系統攻擊或意外。
避免讓模型訪問敏感資料，例如帳戶登入資訊，以防止資訊竊取。
將網際網路訪問限制在允許清單中的網域，以減少暴露於惡意內容的風險。
要求人類確認可能導致有意義的現實世界後果的決定，以及任何需要肯定同意的任務，例如接受 Cookie、執行財務交易或同意服務條款。

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

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

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

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

電腦使用參考實現

使用電腦使用參考實現快速入門，該實現包括網路介面、Docker 容器、範例工具實現和代理迴圈。

注意：該實現已更新，包括適用於 Claude 4 模型和 Claude Sonnet 3.7 的新工具。請確保拉取最新版本的儲存庫以訪問這些新功能。

快速入門

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

client = anthropic.Anthropic()

response = client.beta.messages.create(
    model="claude-opus-4-7",  # or another compatible model
    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."}],
    betas=["computer-use-2025-11-24"],
)
print(response)

測試版標頭僅對電腦使用工具是必需的。

上面的範例顯示了所有三個工具一起使用，這需要測試版標頭，因為它包括電腦使用工具。

電腦使用如何運作

為 Claude 提供電腦使用工具和使用者提示
- 在您的 API 請求中添加電腦使用工具（以及可選的其他工具）。
- 包括需要桌面互動的使用者提示，例如「將貓的圖片保存到我的桌面」。
Claude 決定使用電腦使用工具
- Claude 評估電腦使用工具是否可以幫助解決使用者的查詢。
- 如果是，Claude 會構造一個格式正確的工具使用請求。
- API 回應的 stop_reason 為 tool_use，表示 Claude 的意圖。
提取工具輸入，在電腦上評估工具，並返回結果
- 在您的端，從 Claude 的請求中提取工具名稱和輸入。
- 在容器或虛擬機器上使用該工具。
- 使用包含 tool_result 內容塊的新 user 訊息繼續對話。
Claude 繼續調用電腦使用工具，直到完成任務
- Claude 分析工具結果以確定是否需要更多工具使用或任務已完成。
- 如果 Claude 決定需要另一個工具，它會以另一個 tool_use stop_reason 回應，您應該返回第 3 步。
- 否則，它會為使用者製作文本回應。

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

計算環境

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

虛擬顯示：虛擬 X11 顯示伺服器（使用 Xvfb），它呈現 Claude 將通過螢幕截圖看到的桌面介面，並通過滑鼠/鍵盤操作進行控制。
桌面環境：在 Linux 上運行的輕量級 UI，具有視窗管理器（Mutter）和面板（Tint2），為 Claude 提供一致的圖形介面以進行互動。
應用程式：預安裝的 Linux 應用程式，如 Firefox、LibreOffice、文本編輯器和檔案管理器，Claude 可以使用它們來完成任務。
工具實現：集成代碼，將 Claude 的抽象工具請求（如「移動滑鼠」或「截圖」）轉換為虛擬環境中的實際操作。
代理迴圈：一個程式，處理 Claude 和環境之間的通訊，將 Claude 的操作發送到環境，並將結果（螢幕截圖、命令輸出）返回給 Claude。

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

接收 Claude 的工具使用請求
將它們轉換為您計算環境中的操作
捕捉結果（螢幕截圖、命令輸出等）
將這些結果返回給 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"
    )
    text_editor_type = (
        "text_editor_20250728"
        if "20251124" in tool_version
        else f"text_editor_{tool_version}"
    )

    # 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": text_editor_type, "name": "str_replace_based_edit_tool"},
        {"type": "bash_20250124", "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 成本的潛在無限迴圈。

在閱讀本文檔的其餘部分之前，請先嘗試參考實現。

通過提示優化模型性能

以下是一些獲得最佳品質輸出的提示：

指定簡單、明確定義的任務，並為每個步驟提供明確的指示。
Claude 有時會假設其操作的結果，而不明確檢查它們。為了防止這種情況，您可以使用以下提示提示 Claude：在每個步驟之後，截圖並仔細評估您是否達到了正確的結果。明確顯示您的思考：「我已評估步驟 X...」如果不正確，請重試。只有在您確認步驟執行正確後，才應繼續下一步。
某些 UI 元素（如下拉菜單和滾動條）可能對 Claude 使用滑鼠移動進行操作很棘手。如果您遇到這種情況，請嘗試提示模型使用鍵盤快捷鍵。
對於可重複的任務或 UI 互動，在您的提示中包括成功結果的範例螢幕截圖和工具調用。
如果您需要模型登入，請在您的提示中使用 xml 標籤（如 <robot_credentials>）為其提供使用者名稱和密碼。在需要登入的應用程式中使用電腦使用會增加由於提示注入而導致不良結果的風險。在向模型提供登入認證之前，請查看關於緩解提示注入的指南。

如果您反覆遇到一組明確的問題，或提前知道 Claude 需要完成的任務，請使用系統提示為 Claude 提供明確的提示或有關如何成功完成任務的指示。

對於跨越多個會話的代理，在每個會話開始時運行端到端驗證，而不僅在實現後運行。基於瀏覽器的檢查會捕捉來自先前會話的迴歸，而僅代碼級別的審查會遺漏。有關詳細信息，請參閱長期運行代理的有效工具。

系統提示

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

您可以訪問一組函數來幫助回答使用者的問題。這包括訪問沙盒計算環境。您目前無法檢查檔案或與外部資源互動，除非通過調用以下函數。

與常規工具使用一樣，使用者提供的 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.7、Claude Opus 4.6、Claude Sonnet 4.6 和 Claude Opus 4.5 中可用：

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

工具參數

參數	必需	描述
`type`	是	工具版本（`computer_20251124` 或 `computer_20250124`）
`name`	是	必須為「computer」
`display_width_px`	是	顯示寬度（以像素為單位）
`display_height_px`	是	顯示高度（以像素為單位）
`display_number`	否	X11 環境的顯示編號
`enable_zoom`	否	啟用縮放操作（僅 `computer_20251124`）。設置為 `true` 以允許 Claude 縮放到特定螢幕區域。預設值：`false`

重要：電腦使用工具必須由您的應用程式明確執行 - Claude 無法直接執行它。您負責根據 Claude 的請求實現螢幕截圖捕捉、滑鼠移動、鍵盤輸入和其他操作。

與擴展思考結合

有關將電腦使用與擴展思考結合，請參閱擴展思考。

使用其他工具增強電腦使用

要在電腦使用旁邊添加其他工具，請將它們包括在同一 tools 陣列中。上面的快速入門顯示了此模式，其中包含 bash 工具和文本編輯器工具。您可以以相同的方式添加您自己的自訂工具定義。

建立自訂電腦使用環境

參考實作旨在幫助您開始使用電腦使用功能。它包含了讓 Claude 使用電腦所需的所有元件。不過，您可以建立自己的電腦使用環境來滿足您的需求。您需要：

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

實作電腦使用工具

電腦使用工具實作為無架構工具。使用此工具時，您不需要像其他工具那樣提供輸入架構；架構內建於 Claude 的模型中，無法修改。

設定您的運算環境
建立虛擬顯示器或連接到 Claude 將與之互動的現有顯示器。這通常涉及設定 Xvfb（X 虛擬幀緩衝區）或類似技術。

實作動作處理程式

建立函數來處理 Claude 可能要求的每種動作類型：

def handle_computer_action(action_type, params):
    if action_type == "screenshot":
        return capture_screenshot()
    elif action_type == "left_click":
        x, y = params["coordinate"]
        return click_at(x, y)
    elif action_type == "type":
        return type_text(params["text"])
    # ... handle other actions

處理 Claude 的工具呼叫

從 Claude 的回應中提取並執行工具呼叫：

for content in response.content:
    if content.type == "tool_use":
        action = content.input["action"]
        result = handle_computer_action(action, content.input)

        # Return result to Claude
        tool_result = {
            "type": "tool_result",
            "tool_use_id": content.id,
            "content": result,
        }

實作代理迴圈

建立一個迴圈，持續執行直到 Claude 完成任務：

while True:
    response = client.beta.messages.create(
        model="claude-opus-4-7",
        max_tokens=4096,
        messages=messages,
        tools=tools,
        betas=["computer-use-2025-11-24"],
    )

    # Check if Claude used any tools
    tool_results = process_tool_calls(response)

    if not tool_results:
        # No more tool use, task complete
        break

    # Continue conversation with tool results
    messages.append({"role": "user", "content": tool_results})

處理錯誤

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

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

Claude Opus 4.7 支援長邊最多 2576 像素，其座標與影像像素的比例為 1

（不需要進行縮放因子轉換）。下面的 1568 像素指導適用於較早的模型。

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 的功能是最先進的，但開發人員應該了解其限制：

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

Model	Input tokens per tool definition
Claude 4.x models	735 tokens
Claude Sonnet 3.7 (deprecated)	735 tokens

Additional token consumption:

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

If you're also using bash or text editor tools alongside computer use, those tools have their own token costs as documented in their respective pages.

後續步驟

參考實作

使用完整的 Docker 實作快速開始

工具文件

深入了解工具使用和建立自訂工具

Was this page helpful?

建構工具

電腦使用工具

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

電腦使用處於測試版，需要測試版標頭：

"computer-use-2025-11-24" 適用於 Claude Opus 4.7、Claude Opus 4.6、Claude Sonnet 4.6、Claude Opus 4.5
"computer-use-2025-01-24" 適用於 Sonnet 4.5、Haiku 4.5、Opus 4.1、Sonnet 4、Opus 4 和 Sonnet 3.7（已棄用）

請通過回饋表單分享您對此功能的回饋。

This feature is eligible for Zero Data Retention (ZDR). When your organization has a ZDR arrangement, data sent through this feature is not stored after the API response is returned.

概述

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

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

有關模型支援，請參閱工具參考。

安全考慮

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

為了最小化風險，請考慮採取以下預防措施：

使用具有最小權限的專用虛擬機器或容器，以防止直接系統攻擊或意外。
避免讓模型訪問敏感資料，例如帳戶登入資訊，以防止資訊竊取。
將網際網路訪問限制在允許清單中的網域，以減少暴露於惡意內容的風險。
要求人類確認可能導致有意義的現實世界後果的決定，以及任何需要肯定同意的任務，例如接受 Cookie、執行財務交易或同意服務條款。

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

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

電腦使用參考實現

使用電腦使用參考實現快速入門，該實現包括網路介面、Docker 容器、範例工具實現和代理迴圈。

注意：該實現已更新，包括適用於 Claude 4 模型和 Claude Sonnet 3.7 的新工具。請確保拉取最新版本的儲存庫以訪問這些新功能。

快速入門

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

client = anthropic.Anthropic()

response = client.beta.messages.create(
    model="claude-opus-4-7",  # or another compatible model
    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."}],
    betas=["computer-use-2025-11-24"],
)
print(response)

測試版標頭僅對電腦使用工具是必需的。

上面的範例顯示了所有三個工具一起使用，這需要測試版標頭，因為它包括電腦使用工具。

電腦使用如何運作

為 Claude 提供電腦使用工具和使用者提示
- 在您的 API 請求中添加電腦使用工具（以及可選的其他工具）。
- 包括需要桌面互動的使用者提示，例如「將貓的圖片保存到我的桌面」。
Claude 決定使用電腦使用工具
- Claude 評估電腦使用工具是否可以幫助解決使用者的查詢。
- 如果是，Claude 會構造一個格式正確的工具使用請求。
- API 回應的 stop_reason 為 tool_use，表示 Claude 的意圖。
提取工具輸入，在電腦上評估工具，並返回結果
- 在您的端，從 Claude 的請求中提取工具名稱和輸入。
- 在容器或虛擬機器上使用該工具。
- 使用包含 tool_result 內容塊的新 user 訊息繼續對話。
Claude 繼續調用電腦使用工具，直到完成任務
- Claude 分析工具結果以確定是否需要更多工具使用或任務已完成。
- 如果 Claude 決定需要另一個工具，它會以另一個 tool_use stop_reason 回應，您應該返回第 3 步。
- 否則，它會為使用者製作文本回應。

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

計算環境

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

虛擬顯示：虛擬 X11 顯示伺服器（使用 Xvfb），它呈現 Claude 將通過螢幕截圖看到的桌面介面，並通過滑鼠/鍵盤操作進行控制。
桌面環境：在 Linux 上運行的輕量級 UI，具有視窗管理器（Mutter）和面板（Tint2），為 Claude 提供一致的圖形介面以進行互動。
應用程式：預安裝的 Linux 應用程式，如 Firefox、LibreOffice、文本編輯器和檔案管理器，Claude 可以使用它們來完成任務。
工具實現：集成代碼，將 Claude 的抽象工具請求（如「移動滑鼠」或「截圖」）轉換為虛擬環境中的實際操作。
代理迴圈：一個程式，處理 Claude 和環境之間的通訊，將 Claude 的操作發送到環境，並將結果（螢幕截圖、命令輸出）返回給 Claude。

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

接收 Claude 的工具使用請求
將它們轉換為您計算環境中的操作
捕捉結果（螢幕截圖、命令輸出等）
將這些結果返回給 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"
    )
    text_editor_type = (
        "text_editor_20250728"
        if "20251124" in tool_version
        else f"text_editor_{tool_version}"
    )

    # 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": text_editor_type, "name": "str_replace_based_edit_tool"},
        {"type": "bash_20250124", "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 成本的潛在無限迴圈。

在閱讀本文檔的其餘部分之前，請先嘗試參考實現。

通過提示優化模型性能

以下是一些獲得最佳品質輸出的提示：

指定簡單、明確定義的任務，並為每個步驟提供明確的指示。
Claude 有時會假設其操作的結果，而不明確檢查它們。為了防止這種情況，您可以使用以下提示提示 Claude：在每個步驟之後，截圖並仔細評估您是否達到了正確的結果。明確顯示您的思考：「我已評估步驟 X...」如果不正確，請重試。只有在您確認步驟執行正確後，才應繼續下一步。
某些 UI 元素（如下拉菜單和滾動條）可能對 Claude 使用滑鼠移動進行操作很棘手。如果您遇到這種情況，請嘗試提示模型使用鍵盤快捷鍵。
對於可重複的任務或 UI 互動，在您的提示中包括成功結果的範例螢幕截圖和工具調用。
如果您需要模型登入，請在您的提示中使用 xml 標籤（如 <robot_credentials>）為其提供使用者名稱和密碼。在需要登入的應用程式中使用電腦使用會增加由於提示注入而導致不良結果的風險。在向模型提供登入認證之前，請查看關於緩解提示注入的指南。

如果您反覆遇到一組明確的問題，或提前知道 Claude 需要完成的任務，請使用系統提示為 Claude 提供明確的提示或有關如何成功完成任務的指示。

系統提示

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

您可以訪問一組函數來幫助回答使用者的問題。這包括訪問沙盒計算環境。您目前無法檢查檔案或與外部資源互動，除非通過調用以下函數。

與常規工具使用一樣，使用者提供的 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.7、Claude Opus 4.6、Claude Sonnet 4.6 和 Claude Opus 4.5 中可用：

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

工具參數

參數	必需	描述
`type`	是	工具版本（`computer_20251124` 或 `computer_20250124`）
`name`	是	必須為「computer」
`display_width_px`	是	顯示寬度（以像素為單位）
`display_height_px`	是	顯示高度（以像素為單位）
`display_number`	否	X11 環境的顯示編號
`enable_zoom`	否	啟用縮放操作（僅 `computer_20251124`）。設置為 `true` 以允許 Claude 縮放到特定螢幕區域。預設值：`false`

與擴展思考結合

有關將電腦使用與擴展思考結合，請參閱擴展思考。

使用其他工具增強電腦使用

建立自訂電腦使用環境

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

實作電腦使用工具

電腦使用工具實作為無架構工具。使用此工具時，您不需要像其他工具那樣提供輸入架構；架構內建於 Claude 的模型中，無法修改。

設定您的運算環境
建立虛擬顯示器或連接到 Claude 將與之互動的現有顯示器。這通常涉及設定 Xvfb（X 虛擬幀緩衝區）或類似技術。

實作動作處理程式

建立函數來處理 Claude 可能要求的每種動作類型：

def handle_computer_action(action_type, params):
    if action_type == "screenshot":
        return capture_screenshot()
    elif action_type == "left_click":
        x, y = params["coordinate"]
        return click_at(x, y)
    elif action_type == "type":
        return type_text(params["text"])
    # ... handle other actions

處理 Claude 的工具呼叫

從 Claude 的回應中提取並執行工具呼叫：

for content in response.content:
    if content.type == "tool_use":
        action = content.input["action"]
        result = handle_computer_action(action, content.input)

        # Return result to Claude
        tool_result = {
            "type": "tool_result",
            "tool_use_id": content.id,
            "content": result,
        }

實作代理迴圈

建立一個迴圈，持續執行直到 Claude 完成任務：

while True:
    response = client.beta.messages.create(
        model="claude-opus-4-7",
        max_tokens=4096,
        messages=messages,
        tools=tools,
        betas=["computer-use-2025-11-24"],
    )

    # Check if Claude used any tools
    tool_results = process_tool_calls(response)

    if not tool_results:
        # No more tool use, task complete
        break

    # Continue conversation with tool results
    messages.append({"role": "user", "content": tool_results})

處理錯誤

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

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

Claude Opus 4.7 支援長邊最多 2576 像素，其座標與影像像素的比例為 1

（不需要進行縮放因子轉換）。下面的 1568 像素指導適用於較早的模型。

除非您處理座標轉換，否則這可能會導致 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 的功能是最先進的，但開發人員應該了解其限制：

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

始終仔細檢查並驗證 Claude 的電腦使用動作和日誌。不要在沒有人工監督的情況下使用 Claude 進行需要完美精度或敏感使用者資訊的任務。

資料保留

因為您的應用程式控制電腦使用資料的儲存位置和方式，電腦使用符合 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:

Model	Input tokens per tool definition
Claude 4.x models	735 tokens
Claude Sonnet 3.7 (deprecated)	735 tokens

Additional token consumption:

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

If you're also using bash or text editor tools alongside computer use, those tools have their own token costs as documented in their respective pages.

後續步驟

參考實作

使用完整的 Docker 實作快速開始

工具文件

深入了解工具使用和建立自訂工具

Was this page helpful?

概述

安全考慮

快速入門

電腦使用如何運作

計算環境

如何實現電腦使用

從參考實現開始

理解代理迴圈

通過提示優化模型性能

系統提示

可用操作

範例操作

使用點擊和滾動操作的修飾鍵

工具參數

與擴展思考結合

使用其他工具增強電腦使用

建立自訂電腦使用環境

實作電腦使用工具

處理錯誤

螢幕擷取失敗

無效的座標

動作執行失敗

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

遵循實作最佳實踐

使用適當的顯示解析度

實作適當的螢幕擷取處理

新增動作延遲

在執行前驗證動作

記錄動作以進行除錯

了解電腦使用限制

資料保留

定價

後續步驟

概述

安全考慮

快速入門

電腦使用如何運作

計算環境

如何實現電腦使用

從參考實現開始

理解代理迴圈

通過提示優化模型性能

系統提示

可用操作

範例操作

使用點擊和滾動操作的修飾鍵

工具參數

與擴展思考結合

使用其他工具增強電腦使用

建立自訂電腦使用環境

實作電腦使用工具

處理錯誤

螢幕擷取失敗

無效的座標

動作執行失敗

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

遵循實作最佳實踐

使用適當的顯示解析度

實作適當的螢幕擷取處理

新增動作延遲

在執行前驗證動作

記錄動作以進行除錯

了解電腦使用限制

資料保留

定價

後續步驟