Loading
Loading
Loading
Loading
Loading
Loading
Loading
Loading
Loading
Loading
Loading
Loading
Loading
Loading
Loading
Loading
Claude 可以通过计算机使用工具与计算机环境进行交互，该工具提供截图功能以及鼠标/键盘控制，以实现自主的桌面交互。
计算机使用是一项测试版功能，使 Claude 能够与桌面环境进行交互。此工具提供：
虽然计算机使用可以与其他工具（如 bash 和文本编辑器）结合使用，以实现更全面的自动化工作流，但计算机使用特指计算机使用工具查看和控制桌面环境的能力。
有关模型支持情况，请参阅工具参考。
计算机使用是一项测试版功能，具有与标准 API 功能不同的独特风险。在与互联网交互时，这些风险会进一步加剧。
在某些情况下，Claude 会遵循内容中发现的命令，即使这些命令与您的指令相冲突。例如，网页上的指令或图像中包含的指令可能会覆盖您的指令或导致 Claude 出错。请采取预防措施，将 Claude 与敏感数据和操作隔离开来，以避免与提示注入相关的风险。
Anthropic 已训练模型抵御这些提示注入，并增加了额外的防御层。如果您使用计算机使用工具，分类器将自动对您的提示运行，以标记潜在的提示注入实例。当这些分类器在截图中识别出潜在的提示注入时，它们会自动引导模型在继续下一步操作之前请求用户确认。这种额外的保护并非适用于所有用例（例如，没有人工参与的用例），因此如果您希望选择退出并关闭此功能，请联系支持团队。
即使有分类器防御层，这些预防措施仍然很重要。
在您自己的产品中启用计算机使用之前，请告知最终用户相关风险并获得他们的同意。
开始使用计算机使用参考实现，其中包括 Web 界面、Docker 容器、示例工具实现和智能体循环。
以下是开始使用计算机使用的方法：
client = anthropic.Anthropic()
response = client.beta.messages.create(
model="claude-opus-5", # 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)为 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 数组时，请将指令文本放在截图图像之前。在处理图像之前提供目标描述可以提高点击准确性。enable_zoom: true 的 computer_20251124 时，如果被问及在截图默认分辨率下无法辨认的小文本或特定 UI 元素（如侧边栏中的文件名、标签页标题、状态栏文本、行号或按钮标签），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 Opus 5、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 |
有关将计算机使用与思考功能结合使用的信息，请参阅思考。
要在计算机使用之外添加其他工具，请将它们包含在同一个 tools 数组中。快速入门部分展示了这种模式，其中使用了 bash 工具和文本编辑器工具。您可以用同样的方式添加自己的自定义工具定义。
参考实现旨在帮助您开始使用计算机使用。它包含让 Claude 使用计算机所需的所有组件。但是，您可以构建自己的计算机使用环境以满足您的需求。您需要：
tool_use 结果的智能体循环计算机使用工具是作为无架构工具实现的。使用此工具时，您不需要像其他工具那样提供输入架构；该架构内置于 Claude 的模型中，无法修改。
设置您的计算环境
创建一个虚拟显示器或连接到 Claude 将与之交互的现有显示器。这通常涉及设置 Xvfb（X 虚拟帧缓冲区）或类似技术。
实现操作处理程序
创建函数来处理 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 像素）才会被拒绝并返回验证错误，而不是被缩小。
如果您的屏幕大于该限制，请在发送之前调整截图大小，将 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)如果点击未命中目标，原因通常是以下之一：
| 症状 | 可能原因 | 尝试方法 |
|---|---|---|
| 点击始终向一个方向偏移 | display_width_px/display_height_px 与实际发送的图像尺寸不匹配 | 确保显示尺寸与您发送的截图完全匹配 |
| 点击落在正确区域但未命中目标 | 目标非常小、缩小 4K+ 源图像时丢失了细节，或宽高比被扭曲 | 设置 enable_zoom: true；以较低 DPI 捕获或裁剪到相关区域；调整大小时保持宽高比 |
| Claude 完全点击了错误的元素 | 指令不明确，或附近有视觉上相似的元素 | 使用位置提示（"右下角的蓝色提交按钮"）；将交互分解为更小的步骤 |
| 准确性始终较差 | 分辨率过低 | 尝试以 1280x720 作为基准 |
计算机使用目前处于测试阶段。请牢记以下局限性：
延迟： 当前人机交互的计算机使用延迟可能比常规的人工操作计算机慢。请在可信环境中专注于速度不是关键因素的用例（例如，后台信息收集、自动化软件测试）。
计算机视觉准确性和可靠性： Claude 在生成操作时输出特定坐标可能会出错或产生幻觉。扩展思考可以帮助您理解模型的推理并识别潜在问题。
工具选择准确性和可靠性： Claude 在生成操作时选择工具可能会出错或产生幻觉，或者采取意外的操作来解决问题。此外，在与小众应用程序或同时与多个应用程序交互时，可靠性可能会降低。在请求复杂任务时，请仔细提示模型。
滚动可靠性： 滚动操作支持方向控制（上、下、左、右）和指定的滚动量。在滚动不生效的应用程序中，键盘替代方案（如 Page Down）可能会有所帮助。
电子表格交互： 使用细粒度的鼠标控制操作（left_mouse_down、left_mouse_up）和修饰键组合来选择单个单元格。复杂的电子表格操作可能仍需要多次尝试。
在社交和通信平台上创建账户和生成内容： 虽然 Claude 会访问网站，但 Claude 在社交媒体网站和平台上创建账户、生成和分享内容或以其他方式进行人类冒充的能力是受限的。此功能可能会在未来更新。
漏洞： 越狱或提示注入等漏洞可能在前沿 AI 系统（包括测试版计算机使用 API）中持续存在。在某些情况下，Claude 会遵循内容中发现的命令，有时即使这些命令与您的指令相冲突。例如，网页上的指令或图像中包含的指令可能会覆盖您的指令或导致 Claude 出错。请考虑以下事项：
不当或非法行为： 根据 Anthropic 的服务条款，您不得使用计算机使用来违反任何法律或可接受使用政策。
请始终仔细审查和验证 Claude 的计算机使用操作和日志。在没有人工监督的情况下，请勿将 Claude 用于需要完美精度或涉及敏感用户信息的任务。
计算机使用是一个客户端工具。会话中涉及的所有截图、鼠标操作、键盘输入和任何文件都在您的环境中捕获和存储，而不是由 Anthropic 存储。Anthropic 作为 API 调用的一部分实时处理截图图像和操作请求。这些 API 请求的保留受 API 和数据保留约束。
由于您的应用程序控制计算机使用数据的存储位置和方式，因此计算机使用符合 ZDR 资格。有关所有功能的 ZDR 资格，请参阅 API 和数据保留。
计算机使用遵循标准的工具使用定价。使用计算机使用工具时：
系统提示开销： 计算机使用测试版会向系统提示添加 466–499 个令牌
计算机使用工具令牌使用量：
| 模型 | 每个工具定义的输入令牌数 |
|---|---|
| Claude 4.x 模型 | 735 个令牌 |
额外的令牌消耗：
使用症状到修复的诊断表格修复最常见的工具使用错误。
开始使用完整的基于 Docker 的实现
将 Claude 连接到外部工具和 API。了解工具在哪里执行、Claude 何时调用它们，以及哪种工具适合您的任务。
关于分辨率、思考强度和上下文管理的基准测试建议
| Supported models |
|
|---|---|
| Supported platforms |
|
Was this page helpful?