電腦使用工具

​

概述

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

​

模型相容性

​

安全考慮

​

快速入門

import anthropic

client = anthropic.Anthropic()

response = client.beta.messages.create(
    model="claude-sonnet-4-5",  # 或其他相容模型
    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)

​

電腦使用如何運作

​

計算環境

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

1. 接收 Claude 的工具使用請求
2. 將它們轉換為計算環境中的操作
3. 捕捉結果（螢幕截圖、命令輸出等）
4. 將這些結果返回給 Claude

​

如何實現電腦使用

​

從我們的參考實現開始

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

​

理解多代理迴圈

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})

"betas": ["computer-use-2025-01-24"]

"betas": ["computer-use-2025-01-24"]

​

通過提示優化模型性能

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

​

系統提示

您可以使用一組函數來回答使用者的問題。這包括對沙箱計算環境的存取。您目前無法檢查檔案或與外部資源互動，除非通過呼叫下面的函數。

​

可用操作

• screenshot - 捕捉當前顯示
• left_click - 在座標 [x, y] 處點擊
• type - 輸入文本字符串
• key - 按下鍵或鍵組合（例如「ctrl+s」）
• mouse_move - 將游標移動到座標

• scroll - 在任何方向滾動，具有數量控制
• left_click_drag - 在座標之間點擊並拖動
• right_click、middle_click - 其他滑鼠按鈕
• double_click、triple_click - 多次點擊
• left_mouse_down、left_mouse_up - 細粒度點擊控制
• hold_key - 在執行其他操作時按住鍵
• wait - 在操作之間暫停

// 取得螢幕截圖
{
  "action": "screenshot"
}

// 在位置點擊
{
  "action": "left_click",
  "coordinate": [500, 300]
}

// 輸入文本
{
  "action": "type",
  "text": "Hello, world!"
}

// 向下滾動（Claude 4/3.7）
{
  "action": "scroll",
  "coordinate": [500, 400],
  "scroll_direction": "down",
  "scroll_amount": 3
}

​

工具參數

​

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

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

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-sonnet-4-5",
    "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 進行電腦使用的虛擬化或容器化環境
• 至少一個 Anthropic 定義的電腦使用工具的實現
• 與 Claude API 互動並使用您的工具實現執行 tool_use 結果的代理迴圈
• 允許使用者輸入以啟動代理迴圈的 API 或 UI

​

實現電腦使用工具

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})

​

處理錯誤

{
  "role": "user",
  "content": [
    {
      "type": "tool_result",
      "tool_use_id": "toolu_01A09q90qw90lq917835lq9",
      "content": "Error: Failed to capture screenshot. Display may be locked or unavailable.",
      "is_error": true
    }
  ]
}

{
  "role": "user",
  "content": [
    {
      "type": "tool_result",
      "tool_use_id": "toolu_01A09q90qw90lq917835lq9",
      "content": "Error: Coordinates (1200, 900) are outside display bounds (1024x768).",
      "is_error": true
    }
  ]
}

{
  "role": "user",
  "content": [
    {
      "type": "tool_result",
      "tool_use_id": "toolu_01A09q90qw90lq917835lq9",
      "content": "Error: Failed to perform click action. The application may be unresponsive.",
      "is_error": true
    }
  ]
}

​

遵循實現最佳實踐

def click_and_wait(x, y, wait_time=0.5):
    click_at(x, y)
    time.sleep(wait_time)  # 允許 UI 更新

def validate_action(action_type, params):
    if action_type == "left_click":
        x, y = params.get("coordinate", (0, 0))
        if not (0 <= x < display_width and 0 <= y < display_height):
            return False, "Coordinates out of bounds"
    return True, None

import logging

def log_action(action_type, params, result):
    logging.info(f"Action: {action_type}, Params: {params}, Result: {result}")

​

了解電腦使用限制

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 的服務條款，您不得使用電腦使用來違反任何法律或我們的可接受使用政策。

​

定價

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

​

後續步驟