计算机使用工具

Claude 可以通过计算机使用工具与计算机环境进行交互，该工具提供截图功能和鼠标/键盘控制，用于自主桌面交互。在 WebArena（一个针对真实网站自主网页导航的基准测试）上，Claude 在单智能体系统中取得了最先进的结果，展示了端到端完成多步骤浏览器任务的强大能力。



概述

计算机使用是一项测试版功能，使 Claude 能够与桌面环境进行交互。此工具提供：

• 截图捕获： 查看屏幕上当前显示的内容
• 鼠标控制： 点击、拖动和移动光标
• 键盘输入： 输入文本和使用键盘快捷键
• 桌面自动化： 与任何应用程序或界面进行交互

虽然计算机使用可以与其他工具（如 bash 和文本编辑器）结合使用，以实现更全面的自动化工作流程，但计算机使用特指计算机使用工具查看和控制桌面环境的能力。

有关模型支持情况，请参阅工具参考。



安全注意事项

计算机使用是一项测试版功能，具有与标准 API 功能不同的独特风险。在与互联网交互时，这些风险会进一步加剧。

在某些情况下，Claude 会遵循内容中的命令，即使这些命令与用户的指令相冲突。例如，网页上或图像中包含的 Claude 指令可能会覆盖用户指令或导致 Claude 出错。请采取预防措施，将 Claude 与敏感数据和操作隔离，以避免与提示注入相关的风险。

Anthropic 已训练模型抵御这些提示注入，并增加了额外的防御层。如果您使用计算机使用工具，分类器将自动对您的提示运行，以标记潜在的提示注入实例。当这些分类器在截图中识别出潜在的提示注入时，它们会自动引导模型在继续下一步操作之前请求用户确认。这种额外的保护并不适用于所有用例（例如，没有人工参与的用例），因此如果您希望选择退出并关闭此功能，请联系支持团队。

即使有分类器防御层，这些预防措施仍然很重要。

在您自己的产品中启用计算机使用之前，请告知最终用户相关风险并获得他们的同意。



快速开始

以下是开始使用计算机使用的方法：

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)



计算机使用的工作原理

在没有用户输入的情况下重复步骤 3 和 4 被称为"agent loop"（智能体循环），即 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 容器内运行所有这些内容，并配置适当的端口映射以便查看环境并与之交互。



如何实现计算机使用



从参考实现开始

我们提供了一个参考实现，其中包含开始使用计算机使用所需的一切：

• 适用于 Claude 计算机使用的容器化环境
• 计算机使用工具的实现
• 与 Claude API 交互并运行计算机使用工具的智能体循环
• 用于与容器、智能体循环和工具交互的 Web 界面。



理解智能体循环

计算机使用的核心是"智能体循环"：一个循环过程，其中 Claude 请求工具操作，您的应用程序运行这些操作，并将结果返回给 Claude。以下是一个简化示例：

循环会持续进行，直到 Claude 在不请求任何工具的情况下响应（任务完成）或达到最大迭代限制。此保护措施可防止潜在的无限循环，避免产生意外的 API 费用。

在阅读本文档的其余部分之前，请先试用参考实现。



通过提示优化模型性能

以下是一些获得最佳质量输出的提示：

1. 指定简单、定义明确的任务，并为每个步骤提供明确的指令。
2. 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. 当使用设置了 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_prompt 字段仍然有效，并用于构建组合系统提示。



可用操作

计算机使用工具支持以下操作：

基本操作（所有版本）

• screenshot： 捕获当前显示内容
• left_click： 在坐标 [x, y] 处点击
• type： 输入文本字符串
• key： 按下按键或组合键（例如 "ctrl+s"）
• mouse_move： 将光标移动到指定坐标

增强操作（computer_20250124） 适用于所有支持计算机使用的模型：

• scroll： 向任意方向滚动，并可控制滚动量
• left_click_drag： 在坐标之间点击并拖动
• right_click、middle_click： 其他鼠标按钮
• double_click、triple_click： 多次点击
• left_mouse_down、left_mouse_up： 细粒度的点击控制
• hold_key： 按住某个键指定的持续时间（以秒为单位）
• wait： 在操作之间暂停

增强操作（computer_20251124） 适用于 Claude Opus 4.8、Claude Opus 4.7、Claude Opus 4.6、Claude Sonnet 4.6 和 Claude Opus 4.5：

• computer_20250124 中的所有操作
• zoom： 以完整分辨率查看屏幕的特定区域。需要在工具定义中设置 enable_zoom: true。接受一个 region 参数，其坐标 [x1, y1, x2, y2] 定义要检查区域的左上角和右下角。



工具参数



与扩展思考结合使用

有关将计算机使用与扩展思考结合使用的信息，请参阅扩展思考。



使用其他工具增强计算机使用

要在计算机使用的同时添加其他工具，请将它们包含在同一个 tools 数组中。快速开始部分展示了这种模式，结合使用了 bash 工具和文本编辑器工具。您可以用同样的方式添加自己的自定义工具定义。



构建自定义计算机使用环境

参考实现旨在帮助您开始使用计算机使用功能。它包含让 Claude 使用计算机所需的所有组件。但是，您可以根据自己的需求构建自己的计算机使用环境。您需要：

• 适用于 Claude 计算机使用的虚拟化或容器化环境
• 至少一个 Anthropic 架构计算机使用工具的实现
• 与 Claude API 交互并使用您的工具实现运行 tool_use 结果的智能体循环
• 允许用户输入以启动智能体循环的 API 或 UI



实现计算机使用工具

计算机使用工具作为无架构工具实现。使用此工具时，您不需要像其他工具那样提供输入架构；该架构已内置于 Claude 的模型中，无法修改。



处理错误

在实现计算机使用工具时，可能会出现各种错误。以下是处理方法：



调整截图大小以符合图像限制

发送到计算机工具的截图必须已经符合 Claude 的图像大小限制（请参阅图像大小限制）。API 不会调整过大图像的大小；超出限制的截图会被拒绝，并返回 HTTP 400 验证错误。

如果您的屏幕大于限制，请在发送之前调整截图大小，将 display_width_px/display_height_px 设置为调整后的尺寸，并将 Claude 返回的坐标缩放回原始屏幕空间：



诊断点击问题

如果点击未命中目标，原因通常是以下之一：



遵循实现最佳实践



了解计算机使用的局限性

计算机使用功能目前处于测试阶段。虽然 Claude 的能力处于业界领先水平，但开发者应了解其局限性：

1. 延迟： 当前人机交互中的计算机使用 "latency"（延迟）与常规人工操作计算机相比可能过慢。请在可信环境中专注于对速度要求不高的用例（例如后台信息收集、自动化软件测试）。
2. 计算机视觉的准确性和可靠性： Claude 在生成操作时输出具体坐标可能会出错或产生幻觉。扩展思考可以帮助您理解模型的推理过程并识别潜在问题。
3. 工具选择的准确性和可靠性： Claude 在生成操作时选择工具可能会出错或产生幻觉，或者采取意外的操作来解决问题。此外，在与小众应用程序或同时与多个应用程序交互时，可靠性可能会降低。在请求执行复杂任务时，请谨慎地为模型编写提示。
4. 滚动可靠性： 滚动操作支持方向控制（上、下、左、右）和指定的滚动量。在滚动不生效的应用程序中，键盘替代方案（如 Page Down）可能会有所帮助。
5. 电子表格交互： 使用精细的鼠标控制操作（left_mouse_down、left_mouse_up）和修饰键组合来选择单个单元格。复杂的电子表格操作可能仍需要多次尝试。
6. 在社交和通信平台上创建账户和生成内容： 虽然 Claude 会访问网站，但 Claude 在社交媒体网站和平台上创建账户、生成和分享内容或以其他方式进行人类冒充的能力是受限的。此功能未来可能会更新。
7. 漏洞： 越狱或提示注入等漏洞可能在前沿 AI 系统中持续存在，包括测试版的计算机使用 API。在某些情况下，Claude 会遵循内容中发现的指令，有时甚至与用户的指示相冲突。例如，网页上或图像中包含的针对 Claude 的指令可能会覆盖原有指示或导致 Claude 出错。请考虑以下措施： a. 将计算机使用限制在可信环境中，例如具有最小权限的虚拟机或容器 b. 在没有严格监督的情况下，避免让计算机使用功能访问敏感账户或数据 c. 在您的应用程序中启用或请求计算机使用功能所需的权限之前，告知最终用户相关风险并获得其同意
8. 不当或非法行为： 根据 Anthropic 的服务条款，您不得使用计算机使用功能违反任何法律或可接受使用政策。

请始终仔细审查和验证 Claude 的计算机使用操作和日志。在没有人工监督的情况下，请勿将 Claude 用于需要完美精度或涉及敏感用户信息的任务。



数据保留

计算机使用是一个客户端工具。会话中涉及的所有屏幕截图、鼠标操作、键盘输入和任何文件均在您的环境中捕获和存储，而非由 Anthropic 存储。Anthropic 会在 API 调用过程中实时处理屏幕截图图像和操作请求，但在返回响应后不会保留这些数据。

由于您的应用程序控制计算机使用数据的存储位置和方式，因此计算机使用符合 ZDR（零数据保留）资格。有关所有功能的 ZDR 资格，请参阅 API 和数据保留。



定价

计算机使用遵循标准的工具使用定价。使用计算机使用工具时：

系统提示开销：计算机使用测试版会向系统提示添加 466-499 个令牌

计算机使用工具的令牌用量：

额外的令牌消耗：

• 屏幕截图图像（请参阅视觉定价）
• 返回给 Claude 的工具执行结果



后续步骤