電腦使用工具

Claude 可以透過電腦使用工具（computer use tool）與電腦環境互動，該工具提供螢幕截圖功能以及滑鼠／鍵盤控制，以實現自主的桌面互動。

電腦使用工具是由 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"，每個回合通常會有數個（即批次動作）。

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

安全性考量

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

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

Anthropic 已訓練模型抵抗這些提示注入，並增加了額外的防禦層。如果您使用電腦使用工具，分類器會自動在您的提示上執行，以標記潛在的提示注入情況。當這些分類器在螢幕截圖中識別出潛在的提示注入時，它們會自動引導模型在繼續下一個動作之前要求使用者確認。這項額外保護並不適合每一種使用情境（例如沒有人類參與的使用情境），因此如果您希望選擇退出並將其關閉，請聯絡支援團隊。

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

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

快速開始

將電腦使用工具集以 {"type": "computer_toolset_20260801"} 的形式加入 Messages API 請求的 tools 陣列中。此請求不需要 beta 標頭。此範例同時宣告了文字編輯器工具與 bash 工具，Claude 通常會將它們與電腦使用搭配使用：

client = anthropic.Anthropic()

response = client.messages.create(
    model="claude-opus-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",
  "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 可以規劃一小段動作序列，例如點擊、輸入文字，然後擷取螢幕截圖，並在一個回應中一起回傳。這稱為「batch action」（批次動作）；它使用與平行工具使用相同的回應形式，但有一個差異：您是依序執行這些區塊，而非同時執行。

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

{
  "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": {}
    }
  ]
}

為每個 tool_use 區塊回傳一個 tool_result 區塊，以 tool_use_id 對應，全部放在下一則 user 訊息中。成員工具的每個結果都必須帶有 "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 上執行、具有視窗管理器（Mutter）與面板（Tint2）的輕量級 UI，為 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. 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>）提供使用者名稱與密碼。在需要登入的應用程式中使用電腦使用，會增加因提示注入而導致不良結果的風險。在向模型提供登入憑證之前，請先檢閱減輕越獄與提示注入。
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 會產生一個電腦使用專用的系統提示（system prompt）。它與工具使用系統提示類似，但以下列內容開頭：

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：縮放是一個您透過 configs 控制的成員工具。

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

與思考結合

若要將電腦使用與思考結合，請參閱思考。

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

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

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

建構自訂的電腦使用環境

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

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

實作電腦使用工具

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

1. 1

   設定您的運算環境

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

2. 2

   實作動作處理程式

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

   PythonTypeScriptC#GoJavaPHPRuby

   

   # 佔位圖片資料；實際的執行器會擷取螢幕並回傳 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):
       if name == "screenshot":
           return capture_screenshot()
       elif name == "left_click":
           # coordinate 為選用；若未提供，則在游標目前所在位置點擊
           return click(tool_input.get("coordinate"))
       elif name == "type":
           return type_text(tool_input["text"])
       # 視需要處理其他動作
       raise ValueError(f"Unknown or unimplemented member: {name}")

3. 3

   處理 Claude 的工具呼叫

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

   PythonTypeScriptC#GoJavaPHPRuby

   

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

對於超出顯示器邊界的座標以及執行失敗的動作，請使用相同的形式，並附上說明問題所在的訊息。

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

您回傳給電腦使用工具集的螢幕截圖與縮放圖片必須已符合您模型的圖片大小限制：此工具集不接受顯示器尺寸，且 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 張圖片，其中的每張圖片都會受到更嚴格的單邊尺寸限制。保留螢幕截圖歷史記錄的迴圈會在幾十個回合內達到該數量，因此請將每張螢幕截圖調整大小，使任一邊都不超過 2000 px，或修剪較舊的螢幕截圖，使請求中保持 20 張或更少。

若要在限制上下文的同時保持提示快取（prompt caching）的有效性：

• 在系統提示和工具定義之後放置一個 cache_control 斷點，並在最近幾個回合中每個回合的最後一個 tool_result 區塊上再放置最多三個斷點，每個回合向前推進它們。在批次動作中，多個區塊上的標記會作為單一斷點運作，但每個標記仍計入四個的上限，因此每個回合使用一個。
• 以批次方式修剪舊的螢幕截圖，而不是每個回合修剪一張。每個回合丟棄一張螢幕截圖會使前綴每個回合都改變，並使快取失效。合理的預設做法是保留最後三張螢幕截圖並每 25 個回合修剪一次，如此前綴在修剪事件之間保持位元組完全相同；如果您的螢幕截圖任一邊超過 2000 px，請選擇能讓每個請求保持在 20 張或更少圖片的間隔。
• 在 Claude Fable 5.1 上，請避免在用戶端進行修剪：移除較早的螢幕截圖會使仍攜帶這些回合的每個請求中所有後續的思考區塊失效。請改為將螢幕截圖調整為每邊 2000 px 或更小，並使用伺服器端的工具結果清除從上下文中丟棄舊的螢幕截圖。如果您必須修剪，請從那時起持續設定 prefix_mismatch_behavior: "drop_block"；每次修剪後，Claude 會在該請求及之後的每個請求中，在沒有自被修剪螢幕截圖以來所產生之思考內容的情況下繼續進行。

診斷點擊問題

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

遵循實作最佳實務

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 適用模型會繼續接受它及其 beta 標頭，因此現有的整合在您變更之前會持續運作。若要升級，請一併進行下列變更：

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 成員接受選擇性的 repeat 計數，範圍為 1 到 100。忽略無法辨識欄位的處理程式只會按下按鍵一次，因此請讓您的 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 的較早項目；完全省略 configs 即可接受預設值並讓 Claude 進行縮放：

{
  "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 參考文件中。在 SDK 中，請透過 betas 參數傳遞標頭並使用 beta 命名空間；只有電腦使用工具需要該標頭，同一請求中的 bash 或文字編輯器工具則不需要。

限制

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

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

資料保留

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

由於您的應用程式控制電腦使用資料的儲存位置和方式，電腦使用符合 ZDR 資格。如需所有功能的 ZDR 資格，請參閱 API 與資料保留。

定價

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

工具集定義開銷： 宣告 computer_toolset_20260801 及其預設成員會為請求增加約 4,500 個輸入 token（在 Claude Fable 5、Claude Mythos 5、Claude Opus 5 和 Claude Opus 4.8 上約為 4,520 個，在 Claude Sonnet 5 上約為 4,590 個），其中涵蓋成員工具定義以及工具使用系統提示。使用 configs 停用 zoom 可移除其中約 410 個 token。請求的確切數量會在回應的 usage 中回報，您也可以透過 token 計數端點事先估算。

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

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

額外的 token 消耗：

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

後續步驟

Compatibility