计算机使用工具

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

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

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

有关支持该工具集的模型和平台，请参阅 API 支持。较早的工具版本列出了每个较早版本的 beta 标头以及可搭配使用的模型。

安全注意事项

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

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

Anthropic 已训练模型抵御这些提示注入，并增加了一层额外的防御。如果您使用计算机使用工具，分类器会自动扫描工具返回的内容（例如截图），以标记潜在的提示注入。当这些分类器识别出潜在的提示注入时，它们会引导模型在执行指令之前先确认该指令是否确实来自您。

这种额外保护并不适用于所有用例（例如没有人工参与的用例），因此如果您希望选择退出并将其关闭，请联系支持团队。即使有这些分类器，前面列出的预防措施仍然很重要。

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

快速入门

将计算机使用工具集以 {"type": "computer_toolset_20260801"} 的形式添加到 Messages API可查看包含 API 参考文档链接的预览——按 Tab 键直到焦点进入卡片，按 Escape 键返回。 请求的 tools 数组中。该请求不需要 beta 标头。此示例还声明了文本编辑器工具和 bash 工具，Claude 通常会将它们与计算机使用一起使用：

client = anthropic.Anthropic()

response = client.messages.create(
    model="claude-opus-5-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-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 有时会在没有明确检查结果的情况下假定其操作已成功。为防止这种情况，您可以使用以下提示：After each step, take a screenshot and carefully evaluate if you have achieved the right outcome. State in one sentence what the screenshot shows and whether the step succeeded. If it didn't, 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. 如果您需要模型登录，请在提示中将用户名和密码放在 XML 标签（例如 <robot_credentials>）内提供给模型。在需要登录的应用程序中使用计算机使用，会增加因提示注入而导致不良结果的风险。在向模型提供登录凭据之前，请查看缓解越狱和提示注入。
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：缩放是一个您通过 configs 控制的成员工具。

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

与思考结合使用

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

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

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

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

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

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

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

实现计算机使用工具

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

1. 1

   设置您的计算环境

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

2. 2

   实现操作处理程序

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

   PythonTypeScriptC#GoJavaPHPRuby

   Python

   

   # 占位图像数据；真实的执行器会捕获屏幕并返回 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):
       match name:
           case "screenshot":
               return capture_screenshot()
           case "left_click":
               # coordinate 是可选的；若未提供，则在光标当前位置点击
               return click(tool_input.get("coordinate"))
           case "type":
               return type_text(tool_input["text"])
       # 按需处理其他操作
       raise ValueError(f"Unknown or unimplemented member: {name}")

3. 3

   处理 Claude 的工具调用

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

   PythonTypeScriptC#GoJavaPHPRuby

   Python

   

   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 张图像，其中的每张图像都将受到更严格的单边尺寸限制。保留截图历史的循环会在几十轮内达到该数量，因此请调整每张截图的尺寸以保持在该限制之内，或者修剪较早的截图，使请求中保留 20 张或更少。

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

• 在系统提示和工具定义之后放置一个 cache_control 断点，并在最近几轮中每一轮的最后一个 tool_result 块上最多再放置三个，每轮向前推进这些断点。在一次批量操作中，多个块上的标记会作为单个断点生效，但每个标记仍计入四个断点的限制，因此任何一轮中最多使用一个。
• 请分批修剪旧截图，而不是每轮修剪一张。每轮丢弃一张截图会使前缀每轮都发生变化，从而使缓存失效。一个合理的默认做法是保留最后三张截图，并每 25 轮修剪一次，这样在两次修剪之间前缀保持字节级一致；如果您的截图超出了更严格的限制，请选择一个能使每个请求保持 20 张或更少图像的间隔。
• 在 Claude Fable 5.2、Claude Mythos 5.2、Claude Fable 5.1、Claude Mythos 5.1、Claude Opus 5.5、Claude Sonnet 5.5 和 Claude Haiku 5.5 上，请避免在客户端进行修剪：从请求中移除较早的屏幕截图会使该请求以及之后每个请求中所有后续的思考块失效。请改为调整屏幕截图大小以保持在更严格的限制之内，并使用服务器端的工具结果清除功能从上下文中删除旧的屏幕截图。如果您必须进行修剪，请从此以后一直设置 prefix_mismatch_behavior: "drop_block"；每次修剪后，Claude 会在该请求及之后的每个请求中，在不包含自被修剪的屏幕截图以来所产生的思考的情况下继续。在 Claude Sonnet 5.5 和 Claude Haiku 5.5 上，block_binding 仅适用于 thinking: {"type": "adaptive"}。在这些模型上使用任何其他思考设置时，请保持历史记录仅追加，或者删除被修剪的屏幕截图之后的每个 thinking 和 redacted_thinking 块。

诊断点击问题

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

遵循实现最佳实践

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 的模型（例如 Claude API 上的 Claude 5.5 模型）之前，请先升级该集成。

要进行升级，请同时进行以下更改：

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 的旧条目一致；若要接受默认值并让 Claude 进行缩放，请完全省略 configs：

{
  "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] }
}

较早的工具版本

“Computer use”（计算机使用）工具有两个较早的版本以 beta 形式提供。每个版本都需要在每个请求中包含其 beta 标头，其参数记录在 beta Messages API 参考可查看包含 API 参考文档链接的预览——按 Tab 键直到焦点进入卡片，按 Escape 键返回。中。使用 SDK 时，请通过 betas 传递该标头并使用 beta 命名空间；只有计算机使用工具需要该标头，同一请求中的 bash 或文本编辑器工具则不需要。

在 Amazon Bedrock 上，Claude Fable 5.2、Claude Mythos 5.2、Claude Opus 5.5、Claude Sonnet 5.5 和 Claude Haiku 5.5 也接受搭配 computer-use-2025-11-24 beta 标头的 computer_20251124 工具。

限制

1. 延迟： 与常规的人工指导计算机操作相比，用于人机交互的计算机使用延迟可能过慢。请在受信任的环境中专注于速度不关键的用例（例如后台信息收集、自动化软件测试）。
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 资格。

定价

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

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

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

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

额外令牌消耗：

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

后续步骤

可用性