電腦使用工具

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

​

概述

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

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

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

​

模型相容性

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

​

安全考量

​

快速開始

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

import anthropic

client = anthropic.Anthropic()

response = client.beta.messages.create(
    model="claude-sonnet-4-20250514",  # or another compatible model
    max_tokens=1024,
    tools=[
        {
          "type": "computer_20250124",
          "name": "computer",
          "display_width_px": 1024,
          "display_height_px": 768,
          "display_number": 1,
        },
        {
          "type": "text_editor_20250124",
          "name": "str_replace_editor"
        },
        {
          "type": "bash_20250124",
          "name": "bash"
        }
    ],
    messages=[{"role": "user", "content": "Save a picture of a cat to my desktop."}],
    betas=["computer-use-2025-01-24"]
)
print(response)

​

電腦使用的工作原理

我們將步驟 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 一起使用電腦使用的容器化環境
• 電腦使用工具的實作
• 與 Anthropic 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
):
    """
    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：在每個步驟之後，截圖並仔細評估您是否達到了正確的結果。明確顯示您的思考：「我已經評估了步驟 X...」如果不正確，請重試。只有當您確認步驟執行正確時，才應該繼續下一步。
3. 一些 UI 元素（如下拉選單和捲軸）對於 Claude 使用滑鼠移動來操作可能很棘手。如果您遇到這種情況，請嘗試提示模型使用鍵盤快捷鍵。
4. 對於可重複的任務或 UI 互動，在您的提示中包含成功結果的範例螢幕截圖和工具呼叫。
5. 如果您需要模型登入，請在您的提示中在 xml 標籤內提供使用者名稱和密碼，如 <robot_credentials>。在需要登入的應用程式中使用電腦使用會增加因提示注入而導致不良結果的風險。在為模型提供登入憑證之前，請查看我們的緩解提示注入指南。

​

系統提示

當透過 Anthropic 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 - 在操作之間暫停

​

工具參數

​

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

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

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

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

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

啟用思考時，Claude 會將其推理過程作為回應的一部分返回，這可以幫助您：

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

以下是思考輸出可能看起來的範例：

[思考]
我需要將一張貓的圖片儲存到桌面。讓我將此分解為步驟：

1. 首先，我會截圖看看桌面上有什麼
2. 然後我會尋找網頁瀏覽器來搜尋貓的圖片
3. 找到合適的圖片後，我需要將其儲存到桌面

讓我先截圖看看有什麼可用的...

​

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

電腦使用工具可以與其他工具結合使用，以建立更強大的自動化工作流程。當您需要以下功能時，這特別有用：

• 執行系統命令（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-01-24" \
  -d '{
    "model": "claude-opus-4-20250514",
    "max_tokens": 2000,
    "tools": [
      {
        "type": "computer_20250124",
        "name": "computer",
        "display_width_px": 1024,
        "display_height_px": 768,
        "display_number": 1
      },
      {
        "type": "text_editor_20250124",
        "name": "str_replace_editor"
      },
      {
        "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 定義的電腦使用工具的實作
• 與 Anthropic API 互動並使用您的工具實作執行 tool_use 結果的代理迴圈
• 允許使用者輸入以啟動代理迴圈的 API 或 UI

​

實作電腦使用工具

電腦使用工具實作為無架構工具。使用此工具時，您不需要像其他工具一樣提供輸入架構；架構內建於 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"])
    # ... 處理其他操作

for content in response.content:
    if content.type == "tool_use":
        action = content.input["action"]
        result = handle_computer_action(action, content.input)
        
        # 將結果返回給 Claude
        tool_result = {
            "type": "tool_result",
            "tool_use_id": content.id,
            "content": result
        }

while True:
    response = client.beta.messages.create(...)
    
    # 檢查 Claude 是否使用了任何工具
    tool_results = process_tool_calls(response)
    
    if not tool_results:
        # 沒有更多工具使用，任務完成
        break
        
    # 使用工具結果繼續對話
    messages.append({"role": "user", "content": tool_results})

​

處理錯誤

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

​

遵循實作最佳實務

​

了解電腦使用限制

電腦使用功能處於測試階段。雖然 Claude 的能力是尖端的，但開發人員應該了解其限制：

1. 延遲：目前電腦使用對於人機互動的延遲可能與常規人為導向的電腦操作相比太慢。我們建議專注於速度不重要的使用案例（例如，在受信任環境中的背景資訊收集、自動化軟體測試）。
2. 電腦視覺準確性和可靠性：Claude 在生成操作時輸出特定座標時可能會犯錯或產生幻覺。Claude Sonnet 3.7 引入了思考功能，可以幫助您了解模型的推理並識別潛在問題。
3. 工具選擇準確性和可靠性：Claude 在生成操作時選擇工具時可能會犯錯或產生幻覺，或採取意外操作來解決問題。此外，在與小眾應用程式或同時與多個應用程式互動時，可靠性可能較低。我們建議使用者在請求複雜任務時仔細提示模型。
4. 捲動可靠性：雖然 Claude Sonnet 3.5（新版）在捲動方面有限制，但 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

​

下一步