计算机使用工具

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

​

概述

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

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

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

​

模型兼容性

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

​

安全考虑

​

快速开始

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

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)

​

计算机使用的工作原理

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

​

计算环境

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

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一起使用计算机使用的容器化环境
• 计算机使用工具的实现
• 与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成本的潜在无限循环。

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

​

通过提示优化模型性能

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

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

​

系统提示

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

​

工具参数

​

在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. 更好地了解复杂的多步骤操作

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

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

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的模型中，无法修改。

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"])
    # ... 处理其他操作

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
        }

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})

​

处理错误

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

​

遵循实现最佳实践

​

了解计算机使用限制

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

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

Additional token consumption:

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

​

下一步