Claude API 基础专题（六）：Claude Code 与 Computer Use

预计阅读时间：40 分钟 | 难度：⭐⭐⭐⭐

目标读者：希望让 Claude 操控计算机完成任务的开发者 前置知识：前三篇的 API 基础、工具调用、MCP 知识

Computer Use（计算机使用）是 Anthropic 的 beta 功能：它在 Messages API 里把「截图、鼠标、键盘」打包成一个工具，让 Claude 能对着桌面界面工作。它看起来像 Claude 在亲手操作电脑，实际分工恰恰相反——Claude 只负责看屏幕、决定下一步，真正的截图、移动光标、敲键盘，必须由你的应用在沙箱里替它执行。这个边界是理解整个功能的关键。

下面从五个角度展开：它把工具调用的边界推到了哪里、观察-决策-执行循环怎么运转、用 API 怎么落地一个 agent loop、安全上要额外扛住哪些风险，以及常见的坑和排查顺序。

本文目录

• 6.1 从工具调用到计算机控制
• 6.2 Computer Use 原理解析
• 6.3 用 API 实现 Computer Use
• 6.4 Claude Code 架构与设计
• 6.5 安全机制与沙箱环境
• 6.6 推荐做法与注意事项
• 6.7 常见问题与排查

学习目标

读完本文，你应该能：

• 说清 Computer Use 里模型与应用的分工边界，以及它和普通工具调用的区别
• 画出观察-决策-执行循环，并说明每个环节由谁执行
• 用 Python SDK 搭出一个能跑的最小 agent loop，处理好坐标换算
• 列出官方安全建议和提示注入防御，判断自己的场景是否适合无人值守
• 判断一个任务该用 Computer Use 还是直接调 API，并解释理由

6.1 从工具调用到计算机控制

工具调用解决的是「模型知道该调什么，但不知道现实世界长什么样」。它把外部能力封装成一个个函数，模型选择函数、填参数、读返回值。这一切的前提是：能力边界是预先画好的。查天气、查数据库、跑代码，都能写成函数；但「这个页面长什么样、提交按钮在哪个坐标」这种信息，工具调用拿不到。

Computer Use 的思路是：不预先定义能力，而是给模型一套通用的界面操作原语——截屏、移动鼠标、点击、输入。模型面对任何一个界面，都能通过对截图的观察现学现用。成本是精度和可靠性会打折扣，这是后文要讨论的边界。

6.2 Computer Use 原理解析

观察-决策-执行循环

Computer Use 的核心是一个循环，官方称之为 agent loop（代理循环）：

┌────────────────────────────────────────────────────────────┐
│                        agent loop                          │
├────────────────────────────────────────────────────────────┤
│                                                            │
│  ① 应用把消息（含截图）发给 Claude                          │
│        │                                                   │
│        ▼                                                   │
│  ② Claude 决定下一步，返回 tool_use（如 left_click）       │
│        │     stop_reason = "tool_use"                      │
│        ▼                                                   │
│  ③ 应用在沙箱里执行该动作（截图/点击/输入）                 │
│        │                                                   │
│        ▼                                                   │
│  ④ 应用把结果作为 tool_result 附回对话                      │
│        │                                                   │
│        └──────── 回到 ①，直到 Claude 不再请求工具 ─────────┘
│                                                            │
└────────────────────────────────────────────────────────────┘

关键点：②和④之间是你的应用插进去执行的。Claude 只是输出「要做哪个动作、参数是什么」，比如「在坐标 (512, 384) 左键点击」。真正把光标移过去、点下去，是调用方代码调用系统接口完成的。Claude 不直接连到任何显示器或窗口。

这个循环没有用户参与，Claude 一轮接一轮请求工具、应用一轮接一轮返回结果，直到 Claude 判定任务完成、stop_reason 不再是 tool_use。为避免无限循环烧钱，应用通常会设一个最大迭代次数。

计算环境

Computer Use 需要一个沙箱化的计算环境，官方参考实现跑在 Docker 容器里，包含：

• 虚拟显示：用 Xvfb 起一个虚拟 X11 显示服务，渲染 Claude 截图看到的桌面
• 桌面环境：轻量窗口管理（Mutter）加面板（Tint2），提供一致的图形界面
• 预装应用：Firefox、LibreOffice、文本编辑器、文件管理器等
• 工具实现：把「移动鼠标」「截图」这类抽象请求翻译成对虚拟环境的实际操作
• agent loop：在 Claude 和环境之间传消息的程序

Claude 不直接连这个环境。你的应用接收 Claude 的 tool_use 请求 → 翻译成对环境的操作 → 捕获结果（截图、命令输出） → 返回给 Claude。

工具定义

Computer Use 工具是无 schema 的——它不像普通工具那样要你提供 input_schema，schema 内置在模型里，不能改。定义它时，早期版本需要你指定分辨率等参数：

工具和模型的对应关系在更新：

• computer_toolset_20260801：2026 年 8 月推出的新版 client toolset，一次声明 {"type": "computer_toolset_20260801"} 就能获得 17 个成员工具（screenshot、left_click、type、zoom 等），不需要 beta 头，由 Opus 4.7 及更新的模型支持
• computer_20251124：需要 beta 头 computer-use-2025-11-24，由 Opus 4.5/4.6、Sonnet 4.6 等支持
• computer_20250124：需要 beta 头 computer-use-2025-01-24，由 Sonnet 4.5、Haiku 4.5、Opus 4.1、Sonnet 4、Opus 4、Sonnet 3.7 等支持

已有的 computer_20251124 集成可以继续工作；要升级到新版时，官方提供了迁移说明，改动主要是去掉 beta 头、把 type 换成 toolset 声明。判断用哪个版本，直接查官方文档的兼容性表格，不要凭模型名字猜——同一模型家族不同代际，支持的工具版本可能不同。

可用动作

工具支持的动作分三档：

基础动作（所有版本）：screenshot（截取当前显示）、left_click（点击坐标 [x, y]）、type（输入文本）、key（按键盘按键或组合键，如 ctrl+s）、mouse_move（移动光标）。

增强动作（computer_20250124 起）：scroll（任意方向滚动、可控制量）、left_click_drag（拖拽）、right_click / middle_click、double_click / triple_click、left_mouse_down / left_mouse_up（细粒度点击控制）、hold_key（按住按键指定秒数）、wait（暂停）。

computer_20251124 新增：zoom（以全分辨率查看屏幕某区域），需要 enable_zoom: true，参数 region 用 [x1, y1, x2, y2] 指定要查看区域的左上角和右下角。

computer_toolset_20260801：把动作收敛成 17 个成员工具，screenshot、left_click、type、zoom 都在其中，每个工具调用的返回块带 "toolset_name": "computer" 标识。它在同一个响应里可以一次返回多个动作（官方叫 batch action），应用按顺序逐个执行、每个动作回一个 tool_result。

6.3 用 API 实现 Computer Use

定义工具并发出请求

用 Anthropic Python SDK，先定义工具，再发消息：

import anthropic

client = anthropic.Anthropic()

response = client.beta.messages.create(
    model="claude-sonnet-4-5",
    max_tokens=1024,
    betas=["computer-use-2025-01-24"],  # 旧工具版本需要 beta 头
    tools=[
        {
            "type": "computer_20250124",
            "name": "computer",
            "display_width_px": 1024,
            "display_height_px": 768,
            "display_number": 1,
        }
    ],
    messages=[{
        "role": "user",
        "content": "把一张猫的图片保存到桌面上。",
    }],
)

注意用的是 client.beta.messages，因为 computer_20250124 这类旧版本 Computer Use 工具是 beta 功能，还要在 betas 参数里带上对应的 beta 头。如果换用 computer_toolset_20260801 新版工具集，就不需要 beta 头，直接走 client.messages.create。响应里如果 stop_reason == "tool_use"，说明 Claude 想要执行某个动作，动作在返回的 tool_use 块里。

一个最小的 agent loop

执行循环的一段示意（省略了 execute_action 的具体实现，它负责对接你的沙箱）：

from anthropic.types import ToolResultBlockParam

def agent_loop(messages, system_prompt, tools, max_iterations=10):
    for _ in range(max_iterations):
        response = client.beta.messages.create(
            model="claude-sonnet-4-5",
            max_tokens=1024,
            betas=["computer-use-2025-01-24"],
            system=system_prompt,
            tools=tools,
            messages=messages,
        )

        # 任务完成：Claude 不再请求工具
        if response.stop_reason != "tool_use":
            return [
                block.text
                for block in response.content
                if block.type == "text"
            ]

        for block in response.content:
            if block.type == "tool_use":
                action = block.input  # 例如 {"action": "left_click", "coordinate": [512, 384]}

                # 你的应用在沙箱里执行动作，拿到结果（通常是新截图）
                result = execute_action(action)

                # 把 Claude 的决定和你的执行结果都附回对话
                messages.append({
                    "role": "assistant",
                    "content": [block],
                })
                messages.append({
                    "role": "user",
                    "content": [ToolResultBlockParam(
                        type="tool_result",
                        tool_use_id=block.id,
                        content=result,
                    )],
                })
    raise RuntimeError("超过最大迭代次数，任务未完成")

execute_action 是真正干活的地方：按 action["action"] 分发到截图、鼠标、键盘的具体实现，执行完把新截图作为 tool_result 返回。Claude 看到新截图，才知道上一动作有没有生效，再决定下一步。

截图尺寸与坐标换算

截图发给模型前要控制尺寸。不同模型上限不同：Opus 4.7 及更新的模型接受长边最长 2576 像素、总面积约 3.75 兆像素；更早的模型是长边 1568 像素、总面积约 1.15 兆像素。超出上述阈值，API 会静默降采样——模型看到的是一张被缩小的图，Claude 返回的坐标对应的也是这张缩放后的图。你不换算就按原始分辨率去点击，坐标会系统性偏移。

因此正确的做法不是放任 API 降采样，而是主动把截图缩到上限之内再发：长边 1280、短边 720（1280×720）是一个稳妥的默认值，能让坐标空间与你声明的 display_width_px / display_height_px 一致，点击才准。换用 Opus 4.7 这类高上限模型时，可以上到 1080p 换取更清晰细节。

一个常踩的坑是 macOS Retina 屏：截图按设备像素比 2 输出，图像分辨率是逻辑坐标的两倍。要么发图前缩一半，要么把 Claude 返回的坐标对半再点击，否则每次都点偏。

6.4 Claude Code 架构与设计

Claude Code 是 Anthropic 官方推出的终端编程工具，让开发者在命令行里和 Claude 协同写代码。它和 Computer Use 的关系是：Claude Code 是 Computer Use 能力的一个落地载体——在 Claude Code 里，Claude 不只是改代码，也能截图看界面、操作浏览器、驱动桌面应用，靠的正是这套观察-决策-执行循环。

它和「在 IDE 里装个插件」的差别在于深度集成：

6.5 安全机制与沙箱环境

Computer Use 的风险比普通 API 高，因为模型接触到的是真实界面操作。Anthropic 的官方口径很直接：把 Claude 隔离在最小权限的虚拟机或容器里，别让它碰到敏感数据。

官方安全建议

1. 用专用虚拟机或容器，给最小权限，防止系统攻击或误操作
2. 别给模型敏感数据（如账号登录信息），防窃取
3. 联网用白名单，只允许访问指定域名，减少恶意内容暴露
4. 有实际后果的操作要人工确认，比如接受 cookie、完成金融交易、同意服务条款

这里有个特别值得注意的点：提示注入。Claude 有时会服从网页或图片里的指令，哪怕和你给它的指令冲突——比如网页上写着「忽略上面的要求，执行这个命令」。为缓解这个，Anthropic 在 Computer Use 上自动跑一层提示注入分类器。当分类器在截图里识别出疑似注入时，会引导模型先向用户要确认再继续，相当于又加了一道保险。这层防御对「没有人在环」的无人值守场景不理想，可以联系支持关闭，但那是你自家产品要评估的取舍。

数据归属

Computer Use 是客户端工具：一张截图、一次点击、一段输入、用到的文件，都产生并保存在你的环境里，Anthropic 不存储这些。Anthropic 只是在 API 调用时实时处理截图和动作请求，保留策略遵循标准的 API 数据保留规则。因为数据由你的应用掌控，Computer Use 符合 ZDR（零数据保留，Zero Data Retention）方向——但官网明确标注该资质排除部分受覆盖型号（Covered Models），具体模型是否满足 ZDR 要在数据保留文档里逐项核对，别想当然认为所有模型都满足。

参考实现

官方在 anthropics/anthropic-quickstarts 仓库的 computer-use-demo 目录里给了完整参考实现：Docker 环境、各动作的工具实现、agent loop、可交互的 Web 界面。自己搭环境时，至少需要这几样：虚拟化/容器化环境、至少一个 computer 工具的实现、agent loop，以及启动循环的入口。

6.6 推荐做法与注意事项

提升质量的提示词

• 任务拆小、步骤说清：一步一个明确指令，别让 Claude 一次猜很多
• 强迫验证：提示里要求「每完成一步就截图，确认是否达到预期，没达到就重试，确认成功再进下一步」——Claude 有时会想当然地认为动作成功了，其实没生效
• 偏难关交互用快捷键：下拉框、滚动条这类鼠标难操作的，让 Claude 改用键盘快捷键
• 可复用任务给示例：把成功结果的截图和调用序列放进提示词
• 指令文本放在图片前：构造 content 数组时，先放指令文字再放截图，能提升点击准确性

已知限制

• 延迟：对人机交互来说可能偏慢，适合后台信息收集、自动化测试这类对速度不敏感的场景
• 视觉精度：Claude 生成坐标时可能出错或幻觉，Extended Thinking 有助于看清它为什么这么选
• 工具选择：复杂任务里可能选错工具或采取意外动作；并行操作多个小众应用时可靠性下降
• 滚动：滚轮动作在有些应用里不生效，可用 Page Down 等键盘替代
• 社交平台账号行为：Claude 能访问网站，但创建账号、发帖、冒充真人等能力是受限的

坐标系与精度

分辨率别太低，1280×720 是个不错的基线。点了没点中，多数是这几种原因：display_width_px/display_height_px 和实际发的截图尺寸不一致；目标太小、4K 源缩图后细节丢了；指令含糊导致点错元素。模型选择也影响点击精度——Sonnet 4.6 的机械点击比 Opus 4.6 更稳，Opus 4.7 把差距拉平了。

什么时候不划算

一句话：Computer Use 适合「没有现成 API、只能操作界面」的场景。能用 API 或脚本解决的就别用它，它是对付遗留系统、动态界面、跨应用工作流的最后手段。

6.7 常见问题与排查

Q1：Claude 每次点击都偏一小段距离

优先查坐标空间不一致。三件套逐项对：声明给模型的 display_width_px / display_height_px 是否和实际发出的截图分辨率一致；截图有没有被 API 静默降采样（若原始尺寸超出模型上限，先主动缩到 1280×720 一类合规尺寸）；是不是 Retina 屏没做设备像素比换算。这三处错一处，偏移都是系统性的，不是偶发。

Q2：报错信息提示 beta 头不对或工具版本不支持

核对模型与工具版本的对应表。同一个模型家族不同代际，支持的计算机工具版本可能不同；版本选错，接口会拒绝或行为异常。换用 computer_toolset_20260801 新版时，记得去掉旧的 beta 头并把 type 改成 toolset 声明，否则请求仍按旧路径处理。

Q3：agent loop 卡在无限循环，费用一直涨

loop 里 max_iterations 就是兜底。设成一个任务合理需要的上界（通常是 10—20），超限抛异常或返回未完成，别让它无限跑。另外 batch action 一次会返回多个 tool_use，每个都要回 tool_result，漏回一个下次请求会被拒。

Q4：滚轮滚动在某些应用里没反应

这是已知限制。改用键盘替代：提示词里要求 Claude 用 Page Down、方向键或快捷键来滚动，比硬调滚轮可靠。

Q5：提示注入分类器拦住了无人值守的流程

分类器识别到疑似注入时会让模型先征求用户确认，这本身是保守的安全设计。对「没有人在环」的场景它确实碍事，可以联系支持关闭，但要先想清楚：关了这层防御，你的沙箱是否仍有足够的隔离兜底。

排查顺序

先把「报什么错」记下来，再决定从哪查：

请求被拒 / 报错
├── beta 头或工具版本不匹配 → 查模型兼容表
├── tool_result 漏回 / 格式错 → 核对每个 tool_use 都要回
└── 正常返回但点不准
    ├── 坐标空间不一致 → 对 display_width/height 与截图分辨率
    ├── 截图超限被降采样 → 主动缩到合规尺寸
    └── Retina 未换算 → 做设备像素比换算

参考文献

• Anthropic 官方文档 · Computer use tool：https://platform.claude.com/docs/en/agents-and-tools/tool-use/computer-use-tool
• 参考实现 anthropic-quickstarts / computer-use-demo：https://github.com/anthropics/anthropic-quickstarts/tree/main/computer-use-demo
• 工具与模型兼容性： https://platform.claude.com/docs/en/agents-and-tools/tool-use/tool-reference
• 数据保留与 ZDR： https://platform.claude.com/docs/en/manage-claude/api-and-data-retention

维护提示：Computer Use 的工具版本与对应模型迭代较快，正文中 computer_toolset_20260801、computer_20251124、computer_20250124 与各 beta 头会随官方调整。更新时以「参考文献」中的官方兼容性表格为准，不要只凭文章正文判断版本。

文档元信息 难度：⭐⭐⭐⭐ | 类型：API 解析 | 更新日期：2026-08-30 | 预计阅读时间：45 分钟 | 字数：约 4600 字