计算机使用工具

构建工具

计算机使用工具

Claude 可以通过计算机使用工具与计算机环境交互，该工具提供屏幕截图功能和鼠标/键盘控制，用于自主桌面交互。

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

计算机使用处于测试版阶段，需要 beta 标头：

"computer-use-2025-11-24" 用于 Claude Opus 4.7、Claude Opus 4.6、Claude Sonnet 4.6、Claude Opus 4.5
"computer-use-2025-01-24" 用于 Sonnet 4.5、Haiku 4.5、Opus 4.1、Sonnet 4、Opus 4 和 Sonnet 3.7（已弃用）

请通过反馈表单分享您对此功能的反馈。

This feature is eligible for Zero Data Retention (ZDR). When your organization has a ZDR arrangement, data sent through this feature is not stored after the API response is returned.

概述

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

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

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

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

安全考虑

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

为了最小化风险，请考虑采取以下预防措施：

使用具有最小权限的专用虚拟机或容器，以防止直接系统攻击或意外事故。
避免让模型访问敏感数据，例如账户登录信息，以防止信息被盗。
将互联网访问限制在域名白名单中，以减少暴露于恶意内容的风险。
要求人工确认可能导致有意义的现实世界后果的决定，以及任何需要肯定同意的任务，例如接受 Cookie、执行财务交易或同意服务条款。

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

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

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

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

计算机使用参考实现

使用计算机使用参考实现快速入门，该实现包括网络界面、Docker 容器、示例工具实现和代理循环。

注意：该实现已更新，包括 Claude 4 模型和 Claude Sonnet 3.7 的新工具。请确保拉取最新版本的仓库以访问这些新功能。

快速开始

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

client = anthropic.Anthropic()

response = client.beta.messages.create(
    model="claude-opus-4-7",  # 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 提供计算机使用工具和用户提示
- 在您的 API 请求中添加计算机使用工具（以及可选的其他工具）。
- 包括需要桌面交互的用户提示，例如"将猫的图片保存到我的桌面"。
Claude 决定使用计算机使用工具
- Claude 评估计算机使用工具是否可以帮助解决用户的查询。
- 如果是，Claude 构造一个格式正确的工具使用请求。
- API 响应的 stop_reason 为 tool_use，表示 Claude 的意图。
提取工具输入，在计算机上评估工具，并返回结果
- 在您的一端，从 Claude 的请求中提取工具名称和输入。
- 在容器或虚拟机上使用该工具。
- 继续对话，使用包含 tool_result 内容块的新 user 消息。
Claude 继续调用计算机使用工具，直到完成任务
- Claude 分析工具结果，以确定是否需要更多工具使用或任务已完成。
- 如果 Claude 决定需要另一个工具，它会以另一个 tool_use stop_reason 响应，您应该返回第 3 步。
- 否则，它会为用户制作文本响应。

步骤 3 和 4 在没有用户输入的情况下的重复称为"代理循环"（即 Claude 响应工具使用请求，您的应用程序用评估该请求的结果响应 Claude）。

计算环境

计算机使用需要一个沙箱计算环境，Claude 可以在其中安全地与应用程序和网络交互。此环境包括：

虚拟显示：一个虚拟 X11 显示服务器（使用 Xvfb），它呈现 Claude 将通过屏幕截图看到的桌面界面，并通过鼠标/键盘操作进行控制。
桌面环境：在 Linux 上运行的轻量级 UI，带有窗口管理器（Mutter）和面板（Tint2），为 Claude 提供一致的图形界面来交互。
应用程序：预装的 Linux 应用程序，如 Firefox、LibreOffice、文本编辑器和文件管理器，Claude 可以使用这些应用程序来完成任务。
工具实现：集成代码，将 Claude 的抽象工具请求（如"移动鼠标"或"截图"）转换为虚拟环境中的实际操作。
代理循环：一个程序，处理 Claude 和环境之间的通信，将 Claude 的操作发送到环境，并将结果（屏幕截图、命令输出）返回给 Claude。

当您使用计算机使用时，Claude 不会直接连接到此环境。相反，您的应用程序：

接收 Claude 的工具使用请求
将它们转换为计算环境中的操作
捕获结果（屏幕截图、命令输出等）
将这些结果返回给 Claude

为了安全和隔离，参考实现在 Docker 容器内运行所有这些，具有适当的端口映射，用于查看和与环境交互。

如何实现计算机使用

从参考实现开始

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

一个容器化环境，适合与 Claude 一起使用计算机使用
计算机使用工具的实现
一个代理循环，与 Claude API 交互并执行计算机使用工具
一个网络界面，用于与容器、代理循环和工具交互。

理解代理循环

计算机使用的核心是"代理循环"——一个循环，其中 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"
    )
    text_editor_type = (
        "text_editor_20250728"
        if "20251124" in tool_version
        else f"text_editor_{tool_version}"
    )

    # 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": text_editor_type, "name": "str_replace_based_edit_tool"},
        {"type": "bash_20250124", "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 成本的潜在无限循环。

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

通过提示优化模型性能

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

指定简单、明确定义的任务，并为每个步骤提供明确的说明。
Claude 有时会假设其操作的结果，而不明确检查它们。为了防止这种情况，您可以使用以下提示提示 Claude：在每个步骤之后，截图并仔细评估您是否已实现正确的结果。明确显示您的思考："我已评估步骤 X..."。如果不正确，请重试。只有当您确认步骤执行正确时，才应继续下一步。
某些 UI 元素（如下拉菜单和滚动条）可能对 Claude 使用鼠标移动进行操作很棘手。如果您遇到这种情况，请尝试提示模型使用键盘快捷键。
对于可重复的任务或 UI 交互，在您的提示中包括成功结果的示例屏幕截图和工具调用。
如果您需要模型登录，请在您的提示中使用 xml 标签（如 <robot_credentials>）为其提供用户名和密码。在需要登录的应用程序中使用计算机使用会增加由于提示注入而导致不良结果的风险。在向模型提供登录凭据之前，请查看关于缓解提示注入的指南。

如果您反复遇到一组明确的问题，或者提前知道 Claude 需要完成的任务，请使用系统提示为 Claude 提供明确的提示或说明，说明如何成功完成任务。

对于跨越多个会话的代理，在每个会话开始时运行端到端验证，而不仅仅是在实现后。基于浏览器的检查会捕获来自先前会话的回归，这是仅代码级审查无法发现的。有关详细信息，请参阅长期运行代理的有效工具。

系统提示

当通过 Claude API 请求 Anthropic 架构工具之一时，会生成计算机使用特定的系统提示。它类似于工具使用系统提示，但以以下内容开头：

您可以访问一组函数来回答用户的问题。这包括访问沙箱计算环境。您目前没有检查文件或与外部资源交互的能力，除非通过调用以下函数。

与常规工具使用一样，用户提供的 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.7、Claude Opus 4.6、Claude Sonnet 4.6 和 Claude Opus 4.5 中可用：

computer_20250124 中的所有操作
zoom - 以全分辨率查看屏幕的特定区域。需要在工具定义中设置 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 的请求实现屏幕截图捕获、鼠标移动、键盘输入和其他操作。

与扩展思考相结合

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

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

要在计算机使用旁边添加其他工具，请将它们包括在同一 tools 数组中。上面的快速开始显示了这种模式，使用 bash 工具和文本编辑器工具。您可以以相同的方式添加您自己的自定义工具定义。

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

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

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

实现计算机使用工具

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

设置您的计算环境
创建虚拟显示或连接到 Claude 将与之交互的现有显示。这通常涉及设置 Xvfb（X 虚拟帧缓冲区）或类似技术。

实现操作处理程序

创建函数来处理 Claude 可能请求的每种操作类型：

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"])
    # ... handle other actions

处理 Claude 的工具调用

从 Claude 的响应中提取并执行工具调用：

for content in response.content:
    if content.type == "tool_use":
        action = content.input["action"]
        result = handle_computer_action(action, content.input)

        # Return result to Claude
        tool_result = {
            "type": "tool_result",
            "tool_use_id": content.id,
            "content": result,
        }

实现代理循环

创建一个循环，持续运行直到 Claude 完成任务：

while True:
    response = client.beta.messages.create(
        model="claude-opus-4-7",
        max_tokens=4096,
        messages=messages,
        tools=tools,
        betas=["computer-use-2025-11-24"],
    )

    # Check if Claude used any tools
    tool_results = process_tool_calls(response)

    if not tool_results:
        # No more tool use, task complete
        break

    # Continue conversation with tool results
    messages.append({"role": "user", "content": tool_results})

处理错误

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

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

Claude Opus 4.7 支持长边最多 2576 像素，其坐标与图像像素的比例为 1

（不需要缩放因子转换）。下面的 1568 像素指导适用于早期模型。

API 将图像限制为最长边最多 1568 像素，总共约 1.15 百万像素（有关详细信息，请参阅图像调整大小）。例如，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 的功能处于最前沿，但开发人员应该了解其限制：

延迟：当前人工智能交互的计算机使用延迟可能与常规人工指导的计算机操作相比太慢。专注于速度不是关键的用例（例如，后台信息收集、自动化软件测试）在受信任的环境中。
计算机视觉准确性和可靠性：Claude 在输出特定坐标同时生成操作时可能会犯错误或产生幻觉。Claude Sonnet 3.7 引入了思维能力，可以帮助您理解模型的推理并识别潜在问题。
工具选择准确性和可靠性：Claude 在选择工具同时生成操作时可能会犯错误或产生幻觉，或采取意外操作来解决问题。此外，与利基应用程序或多个应用程序同时交互时，可靠性可能较低。在请求复杂任务时，请仔细提示模型。
滚动可靠性：Claude Sonnet 3.7 引入了具有方向控制的专用滚动操作，提高了可靠性。该模型现在可以显式地按指定数量向任何方向（上/下/左/右）滚动。
电子表格交互：Claude Sonnet 3.7 中的电子表格交互鼠标点击通过添加更精确的鼠标控制操作（如 left_mouse_down、left_mouse_up）和新的修饰键支持得到了改进。通过使用这些细粒度控制和将修饰键与点击结合，单元格选择可以更可靠。
社交和通信平台上的账户创建和内容生成：虽然 Claude 会访问网站，但 Claude 在社交媒体网站和平台上创建账户或生成和共享内容或以其他方式进行人类模拟的能力是有限的。此功能可能在将来更新。
漏洞：越狱或提示注入等漏洞可能在包括测试版计算机使用 API 在内的前沿 AI 系统中持续存在。在某些情况下，Claude 会遵循内容中找到的命令，有时甚至与用户的指示相冲突。例如，网页上或图像中包含的 Claude 指示可能会覆盖指示或导致 Claude 犯错误。请考虑以下事项： a. 将计算机使用限制在受信任的环境中，如具有最小权限的虚拟机或容器 b. 避免在没有严格监督的情况下向计算机使用访问敏感账户或数据 c. 在启用或请求应用程序中计算机使用功能所需的权限之前，通知最终用户相关风险并获得其同意
不适当或非法操作：根据 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:

Model	Input tokens per tool definition
Claude 4.x models	735 tokens

Additional token consumption:

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

If you're also using bash or text editor tools alongside computer use, those tools have their own token costs as documented in their respective pages.

后续步骤

参考实现

使用完整的基于 Docker 的实现快速入门

工具文档

了解有关工具使用和创建自定义工具的更多信息

Was this page helpful?

构建工具

计算机使用工具

Claude 可以通过计算机使用工具与计算机环境交互，该工具提供屏幕截图功能和鼠标/键盘控制，用于自主桌面交互。

计算机使用处于测试版阶段，需要 beta 标头：

"computer-use-2025-11-24" 用于 Claude Opus 4.7、Claude Opus 4.6、Claude Sonnet 4.6、Claude Opus 4.5
"computer-use-2025-01-24" 用于 Sonnet 4.5、Haiku 4.5、Opus 4.1、Sonnet 4、Opus 4 和 Sonnet 3.7（已弃用）

请通过反馈表单分享您对此功能的反馈。

This feature is eligible for Zero Data Retention (ZDR). When your organization has a ZDR arrangement, data sent through this feature is not stored after the API response is returned.

概述

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

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

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

安全考虑

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

为了最小化风险，请考虑采取以下预防措施：

使用具有最小权限的专用虚拟机或容器，以防止直接系统攻击或意外事故。
避免让模型访问敏感数据，例如账户登录信息，以防止信息被盗。
将互联网访问限制在域名白名单中，以减少暴露于恶意内容的风险。
要求人工确认可能导致有意义的现实世界后果的决定，以及任何需要肯定同意的任务，例如接受 Cookie、执行财务交易或同意服务条款。

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

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

计算机使用参考实现

使用计算机使用参考实现快速入门，该实现包括网络界面、Docker 容器、示例工具实现和代理循环。

注意：该实现已更新，包括 Claude 4 模型和 Claude Sonnet 3.7 的新工具。请确保拉取最新版本的仓库以访问这些新功能。

快速开始

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

client = anthropic.Anthropic()

response = client.beta.messages.create(
    model="claude-opus-4-7",  # 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 提供计算机使用工具和用户提示
- 在您的 API 请求中添加计算机使用工具（以及可选的其他工具）。
- 包括需要桌面交互的用户提示，例如"将猫的图片保存到我的桌面"。
Claude 决定使用计算机使用工具
- Claude 评估计算机使用工具是否可以帮助解决用户的查询。
- 如果是，Claude 构造一个格式正确的工具使用请求。
- API 响应的 stop_reason 为 tool_use，表示 Claude 的意图。
提取工具输入，在计算机上评估工具，并返回结果
- 在您的一端，从 Claude 的请求中提取工具名称和输入。
- 在容器或虚拟机上使用该工具。
- 继续对话，使用包含 tool_result 内容块的新 user 消息。
Claude 继续调用计算机使用工具，直到完成任务
- Claude 分析工具结果，以确定是否需要更多工具使用或任务已完成。
- 如果 Claude 决定需要另一个工具，它会以另一个 tool_use stop_reason 响应，您应该返回第 3 步。
- 否则，它会为用户制作文本响应。

步骤 3 和 4 在没有用户输入的情况下的重复称为"代理循环"（即 Claude 响应工具使用请求，您的应用程序用评估该请求的结果响应 Claude）。

计算环境

计算机使用需要一个沙箱计算环境，Claude 可以在其中安全地与应用程序和网络交互。此环境包括：

虚拟显示：一个虚拟 X11 显示服务器（使用 Xvfb），它呈现 Claude 将通过屏幕截图看到的桌面界面，并通过鼠标/键盘操作进行控制。
桌面环境：在 Linux 上运行的轻量级 UI，带有窗口管理器（Mutter）和面板（Tint2），为 Claude 提供一致的图形界面来交互。
应用程序：预装的 Linux 应用程序，如 Firefox、LibreOffice、文本编辑器和文件管理器，Claude 可以使用这些应用程序来完成任务。
工具实现：集成代码，将 Claude 的抽象工具请求（如"移动鼠标"或"截图"）转换为虚拟环境中的实际操作。
代理循环：一个程序，处理 Claude 和环境之间的通信，将 Claude 的操作发送到环境，并将结果（屏幕截图、命令输出）返回给 Claude。

当您使用计算机使用时，Claude 不会直接连接到此环境。相反，您的应用程序：

接收 Claude 的工具使用请求
将它们转换为计算环境中的操作
捕获结果（屏幕截图、命令输出等）
将这些结果返回给 Claude

为了安全和隔离，参考实现在 Docker 容器内运行所有这些，具有适当的端口映射，用于查看和与环境交互。

如何实现计算机使用

从参考实现开始

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

一个容器化环境，适合与 Claude 一起使用计算机使用
计算机使用工具的实现
一个代理循环，与 Claude API 交互并执行计算机使用工具
一个网络界面，用于与容器、代理循环和工具交互。

理解代理循环

计算机使用的核心是"代理循环"——一个循环，其中 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"
    )
    text_editor_type = (
        "text_editor_20250728"
        if "20251124" in tool_version
        else f"text_editor_{tool_version}"
    )

    # 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": text_editor_type, "name": "str_replace_based_edit_tool"},
        {"type": "bash_20250124", "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 成本的潜在无限循环。

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

通过提示优化模型性能

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

指定简单、明确定义的任务，并为每个步骤提供明确的说明。
Claude 有时会假设其操作的结果，而不明确检查它们。为了防止这种情况，您可以使用以下提示提示 Claude：在每个步骤之后，截图并仔细评估您是否已实现正确的结果。明确显示您的思考："我已评估步骤 X..."。如果不正确，请重试。只有当您确认步骤执行正确时，才应继续下一步。
某些 UI 元素（如下拉菜单和滚动条）可能对 Claude 使用鼠标移动进行操作很棘手。如果您遇到这种情况，请尝试提示模型使用键盘快捷键。
对于可重复的任务或 UI 交互，在您的提示中包括成功结果的示例屏幕截图和工具调用。
如果您需要模型登录，请在您的提示中使用 xml 标签（如 <robot_credentials>）为其提供用户名和密码。在需要登录的应用程序中使用计算机使用会增加由于提示注入而导致不良结果的风险。在向模型提供登录凭据之前，请查看关于缓解提示注入的指南。

如果您反复遇到一组明确的问题，或者提前知道 Claude 需要完成的任务，请使用系统提示为 Claude 提供明确的提示或说明，说明如何成功完成任务。

系统提示

当通过 Claude API 请求 Anthropic 架构工具之一时，会生成计算机使用特定的系统提示。它类似于工具使用系统提示，但以以下内容开头：

您可以访问一组函数来回答用户的问题。这包括访问沙箱计算环境。您目前没有检查文件或与外部资源交互的能力，除非通过调用以下函数。

与常规工具使用一样，用户提供的 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.7、Claude Opus 4.6、Claude Sonnet 4.6 和 Claude Opus 4.5 中可用：

computer_20250124 中的所有操作
zoom - 以全分辨率查看屏幕的特定区域。需要在工具定义中设置 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 一起使用的虚拟化或容器化环境
至少一个 Anthropic 架构计算机使用工具的实现
与 Claude API 交互并使用您的工具实现执行 tool_use 结果的代理循环
允许用户输入以启动代理循环的 API 或 UI

实现计算机使用工具

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

设置您的计算环境
创建虚拟显示或连接到 Claude 将与之交互的现有显示。这通常涉及设置 Xvfb（X 虚拟帧缓冲区）或类似技术。

实现操作处理程序

创建函数来处理 Claude 可能请求的每种操作类型：

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"])
    # ... handle other actions

处理 Claude 的工具调用

从 Claude 的响应中提取并执行工具调用：

for content in response.content:
    if content.type == "tool_use":
        action = content.input["action"]
        result = handle_computer_action(action, content.input)

        # Return result to Claude
        tool_result = {
            "type": "tool_result",
            "tool_use_id": content.id,
            "content": result,
        }

实现代理循环

创建一个循环，持续运行直到 Claude 完成任务：

while True:
    response = client.beta.messages.create(
        model="claude-opus-4-7",
        max_tokens=4096,
        messages=messages,
        tools=tools,
        betas=["computer-use-2025-11-24"],
    )

    # Check if Claude used any tools
    tool_results = process_tool_calls(response)

    if not tool_results:
        # No more tool use, task complete
        break

    # Continue conversation with tool results
    messages.append({"role": "user", "content": tool_results})

处理错误

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

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

Claude Opus 4.7 支持长边最多 2576 像素，其坐标与图像像素的比例为 1

（不需要缩放因子转换）。下面的 1568 像素指导适用于早期模型。

这可能导致 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 的功能处于最前沿，但开发人员应该了解其限制：

延迟：当前人工智能交互的计算机使用延迟可能与常规人工指导的计算机操作相比太慢。专注于速度不是关键的用例（例如，后台信息收集、自动化软件测试）在受信任的环境中。
计算机视觉准确性和可靠性：Claude 在输出特定坐标同时生成操作时可能会犯错误或产生幻觉。Claude Sonnet 3.7 引入了思维能力，可以帮助您理解模型的推理并识别潜在问题。
工具选择准确性和可靠性：Claude 在选择工具同时生成操作时可能会犯错误或产生幻觉，或采取意外操作来解决问题。此外，与利基应用程序或多个应用程序同时交互时，可靠性可能较低。在请求复杂任务时，请仔细提示模型。
滚动可靠性：Claude Sonnet 3.7 引入了具有方向控制的专用滚动操作，提高了可靠性。该模型现在可以显式地按指定数量向任何方向（上/下/左/右）滚动。
电子表格交互：Claude Sonnet 3.7 中的电子表格交互鼠标点击通过添加更精确的鼠标控制操作（如 left_mouse_down、left_mouse_up）和新的修饰键支持得到了改进。通过使用这些细粒度控制和将修饰键与点击结合，单元格选择可以更可靠。
社交和通信平台上的账户创建和内容生成：虽然 Claude 会访问网站，但 Claude 在社交媒体网站和平台上创建账户或生成和共享内容或以其他方式进行人类模拟的能力是有限的。此功能可能在将来更新。
漏洞：越狱或提示注入等漏洞可能在包括测试版计算机使用 API 在内的前沿 AI 系统中持续存在。在某些情况下，Claude 会遵循内容中找到的命令，有时甚至与用户的指示相冲突。例如，网页上或图像中包含的 Claude 指示可能会覆盖指示或导致 Claude 犯错误。请考虑以下事项： a. 将计算机使用限制在受信任的环境中，如具有最小权限的虚拟机或容器 b. 避免在没有严格监督的情况下向计算机使用访问敏感账户或数据 c. 在启用或请求应用程序中计算机使用功能所需的权限之前，通知最终用户相关风险并获得其同意
不适当或非法操作：根据 Anthropic 的服务条款，您不得使用计算机使用来违反任何法律或可接受的使用政策。

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

数据保留

因为您的应用程序控制计算机使用数据的存储位置和方式，计算机使用符合 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:

Model	Input tokens per tool definition
Claude 4.x models	735 tokens

Additional token consumption:

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

If you're also using bash or text editor tools alongside computer use, those tools have their own token costs as documented in their respective pages.

后续步骤

参考实现

使用完整的基于 Docker 的实现快速入门

工具文档

了解有关工具使用和创建自定义工具的更多信息

Was this page helpful?

概述

安全考虑

快速开始

计算机使用如何工作

计算环境

如何实现计算机使用

从参考实现开始

理解代理循环

通过提示优化模型性能

系统提示

可用操作

示例操作

带有点击和滚动操作的修饰键

工具参数

与扩展思考相结合

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

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

实现计算机使用工具

处理错误

屏幕截图捕获失败

无效坐标

操作执行失败

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

遵循实现最佳实践

使用适当的显示分辨率

实现适当的屏幕截图处理

添加操作延迟

在执行前验证操作

记录操作以进行调试

了解计算机使用的限制

数据保留

定价

后续步骤

概述

安全考虑

快速开始

计算机使用如何工作

计算环境

如何实现计算机使用

从参考实现开始

理解代理循环

通过提示优化模型性能

系统提示

可用操作

示例操作

带有点击和滚动操作的修饰键

工具参数

与扩展思考相结合

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

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

实现计算机使用工具

处理错误

屏幕截图捕获失败

无效坐标

操作执行失败

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

遵循实现最佳实践

使用适当的显示分辨率

实现适当的屏幕截图处理

添加操作延迟

在执行前验证操作

记录操作以进行调试

了解计算机使用的限制

数据保留

定价

后续步骤