電腦使用工具

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

電腦使用工具是 Anthropic 定義的「client toolset」（用戶端工具集）：在 tools 中加入一個 {"type": "computer_toolset_20260801"} 項目，即可讓 Claude 取得 17 個成員工具，例如 screenshot、left_click、type 與 zoom，而您的應用程式會在您所控制的環境中執行每一個呼叫。此工具目前無法在 Claude Managed Agents 中使用。Claude 的呼叫是 tool_use 區塊，其 name 為成員名稱，並帶有 "toolset_name": "computer"，且通常在單一回合中包含多個（即「batch action」（批次動作））。

對於停留在網頁內的任務，瀏覽器使用工具更為合適：其成員工具會直接讀取並操作頁面本身，且不需要完整的桌面環境。

請參閱 API 支援，了解支援此「toolset」（工具集）的模型和平台。較早的工具版本列出了每個較早版本的 beta 標頭，以及適用的模型。

安全性考量

電腦使用具有不同於標準 API 功能的獨特風險。與網際網路互動時，這些風險會更加顯著。

在某些情況下，Claude 會遵循內容中找到的指令，即使這些指令與您的指示相衝突。例如，網頁上或圖片中包含的指示可能會覆寫您的指示，或導致 Claude 犯錯。請採取預防措施，將 Claude 與敏感資料及動作隔離，以避免與「prompt injection」（提示注入）相關的風險。

Anthropic 已訓練模型抵抗這些提示注入，並增加了一層額外的防禦。如果您使用電腦使用工具，分類器會自動掃描工具傳回的內容（例如螢幕截圖），以標記潛在的提示注入。當這些分類器識別出潛在的提示注入時，會引導模型在執行指令之前，先確認該指令是否確實來自您。

這項額外保護並非適用於所有使用情境（例如沒有人員參與流程的使用情境），因此如果您想選擇退出並關閉此功能，請聯絡支援團隊。即使有這些分類器，前述的預防措施仍然很重要。

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

快速入門

將電腦使用工具集以 {"type": "computer_toolset_20260801"} 的形式加入 Messages API可檢視預覽，內含 API 參考文件連結——按 Tab 鍵直到焦點進入卡片，按 Escape 鍵返回。 請求的 tools 陣列。此請求不需要 beta 標頭。此範例也宣告了 文字編輯器工具 與 bash 工具，Claude 通常會將它們與電腦使用搭配使用：

client = anthropic.Anthropic()

response = client.messages.create(
    model="claude-opus-5-5",
    max_tokens=1024,
    tools=[
        {"type": "computer_toolset_20260801"},
        {"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."}],
)
print(response)

當 Claude 在桌面上執行動作時，回應的 stop_reason 為 tool_use，並包含一個或多個成員 tool_use 區塊，每個區塊都指定一個成員工具並帶有 "toolset_name": "computer"。在此任務進行到一半、Claude 已收到桌面的螢幕截圖之後，回應可能如下所示：

{
  "id": "msg_01UZ3bXcQH8mTqNhVfL9eK2p",
  "type": "message",
  "role": "assistant",
  "model": "claude-opus-5-5",
  "content": [
    {
      "type": "text",
      "text": "I'll open the web browser to find a picture of a cat."
    },
    {
      "type": "tool_use",
      "id": "toolu_01WkoTUvSHDzTBu2xnGk8Ep8",
      "name": "left_click",
      "toolset_name": "computer",
      "input": { "coordinate": [512, 742] }
    },
    {
      "type": "tool_use",
      "id": "toolu_017nJn3RgSCkTMwuZDb4uUov",
      "name": "screenshot",
      "toolset_name": "computer",
      "input": {}
    }
  ],
  "stop_reason": "tool_use",
  "stop_sequence": null
}

您的應用程式會在您自己的環境中依序執行每個呼叫，為每個 tool_use 區塊傳回一個 tool_result 區塊，然後再次呼叫 API；電腦使用的運作方式說明了這個迴圈，本頁其餘部分則說明如何實作它。

電腦使用的運作方式

1. 1

   為 Claude 提供電腦使用工具與使用者提示

   • 將電腦使用工具集（以及選擇性的其他工具）加入 API 請求的 tools 陣列。
   • 加入需要桌面互動的使用者提示，例如「將一張貓的圖片儲存到我的桌面」。
2. 2

   Claude 以成員工具呼叫回應

   • Claude 評估在桌面上執行動作是否有助於處理使用者的查詢。
   • 如果有幫助，Claude 會以一個或多個成員 tool_use 區塊回應，例如 screenshot、left_click 或 type，每個區塊都帶有 "toolset_name": "computer"。包含多個此類區塊的回應即為批次動作。
   • API 回應的 stop_reason 為 tool_use，表示這是一個工具使用請求。
3. 3

   依序執行呼叫並傳回結果

   • 依序逐一處理回應中的每個 tool_use 區塊。對於每個區塊，根據成員 name 與 toolset_name 進行分派，並在您的容器或虛擬機器上以該區塊的 input 執行該動作。
   • 以新的 user 訊息繼續對話，其中為每個 tool_use 區塊包含一個 tool_result 區塊，透過 tool_use_id 對應，且每個區塊都回傳 "toolset_name": "computer"。對 screenshot 與 zoom 傳回圖片；其他動作只需傳回簡短文字（例如 OK）即可。
   • 如果某個動作失敗，請為該區塊傳回 is_error: true，並依照批次動作中的說明回應批次中的其餘部分。
4. 4

   Claude 持續進行直到任務完成

   • Claude 分析工具結果，以判斷是否需要更多動作或任務是否已完成。
   • 如果 Claude 判斷需要更多動作，它會再次以 tool_use stop_reason 回應；請回到步驟 3。
   • 否則，它會向使用者傳回文字回應。

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

批次動作

Claude 可以規劃一小段動作序列，例如點擊、輸入，然後擷取螢幕截圖，並在單一回應中一併傳回。這稱為批次動作；它使用與平行工具使用相同的回應結構，但有一點不同：您需要依序執行這些區塊，而非同時執行。

包含三個動作的批次回應如下所示：

{
  "role": "assistant",
  "content": [
    {
      "type": "tool_use",
      "id": "toolu_01HqCF3nJ4Vzr8sTkPZ2wxYA",
      "name": "left_click",
      "toolset_name": "computer",
      "input": { "coordinate": [640, 60] }
    },
    {
      "type": "tool_use",
      "id": "toolu_01Ppr3sZ3TnE9m6VUu4RyH2K",
      "name": "type",
      "toolset_name": "computer",
      "input": { "text": "pictures of cats" }
    },
    {
      "type": "tool_use",
      "id": "toolu_01Xf5W1sD8Q9aBcJ7kLmN2pQ",
      "name": "screenshot",
      "toolset_name": "computer",
      "input": {}
    }
  ]
}

在下一個 user 訊息中，為每個 tool_use 區塊傳回一個 tool_result 區塊，並透過 tool_use_id 對應。每個成員工具的結果都必須帶有 "toolset_name": "computer"；省略此欄位，或指定的工具集與其 tool_use 區塊不同的結果，將會被拒絕。只有 screenshot 與 zoom 的結果需要圖片；對於其他成員，簡短的文字確認（例如 OK）即可（cursor_position 會以文字形式傳回座標）：

{
  "role": "user",
  "content": [
    {
      "type": "tool_result",
      "tool_use_id": "toolu_01HqCF3nJ4Vzr8sTkPZ2wxYA",
      "toolset_name": "computer",
      "content": [{ "type": "text", "text": "OK" }]
    },
    {
      "type": "tool_result",
      "tool_use_id": "toolu_01Ppr3sZ3TnE9m6VUu4RyH2K",
      "toolset_name": "computer",
      "content": [{ "type": "text", "text": "OK" }]
    },
    {
      "type": "tool_result",
      "tool_use_id": "toolu_01Xf5W1sD8Q9aBcJ7kLmN2pQ",
      "toolset_name": "computer",
      "content": [
        {
          "type": "image",
          "source": {
            "type": "base64",
            "media_type": "image/png",
            "data": "iVBORw0KGgo..."
          }
        }
      ]
    }
  ]
}

依序執行區塊，並在第一次失敗時停止。 批次中較後面的動作通常依賴於較前面的動作：此範例中的 type 會將文字輸入到前一次點擊所聚焦的位置。請依照區塊在 content 中出現的順序依序執行，若其中一個失敗，就不要執行其餘區塊。每個 tool_use 區塊仍然需要一個 tool_result，因此請以下列方式回應批次：

• 對於每個成功的動作，傳回其正常結果。
• 對於失敗的動作，傳回 is_error: true，並附上說明問題的文字描述。
• 對於批次中之後的每個動作，傳回 is_error: true 並附上完全相同的下列文字（瀏覽器使用工具則使用其自己的中止文字）：

{
  "type": "tool_result",
  "tool_use_id": "toolu_01Xf5W1sD8Q9aBcJ7kLmN2pQ",
  "toolset_name": "computer",
  "is_error": true,
  "content": "Not executed: an earlier computer action in this turn failed."
}

接著 Claude 會讀取哪些動作成功、哪一個失敗、以及哪些被略過，並在下一回合重新規劃。若請求中批次內有任何 tool_use 區塊未獲回應，將會以 invalid_request_error 被拒絕，因此只讀取第一個區塊的代理迴圈會在下一次呼叫時失敗。如果您的應用程式會請人員確認具重大影響的動作，請在每個區塊執行之前進行該檢查，因為一個批次可以在單一回合內完成多步驟的動作。

Claude 通常會以 screenshot 結束一個批次，以便在決定下一步之前觀察結果。當批次未以螢幕截圖結束時，您的應用程式可以在批次的最後一個結果中附加一張螢幕截圖作為額外的 image 區塊，讓 Claude 始終能收到螢幕的目前狀態，相較於等待 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 容器內執行上述所有內容，並設定適當的連接埠對應，以便檢視環境並與之互動。

如何實作電腦使用

要升級現有的 computer_20251124 整合嗎？請從從 computer_20251124 遷移開始；本節其餘內容同時適用於新的整合與已遷移的整合。

了解代理迴圈

電腦使用的核心是「代理迴圈」：一個由 Claude 請求工具動作，而您的應用程式執行這些動作並將結果傳回給 Claude 的循環。此迴圈使用您在快速入門中建立的用戶端、一個僅宣告電腦使用工具集的 tools 陣列，以及實作電腦使用工具中的工具呼叫處理輔助函式。如果您也宣告了其他工具（例如快速入門中的 bash 與文字編輯器工具），請在同一輪處理中分派它們的 tool_use 區塊；該輔助函式只會回應電腦使用成員的呼叫，而迴圈會將沒有任何已回應呼叫的回合視為已完成。以下是一個簡化的範例：

def sampling_loop(model: str, messages: list[MessageParam], max_iterations: int = 10):
    """
    Run the computer-use agent loop until Claude stops requesting tools
    or the iteration limit is reached.
    """
    for _ in range(max_iterations):
        response = client.messages.create(
            model=model,
            max_tokens=4096,
            messages=messages,
            tools=TOOLS,
        )

        # 將 Claude 的回應加入對話歷史
        messages.append({"role": "assistant", "content": response.content})

        # 依序執行 Claude 請求的動作，並收集結果
        tool_results = process_tool_calls(response)
        if not tool_results:
            return messages  # No more tool use; task complete

        # 將所有結果以單一 user 訊息傳回給 Claude
        messages.append({"role": "user", "content": tool_results})

    return messages

迴圈會持續進行，直到 Claude 在未請求任何工具的情況下回應（任務完成），或達到最大迭代次數限制為止。此保護措施可防止可能導致非預期 API 費用的無限迴圈。

透過提示最佳化模型效能

1. 指定簡單、定義明確的任務，並為每個步驟提供明確的指示。
2. Claude 有時會在未明確檢查結果的情況下，表現得好像其動作已成功。為避免這種情況，您可以用以下內容提示 Claude：After each step, take a screenshot and carefully evaluate if you have achieved the right outcome. State in one sentence what the screenshot shows and whether the step succeeded. If it didn't, 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>）包住使用者名稱與密碼提供給它。在需要登入的應用程式中使用電腦使用，會增加因提示注入而導致不良結果的風險。在向模型提供登入憑證之前，請先閱讀減輕越獄與提示注入。
6. 建構使用者回合的 content 陣列時，請將指示文字放在螢幕截圖圖片之前。在處理圖片之前先提供目標描述，可以提高點擊準確度。
7. 當被問及在螢幕截圖預設解析度下無法辨識的小型文字或特定 UI 元素時（例如側邊欄中的檔案名稱、分頁標題、狀態列文字、行號或按鈕標籤），Claude 會使用 zoom 動作以完整解析度檢查某個區域。如果 Claude 沒有在您預期時進行縮放，請詢問特定區域或元素，而非整個螢幕。
8. 如果您希望每個批次動作都以螢幕截圖結束，請在系統提示中說明，例如：End each group of actions with a screenshot so you can verify the result before continuing.

系統提示

當您在請求中加入電腦使用工具時，API 會產生電腦使用專用的系統提示。它類似於工具使用系統提示，但開頭如下：

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 參數仍會受到採用，並用於建構合併後的系統提示。

可用動作

每個動作都是電腦使用工具集的一個成員工具：Claude 會在帶有 "toolset_name": "computer" 的 tool_use 區塊中指定成員名稱，而該區塊的 input 僅包含該成員的參數，沒有 action 欄位。此工具集有 17 個成員工具：

實作這些成員時，請注意以下事項：

• 座標以螢幕截圖像素為單位。 每個 coordinate、start_coordinate 與 region 值，以及 cursor_position 回報的位置，都位於您所傳回之完整顯示畫面螢幕截圖的像素空間中，原點位於左上角。縮放圖片不會改變這一點：在 zoom 之後，Claude 仍以完整螢幕截圖的空間表示座標，絕不會相對於縮放後的圖片。如果您在傳回螢幕截圖之前先將其縮小，請在將 Claude 的座標套用到實際顯示器之前，先將其按比例放大回去（請參閱調整螢幕截圖大小以符合影像限制）。
• 所有成員預設皆為啟用，包括 zoom。 如果您的環境無法產生縮放圖片，請使用 configs 停用該成員（請參閱工具參數），而不是保持啟用並傳回錯誤。如果 Claude 呼叫了您已停用或未實作的成員，請為該區塊傳回帶有 is_error: true 的 tool_result。
• 根據 (toolset_name, name) 這組配對進行分派。 toolset_name 才是將區塊標記為電腦動作的依據：同一請求中的自訂工具可能與某個成員同名，且較新的工具集版本可能會新增成員（請參閱用戶端工具集）。

{
  "type": "tool_use",
  "id": "toolu_01Qg8m3XqC5aRy7tD2eS4jUg",
  "name": "left_click",
  "toolset_name": "computer",
  "input": { "coordinate": [500, 300], "text": "shift" }
}

{
  "type": "tool_use",
  "id": "toolu_01Ed6j9VnA3yPw5rB8cQ2gSe",
  "name": "left_click_drag",
  "toolset_name": "computer",
  "input": {
    "start_coordinate": [200, 300],
    "coordinate": [600, 300]
  }
}

{
  "type": "tool_use",
  "id": "toolu_01Yc5h8UmZ2xNv4qA7bP9fRd",
  "name": "scroll",
  "toolset_name": "computer",
  "input": {
    "coordinate": [500, 400],
    "scroll_direction": "down",
    "scroll_amount": 3
  }
}

{
  "type": "tool_use",
  "id": "toolu_01Sb4g7TkY9wLu3pX6zM8eQc",
  "name": "key",
  "toolset_name": "computer",
  "input": { "text": "Tab", "repeat": 4 }
}

{
  "type": "tool_use",
  "id": "toolu_01Kf7k2WpB4zQx6sC9dR3hTf",
  "name": "zoom",
  "toolset_name": "computer",
  "input": { "region": [100, 200, 400, 350] }
}

{
  "type": "tool_use",
  "id": "toolu_01Ekh3vqB6yTs2mNc4Rw8pLd",
  "name": "cursor_position",
  "toolset_name": "computer",
  "input": {}
}

工具參數

tools 陣列中的工具集項目接受四個參數；它們與瀏覽器使用工具集共用的規則列於用戶端工具集中。

例如，此項目為未實作 zoom 的環境停用該成員，並在工具集定義處設定快取中斷點：

{
  "type": "computer_toolset_20260801",
  "configs": {
    "zoom": { "enabled": false }
  },
  "cache_control": { "type": "ephemeral" }
}

如果您的代理迴圈每次往返只能執行一個動作，請在 tool_choice 中將 disable_parallel_tool_use 設為 true；Claude 接著每個回合最多只會傳回一個成員 tool_use 區塊（請參閱停用平行工具使用）。

此項目會拒絕來自較早工具版本的下列參數，包含其中任何一個的請求都會傳回 invalid_request_error：

• name：成員名稱由工具集版本固定。
• display_width_px、display_height_px 與 display_number：座標一律位於您所傳回之螢幕截圖的像素空間中。
• enable_zoom：zoom 是一個成員工具，您可透過 configs 加以控制。

此項目也不能與 computer_20251124 項目或其他名為 computer 的工具在同一請求中宣告。關於 strict、input_examples、defer_loading 的放置位置、tool_choice、串流以及呼叫者限制，請參閱用戶端工具集。

搭配思考使用

若要將電腦使用與思考搭配使用，請參閱思考。

以其他工具擴充電腦使用

若要在電腦使用之外加入其他工具，請將它們包含在同一個 tools 陣列中。快速入門章節以 bash 工具與文字編輯器工具示範了這種模式。您也可以用相同方式加入您自己的自訂工具定義。

對於停留在網頁內的任務，您也可以在同一請求中宣告瀏覽器使用工具。這兩個工具集各自獨立運作，各有其座標系。toolset_name 值可區分對同名成員（例如 screenshot 或 key）的呼叫。

建構自訂電腦使用環境

參考實作旨在協助您開始使用電腦使用。它包含讓 Claude 使用電腦所需的所有元件。不過，您也可以依照需求建構自己的電腦使用環境。您需要：

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

實作電腦使用工具

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

1. 1

   設定您的運算環境

   建立虛擬顯示器，或連線到 Claude 與之互動的現有顯示器。這通常涉及設定 Xvfb（X Virtual Framebuffer）或類似技術。

2. 2

   實作動作處理函式

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

   PythonTypeScriptC#GoJavaPHPRuby

   Python

   

   # 佔位圖片資料；實際的執行器會擷取螢幕並回傳 PNG 位元組
   PLACEHOLDER_PNG = "iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mNkYPhfDwAChwGA60e6kgAAAABJRU5ErkJggg=="
   
   
   def capture_screenshot() -> list[ImageBlockParam]:
       # screenshot 以圖片區塊而非文字回應：回傳結果內容清單
       return [
           {
               "type": "image",
               "source": {
                   "type": "base64",
                   "media_type": "image/png",
                   "data": PLACEHOLDER_PNG,
               },
           }
       ]
   
   
   def click(coordinate=None):
       if coordinate is None:
           return "clicked at current cursor"
       x, y = coordinate
       return f"clicked at ({x}, {y})"
   
   
   def type_text(text):
       return f"typed: {text}"
   
   
   def handle_computer_action(name, tool_input):
       match name:
           case "screenshot":
               return capture_screenshot()
           case "left_click":
               # coordinate 為選用；若未提供，則在游標目前所在位置點擊
               return click(tool_input.get("coordinate"))
           case "type":
               return type_text(tool_input["text"])
       # 視需要處理其他動作
       raise ValueError(f"Unknown or unimplemented member: {name}")

3. 3

   處理 Claude 的工具呼叫

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

   PythonTypeScriptC#GoJavaPHPRuby

   Python

   

   NOT_EXECUTED = "Not executed: an earlier computer action in this turn failed."
   
   
   def process_tool_calls(response: Message) -> list[ToolResultBlockParam]:
       """
       Run the computer actions in Claude's response in order and answer each
       one. After the first failure the rest are skipped, because Claude planned
       them assuming the earlier actions succeeded.
       """
       tool_results: list[ToolResultBlockParam] = []
       failed = False
       for block in response.content:
           # 僅宣告了 computer 工具集；若您新增其他工具，請在此處路由
           if block.type != "tool_use" or block.toolset_name != "computer":
               continue
           result: ToolResultBlockParam = {
               "type": "tool_result",
               "tool_use_id": block.id,
               "toolset_name": "computer",
           }
           if failed:
               result["content"] = NOT_EXECUTED
               result["is_error"] = True
           else:
               try:
                   # 字串，或內容區塊清單（例如螢幕截圖圖片）
                   result["content"] = handle_computer_action(block.name, block.input)
               except Exception as err:
                   result["content"] = f"Error: {err}"
                   result["is_error"] = True
                   failed = True
           tool_results.append(result)
       return tool_results

4. 4

   實作代理迴圈

   將前兩個步驟包裝在一個迴圈中，該迴圈會將結果傳回，並重複執行直到 Claude 不再傳回任何成員工具呼叫；了解代理迴圈示範了這個迴圈。

處理錯誤

以帶有 is_error: true 與簡短描述的 tool_result 向 Claude 回報失敗的動作，並如同其他成員結果一樣包含 "toolset_name": "computer"。如果失敗的動作屬於某個批次動作，請以該處所示的中止文字回應批次中剩餘的區塊，而不要執行它們。

例如，當螢幕截圖擷取失敗時：

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

對於超出顯示範圍的座標以及無法執行的動作，請使用相同的結構，並附上說明問題所在的訊息。

調整螢幕截圖大小以符合影像限制

您傳回給電腦使用工具集（computer use toolset）的螢幕截圖與縮放影像，必須已符合您模型的影像大小限制：工具集不接受顯示器尺寸參數，API 也不會替您縮小影像，因此過大的 tool_result 影像會因驗證錯誤而遭到拒絕。由於 Claude 會以其收到影像的像素空間傳回座標，請保留您所使用的縮放比例，以便將這些座標對應回您的螢幕。

如果您的螢幕大於限制，請在傳回每張螢幕截圖前先調整其大小，並將 Claude 傳回的座標縮放回原始螢幕空間。由於工具集不接受顯示器尺寸參數，您只需在應用程式程式碼中進行調整大小與座標縮放即可：

import math

screen_width, screen_height = 1512, 982


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)


# 擷取螢幕截圖時
scale = get_scale_factor(screen_width, screen_height)
scaled_width = int(screen_width * scale)
scaled_height = int(screen_height * scale)

# 將圖片調整為縮放後的尺寸，再傳送給 Claude
screenshot = capture_and_resize(scaled_width, scaled_height)


# 處理 Claude 回傳的座標時，將其放大還原
def execute_click(x, y):
    screen_x = x / scale
    screen_y = y / scale
    perform_click(screen_x, screen_y)

當您選擇顯示器解析度並傳回螢幕截圖時：

• 一般桌面任務請使用 1024x768 或 1280x720；網頁應用程式請使用 1280x800 或 1366x768。
• 避免使用高於 1920x1080 的解析度，以防止效能問題。
• 將螢幕截圖編碼為 base64 PNG 或 JPEG，並考慮壓縮大型螢幕截圖以提升效能。
• 包含相關的中繼資料，例如時間戳記或顯示狀態。
• 如果您使用較高的解析度，請確保座標已正確縮放。

管理螢幕截圖歷史

長時間的代理迴圈會快速累積螢幕截圖（每張約 1,000–1,800 個輸入 token）。API 的請求限制也同樣適用。一旦單一請求攜帶超過 20 張影像，其中每張影像都會受到更嚴格的單邊限制。保留螢幕截圖歷史的迴圈在幾十個回合內就會達到該數量，因此請將每張螢幕截圖調整大小，以維持在該限制之內，或修剪較舊的螢幕截圖，使請求中保持 20 張或更少。

為了在限制上下文的同時維持提示快取的有效性：

• 在系統提示與工具定義之後放置一個 cache_control 中斷點，並在最近幾個回合各自的最後一個 tool_result 區塊上最多再放置三個，每回合往前推進。在批次動作中，多個區塊上的標記視為單一中斷點，但每個標記仍會計入四個的上限，因此任一回合最多使用一個。
• 以批次方式修剪舊的螢幕截圖，而非每回合修剪一張。每回合丟棄一張螢幕截圖會使前綴每回合都改變，導致快取失效。合理的預設做法是保留最後三張螢幕截圖，並每 25 個回合修剪一次，讓前綴在兩次修剪之間保持逐位元組一致；如果您的螢幕截圖超過更嚴格的限制，請選擇能讓每個請求保持在 20 張或更少影像的間隔。
• 在 Claude 5.1 及更新的模型上，請避免在用戶端進行修剪：從請求中移除較早的螢幕截圖會使該請求以及之後每個請求中所有後續的思考區塊失效。請改為調整螢幕截圖大小以維持在更嚴格的限制之內，並使用伺服器端的工具結果清除從上下文中移除舊的螢幕截圖。如果您必須修剪，請從此之後持續設定 prefix_mismatch_behavior: "drop_block"；每次修剪後，Claude 會在該請求及之後的每個請求中，在不包含自被修剪螢幕截圖以來所產生之思考的情況下繼續運作。在 Claude Sonnet 5.5 和 Claude Haiku 5.5 上，block_binding 僅適用於 thinking: {"type": "adaptive"}。在這些模型上使用任何其他思考設定時，請讓歷史記錄保持僅附加，或移除被修剪螢幕截圖之後的每個 thinking 和 redacted_thinking 區塊。

診斷點擊問題

如果點擊未命中目標，原因通常是下列之一：

遵循實作最佳實務

def click_and_wait(x, y, wait_time=0.5):
    click_at(x, y)
    time.sleep(wait_time)  # Allow UI to update

display_width, display_height = 1024, 768


def validate_action(action_type, params):
    if action_type == "left_click" and "coordinate" in params:
        x, y = params["coordinate"]
        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}")

從 computer_20251124 遷移

computer_20251124 整合在較早的工具版本中該版本所列的模型上無需任何變更即可運作。在將整合移至不接受 computer_20251124 的模型（例如 Claude API 上的 Claude 5.5 模型）之前，請先升級該整合。

若要升級，請同時進行以下變更：

1. 移除 beta 標頭。從您的請求中移除 anthropic-beta: computer-use-2025-11-24。使用 SDK 時，請移除 betas，並透過標準用戶端而非 beta 命名空間呼叫 Messages API。
2. 變更 tools 項目。將 type 設為 computer_toolset_20260801，並刪除 name、display_width_px、display_height_px、display_number 和 enable_zoom。工具集會拒絕這些欄位中的每一個。
3. 選擇是否保持啟用縮放。工具集預設啟用縮放，而 enable_zoom 預設為 false。如果您的環境未實作縮放，請加入 "configs": {"zoom": {"enabled": false}} 以保留先前的行為；否則請實作它（請參閱可用動作）。
4. 處理一個回合中的每個區塊。更新您的代理迴圈，使其逐一處理回應中的每個 tool_use 區塊，而非只讀取第一個，並依據區塊的 name 搭配 toolset_name 進行分派，而非依據 input.action。成員輸入不再包含 action 欄位；其餘欄位維持不變。
5. 依序執行區塊並使用中止文字。依序執行區塊，在第一個失敗處停止，並以 Not executed: an earlier computer action in this turn failed. 回應其餘區塊，如批次動作中所述。如果您的迴圈尚無法執行批次，工具參數說明了如何將 Claude 限制為每回合一個動作。
6. 在結果中回傳 toolset_name。在每個回應成員呼叫的 tool_result 中加入 "toolset_name": "computer"。結果只能包含 text 和 image 內容。
7. 在 key 上支援 repeat。key 成員接受一個介於 1 到 100 之間的選擇性 repeat 次數。忽略無法識別欄位的處理常式只會按鍵一次，因此請讓您的 key 處理常式遵循 repeat。
8. 自行調整螢幕截圖大小。工具集會拒絕超過模型影像限制的螢幕截圖或縮放影像，而不會將其縮小。請在傳回影像前調整大小，並如調整螢幕截圖大小以符合影像限制中所述持續縮放座標。
9. 移除不支援的選項。將項目中的任何 defer_loading 移至 configs，並在每個已啟用的成員上使用相同的值。工具集項目不支援的其他選項列於用戶端工具集下。

以下是變更前的 tools 項目，搭配 anthropic-beta: computer-use-2025-11-24 標頭傳送：

{
  "type": "computer_20251124",
  "name": "computer",
  "display_width_px": 1024,
  "display_height_px": 768,
  "display_number": 1
}

以下是變更後的 tools 項目，不搭配 beta 標頭傳送。configs 物件會關閉縮放，以符合未設定 enable_zoom 的先前項目；若要接受預設值並讓 Claude 縮放，請完全省略 configs：

{
  "type": "computer_toolset_20260801",
  "configs": {
    "zoom": { "enabled": false }
  }
}

以下這組範例顯示變更前後的 tool_use 區塊。動作名稱從 input.action 移至 name，且區塊新增了 toolset_name：

{
  "type": "tool_use",
  "id": "toolu_01A9r5kQm2LxWc7vT3nZ4bJs",
  "name": "computer",
  "input": { "action": "left_click", "coordinate": [500, 300] }
}

{
  "type": "tool_use",
  "id": "toolu_01A9r5kQm2LxWc7vT3nZ4bJs",
  "name": "left_click",
  "toolset_name": "computer",
  "input": { "coordinate": [500, 300] }
}

較早的工具版本

電腦使用工具有兩個較早的版本以 beta 形式提供。每個版本都需要在每個請求中加入其 beta 標頭，其參數記載於 beta Messages API 參考可檢視預覽，內含 API 參考文件連結——按 Tab 鍵直到焦點進入卡片，按 Escape 鍵返回。中。使用 SDK 時，請透過 betas 傳入標頭並使用 beta 命名空間；只有電腦使用工具需要該標頭，同一請求中的 bash 或文字編輯器工具則不需要。

在 Amazon Bedrock 上，Claude Opus 5.5、Claude Sonnet 5.5 和 Claude Haiku 5.5 也接受搭配 computer-use-2025-11-24 beta 標頭的 computer_20251124 工具。

限制

1. 延遲：電腦使用在人機互動上的「latency」（延遲），相較於一般由人類操作的電腦動作可能過慢。請在受信任的環境中專注於速度並非關鍵的使用案例（例如背景資訊蒐集、自動化軟體測試）。
2. 電腦視覺的準確度與可靠性：Claude 在產生動作時輸出特定座標，可能會出錯或產生幻覺。Claude 的摘要思考輸出可協助您了解模型的推理並找出潛在問題；請在思考設定中設定 display: "summarized"，因為支援工具集的模型預設會省略思考文字。
3. 工具選擇的準確度與可靠性：Claude 在產生動作時選擇工具可能會出錯或產生幻覺，或採取非預期的動作來解決問題。此外，在與小眾應用程式或同時與多個應用程式互動時，可靠性可能較低。請求複雜任務時，請謹慎地提示模型。
4. 捲動的可靠性：捲動動作支援方向控制（上、下、左、右）與指定的捲動量。在捲動無效的應用程式中，Page Down 等鍵盤替代方式會有所幫助。
5. 試算表互動：使用精細的滑鼠控制動作（left_mouse_down、left_mouse_up）與輔助鍵組合來選取個別儲存格。複雜的試算表操作可能仍需要多次嘗試。
6. 在社群與通訊平台上建立帳戶及產生內容：雖然 Claude 會造訪網站，但其在社群媒體網站與平台上建立帳戶、產生並分享內容，或以其他方式冒充人類的能力是受限的。
7. 漏洞：越獄與「prompt injection」（提示注入）可能影響電腦使用，如同它們可能影響任何前沿 AI 系統一樣，包括透過嵌入在網頁或影像中的指示；請採取安全性考量中的預防措施。
8. 不當或非法動作：根據 Anthropic 的服務條款，您不得利用電腦使用來違反任何法律或可接受使用政策。

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

資料保留

電腦使用是用戶端工具。工作階段中涉及的所有螢幕截圖、滑鼠動作、鍵盤輸入及任何檔案，都會在您的環境中擷取與儲存，而非由 Anthropic 儲存。Anthropic 會在 API 呼叫過程中即時處理螢幕截圖影像與動作請求。這些 API 請求的保留方式受 API 與資料保留規範。

由於您的應用程式控制電腦使用資料的儲存位置與方式，電腦使用符合 ZDR 資格。

定價

電腦使用遵循標準的工具使用定價。使用電腦使用工具時：

工具集定義開銷： 宣告帶有預設成員的 computer_toolset_20260801 會為請求增加約 4,500 個輸入 token（在 Claude Sonnet 5 上約為 4,590 個，在其他支援的模型上約為 4,520 個），涵蓋成員工具定義以及工具使用系統提示。使用 configs 停用 zoom 可減少其中約 410 個 token。請求的確切數量會在回應的 usage 中回報，您也可以使用 token 計數端點事先估算。

較早的工具版本： 以下數字適用於 computer_20251124 和 computer_20250124 工具版本，不適用於 computer_toolset_20260801：

• 系統提示開銷：系統提示中增加 466–499 個 token
• 工具定義：每個工具定義約 735 個輸入 token（以 computer_20250124 測量）

額外的 token 消耗：

• 工具結果中回傳的螢幕截圖和縮放影像，以影像輸入計費（請參閱視覺定價）
• 回傳給 Claude 的工具執行結果

後續步驟

可用性

電腦使用工具在特定模型上可供使用或處於 Beta 階段，且具備零資料保留和HIPAA 就緒資格。

API 支援

Beta 標頭可讓您在實驗性功能與新模型能力成為標準 API 的一部分之前搶先存取。