claude-quickstarts 之 Computer Use Demo：基于 Claude API 构建可操控电脑桌面的 Agent 循环

claude-quickstarts 之 Computer Use Demo：基于 Claude API 构建可操控电脑桌面的 Agent 循环

【免费下载链接】claude-quickstartsA collection of projects designed to help developers quickly get started with building deployable applications using the Claude API项目地址: https://gitcode.com/GitHub_Trending/an/claude-quickstarts

本指南以仓库中 computer-use-demo/README.md 为骨架，结合 agent 循环源码、Streamlit 界面、工具实现 与 Dockerfile 展开，系统讲解如何通过 Claude API（亦支持 Amazon Bedrock、Google Vertex）在 Docker 容器内运行一个能"看见屏幕、点击鼠标、敲击键盘、执行命令"的 computer use Agent 循环。读完本文，你将掌握完整的环境搭建命令、三种 API 提供方的接入方式、屏幕分辨率与坐标缩放的工程要点，以及工具版本选型（含最新 toolset 形态）的底层原理。

一、项目定位：最小可运行的 Computer Use 参考实现

computer-use-demo是 claude-quickstarts 集合中用于"让 Claude 直接操作电脑"的最小化参考实现，仓库提供四类资产：

• Docker 构建文件：一键构建包含 Xvfb 虚拟显示器、X11 + VNC、Firefox、LibreOffice 等桌面依赖的容器镜像（见 Dockerfile）；
• Computer use agent loop：基于 Claude API / Bedrock / Vertex 的采样循环，负责"调用模型 → 解析工具调用 → 执行工具 → 回传结果"的完整闭环（见 loop.py）；
• Anthropic 定义的 computer use 工具：computer（屏幕/鼠标/键盘）、bash（shell 会话）、edit（基于str_replace_based_edit_tool的文件编辑），全部位于 tools 目录；
• Streamlit 交互应用：提供聊天式控制台与 HTTP 请求日志面板（见 streamlit.py）。

[!TIP] 该 demo 刻意保持"最小、容器化"：它展示的是跑在 Docker 中 Linux 桌面（X11 + VNC）上的核心 agent 循环。若你需要生产级模式——显式工具定义、图像尺寸裁剪与去重、prompt caching、服务端压缩、批处理工具调用、沙箱 shell、轨迹录制等——请参考同一仓库中的 Computer Use Best Practices quickstart，它可在 macOS 上原生运行（无需容器）。

两个重要约束需要先说明：

• Beta 特性：本项目使用的 Beta API 可能随时变更，应持续关注 Anthropic 官方 API 发布说明。
• 弱隔离组件：agent 循环运行在被 Claude 控制的容器内部，同一时刻只能被一个会话使用；会话之间需要重启或重置容器（详见下文"重置机制"）。

二、模型与思考模式：默认 Opus 4.8 + 自适应思考

README 明确指出 demo 默认使用最新模型Claude Opus 4.8（claude-opus-4-8），并配合自适应思考（adaptive thinking）——由模型自行决定推理多少，通过可选的 effort 级别（low/medium/high/max）进行引导。此外 Claude Opus 4.7、Opus 4.6、Sonnet 4.6 同样支持自适应思考；而较老的模型（Opus 4.5、Sonnet 4.5、Sonnet 4、Opus 4、Haiku 4.5）继续使用固定预算的 extended thinking，并依赖str_replace_based_edit_tool。

在 streamlit.py 中，每种模型对应一份ModelConfig，其thinking_modes元组严格声明了该模型支持的思考模式，并按优先级排序（第一个为默认项）：

模型族	工具版本	max_output_tokens	默认输出 tokens	思考模式（按优先级）
Claude 4 系列	computer_use_20250429	64,000	16,384	off, extended
Claude 4.5 系列（含 zoom 版）	computer_use_20250124 / 20251124	128,000 / 64,000	16,384	off, extended
Haiku 4.5	computer_use_20250124	8,192	4,096	off
Opus 4.6 / Sonnet 4.6	computer_use_20251124	128,000	16,384	adaptive, extended, off
Opus 4.7 / Opus 4.8	computer_use_20251124	128,000	16,384	adaptive, off
未识别的模型 ID（回退）	computer_use_20250429	64,000	16,384	off, adaptive, extended

从源码可以确认两个关键事实：

1. Opus 4.7 及更新模型只支持自适应思考，手动指定 thinking budget 会被 API 拒绝；因此 loop.py 在thinking_mode == "adaptive"时发送thinking={"type": "adaptive"}加output_config={"effort": ...}，在extended时才发送thinking={"type": "enabled", "budget_tokens": ...}，而off则不发送任何 thinking 参数。
2. 模型识别采用"精确匹配 + 最长前缀匹配"（_lookup_model_conf，streamlit.py）：对anthropic.claude-sonnet-4-5-20250929-v1:0（Bedrock 形式）或claude-sonnet-4-5@20250929（Vertex 形式）这类带前缀/带日期的 ID，会归一化后按最长已知前缀解析到正确配置，避免落入宽松的默认配置而把不支持的思考模式发给 API。

各 API 提供方的默认模型分别为：Anthropic 使用claude-opus-4-8；Bedrock 使用anthropic.claude-3-5-sonnet-20241022-v2:0；Vertex 使用claude-3-5-sonnet-v2@20241022（见 streamlit.py）。

三、工具版本体系：从单computer工具到computer_toolset_20260801

demo 支持所有已发布日期的 Anthropic computer use 工具版本，可在 Streamlit 侧边栏的 "Tool Versions" 中切换，侧边栏默认选中与当前模型匹配的版本。版本定义集中在 tools/groups.py：

ToolVersion = Literal[ "computer_use_20250124", "computer_use_20241022", "computer_use_20250429", "computer_use_20251124", "computer_toolset_20260801", ]

3.1 最新形态：computer_toolset_20260801（toolset，无需 beta 头）

README 特别说明了最新版本computer_toolset_20260801的结构变化：computer 工具被声明为一个toolset——tools[]中一条无名条目，为每个 computer 动作声明一个成员工具。模型随后把每个动作当作独立工具调用：

• tool_use.name是成员名（left_click、screenshot……）；
• 调用块携带toolset_name: "computer"；
• 输入是该动作的参数集合，不再有action判别字段；
• 每个回答成员调用的tool_result携带相同的toolset_name；
• 同一轮中的成员调用按块顺序串行执行，首个失败即停止；
• toolset 不需要任何anthropic-beta头（GA 形态）。

对应实现见 tools/computer.py：成员集合是固定的 17 个动作（key、hold_key、type、cursor_position、mouse_move、left_mouse_down、left_mouse_up、left_click、left_click_drag、right_click、middle_click、double_click、triple_click、scroll、wait、screenshot、zoom）。toolset 的to_params()返回无名条目{"type": self.api_type}，不携带display_*选项——坐标直接在截图像素帧中交换。toolset 成员语义与computer_20251124的对应动作基本一致，但有三处差异：

• zoom是默认启用的常驻成员（不再需要enable_zoom开关）；
• key接受可选repeat计数（1–100）；
• 指针类成员（点击、拖拽）用text表达按住的修饰键组合（computer_20250124中叫key）。

在 loop.py 中，当某个成员调用失败后，同一轮后续成员调用会被直接以ToolFailure(error=NOT_EXECUTED_ERROR)应答而不执行；tools/collection.py 则按toolset_name路由到对应工具族，并把成员名作为action分发给族实现。

3.2 早期 dated 版本

更早的版本（API 类型computer_20241022至computer_20251124，即侧边栏中的computer_use_*条目）保持单一computer工具 +action参数的形态，并分别携带各自的 beta 头：

工具组版本	computer 工具	beta 头
computer_use_20241022	ComputerTool20241022	computer-use-2024-10-22
computer_use_20250124	ComputerTool20250124	computer-use-2025-01-24
computer_use_20250429	ComputerTool20250124	computer-use-2025-01-24
computer_use_20251124	ComputerTool20251124	computer-use-2025-11-24
computer_toolset_20260801	ComputerToolset20260801	无

各版本的动作集也随日期递增：computer_20241022支持 10 个动作（key、type、mouse_move、left_click、left_click_drag、right_click、middle_click、double_click、screenshot、cursor_position）；computer_20250124新增left_mouse_down、left_mouse_up、scroll、hold_key、wait、triple_click；computer_20251124新增zoom（配合region四元坐标做局部放大，见 computer.py）。模型只支持 toolset 或它训练过的早期 dated 版本之一，具体以官方 computer use 文档中每个模型的受支持版本为准。

四、快速开始：Docker 容器运行

4.1 Claude API（Anthropic 官方入口）

API Key 可在 Anthropic Console 获取。将%your_api_key%替换为真实 Key 后执行：

export ANTHROPIC_API_KEY=%your_api_key% docker run \ -e ANTHROPIC_API_KEY=$ANTHROPIC_API_KEY \ -v $HOME/.anthropic:/home/computeruse/.anthropic \ -p 5900:5900 \ -p 8501:8501 \ -p 6080:6080 \ -p 8080:8080 \ -it ghcr.io/anthropics/anthropic-quickstarts:computer-use-demo-latest

各参数含义：

• -e ANTHROPIC_API_KEY：注入 API Key；
• -v $HOME/.anthropic:/home/computeruse/.anthropic：挂载配置目录，持久化 API Key、自定义系统提示词等设置（详见下文）；
• -p 5900:5900：VNC 直连端口；
• -p 8501:8501：仅 Streamlit 界面；
• -p 6080:6080：noVNC 网页桌面视图；
• -p 8080:8080：聚合界面（聊天 + 桌面视图一体）。

4.2 Bedrock（AWS）

使用 Bedrock 前需在 AWS 侧申请对应模型的访问权限（README 特别提示使用新的 Claude 3.7 Sonnet 需要先请求模型访问），并准备具备相应权限的 AWS 凭证。提供两种认证方式：

方式一（推荐）：复用宿主机的 AWS 凭证文件与 profile

export AWS_PROFILE=<your_aws_profile> docker run \ -e API_PROVIDER=bedrock \ -e AWS_PROFILE=$AWS_PROFILE \ -e AWS_REGION=us-west-2 \ -v $HOME/.aws:/home/computeruse/.aws \ -v $HOME/.anthropic:/home/computeruse/.anthropic \ -p 5900:5900 \ -p 8501:8501 \ -p 6080:6080 \ -p 8080:8080 \ -it ghcr.io/anthropics/anthropic-quickstarts:computer-use-demo-latest

方式二：使用访问密钥与密钥对

export AWS_ACCESS_KEY_ID=%your_aws_access_key% export AWS_SECRET_ACCESS_KEY=%your_aws_secret_access_key% export AWS_SESSION_TOKEN=%your_aws_session_token% docker run \ -e API_PROVIDER=bedrock \ -e AWS_ACCESS_KEY_ID=$AWS_ACCESS_KEY_ID \ -e AWS_SECRET_ACCESS_KEY=$AWS_SECRET_ACCESS_KEY \ -e AWS_SESSION_TOKEN=$AWS_SESSION_TOKEN \ -e AWS_REGION=us-west-2 \ -v $HOME/.anthropic:/home/computeruse/.anthropic \ -p 5900:5900 \ -p 8501:8501 \ -p 6080:6080 \ -p 8080:8080 \ -it ghcr.io/anthropics/anthropic-quickstarts:computer-use-demo-latest

认证校验逻辑在 streamlit.py：Bedrock 路径下若无可用 boto3 凭证，界面会提示先配置 AWS 凭证。

4.3 Vertex（Google Cloud）

Vertex 需要本地先构建镜像，并使用 Google Cloud 应用默认凭证（ADC）：

docker build . -t computer-use-demo gcloud auth application-default login export VERTEX_REGION=%your_vertex_region% export VERTEX_PROJECT_ID=%your_vertex_project_id% docker run \ -e API_PROVIDER=vertex \ -e CLOUD_ML_REGION=$VERTEX_REGION \ -e ANTHROPIC_VERTEX_PROJECT_ID=$VERTEX_PROJECT_ID \ -v $HOME/.config/gcloud/application_default_credentials.json:/home/computeruse/.config/gcloud/application_default_credentials.json \ -p 5900:5900 \ -p 8501:8501 \ -p 6080:6080 \ -p 8080:8080 \ -it computer-use-demo

Vertex 路径的认证校验要求设置CLOUD_ML_REGION环境变量，并通过google.auth.default验证 ADC 凭证。除 ADC 外，也可设置GOOGLE_APPLICATION_CREDENTIALS指向任意凭证文件（详见 Google Cloud 认证文档）。三种提供方统一由API_PROVIDER环境变量切换，loop.py 中按 provider 分别构造Anthropic、AnthropicVertex、AnthropicBedrock客户端（仅 Anthropic 路径启用 prompt caching 并注入对应 beta 头）。

4.4 访问 Demo 界面

容器启动后，在浏览器打开http://localhost:8080即可使用"聊天 + 桌面视图"一体的聚合界面。其他访问入口：

• 仅 Streamlit 界面：http://localhost:8501
• 仅桌面视图（noVNC）：http://localhost:6080/vnc.html
• VNC 客户端直连：vnc://localhost:5900

容器会把 API Key、自定义系统提示词等设置存放在~/.anthropic/目录；挂载该目录即可在多次容器运行之间持久化这些设置。对应的读写实现是 streamlit.py：api_key与system_prompt以0o600权限写入~/.anthropic/，错误堆栈也会以时间戳命名落盘便于排查。

五、屏幕分辨率与坐标缩放工程要点

5.1 用 WIDTH / HEIGHT 控制屏幕尺寸

环境变量WIDTH和HEIGHT可设置屏幕尺寸，例如：

docker run \ -e ANTHROPIC_API_KEY=$ANTHROPIC_API_KEY \ -v $HOME/.anthropic:/home/computeruse/.anthropic \ -p 5900:5900 \ -p 8501:8501 \ -p 6080:6080 \ -p 8080:8080 \ -e WIDTH=1920 \ -e HEIGHT=1080 \ -it ghcr.io/anthropics/anthropic-quickstarts:computer-use-demo-latest

Dockerfile 中镜像默认参数为DISPLAY_NUM=1、WIDTH=1024、HEIGHT=768；computer.py 通过os.getenv("WIDTH")/os.getenv("HEIGHT")读取，未设置时会断言报错"WIDTH, HEIGHT must be set"。

5.2 为什么建议 XGA/WXGA，以及官方推荐做法

README 明确不建议发送高于 XGA/WXGA 分辨率的截图，原因有两个：

1. 依赖 API 侧的图像 resize 行为会导致模型准确率下降、速度变慢；
2. 正确的做法是在工具内部自行实现缩放。

本项目computer工具正是"在工具内缩放图像与坐标"的参考实现。当实现自己的 computer use 时，官方推荐：

• 高分辨率场景：先把图像缩小到 XGA（1024×768），让模型基于缩放版交互，再把坐标按比例映射回原始分辨率；
• 低分辨率或小屏幕（如移动设备）：在显示区域四周填充黑色 padding，直到达到 1024×768。

源码层面，computer.py 定义了三个缩放目标：XGA（1024×768，4:3）、WXGA（1280×800，16:10）、FWXGA（1366×768，约 16:9）。scale_coordinates（computer.py）会：

• 当物理分辨率高于目标且宽高比偏差小于 0.02 时，把截图缩放到目标分辨率（convert {path} -resize {x}x{y}!，见screenshot）；
• 对模型返回的坐标（ScalingSource.API）先做越界校验，再按比例放大回物理分辨率交给 xdotool 执行；
• 对物理坐标（ScalingSource.COMPUTER）则缩小后随截图帧一起呈现给模型。

这一来一回保证了"模型看到的坐标帧"与"真实执行坐标帧"严格一致，是避免点击错位的关键。

六、Agent 循环与工具系统源码剖析

6.1 sampling_loop：完整的"模型-工具"闭环

loop.py 中的sampling_loop是整个 demo 的核心，其工作流程：

1. 根据工具版本取工具组，实例化ToolCollection，拼装系统提示词（内置SYSTEM_PROMPT描述了 Ubuntu 虚拟机环境、firefox-esr、DISPLAY=:1启动 GUI 的注意事项、用str_replace_based_edit_tool或grep -n -B/-A查看大输出、建议"尽量把多个工具调用合并到一次请求"等行为准则）；
2. 按 provider 构造客户端；Anthropic 路径注入prompt-caching-2024-07-31beta 头并调用_inject_prompt_caching为最近 3 轮用户消息设置cache_control断点；
3. 若开启token-efficient-toolsbeta（token-efficient-tools-2025-02-19）则追加对应 beta 头；若启用图像裁剪，则调用_maybe_filter_to_n_most_recent_images只保留最近 N 张截图（按min_removal_threshold整块删除以不破坏隐式缓存）；
4. 调用client.beta.messages.with_raw_response.create(...)发送请求（betas为空时用omit省略该字段，避免发送空头）；
5. 解析响应中的 text / thinking / tool_use 块，逐块执行工具、收集tool_result；toolset 成员调用串行执行、失败即停；
6. 若本轮无工具调用则返回消息列表，否则把tool_result追加为新的 user 消息后进入下一轮循环。

调用失败处理也相当完备：APIStatusError、APIResponseValidationError、APIError均会被捕获并回调渲染，不会让会话崩溃。

6.2 工具系统：computer / bash / edit

• computer：前面已详述，动作全部经由 xdotool 落盘到 X11 显示（left_click_drag用mousemove --sync ... mousedown 1 ... mouseup 1组合；type按 50 字符一组、12ms 延迟分批输入并最终截图；scroll映射到鼠标滚轮按钮 4/5/6/7；hold_key与wait限制时长不超过 100 秒），详见 computer.py；
• bash：基于/bin/bash的常驻 asyncio 子进程会话（preexec_fn=os.setsid保证进程组独立），单条命令超时 120 秒、以<<exit>>哨兵界定输出（见 tools/bash.py），并支持用DISPLAY=:1前缀启动 GUI 应用；
• edit：对应str_replace_based_edit_tool，用于精确的字符串替换式文件编辑（如 README 系统提示词中所建议的读取大文件 / PDF 转换文本的方式）。

工具基类BaseAnthropicTool定义了__call__与to_params抽象方法；ToolResult（output/error/base64_image/system）统一承载执行结果，支持+拼接与replace派生（见 tools/base.py）。

6.3 容器环境与桌面栈

Dockerfile 基于 Ubuntu 22.04 构建，关键组件：

• 桌面与显示：xvfb（虚拟帧缓冲）、mutter（窗口管理器）、x11vnc（VNC 服务）、xdotool（键鼠控制）、scrot/imagemagick（截图与缩放）；
• 应用：firefox-esr、libreoffice、gedit、xpaint、tint2、galculator、pcmanfm；
• 远程访问：noVNC v1.5.0 + websockify v0.12.0，映射/opt/noVNC/vnc.html为默认首页；
• 运行环境：pyenv 安装 Python 3.11.6，computeruse非 root 用户（可免密 sudo），入口为./entrypoint.sh（见 image/entrypoint.sh，默认DISPLAY_NUM=1）。

七、开发模式：本地改代码 + 热重载

对于希望二次开发的读者，README 给出了开发工作流：

./setup.sh # 配置 venv、安装开发依赖、安装 pre-commit 钩子 docker build . -t computer-use-demo:local # （可选）手动构建镜像 export ANTHROPIC_API_KEY=%your_api_key% docker run \ -e ANTHROPIC_API_KEY=$ANTHROPIC_API_KEY \ -v $(pwd)/computer_use_demo:/home/computeruse/computer_use_demo/ `# 挂载本地 Python 模块用于开发` \ -v $HOME/.anthropic:/home/computeruse/.anthropic \ -p 5900:5900 \ -p 8501:8501 \ -p 6080:6080 \ -p 8080:8080 \ -it computer-use-demo:local # 也可以使用 ghcr.io/anthropics/anthropic-quickstarts:computer-use-demo-latest

其中./setup.sh（setup.sh）会校验两点：Python 必须 ≤ 3.12（高于 3.12 会退出并提示改用python3.12 -m venv .venv），且系统需安装 Cargo（Rust 工具链）——这是某个 Python 依赖的编译前提。随后创建.venv、安装dev-requirements.txt并执行pre-commit install。上述docker run把宿主机仓库挂载进镜像，宿主侧修改文件即可生效，因为 Streamlit 已配置自动重载。仓库还自带测试套件（tests 目录 下的loop_test.py、tools/computer_test.py、tools/bash_test.py、tools/edit_test.py、streamlit_test.py等），可在 pyproject.toml 的 pytest 配置（asyncio_mode = "auto"）下直接运行验证改动。

八、安全边界与使用限制

computer use 是 beta 特性，与标准 API 功能或聊天界面相比存在独特风险，联网交互时风险更高。README 给出的风险缓解建议：

1. 使用最小权限的专用虚拟机或容器，防止直接的系统攻击或误操作；
2. 不要让模型接触敏感数据（如账户登录信息），防止信息窃取；
3. 将互联网访问限制在白名单域名，减少恶意内容暴露面；
4. 对会产生真实世界后果的决策、以及需要肯定性同意的事项（接受 cookie、金融交易、同意服务条款），安排人类确认。

特别需要警惕提示注入：在某些情况下，Claude 会遵循内容中出现的指令，即使它与用户指令冲突——例如网页或图片中嵌入的指令可能覆盖用户指令或导致模型犯错。因此建议把 Claude 与敏感数据和敏感操作隔离。在自有产品中启用 computer use 前，还应向最终用户告知相关风险并取得同意。

此外，本 demo 的组件是弱隔离的：agent 循环运行在被 Claude 控制的容器内、单会话可用、会话间需重启。界面侧边栏提供 "Reset" 按钮（pkill Xvfb; pkill tint2后重新执行./start_all.sh拉起桌面），配合maybe_add_interruption_blocks对被打断的工具调用注入错误结果与说明文本，实现会话的干净重置（见 streamlit.py 与 streamlit.py）。

九、小结

从 README 出发，结合源码可以看到：computer-use-demo提供了一条从"一条 docker run 命令"到"Claude 自主操作 Linux 桌面"的最短路径，覆盖三大 API 提供方、五档工具版本（含 GA 的 toolset 形态）、自适应/扩展思考两种推理模式，以及一套经过工程验证的屏幕缩放与坐标映射方案。对于希望在生产环境落地 computer use 的团队，建议在此基础上参考 Computer Use Best Practices 引入显式工具定义、prompt caching、服务端压缩、轨迹录制等可靠性手段，并结合自身场景修改 SYSTEM_PROMPT，让模型充分了解其运行环境与任务约束。

【免费下载链接】claude-quickstartsA collection of projects designed to help developers quickly get started with building deployable applications using the Claude API项目地址: https://gitcode.com/GitHub_Trending/an/claude-quickstarts