Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Claude 可以透過電腦使用工具與電腦環境互動，該工具提供螢幕截圖功能以及滑鼠/鍵盤控制，以實現自主的桌面互動。
電腦使用功能處於測試階段，需要 beta 標頭：
"computer-use-2025-11-24" 適用於 Claude Sonnet 5、Claude Opus 4.8、Claude Opus 4.7、Claude Opus 4.6、Claude Sonnet 4.6 和 Claude Opus 4.5"computer-use-2025-01-24" 適用於 Claude Sonnet 4.5、Claude Haiku 4.5、Claude Opus 4.1（已棄用）、Claude Sonnet 4（已停用，Bedrock 和 Google Cloud 除外）和 Claude Opus 4（已停用，Google Cloud 除外）請透過意見回饋表單分享您對此功能的意見回饋。
此功能符合「Zero Data Retention」（零資料保留），即 ZDR 的資格。當您的組織具有 ZDR 安排時，透過此功能傳送的資料在 API 回應返回後不會被儲存。
電腦使用是一項測試版功能，讓 Claude 能夠與桌面環境互動。此工具提供：
雖然電腦使用可以與其他工具（例如 bash 和文字編輯器）搭配使用，以實現更全面的自動化工作流程，但電腦使用特指電腦使用工具查看和控制桌面環境的能力。
有關模型支援，請參閱工具參考。
電腦使用是一項測試版功能，具有與標準 API 功能不同的獨特風險。與網際網路互動時，這些風險會更高。
為了將風險降至最低，請考慮採取以下預防措施：
在某些情況下，Claude 會遵循內容中發現的指令，即使這些指令與您的指示相衝突。例如，網頁上或圖片中包含的指令可能會覆蓋您的指示，或導致 Claude 犯錯。請採取預防措施，將 Claude 與敏感資料和操作隔離，以避免與提示注入（prompt injection）相關的風險。
Anthropic 已訓練模型抵抗這些提示注入，並增加了額外的防禦層。如果您使用電腦使用工具，分類器將自動在您的提示上執行，以標記潛在的提示注入實例。當這些分類器在螢幕截圖中識別出潛在的提示注入時，它們會自動引導模型在繼續下一個操作之前要求使用者確認。這種額外的保護並不適合每個使用案例（例如，沒有人工參與的使用案例），因此如果您想選擇退出並關閉它，請聯絡支援。
即使有分類器防禦層，這些預防措施仍然很重要。
在您自己的產品中啟用電腦使用之前，請告知終端使用者相關風險並取得他們的同意。
開始使用電腦使用參考實作，其中包括網頁介面、Docker 容器、範例工具實作和代理迴圈。
以下是開始使用電腦使用的方法：
client = anthropic.Anthropic()
response = client.beta.messages.create(
model="claude-opus-4-8", # 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)只有電腦使用工具需要 beta 標頭。
前面的範例顯示了三個工具一起使用，由於包含電腦使用工具，因此需要 beta 標頭。
向 Claude 提供電腦使用工具和使用者提示
Claude 選擇電腦使用工具
stop_reason 為 tool_use，表示這是一個工具使用請求。擷取工具輸入、在電腦上評估工具並回傳結果
tool_result 內容區塊的新 user 訊息繼續對話。Claude 持續呼叫電腦使用工具，直到完成任務
tool_use stop_reason 回應，您應該回到步驟 3。在沒有使用者輸入的情況下重複步驟 3 和 4 被稱為「代理迴圈」（agent loop）（也就是說，Claude 以工具使用請求回應，而您的應用程式以評估該請求的結果回應 Claude）。
電腦使用需要一個沙盒化的運算環境，讓 Claude 可以安全地與應用程式和網路互動。此環境包括：
虛擬顯示器： 一個虛擬 X11 顯示伺服器（使用 Xvfb），用於呈現 Claude 將透過螢幕截圖看到並透過滑鼠/鍵盤操作控制的桌面介面。
桌面環境： 在 Linux 上執行的輕量級 UI，包含視窗管理器（Mutter）和面板（Tint2），為 Claude 提供一致的圖形介面進行互動。
應用程式： 預先安裝的 Linux 應用程式，例如 Firefox、LibreOffice、文字編輯器和檔案管理器，Claude 可以使用這些應用程式來完成任務。
工具實作： 整合程式碼，將 Claude 的抽象工具請求（例如「移動滑鼠」或「擷取螢幕截圖」）轉換為虛擬環境中的實際操作。
代理迴圈： 處理 Claude 與環境之間通訊的程式，將 Claude 的操作傳送到環境，並將結果（螢幕截圖、命令輸出）回傳給 Claude。
當您使用電腦使用時，Claude 不會直接連接到此環境。相反地，您的應用程式會：
為了安全性和隔離性，參考實作在 Docker 容器內執行所有這些操作，並具有適當的連接埠對應，以便查看環境並與之互動。
我們提供了一個參考實作，其中包含開始使用電腦使用所需的一切：
電腦使用的核心是「代理迴圈」：一個 Claude 請求工具操作、您的應用程式執行這些操作並將結果回傳給 Claude 的循環。該迴圈使用您在快速入門中建立的用戶端、形狀類似快速入門的 tools 陣列的工具清單，以及在處理 Claude 的工具呼叫中定義的工具呼叫處理輔助函式。以下是一個簡化的範例：
def sampling_loop(model, messages, max_iterations=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.beta.messages.create(
model=model,
max_tokens=4096,
messages=messages,
tools=TOOLS,
betas=["computer-use-2025-11-24"],
)
# 將 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
# 將工具結果傳回給 Claude 以進行下一次迭代
messages.append({"role": "user", "content": tool_results})
return messages迴圈會持續進行，直到 Claude 在沒有請求任何工具的情況下回應（任務完成）或達到最大迭代限制為止。此保護措施可防止可能導致意外 API 成本的潛在無限迴圈。
在閱讀本文件的其餘部分之前，請先試用參考實作。
以下是一些關於如何獲得最佳品質輸出的提示：
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.<robot_credentials>）提供使用者名稱和密碼。在需要登入的應用程式中使用電腦使用會增加因提示注入而導致不良結果的風險。在向模型提供登入憑證之前，請先查看減輕越獄和提示注入。content 陣列時，請將指示文字放在螢幕截圖影像之前。在處理影像之前提供目標描述可以提高點擊準確性。computer_20251124 並設定 enable_zoom: true 時，當被詢問有關小文字或在螢幕截圖預設解析度下無法辨識的特定 UI 元素（例如側邊欄中的檔案名稱、分頁標題、狀態列文字、行號或按鈕標籤）時，Claude 會放大某個區域。如果 Claude 沒有在您預期的時候進行縮放，請詢問特定區域或元素，而不是整個螢幕。如果您反覆遇到一組明確的問題，或事先知道 Claude 需要完成的任務， 請使用系統提示向 Claude 提供有關如何成功完成任務的明確提示或指示。
對於跨越多個工作階段的代理，請在每個工作階段開始時執行端對端驗證， 而不僅僅是在實作之後。基於瀏覽器的檢查可以捕捉到僅靠程式碼層級審查 會遺漏的先前工作階段的回歸問題。詳情請參閱 長時間執行代理的有效框架。
當透過 Claude API 請求其中一個 Anthropic 結構描述工具時，會產生一個電腦使用專用的系統提示。它類似於工具使用系統提示，但開頭為：
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 參數仍然會被尊重，並用於建構組合的系統提示。
電腦使用工具支援以下操作：
基本操作（所有版本）
[x, y] 處點擊增強操作（computer_20250124 及更新版本）
在 computer_20250124 和 computer_20251124 中可用：
增強操作（computer_20251124）
在 Claude Sonnet 5、Claude Opus 4.8、Claude Opus 4.7、Claude Opus 4.6、Claude Sonnet 4.6 和 Claude Opus 4.5 中可用：
computer_20250124 的所有操作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 的請求實作螢幕截圖擷取、滑鼠移動、鍵盤輸入和其他操作。
有關將電腦使用與擴展思考結合的資訊，請參閱擴展思考。
特別針對電腦使用，內部基準測試建議以下 effort 設定：
high 作為預設值；對於高吞吐量或成本敏感的工作負載，使用 low。medium 作為預設值（最佳準確度與成本比）。避免使用 max，它會增加 token 成本，但不會提高 UI 任務的準確度。在這些模型上，low 使用的輸出 token 少於完全停用思考（更少的錯誤意味著更少的重試），使其成為成本敏感迴圈的強力選擇。若要在電腦使用之外新增其他工具，請將它們包含在同一個 tools 陣列中。快速入門章節展示了這種模式，其中包含 bash 工具和文字編輯器工具。您可以用同樣的方式新增自己的自訂工具定義。
參考實作旨在協助您開始使用電腦使用。它包含讓 Claude 使用電腦所需的所有元件。不過，您可以建立自己的電腦使用環境以滿足您的需求。您需要：
tool_use 結果的代理迴圈電腦使用工具是以無結構描述（schema-less）工具的形式實作的。使用此工具時，您不需要像其他工具一樣提供輸入結構描述；結構描述已內建於 Claude 的模型中，無法修改。
設定您的運算環境
建立虛擬顯示器或連接到 Claude 將與之互動的現有顯示器。這通常涉及設定 Xvfb（X Virtual Framebuffer）或類似技術。
實作操作處理器
建立函式來處理 Claude 可能請求的每種操作類型：
def capture_screenshot():
return "<screenshot data>"
def click_at(x, y):
return f"clicked at ({x}, {y})"
def type_text(text):
return f"typed: {text}"
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"])
# 視需要處理其他動作
return f"unhandled action: {action_type}"處理 Claude 的工具呼叫
從 Claude 的回應中擷取並執行工具呼叫：
def process_tool_calls(response):
tool_results = []
for block in response.content:
if block.type == "tool_use":
action = block.input["action"]
result = handle_computer_action(action, block.input)
tool_results.append(
{
"type": "tool_result",
"tool_use_id": block.id,
"content": result,
}
)
return tool_results實作代理迴圈
建立一個持續進行直到 Claude 完成任務的迴圈：
def sampling_loop(model, messages, max_iterations=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.beta.messages.create(
model=model,
max_tokens=4096,
messages=messages,
tools=TOOLS,
betas=["computer-use-2025-11-24"],
)
# 將 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
# 將工具結果傳回給 Claude 以進行下一次迭代
messages.append({"role": "user", "content": tool_results})
return messages實作電腦使用工具時，可能會發生各種錯誤。以下是處理方法：
傳送到電腦工具的螢幕截圖應符合 Claude 的影像大小限制（請參閱影像大小限制）。API 會在 Claude 看到之前縮小過大的影像，而 Claude 會回傳它所看到的影像的座標，因此依賴伺服器端的縮小會讓您缺少將這些座標對應回您的螢幕所需的縮放係數。只有超過 API 單獨的請求限制的影像（例如，單邊超過 8,000 px）才會被驗證錯誤拒絕，而不是被縮小。
限制因模型而異。Claude Sonnet 5、Claude Opus 4.8 和 Claude Opus 4.7 的長邊最多可接受 2576 像素；較早的模型長邊最多可接受 1568 像素，總計約 1.15 百萬像素。以下範例使用較早模型的 1568 px / 1.15 MP 限制；請替換為您模型的限制。
如果您的螢幕大於限制，請在傳送之前調整螢幕截圖的大小，將 display_width_px/display_height_px 設定為調整後的尺寸，並將 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)
# 擷取螢幕截圖時
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)macOS Retina 顯示器以裝置像素比 2 擷取螢幕截圖，因此影像的解析度是邏輯螢幕座標的兩倍。請在傳送之前將螢幕截圖縮小 2 倍，或在發出點擊之前將 Claude 回傳的座標減半。
如果點擊未命中目標，原因通常是以下其中之一：
| 症狀 | 可能原因 | 嘗試 |
|---|---|---|
| 點擊持續向一個方向偏移 | display_width_px/display_height_px 與實際傳送的影像尺寸不符 | 確保顯示尺寸與您傳送的螢幕截圖完全相符 |
| 點擊落在正確區域但未命中目標 | 目標非常小、縮小 4K+ 來源時遺失細節，或長寬比被扭曲 | 設定 enable_zoom: true；以較低的 DPI 擷取或裁剪到相關區域；調整大小時保留長寬比 |
| Claude 完全點擊了錯誤的元素 | 指示模糊，或附近有視覺上相似的元素 | 使用位置提示（「右下角的藍色提交按鈕」）；將互動分解為更小的步驟 |
| 準確度持續不佳 | 解析度太低 | 嘗試以 1280x720 作為基準 |
模型選擇會影響點擊精確度。 Claude Sonnet 4.6 在點擊方面比 Claude Opus 4.6 在機械上更精確，並且在螢幕截圖需要大幅縮小時更穩健。Claude Opus 4.7 縮小了這個差距：其點擊精確度大致與 Sonnet 4.6 相當，而且其更高的解析度限制意味著需要更少的縮小。
電腦使用處於測試階段。請記住以下限制：
延遲： 目前人機互動的電腦使用延遲（latency）與一般人工指導的電腦操作相比可能太慢。請在受信任的環境中，專注於速度不是關鍵的使用案例（例如，背景資訊收集、自動化軟體測試）。
電腦視覺準確性和可靠性： Claude 在產生操作時輸出特定座標時可能會犯錯或產生幻覺。擴展思考可以幫助您了解模型的推理並識別潛在問題。
工具選擇準確性和可靠性： Claude 在產生操作時選擇工具可能會犯錯或產生幻覺，或採取意外的操作來解決問題。此外，與小眾應用程式或同時與多個應用程式互動時，可靠性可能較低。在請求複雜任務時，請謹慎提示模型。
捲動可靠性： 捲動操作支援方向控制（上、下、左、右）和指定的量。在捲動不生效的應用程式中，鍵盤替代方案（例如 Page Down）可能會有所幫助。
試算表互動： 使用精細的滑鼠控制操作（left_mouse_down、left_mouse_up）和修飾鍵組合來選取個別儲存格。複雜的試算表操作可能仍需要多次嘗試。
在社交和通訊平台上建立帳戶和產生內容： 雖然 Claude 會造訪網站，但 Claude 在社交媒體網站和平台上建立帳戶、產生和分享內容或以其他方式進行人類冒充的能力是有限的。此功能未來可能會更新。
漏洞： 越獄（jailbreaking）或提示注入等漏洞可能會持續存在於前沿 AI 系統中，包括測試版電腦使用 API。在某些情況下，Claude 會遵循內容中發現的指令，有時甚至在這些指令與您的指示相衝突時也是如此。例如，網頁上或圖片中包含的指令可能會覆蓋您的指示或導致 Claude 犯錯。請考慮以下事項：
不當或非法行為： 根據 Anthropic 的服務條款，您不得使用電腦使用來違反任何法律或可接受使用政策。
請務必仔細審查和驗證 Claude 的電腦使用操作和日誌。在沒有人工監督的情況下，請勿將 Claude 用於需要完美精確度或敏感使用者資訊的任務。
電腦使用是一個用戶端工具。工作階段中涉及的所有螢幕截圖、滑鼠操作、鍵盤輸入和任何檔案都在您的環境中擷取和儲存，而不是由 Anthropic 儲存。Anthropic 會在 API 呼叫過程中即時處理螢幕截圖影像和操作請求。這些 API 請求的保留受 API 和資料保留的規範。
由於您的應用程式控制電腦使用資料的儲存位置和方式，因此電腦使用符合 ZDR 資格。有關所有功能的 ZDR 資格，請參閱 API 和資料保留。
電腦使用遵循標準的工具使用定價。使用電腦使用工具時：
系統提示額外開銷：電腦使用測試版會在系統提示中增加 466-499 個 token
電腦使用工具的 token 用量：
| 模型 | 每個工具定義的輸入 token 數 |
|---|---|
| Claude 4.x 模型 | 735 個 token |
額外的 token 消耗：
如果您同時搭配電腦使用功能使用 bash 或文字編輯器工具，這些工具各自有其 token 成本，詳情請參閱各自的說明頁面。
使用症狀到修復的診斷表格修復最常見的工具使用錯誤。
開始使用完整的基於 Docker 的實作
將 Claude 連接到外部工具和 API。了解工具在哪裡執行、Claude 何時呼叫它們，以及哪個工具適合您的任務。
針對解析度、思考投入程度和上下文管理的基準測試建議
Was this page helpful?