计算机使用工具

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

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

"computer-use-2025-01-24"（Claude 4和3.7模型）
"computer-use-2024-10-22"（Claude Sonnet 3.5）

概述

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

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

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

模型兼容性

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

模型	工具版本	测试版标志
Claude 4 Opus & Sonnet	`computer_20250124`	`computer-use-2025-01-24`
Claude Sonnet 3.7	`computer_20250124`	`computer-use-2025-01-24`
Claude Sonnet 3.5 (new)	`computer_20241022`	`computer-use-2024-10-22`

Claude 4模型使用针对新架构优化的更新工具版本。Claude Sonnet 3.7引入了额外功能，包括思考功能，可以更深入地了解模型的推理过程。

安全考虑

计算机使用是一个测试版功能，具有与标准API功能不同的独特风险。在与互联网交互时，这些风险会加剧。为了最小化风险，请考虑采取以下预防措施：

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

在某些情况下，Claude会遵循内容中找到的命令，即使这与用户的指令冲突。例如，网页上的Claude指令或图像中包含的指令可能会覆盖指令或导致Claude犯错。我们建议采取预防措施，将Claude与敏感数据和操作隔离，以避免与提示注入相关的风险。我们已经训练模型抵制这些提示注入，并添加了额外的防御层。如果您使用我们的计算机使用工具，我们将自动在您的提示上运行分类器，以标记潜在的提示注入实例。当这些分类器在截图中识别出潜在的提示注入时，它们将自动引导模型在继续下一个操作之前要求用户确认。我们认识到这种额外的保护对于每个用例都不是理想的（例如，没有人工参与的用例），所以如果您想选择退出并关闭它，请联系我们。我们仍然建议采取预防措施，将Claude与敏感数据和操作隔离，以避免与提示注入相关的风险。最后，在您自己的产品中启用计算机使用之前，请告知最终用户相关风险并获得他们的同意。

计算机使用参考实现

通过我们的计算机使用参考实现快速开始，该实现包括Web界面、Docker容器、示例工具实现和代理循环。**注意：**该实现已更新，包含Claude 4和Claude Sonnet 3.7的新工具。请确保拉取仓库的最新版本以访问这些新功能。

请使用此表单提供关于模型响应质量、API本身或文档质量的反馈 - 我们迫不及待想听到您的意见！

快速开始

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

import anthropic

client = anthropic.Anthropic()

response = client.beta.messages.create(
    model="claude-sonnet-4-20250514",  # or another compatible model
    max_tokens=1024,
    tools=[
        {
          "type": "computer_20250124",
          "name": "computer",
          "display_width_px": 1024,
          "display_height_px": 768,
          "display_number": 1,
        },
        {
          "type": "text_editor_20250124",
          "name": "str_replace_editor"
        },
        {
          "type": "bash_20250124",
          "name": "bash"
        }
    ],
    messages=[{"role": "user", "content": "Save a picture of a cat to my desktop."}],
    betas=["computer-use-2025-01-24"]
)
print(response)

测试版标头要求：

Claude 4和Sonnet 3.7：仅计算机使用工具需要测试版标头
Claude Sonnet 3.5：计算机、bash和文本编辑器工具都需要测试版标头

上面的示例显示了三个工具一起使用，这需要任何Claude模型的测试版标头，因为它包含计算机使用工具。

计算机使用的工作原理

1. 为Claude提供计算机使用工具和用户提示

将计算机使用工具（以及可选的其他工具）添加到您的API请求中。
包含需要桌面交互的用户提示，例如”将一张猫的图片保存到我的桌面”。

2. Claude决定使用计算机使用工具

Claude评估计算机使用工具是否可以帮助处理用户的查询。
如果是，Claude构造一个格式正确的工具使用请求。
API响应的stop_reason为tool_use，表示Claude的意图。

3. 提取工具输入，在计算机上评估工具，并返回结果

在您这边，从Claude的请求中提取工具名称和输入。
在容器或虚拟机上使用该工具。
使用包含tool_result内容块的新user消息继续对话。

4. Claude继续调用计算机使用工具，直到完成任务

Claude分析工具结果，确定是否需要更多工具使用或任务已完成。
如果Claude决定需要另一个工具，它会响应另一个tool_use stop_reason，您应该返回到步骤3。
否则，它会为用户制作文本响应。

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

计算环境

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

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

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

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

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

如何实现计算机使用

从我们的参考实现开始

我们构建了一个参考实现，包含您快速开始使用计算机使用所需的一切：

适合与Claude一起使用计算机使用的容器化环境
计算机使用工具的实现
与Anthropic 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
):
    """
    Claude计算机使用交互的简单代理循环。

    此函数处理以下之间的来回交互：
    1. 向Claude发送用户消息
    2. Claude请求使用工具
    3. 您的应用程序执行这些工具
    4. 将工具结果发送回Claude
    """
    # 设置工具和API参数
    client = Anthropic(api_key=api_key)
    beta_flag = "computer-use-2025-01-24" if "20250124" in tool_version else "computer-use-2024-10-22"

    # 配置工具 - 您应该已经在其他地方初始化了这些
    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"}
    ]

    # 主代理循环（带有迭代限制以防止失控的API成本）
    iterations = 0
    while True and iterations < max_iterations:
        iterations += 1
        # 设置可选的思考参数（用于Claude Sonnet 3.7）
        thinking = None
        if thinking_budget:
            thinking = {"type": "enabled", "budget_tokens": thinking_budget}

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

        # 将Claude的响应添加到对话历史中
        response_content = response.content
        messages.append({"role": "assistant", "content": response_content})

        # 检查Claude是否使用了任何工具
        tool_results = []
        for block in response_content:
            if block.type == "tool_use":
                # 在真实应用中，您会在这里执行工具
                # 例如：result = run_tool(block.name, block.input)
                result = {"result": "Tool executed successfully"}

                # 为Claude格式化结果
                tool_results.append({
                    "type": "tool_result",
                    "tool_use_id": block.id,
                    "content": result
                })

        # 如果没有使用工具，Claude完成了 - 返回最终消息
        if not tool_results:
            return messages

        # 将工具结果添加到消息中，用于与Claude的下一次迭代
        messages.append({"role": "user", "content": tool_results})

循环继续，直到Claude响应时不请求任何工具（任务完成）或达到最大迭代限制。这种保护措施防止可能导致意外API成本的潜在无限循环。

使用计算机使用工具时，您必须为您的模型版本包含适当的测试版标志：

Claude 4模型

Claude Sonnet 3.7

Claude Sonnet 3.5 (new)

注意：对于Claude 4和Sonnet 3.7，测试版标志仅对计算机使用工具是必需的。对于Claude Sonnet 3.5，计算机、bash和文本编辑器工具都需要测试版标志。

我们建议在阅读本文档的其余部分之前先尝试参考实现。

通过提示优化模型性能

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

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

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

系统提示

当通过Anthropic 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 - 在操作之间暂停

示例操作

//截图
{
  "action": "screenshot"
}

// 在位置点击
{
  "action": "left_click",
  "coordinate": [500, 300]
}

// 输入文本
{
  "action": "type",
  "text": "Hello, world!"
}

// 向下滚动（Claude 4/3.7）
{
  "action": "scroll",
  "coordinate": [500, 400],
  "scroll_direction": "down",
  "scroll_amount": 3
}

工具参数

参数	必需	描述
`type`	是	工具版本（`computer_20250124`或`computer_20241022`）
`name`	是	必须是”computer”
`display_width_px`	是	显示宽度（像素）
`display_height_px`	是	显示高度（像素）
`display_number`	否	X11环境的显示编号

为了获得最佳性能，请将显示分辨率保持在1280x800（WXGA）或以下。更高的分辨率可能由于图像调整大小而导致准确性问题。

重要：计算机使用工具必须由您的应用程序明确执行 - Claude无法直接执行它。您负责根据Claude的请求实现截图捕获、鼠标移动、键盘输入和其他操作。

在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将返回其推理过程作为响应的一部分，这可以帮助您：

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

以下是思考输出可能的样子：

[思考]
我需要将一张猫的图片保存到桌面。让我将此分解为步骤：

1. 首先，我将截图查看桌面上有什么
2. 然后我将寻找Web浏览器来搜索猫的图片
3. 找到合适的图片后，我需要将其保存到桌面

让我先截图看看有什么可用的...

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

计算机使用工具可以与其他工具结合使用，创建更强大的自动化工作流程。当您需要以下功能时，这特别有用：

执行系统命令（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-01-24" \
  -d '{
    "model": "claude-opus-4-20250514",
    "max_tokens": 2000,
    "tools": [
      {
        "type": "computer_20250124",
        "name": "computer",
        "display_width_px": 1024,
        "display_height_px": 768,
        "display_number": 1
      },
      {
        "type": "text_editor_20250124",
        "name": "str_replace_editor"
      },
      {
        "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定义的计算机使用工具的实现
与Anthropic 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"])
    # ... 处理其他操作

处理Claude的工具调用

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

for content in response.content:
    if content.type == "tool_use":
        action = content.input["action"]
        result = handle_computer_action(action, content.input)
        
        # 将结果返回给Claude
        tool_result = {
            "type": "tool_result",
            "tool_use_id": content.id,
            "content": result
        }

实现代理循环

创建一个循环，直到Claude完成任务：

while True:
    response = client.beta.messages.create(...)
    
    # 检查Claude是否使用了任何工具
    tool_results = process_tool_calls(response)
    
    if not tool_results:
        # 没有更多工具使用，任务完成
        break
        
    # 使用工具结果继续对话
    messages.append({"role": "user", "content": tool_results})

处理错误

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

截图捕获失败

如果截图捕获失败，返回适当的错误消息：

{
  "role": "user",
  "content": [
    {
      "type": "tool_result",
      "tool_use_id": "toolu_01A09q90qw90lq917835lq9",
      "content": "错误：截图捕获失败。显示可能被锁定或不可用。",
      "is_error": true
    }
  ]
}

无效坐标

如果Claude提供超出显示边界的坐标：

{
  "role": "user",
  "content": [
    {
      "type": "tool_result",
      "tool_use_id": "toolu_01A09q90qw90lq917835lq9",
      "content": "错误：坐标(1200, 900)超出显示边界(1024x768)。",
      "is_error": true
    }
  ]
}

操作执行失败

如果操作执行失败：

{
  "role": "user",
  "content": [
    {
      "type": "tool_result",
      "tool_use_id": "toolu_01A09q90qw90lq917835lq9",
      "content": "错误：点击操作执行失败。应用程序可能无响应。",
      "is_error": true
    }
  ]
}

遵循实现最佳实践

使用适当的显示分辨率

实现适当的截图处理

添加操作延迟

在执行前验证操作

检查请求的操作是否安全和有效：

def validate_action(action_type, params):
    if action_type == "left_click":
        x, y = params.get("coordinate", (0, 0))
        if not (0 <= x < display_width and 0 <= y < display_height):
            return False, "坐标超出边界"
    return True, None

记录操作以进行调试

保留所有操作的日志以进行故障排除：

import logging

def log_action(action_type, params, result):
    logging.info(f"操作：{action_type}，参数：{params}，结果：{result}")

了解计算机使用限制

计算机使用功能处于测试阶段。虽然Claude的功能是前沿的，但开发人员应该了解其限制：

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

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

定价

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 / Sonnet 3.7	735 tokens
Claude Sonnet 3.5 (deprecated)	683 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.

入门步骤

模型与定价

了解 Claude

功能

工具

模型上下文协议 (MCP)

使用案例

提示工程

测试与评估

加强防护措施

法律中心

计算机使用工具

概述

模型兼容性

安全考虑

计算机使用参考实现

快速开始

计算机使用的工作原理

计算环境

如何实现计算机使用

从我们的参考实现开始

理解多代理循环

通过提示优化模型性能

系统提示

可用操作

工具参数

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

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

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

实现计算机使用工具

处理错误

遵循实现最佳实践

了解计算机使用限制

定价

下一步

参考实现

工具文档

入门步骤

模型与定价

了解 Claude

功能

工具

模型上下文协议 (MCP)

使用案例

提示工程

测试与评估

加强防护措施

法律中心

​概述

​模型兼容性

​安全考虑

计算机使用参考实现

​快速开始

​计算机使用的工作原理

​计算环境

​如何实现计算机使用

​从我们的参考实现开始

​理解多代理循环

​通过提示优化模型性能

​系统提示

​可用操作

​工具参数

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

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

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

​实现计算机使用工具

​处理错误

​遵循实现最佳实践

​了解计算机使用限制

​定价

​下一步

参考实现

工具文档

概述

模型兼容性

安全考虑

快速开始

计算机使用的工作原理

计算环境

如何实现计算机使用

从我们的参考实现开始

理解多代理循环

通过提示优化模型性能

系统提示

可用操作

工具参数

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

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

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

实现计算机使用工具

处理错误

遵循实现最佳实践

了解计算机使用限制

定价

下一步