计算机使用工具

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

概述

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

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

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

模型兼容性

计算机使用功能适用于以下 Claude 模型：

安全注意事项

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

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

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

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

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

快速入门

以下是如何开始使用计算机使用功能：

curl https://api.anthropic.com/v1/messages \
  -H "content-type: application/json" \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "anthropic-beta: computer-use-2025-11-24" \
  -d '{
    "model": "claude-opus-4-6",
    "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."
      }
    ]
  }'

计算机使用的工作原理

在没有用户输入的情况下重复步骤 3 和 4 被称为"智能体循环"（即 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 的循环。以下是一个简化示例：

async def sampling_loop(
    *,
    model: str,
    messages: list[dict],
    api_key: str,
    max_tokens: int = 4096,
    tool_version: str,
    thinking_budget: int | None = None,
    max_iterations: int = 10,  # Add iteration limit to prevent infinite loops
):
    """
    A simple agent loop for Claude computer use interactions.

    This function handles the back-and-forth between:
    1. Sending user messages to Claude
    2. Claude requesting to use tools
    3. Your app executing those tools
    4. Sending tool results back to Claude
    """
    # Set up tools and API parameters
    client = Anthropic(api_key=api_key)
    beta_flag = (
        "computer-use-2025-11-24"
        if "20251124" in tool_version
        else "computer-use-2025-01-24"
        if "20250124" in tool_version
        else "computer-use-2024-10-22"
    )

    # Configure tools - you should already have these initialized elsewhere
    tools = [
        {
            "type": f"computer_{tool_version}",
            "name": "computer",
            "display_width_px": 1024,
            "display_height_px": 768,
        },
        {"type": f"text_editor_{tool_version}", "name": "str_replace_editor"},
        {"type": f"bash_{tool_version}", "name": "bash"},
    ]

    # Main agent loop (with iteration limit to prevent runaway API costs)
    iterations = 0
    while True and iterations < max_iterations:
        iterations += 1
        # Set up optional thinking parameter (for Claude Sonnet 3.7)
        thinking = None
        if thinking_budget:
            thinking = {"type": "enabled", "budget_tokens": thinking_budget}

        # Call the Claude API
        response = client.beta.messages.create(
            model=model,
            max_tokens=max_tokens,
            messages=messages,
            tools=tools,
            betas=[beta_flag],
            thinking=thinking,
        )

        # Add Claude's response to the conversation history
        response_content = response.content
        messages.append({"role": "assistant", "content": response_content})

        # Check if Claude used any tools
        tool_results = []
        for block in response_content:
            if block.type == "tool_use":
                # In a real app, you would execute the tool here
                # For example: result = run_tool(block.name, block.input)
                result = {"result": "Tool executed successfully"}

                # Format the result for Claude
                tool_results.append(
                    {"type": "tool_result", "tool_use_id": block.id, "content": result}
                )

        # If no tools were used, Claude is done - return the final messages
        if not tool_results:
            return messages

        # Add tool results to messages for the next iteration with Claude
        messages.append({"role": "user", "content": tool_results})

循环持续进行，直到 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>）提供用户名和密码。在需要登录的应用程序中使用计算机使用会增加因提示注入而导致不良结果的风险。在向模型提供登录凭据之前，请查阅缓解提示注入的指南。

系统提示

当通过 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） 适用于 Claude 4 模型和 Claude Sonnet 3.7：

• 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.6 和 Claude Opus 4.5：

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

工具参数

在 Claude 4 模型和 Claude Sonnet 3.7 中启用思考功能

Claude Sonnet 3.7 引入了一种新的"思考"功能，允许您在模型处理复杂任务时查看其推理过程。此功能帮助您了解 Claude 如何处理问题，对于调试或教育目的特别有价值。

要启用思考功能，请在您的 API 请求中添加 thinking 参数：

"thinking": {
  "type": "enabled",
  "budget_tokens": 1024
}

budget_tokens 参数指定 Claude 可以用于思考的令牌数量。这将从您的整体 max_tokens 预算中扣除。

启用思考功能后，Claude 将在响应中返回其推理过程，这可以帮助您：

1. 了解模型的决策过程
2. 识别潜在问题或误解
3. 从 Claude 解决问题的方法中学习
4. 更好地了解复杂的多步骤操作

以下是思考输出可能的示例：

[Thinking]
I need to save a picture of a cat to the desktop. Let me break this down into steps:

1. First, I'll take a screenshot to see what's on the desktop
2. Then I'll look for a web browser to search for cat images
3. After finding a suitable image, I'll need to save it to the desktop

Let me start by taking a screenshot to see what's available...

将计算机使用与其他工具结合

计算机使用工具可以与其他工具结合，创建更强大的自动化工作流程。这在以下情况下特别有用：

• 执行系统命令（bash 工具）
• 编辑配置文件或脚本（文本编辑器工具）
• 与自定义 API 或服务集成（自定义工具）

curl https://api.anthropic.com/v1/messages \
  -H "content-type: application/json" \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "anthropic-beta: computer-use-2025-11-24" \
  -d '{
    "model": "claude-opus-4-6",
    "max_tokens": 2000,
    "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"
      },
      {
        "name": "get_weather",
        "description": "Get the current weather in a given location",
        "input_schema": {
          "type": "object",
          "properties": {
            "location": {
              "type": "string",
              "description": "The city and state, e.g. San Francisco, CA"
            },
            "unit": {
              "type": "string",
              "enum": ["celsius", "fahrenheit"],
              "description": "The unit of temperature, either 'celsius' or 'fahrenheit'"
            }
          },
          "required": ["location"]
        }
      }
    ],
    "messages": [
      {
        "role": "user",
        "content": "Find flights from San Francisco to a place with warmer weather."
      }
    ],
    "thinking": {
      "type": "enabled",
      "budget_tokens": 1024
    }
  }'

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

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

• 适合 Claude 进行计算机使用的虚拟化或容器化环境
• 至少一个 Anthropic 定义的计算机使用工具的实现
• 与 Claude API 交互并使用您的工具实现执行 tool_use 结果的代理循环
• 允许用户输入以启动代理循环的 API 或 UI

实现计算机使用工具

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

处理错误

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

处理更高分辨率的坐标缩放

API 将图像限制为最长边最多 1568 像素，总计约 115 万像素（详见图像调整大小）。例如，1512x982 的屏幕会被降采样至约 1330x864。Claude 分析这个较小的图像并在该空间中返回坐标，但您的工具在原始屏幕空间中执行点击。

除非您处理坐标转换，否则这可能导致 Claude 的点击坐标偏离目标。

要解决此问题，请自行调整截图大小并将 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)


# When capturing screenshot
scale = get_scale_factor(screen_width, screen_height)
scaled_width = int(screen_width * scale)
scaled_height = int(screen_height * scale)

# Resize image to scaled dimensions before sending to Claude
screenshot = capture_and_resize(scaled_width, scaled_height)


# When handling Claude's coordinates, scale them back up
def execute_click(x, y):
    screen_x = x / scale
    screen_y = y / scale
    perform_click(screen_x, screen_y)

遵循实现最佳实践

了解计算机使用的局限性

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

1. 延迟：当前计算机使用中人机交互的延迟可能比常规人工操作计算机慢。请专注于速度不是关键因素的使用场景（例如，在可信环境中进行后台信息收集、自动化软件测试）。
2. 计算机视觉准确性和可靠性：Claude 在生成动作时输出特定坐标时可能会出错或产生幻觉。Claude Sonnet 3.7 引入了思考能力，可以帮助您了解模型的推理过程并识别潜在问题。
3. 工具选择准确性和可靠性：Claude 在生成动作时选择工具时可能会出错或产生幻觉，或采取意外动作来解决问题。此外，与小众应用程序或同时与多个应用程序交互时，可靠性可能较低。在请求复杂任务时请仔细提示模型。
4. 滚动可靠性：Claude Sonnet 3.7 引入了带方向控制的专用滚动动作，提高了可靠性。模型现在可以按指定量明确地向任意方向（上/下/左/右）滚动。
5. 电子表格交互：Claude Sonnet 3.7 通过添加更精确的鼠标控制动作（如 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 和数据保留。

定价

Computer use follows the standard tool use pricing. When using the computer use tool:

System prompt overhead: The computer use beta adds 466-499 tokens to the system prompt

Computer use tool token usage:

Additional token consumption:

• Screenshot images (see Vision pricing)
• Tool execution results returned to Claude

后续步骤