计算机使用工具

​

概述

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

​

模型兼容性

​

安全考虑

​

快速开始

import anthropic

client = anthropic.Anthropic()

response = client.beta.messages.create(
    model="claude-sonnet-4-5",  # 或其他兼容模型
    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": "保存一张猫的图片到我的桌面。"}],
    betas=["computer-use-2025-01-24"]
)
print(response)

​

计算机使用的工作原理

​

计算环境

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

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

​

如何实现计算机使用

​

从我们的参考实现开始

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

​

理解多代理循环

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,  # 添加迭代限制以防止无限循环
):
    """
    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": "工具执行成功"}

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

"betas": ["computer-use-2025-01-24"]

"betas": ["computer-use-2025-01-24"]

"betas": ["computer-use-2024-10-22"]

​

通过提示优化模型性能

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

​

系统提示

您可以访问一组函数，可以使用这些函数来回答用户的问题。这包括访问沙盒计算环境。除了调用以下函数外，您目前无法检查文件或与外部资源交互。

​

可用操作

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

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

​

工具参数

​

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

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

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

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

1. 首先，我将截图查看桌面上有什么
2. 然后我将寻找网络浏览器来搜索猫的图片
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-sonnet-4-5",
    "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": "获取给定位置的当前天气",
        "input_schema": {
          "type": "object",
          "properties": {
            "location": {
              "type": "string",
              "description": "城市和州，例如 San Francisco, CA"
            },
            "unit": {
              "type": "string",
              "enum": ["celsius", "fahrenheit"],
              "description": "温度单位，'celsius' 或 'fahrenheit'"
            }
          },
          "required": ["location"]
        }
      }
    ],
    "messages": [
      {
        "role": "user",
        "content": "查找从旧金山到天气更温暖的地方的航班。"
      }
    ],
    "thinking": {
      "type": "enabled",
      "budget_tokens": 1024
    }
  }'

​

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

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

​

实现计算机使用工具

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

​

处理错误

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

{
  "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 click_and_wait(x, y, wait_time=0.5):
    click_at(x, y)
    time.sleep(wait_time)  # 允许 UI 更新

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

​

了解计算机使用限制

1. 延迟：当前计算机使用的人机交互延迟与常规人工指导的计算机操作相比可能太慢。我们建议专注于速度不重要的用例（例如，在可信环境中的后台信息收集、自动化软件测试）。
2. 计算机视觉准确性和可靠性：Claude 在生成操作时输出特定坐标时可能会犯错误或产生幻觉。Claude Sonnet 3.7 引入了思考功能，可以帮助您了解模型的推理并识别潜在问题。
3. 工具选择准确性和可靠性：Claude 在生成操作时选择工具时可能会犯错误或产生幻觉，或采取意外操作来解决问题。此外，在与小众应用程序或同时与多个应用程序交互时，可靠性可能较低。我们建议用户在请求复杂任务时仔细提示模型。
4. 滚动可靠性：虽然 Claude Sonnet 3.5 v2（已弃用）在滚动方面有限制，但 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 的服务条款，您不得使用计算机使用来违反任何法律或我们的可接受使用政策。

​

定价

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

​

下一步