计算机使用工具

Claude 可以通过计算机使用工具（computer use tool）与计算机环境交互，该工具提供截图功能以及鼠标/键盘控制，用于自主的桌面交互。

计算机使用工具是 Anthropic 定义的 client toolset（客户端工具集）：在 tools 中添加一个 {"type": "computer_toolset_20260801"} 条目，即可为 Claude 提供 17 个成员工具，例如 screenshot、left_click、type 和 zoom，而您的应用程序在您控制的环境中运行每一次调用。它目前在 Claude Managed Agents 中不可用。Claude 的调用是 tool_use 块，其 name 为成员名称，并携带 "toolset_name": "computer"，通常每轮有多个（即批量操作）。

对于停留在网页内部的任务，浏览器使用工具更为合适：它的成员工具直接读取并操作页面本身，并且不需要完整的桌面环境。

安全注意事项

计算机使用具有与标准 API 功能不同的独特风险。在与互联网交互时，这些风险会进一步加剧。

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

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

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

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

快速开始

将计算机使用工具集以 {"type": "computer_toolset_20260801"} 的形式添加到 Messages API 请求的 tools 数组中。该请求不需要 beta 标头。此示例还声明了文本编辑器工具和 bash 工具，Claude 通常会将它们与计算机使用一起使用：

client = anthropic.Anthropic()

response = client.messages.create(
    model="claude-opus-5",
    max_tokens=1024,
    tools=[
        {"type": "computer_toolset_20260801"},
        {"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."}],
)
print(response)

当 Claude 在桌面上执行操作时，响应的 stop_reason 为 tool_use，并包含一个或多个成员 tool_use 块，每个块指定一个成员工具并携带 "toolset_name": "computer"。在此任务进行到一半、Claude 已看到桌面截图之后，响应可能如下所示：

{
  "id": "msg_01UZ3bXcQH8mTqNhVfL9eK2p",
  "type": "message",
  "role": "assistant",
  "model": "claude-opus-5",
  "content": [
    {
      "type": "text",
      "text": "I'll open the web browser to find a picture of a cat."
    },
    {
      "type": "tool_use",
      "id": "toolu_01WkoTUvSHDzTBu2xnGk8Ep8",
      "name": "left_click",
      "toolset_name": "computer",
      "input": { "coordinate": [512, 742] }
    },
    {
      "type": "tool_use",
      "id": "toolu_017nJn3RgSCkTMwuZDb4uUov",
      "name": "screenshot",
      "toolset_name": "computer",
      "input": {}
    }
  ],
  "stop_reason": "tool_use",
  "stop_sequence": null
}

您的应用程序在您自己的环境中按顺序运行每个调用，为每个 tool_use 块返回一个 tool_result 块，然后再次调用 API；计算机使用的工作原理描述了该循环，本页的其余部分展示了如何实现它。

计算机使用的工作原理

1. 1

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

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

   Claude 以成员工具调用进行响应

   • Claude 评估在桌面上执行操作是否有助于解决用户的查询。
   • 如果是，Claude 会以一个或多个成员 tool_use 块进行响应，例如 screenshot、left_click 或 type，每个块都携带 "toolset_name": "computer"。包含多个此类块的响应即为批量操作。
   • API 响应的 stop_reason 为 tool_use，表示工具使用请求。
3. 3

   按顺序运行调用并返回结果

   • 按顺序遍历响应中的每个 tool_use 块。对于每个块，根据成员 name 和 toolset_name 进行分派，并使用该块的 input 在您的容器或虚拟机上执行该操作。
   • 使用一条新的 user 消息继续对话，该消息为每个 tool_use 块包含一个 tool_result 块，通过 tool_use_id 匹配，并且每个块都回显 "toolset_name": "computer"。对于 screenshot 和 zoom 返回图像；对于其他操作，返回诸如 OK 之类的简短文本即可。
   • 如果某个操作失败，请为该块返回 is_error: true，并按照批量操作中的说明回答批次中的其余部分。
4. 4

   Claude 继续执行直到任务完成

   • Claude 分析工具结果，以确定是否需要更多操作或任务是否已完成。
   • 如果 Claude 确定需要更多操作，它会以另一个 tool_use stop_reason 进行响应，您应返回第 3 步。
   • 否则，它会向用户返回文本响应。

在没有用户输入的情况下重复第 3 步和第 4 步被称为"agent loop"（智能体循环），即 Claude 以工具使用请求进行响应，而您的应用程序以评估该请求的结果回应 Claude。

批量操作

Claude 可以规划一小段操作序列，例如点击、输入，然后截图，并在一个响应中一起返回它们。这称为 batch action（批量操作）；它使用与并行工具使用相同的响应形式，但有一个区别：您按顺序运行这些块，而不是并发运行。

包含三个操作的批量响应如下所示：

{
  "role": "assistant",
  "content": [
    {
      "type": "tool_use",
      "id": "toolu_01HqCF3nJ4Vzr8sTkPZ2wxYA",
      "name": "left_click",
      "toolset_name": "computer",
      "input": { "coordinate": [640, 60] }
    },
    {
      "type": "tool_use",
      "id": "toolu_01Ppr3sZ3TnE9m6VUu4RyH2K",
      "name": "type",
      "toolset_name": "computer",
      "input": { "text": "pictures of cats" }
    },
    {
      "type": "tool_use",
      "id": "toolu_01Xf5W1sD8Q9aBcJ7kLmN2pQ",
      "name": "screenshot",
      "toolset_name": "computer",
      "input": {}
    }
  ]
}

为每个 tool_use 块返回一个 tool_result 块，通过 tool_use_id 匹配，全部放在下一条 user 消息中。成员工具的每个结果都必须携带 "toolset_name": "computer"；省略它的结果，或指定了与其 tool_use 块不同的工具集的结果，都会被拒绝。只有 screenshot 和 zoom 的结果需要图像；对于其他成员，诸如 OK 之类的简短文本确认即可（cursor_position 以文本形式返回坐标）：

{
  "role": "user",
  "content": [
    {
      "type": "tool_result",
      "tool_use_id": "toolu_01HqCF3nJ4Vzr8sTkPZ2wxYA",
      "toolset_name": "computer",
      "content": [{ "type": "text", "text": "OK" }]
    },
    {
      "type": "tool_result",
      "tool_use_id": "toolu_01Ppr3sZ3TnE9m6VUu4RyH2K",
      "toolset_name": "computer",
      "content": [{ "type": "text", "text": "OK" }]
    },
    {
      "type": "tool_result",
      "tool_use_id": "toolu_01Xf5W1sD8Q9aBcJ7kLmN2pQ",
      "toolset_name": "computer",
      "content": [
        {
          "type": "image",
          "source": {
            "type": "base64",
            "media_type": "image/png",
            "data": "iVBORw0KGgo..."
          }
        }
      ]
    }
  ]
}

按顺序运行块，并在第一次失败时停止。 批次中后面的操作通常依赖于前面的操作：此示例中的 type 会将文本输入到前一次点击所聚焦的任何位置。按照块在 content 中出现的顺序依次运行它们，如果其中一个失败，则不要运行其余的块。每个 tool_use 块仍然需要一个 tool_result，因此请按如下方式回答该批次：

• 对于每个成功的操作，返回其正常结果。
• 对于失败的操作，返回 is_error: true 以及描述出错原因的文本。
• 对于批次中每个后续操作，返回 is_error: true 并附上以下确切文本（浏览器使用工具使用其自己的中止文本）：

{
  "type": "tool_result",
  "tool_use_id": "toolu_01Xf5W1sD8Q9aBcJ7kLmN2pQ",
  "toolset_name": "computer",
  "is_error": true,
  "content": "Not executed: an earlier computer action in this turn failed."
}

然后 Claude 会看到哪些操作成功、哪个操作失败以及哪些操作被跳过，并在下一轮重新规划。如果请求中批次内的任何 tool_use 块未得到回答，该请求将被拒绝并返回 invalid_request_error，因此只读取第一个块的智能体循环会在下一次调用时失败。如果您的应用程序要求人工确认有重大影响的操作，请在每个块运行之前进行该检查，因为一个批次可以在一轮内完成多步操作。

Claude 通常以 screenshot 结束一个批次，以便在决定下一步做什么之前观察结果。当批次没有以截图结束时，您的应用程序可以将截图作为额外的 image 块附加到批次中的最后一个结果上，这样 Claude 始终能看到屏幕的当前状态，与等待 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 容器内，并配有适当的端口映射，用于查看环境并与之交互。

如何实现计算机使用

要升级现有的 computer_20251124 集成？请从从 computer_20251124 迁移开始；本节的其余部分同时适用于新集成和已迁移的集成。

理解智能体循环

计算机使用的核心是"智能体循环"：一个 Claude 请求工具操作、您的应用程序运行它们并将结果返回给 Claude 的循环。该循环使用您在快速开始中创建的客户端、一个仅声明计算机使用工具集的 tools 数组，以及实现计算机使用工具下的工具调用处理辅助函数。如果您还声明了其他工具，例如快速开始中的 bash 和文本编辑器工具，请在同一遍处理中分派它们的 tool_use 块；该辅助函数仅回答计算机使用成员调用，并且循环会将没有已回答调用的轮次视为已完成。以下是一个简化示例：

def sampling_loop(model: str, messages: list[MessageParam], max_iterations: int = 10):
    """
    Run the computer-use agent loop until Claude stops requesting tools
    or the iteration limit is reached.
    """
    for _ in range(max_iterations):
        response = client.messages.create(
            model=model,
            max_tokens=4096,
            messages=messages,
            tools=TOOLS,
        )

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

        # 按顺序执行 Claude 请求的操作，并收集结果
        tool_results = process_tool_calls(response)
        if not tool_results:
            return messages  # No more tool use; task complete

        # 在单条用户消息中将所有结果发回给 Claude
        messages.append({"role": "user", "content": tool_results})

    return messages

循环会一直持续，直到 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. 如果您需要模型登录，请在提示中将用户名和密码放在诸如 <robot_credentials> 之类的 XML 标签内提供给它。在需要登录的应用程序中使用计算机使用会增加因提示注入而导致不良结果的风险。在向模型提供登录凭据之前，请查阅缓解越狱和提示注入。
6. 在构建用户轮次的 content 数组时，请将指令文本放在截图图像之前。在处理图像之前提供目标描述可以提高点击准确性。
7. 当被问及在截图默认分辨率下难以辨认的小文本或特定 UI 元素（例如侧边栏中的文件名、标签页标题、状态栏文本、行号或按钮标签）时，Claude 会使用 zoom 操作以全分辨率检查某个区域。如果 Claude 没有在您期望的时候进行缩放，请询问特定的区域或元素，而不是整个屏幕。
8. 如果您希望每个批量操作都以截图结束，请在系统提示中说明，例如：End each group of actions with a screenshot so you can verify the result before continuing.

系统提示

当您在请求中包含计算机使用工具时，API 会生成一个特定于计算机使用的系统提示。它类似于工具使用系统提示，但以如下内容开头：

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 参数仍然会被遵循，并用于构建组合后的系统提示。

可用操作

每个操作都是计算机使用工具集的一个成员工具：Claude 在携带 "toolset_name": "computer" 的 tool_use 块中指定成员名称，并且该块的 input 仅包含该成员的参数，没有 action 字段。该工具集有 17 个成员工具：

在实现这些成员时，请记住以下几点：

• 坐标以截图像素为单位。 每个 coordinate、start_coordinate 和 region 值，以及 cursor_position 报告的位置，都位于您返回的全显示器截图的像素空间中，原点在左上角。缩放图像不会改变这一点：在 zoom 之后，Claude 仍然以完整截图的空间表示坐标，而绝不会相对于缩放后的图像。如果您在返回截图之前将其缩小，请在将 Claude 的坐标应用到真实显示器之前将其放大回去（请参阅调整截图大小以符合图像限制）。
• 所有成员默认启用，包括 zoom。 如果您的环境无法生成缩放图像，请使用 configs 禁用该成员（请参阅工具参数），而不是让它保持启用并返回错误。如果 Claude 调用了您已禁用或未实现的成员，请为该块返回带有 is_error: true 的 tool_result。
• 根据（toolset_name，name）这一对进行分派。 toolset_name 是将一个块标记为计算机操作的依据：同一请求中的自定义工具可能与某个成员同名，并且更高版本的工具集可能会添加成员（请参阅客户端工具集）。

{
  "type": "tool_use",
  "id": "toolu_01Qg8m3XqC5aRy7tD2eS4jUg",
  "name": "left_click",
  "toolset_name": "computer",
  "input": { "coordinate": [500, 300], "text": "shift" }
}

{
  "type": "tool_use",
  "id": "toolu_01Ed6j9VnA3yPw5rB8cQ2gSe",
  "name": "left_click_drag",
  "toolset_name": "computer",
  "input": {
    "start_coordinate": [200, 300],
    "coordinate": [600, 300]
  }
}

{
  "type": "tool_use",
  "id": "toolu_01Yc5h8UmZ2xNv4qA7bP9fRd",
  "name": "scroll",
  "toolset_name": "computer",
  "input": {
    "coordinate": [500, 400],
    "scroll_direction": "down",
    "scroll_amount": 3
  }
}

{
  "type": "tool_use",
  "id": "toolu_01Sb4g7TkY9wLu3pX6zM8eQc",
  "name": "key",
  "toolset_name": "computer",
  "input": { "text": "Tab", "repeat": 4 }
}

{
  "type": "tool_use",
  "id": "toolu_01Kf7k2WpB4zQx6sC9dR3hTf",
  "name": "zoom",
  "toolset_name": "computer",
  "input": { "region": [100, 200, 400, 350] }
}

{
  "type": "tool_use",
  "id": "toolu_01Ekh3vqB6yTs2mNc4Rw8pLd",
  "name": "cursor_position",
  "toolset_name": "computer",
  "input": {}
}

工具参数

tools 数组中的工具集条目接受四个参数；它们与浏览器使用工具集共享的规则列在客户端工具集下。

例如，此条目为未实现 zoom 的环境禁用了该成员，并在工具集定义处设置了缓存断点：

{
  "type": "computer_toolset_20260801",
  "configs": {
    "zoom": { "enabled": false }
  },
  "cache_control": { "type": "ephemeral" }
}

如果您的智能体循环每次往返只能运行一个操作，请在 tool_choice 中将 disable_parallel_tool_use 设置为 true；这样 Claude 每轮最多返回一个成员 tool_use 块（请参阅禁用并行工具使用）。

该条目拒绝来自较早工具版本的以下参数，包含其中任何一个的请求都会返回 invalid_request_error：

• name：成员名称由工具集版本固定。
• display_width_px、display_height_px 和 display_number：坐标始终位于您返回的截图的像素空间中。
• enable_zoom：zoom 是一个您通过 configs 控制的成员工具。

该条目也不能与 computer_20251124 条目或另一个名为 computer 的工具在同一请求中声明。有关 strict、input_examples、defer_loading 的放置位置、tool_choice、流式传输和调用方限制，请参阅客户端工具集。

与思考结合使用

要将计算机使用与思考结合使用，请参阅思考。

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

要在计算机使用之外添加其他工具，请将它们包含在同一个 tools 数组中。快速开始部分通过 bash 工具和文本编辑器工具展示了这种模式。您可以用同样的方式添加自己的自定义工具定义。

对于停留在网页内部的任务，您还可以在同一请求中声明浏览器使用工具：这两个工具集独立工作，各自使用自己的坐标系，对同名成员（例如 screenshot 或 key）的调用通过 toolset_name 加以区分。

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

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

• 一个适合 Claude 进行计算机使用的虚拟化或容器化环境
• 计算机使用工具操作的实现
• 一个与 Claude API 交互并使用您的工具实现运行 tool_use 结果的智能体循环
• 一个允许用户输入以启动智能体循环的 API 或 UI

实现计算机使用工具

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

1. 1

   设置您的计算环境

   创建一个虚拟显示器或连接到 Claude 将与之交互的现有显示器。这通常涉及设置 Xvfb（X Virtual Framebuffer）或类似技术。

2. 2

   实现操作处理程序

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

   PythonTypeScriptC#GoJavaPHPRuby

   

   # 占位图像数据；真实的执行器会捕获屏幕并返回 PNG 字节
   PLACEHOLDER_PNG = "iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mNkYPhfDwAChwGA60e6kgAAAABJRU5ErkJggg=="
   
   
   def capture_screenshot() -> list[ImageBlockParam]:
       # screenshot 以图像块而非文本作答：返回结果内容列表
       return [
           {
               "type": "image",
               "source": {"type": "base64", "media_type": "image/png", "data": PLACEHOLDER_PNG},
           }
       ]
   
   
   def click(coordinate=None):
       if coordinate is None:
           return "clicked at current cursor"
       x, y = coordinate
       return f"clicked at ({x}, {y})"
   
   
   def type_text(text):
       return f"typed: {text}"
   
   
   def handle_computer_action(name, tool_input):
       if name == "screenshot":
           return capture_screenshot()
       elif name == "left_click":
           # coordinate 为可选项；若未提供，则在光标当前位置点击
           return click(tool_input.get("coordinate"))
       elif name == "type":
           return type_text(tool_input["text"])
       # 按需处理其他操作
       raise ValueError(f"Unknown or unimplemented member: {name}")

3. 3

   处理 Claude 的工具调用

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

   PythonTypeScriptC#GoJavaPHPRuby

   

   NOT_EXECUTED = "Not executed: an earlier computer action in this turn failed."
   
   
   def process_tool_calls(response: Message) -> list[ToolResultBlockParam]:
       """
       Run the computer actions in Claude's response in order and answer each
       one. After the first failure the rest are skipped, because Claude planned
       them assuming the earlier actions succeeded.
       """
       tool_results: list[ToolResultBlockParam] = []
       failed = False
       for block in response.content:
           # 仅声明了 computer 工具集；如添加其他工具，请在此处路由
           if block.type != "tool_use" or block.toolset_name != "computer":
               continue
           result: ToolResultBlockParam = {
               "type": "tool_result",
               "tool_use_id": block.id,
               "toolset_name": "computer",
           }
           if failed:
               result["content"] = NOT_EXECUTED
               result["is_error"] = True
           else:
               try:
                   # 字符串，或内容块列表（例如截图图像）
                   result["content"] = handle_computer_action(block.name, block.input)
               except Exception as err:
                   result["content"] = f"Error: {err}"
                   result["is_error"] = True
                   failed = True
           tool_results.append(result)
       return tool_results

4. 4

   实现智能体循环

   将前两个步骤包装在一个循环中，该循环将结果发送回去并重复执行，直到 Claude 不再返回成员工具调用；理解智能体循环展示了每种语言的该循环。

处理错误

将失败的操作以带有 is_error: true 和简短描述的 tool_result 报告给 Claude，并像任何其他成员结果一样包含 "toolset_name": "computer"。如果失败的操作是批量操作的一部分，请使用该处所示的中止文本回答批次中的其余块，而不是运行它们。

例如，当截图捕获失败时：

{
  "role": "user",
  "content": [
    {
      "type": "tool_result",
      "tool_use_id": "toolu_01A09q90qw90lq917835lq9",
      "toolset_name": "computer",
      "content": "Error: Failed to capture screenshot. Display may be locked or unavailable.",
      "is_error": true
    }
  ]
}

对于超出显示器边界的坐标以及运行失败的操作，请使用相同的形式，并附上说明出错原因的消息。

调整截图大小以符合图像限制

您返回给计算机使用工具集的截图和缩放图像必须已经符合您模型的图像大小限制：该工具集不接受显示器尺寸，API 也不会为您缩小图像，因此过大的 tool_result 图像会因验证错误而被拒绝。由于 Claude 以其所见图像的像素空间返回坐标，请保留您使用的缩放因子，以便将这些坐标映射回您的屏幕。

如果您的屏幕大于限制，请在返回每张截图之前调整其大小，并将 Claude 返回的坐标缩放回原始屏幕空间。由于该工具集不接受显示器尺寸，您只需在应用程序代码中进行调整大小和坐标缩放即可：

import math

screen_width, screen_height = 1512, 982


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)


# 捕获屏幕截图时
scale = get_scale_factor(screen_width, screen_height)
scaled_width = int(screen_width * scale)
scaled_height = int(screen_height * scale)

# 在发送给 Claude 之前，将图像调整为缩放后的尺寸
screenshot = capture_and_resize(scaled_width, scaled_height)


# 处理 Claude 返回的坐标时，将其按比例放大还原
def execute_click(x, y):
    screen_x = x / scale
    screen_y = y / scale
    perform_click(screen_x, screen_y)

当您选择显示分辨率并返回截图时：

• 对于一般桌面任务，使用 1024x768 或 1280x720；对于 Web 应用程序，使用 1280x800 或 1366x768。
• 避免使用高于 1920x1080 的分辨率，以防止性能问题。
• 将截图编码为 base64 PNG 或 JPEG，并考虑压缩大型截图以提高性能。
• 包含相关元数据，例如时间戳或显示状态。
• 如果您使用更高的分辨率，请确保坐标得到准确缩放。

管理截图历史

长时间运行的智能体循环会快速累积截图（每张大约 1,000–1,800 个输入令牌）。API 的请求限制同样适用。一旦单个请求携带超过 20 张图像，其中的每张图像都会受到更严格的单边尺寸限制。保留截图历史的循环会在几十轮之内达到该数量，因此要么调整每张截图的大小使任一边都不超过 2000 px，要么修剪较旧的截图，使请求中保留 20 张或更少。

要在限制上下文的同时保持 prompt caching（提示缓存）的有效性：

• 在系统提示和工具定义之后放置一个 cache_control 断点，并在最近几轮中每一轮的最后一个 tool_result 块上再放置最多三个断点，每轮向前推进。在批量操作中，多个块上的标记作为单个断点起作用，但每个标记仍计入四个断点的上限，因此每轮使用一个。
• 批量修剪旧截图，而不是每轮修剪一张。每轮丢弃一张截图会使前缀每轮都发生变化，从而使缓存失效。一个合理的默认做法是保留最后三张截图并每 25 轮修剪一次，这样前缀在两次修剪事件之间保持字节级一致；如果您的截图任一边超过 2000 px，请选择一个能使每个请求保持在 20 张或更少图像的间隔。
• 在 Claude Fable 5.1 上，避免在客户端进行修剪：移除较早的截图会使仍携带这些轮次的每个请求中之后的每个思考块失效。请改为将截图调整为每边 2000 px 或更小，并使用服务器端的工具结果清除从上下文中丢弃旧截图。如果您必须修剪，请从那时起保持设置 prefix_mismatch_behavior: "drop_block"；每次修剪后，Claude 会在该请求及之后的每个请求中，在没有自被修剪截图以来所产生的思考内容的情况下继续。

诊断点击问题

如果点击未命中目标，原因通常是以下之一：

遵循实现最佳实践

def click_and_wait(x, y, wait_time=0.5):
    click_at(x, y)
    time.sleep(wait_time)  # Allow UI to update

display_width, display_height = 1024, 768


def validate_action(action_type, params):
    if action_type == "left_click" and "coordinate" in params:
        x, y = params["coordinate"]
        if not (0 <= x < display_width and 0 <= y < display_height):
            return False, "Coordinates out of bounds"
    return True, None

import logging


def log_action(action_type, params, result):
    logging.info(f"Action: {action_type}, Params: {params}, Result: {result}")

从 computer_20251124 迁移

从 computer_20251124 升级到工具集是可选的：较早的工具版本下为 computer_20251124 列出的模型会继续接受它及其 beta 标头，因此现有集成在您更改之前会继续工作。要升级，请一并进行以下更改：

1. 移除 beta 标头。 从您的请求中删除 anthropic-beta: computer-use-2025-11-24。在 SDK 中，移除 betas 参数，并通过标准客户端而非 beta 命名空间调用 Messages API。
2. 更改 tools 条目。 将 type 设置为 computer_toolset_20260801，并删除 name、display_width_px、display_height_px、display_number 和 enable_zoom。工具集会拒绝这些字段中的每一个。
3. 选择是否保持启用缩放。 工具集默认启用缩放，而 enable_zoom 默认为 false。如果您的环境未实现缩放，请添加 "configs": {"zoom": {"enabled": false}} 以保持之前的行为；否则请实现它（请参阅可用操作）。
4. 处理一轮中的每个块。 更新您的智能体循环，使其遍历响应中的每个 tool_use 块而不是只读取第一个，并根据块的 name 结合 toolset_name 进行分派，而不是根据 input.action。成员输入不再包含 action 字段；其余字段保持不变。
5. 按顺序运行块并使用中止文本。 按顺序运行各块，在第一次失败时停止，并按照批量操作中的描述，用 Not executed: an earlier computer action in this turn failed. 回复剩余的块。如果您的循环尚无法运行批量操作，工具参数说明了如何将 Claude 限制为每轮一个操作。
6. 在结果中回显 toolset_name。 在回复成员调用的每个 tool_result 中添加 "toolset_name": "computer"。结果只能包含 text 和 image 内容。
7. 在 key 上支持 repeat。 key 成员接受一个可选的 repeat 计数，范围为 1 到 100。忽略未识别字段的处理程序只会按一次键，因此请让您的 key 处理程序遵循 repeat。
8. 自行调整截图大小。 工具集会拒绝超出模型图像限制的截图或缩放图像，而不是将其缩小。请在返回图像之前调整大小，并按照调整截图大小以符合图像限制中的描述继续缩放坐标。
9. 移除不支持的选项。 将条目中的任何 defer_loading 移入 configs，并在每个启用的成员上使用相同的值。工具集条目不支持的其他选项列在客户端工具集下。

这是更改前的 tools 条目，随 anthropic-beta: computer-use-2025-11-24 标头一起发送：

{
  "type": "computer_20251124",
  "name": "computer",
  "display_width_px": 1024,
  "display_height_px": 768,
  "display_number": 1
}

这是更改后的 tools 条目，发送时不带 beta 标头。configs 对象保持缩放关闭，以匹配未设置 enable_zoom 的较早条目；完全省略 configs 即可接受默认值并允许 Claude 缩放：

{
  "type": "computer_toolset_20260801",
  "configs": {
    "zoom": { "enabled": false }
  }
}

以下一对示例展示了更改前后的 tool_use 块。操作名称从 input.action 移至 name，并且该块新增了 toolset_name：

{
  "type": "tool_use",
  "id": "toolu_01A9r5kQm2LxWc7vT3nZ4bJs",
  "name": "computer",
  "input": { "action": "left_click", "coordinate": [500, 300] }
}

{
  "type": "tool_use",
  "id": "toolu_01A9r5kQm2LxWc7vT3nZ4bJs",
  "name": "left_click",
  "toolset_name": "computer",
  "input": { "coordinate": [500, 300] }
}

较早的工具版本

计算机使用工具的两个较早版本仍以 beta 形式提供，适用于现有集成、不支持工具集的模型，以及工具集当前不可用的平台。每个版本都要求在每个请求上附带其 beta 标头，其参数记录在 beta Messages API 参考中。在 SDK 中，通过 betas 参数传递标头并使用 beta 命名空间；只有计算机使用工具需要该标头，同一请求中的 bash 或文本编辑器工具不需要。

限制

1. 延迟（Latency）： 当前人机交互中的计算机使用延迟与常规的人类直接操作计算机相比可能过慢。请专注于在受信任环境中速度不关键的用例（例如，后台信息收集、自动化软件测试）。
2. 计算机视觉的准确性和可靠性： Claude 在生成操作时输出特定坐标时可能会出错或产生幻觉。Claude 的摘要思考输出可以帮助您理解模型的推理并识别潜在问题；请在思考配置上设置 display: "summarized"，因为支持工具集的模型默认省略思考文本。
3. 工具选择的准确性和可靠性： Claude 在生成操作时选择工具时可能会出错或产生幻觉，或采取意外的操作来解决问题。此外，在与小众应用程序或同时与多个应用程序交互时，可靠性可能较低。在请求复杂任务时请仔细地向模型提供提示。
4. 滚动可靠性： 滚动操作支持方向控制（上、下、左、右）和指定的滚动量。在滚动不生效的应用程序中，Page Down 等键盘替代方式可能有所帮助。
5. 电子表格交互： 使用细粒度的鼠标控制操作（left_mouse_down、left_mouse_up）和修饰键组合来选择单个单元格。复杂的电子表格操作可能仍需要多次尝试。
6. 在社交和通信平台上创建账户和生成内容： 尽管 Claude 会访问网站，但其在社交媒体网站和平台上创建账户、生成和分享内容或以其他方式进行人类冒充的能力是有限的。
7. 漏洞： 越狱和提示注入可能会影响计算机使用，正如它们可能影响任何前沿 AI 系统一样，包括通过嵌入在网页或图像中的指令；请应用安全注意事项中的预防措施。
8. 不当或非法操作： 根据 Anthropic 的服务条款，您不得利用计算机使用来违反任何法律或可接受使用政策。

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

数据保留

计算机使用是一种客户端工具。会话中涉及的所有截图、鼠标操作、键盘输入和任何文件都在您的环境中捕获和存储，而非由 Anthropic 存储。Anthropic 作为 API 调用的一部分实时处理截图图像和操作请求。这些 API 请求的保留受 API 和数据保留约束。

由于您的应用程序控制计算机使用数据的存储位置和方式，计算机使用符合 ZDR 资格。有关所有功能的 ZDR 资格，请参阅 API 和数据保留。

定价

计算机使用遵循标准的工具使用定价。使用计算机使用工具时：

工具集定义开销： 声明 computer_toolset_20260801 及其默认成员会为请求增加约 4,500 个输入令牌（在 Claude Fable 5、Claude Mythos 5、Claude Opus 5 和 Claude Opus 4.8 上约为 4,520 个，在 Claude Sonnet 5 上约为 4,590 个），其中涵盖了成员工具定义和工具使用系统提示。通过 configs 禁用 zoom 可减少其中约 410 个令牌。请求的确切数量会在响应的 usage 中报告，您也可以使用令牌计数端点提前进行估算。

早期工具版本： 以下数据适用于 computer_20251124 和 computer_20250124 工具版本，不适用于 computer_toolset_20260801：

• 系统提示开销：向系统提示中添加 466–499 个令牌
• 工具定义：每个工具定义约 735 个输入令牌（使用 computer_20250124 测量）

额外令牌消耗：

• 工具结果中返回的屏幕截图和缩放图像，按图像输入计费（请参阅视觉定价）
• 返回给 Claude 的工具执行结果

后续步骤

Compatibility