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 等桌面依赖的容器镜像见 DockerfileComputer use agent loop基于 Claude API / Bedrock / Vertex 的采样循环负责调用模型 → 解析工具调用 → 执行工具 → 回传结果的完整闭环见 loop.pyAnthropic 定义的 computer use 工具computer屏幕/鼠标/键盘、bashshell 会话、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.8claude-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_2025042964,00016,384off, extendedClaude 4.5 系列含 zoom 版computer_use_20250124 / 20251124128,000 / 64,00016,384off, extendedHaiku 4.5computer_use_202501248,1924,096offOpus 4.6 / Sonnet 4.6computer_use_20251124128,00016,384adaptive, extended, offOpus 4.7 / Opus 4.8computer_use_20251124128,00016,384adaptive, off未识别的模型 ID回退computer_use_2025042964,00016,384off, adaptive, extended从源码可以确认两个关键事实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 参数。模型识别采用精确匹配 最长前缀匹配_lookup_model_confstreamlit.py对anthropic.claude-sonnet-4-5-20250929-v1:0Bedrock 形式或claude-sonnet-4-520250929Vertex 形式这类带前缀/带日期的 ID会归一化后按最长已知前缀解析到正确配置避免落入宽松的默认配置而把不支持的思考模式发给 API。各 API 提供方的默认模型分别为Anthropic 使用claude-opus-4-8Bedrock 使用anthropic.claude-3-5-sonnet-20241022-v2:0Vertex 使用claude-3-5-sonnet-v220241022见 streamlit.py。三、工具版本体系从单computer工具到computer_toolset_20260801demo 支持所有已发布日期的 Anthropic computer use 工具版本可在 Streamlit 侧边栏的 Tool Versions 中切换侧边栏默认选中与当前模型匹配的版本。版本定义集中在 tools/groups.pyToolVersion Literal[ computer_use_20250124, computer_use_20241022, computer_use_20250429, computer_use_20251124, computer_toolset_20260801, ]3.1 最新形态computer_toolset_20260801toolset无需 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(errorNOT_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_20241022ComputerTool20241022computer-use-2024-10-22computer_use_20250124ComputerTool20250124computer-use-2025-01-24computer_use_20250429ComputerTool20250124computer-use-2025-01-24computer_use_20251124ComputerTool20251124computer-use-2025-11-24computer_toolset_20260801ComputerToolset20260801无各版本的动作集也随日期递增computer_20241022支持 10 个动作key、type、mouse_move、left_click、left_click_drag、right_click、middle_click、double_click、screenshot、cursor_positioncomputer_20250124新增left_mouse_down、left_mouse_up、scroll、hold_key、wait、triple_clickcomputer_20251124新增zoom配合region四元坐标做局部放大见 computer.py。模型只支持 toolset 或它训练过的早期 dated 版本之一具体以官方 computer use 文档中每个模型的受支持版本为准。四、快速开始Docker 容器运行4.1 Claude APIAnthropic 官方入口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:5900VNC 直连端口-p 8501:8501仅 Streamlit 界面-p 6080:6080noVNC 网页桌面视图-p 8080:8080聚合界面聊天 桌面视图一体。4.2 BedrockAWS使用 Bedrock 前需在 AWS 侧申请对应模型的访问权限README 特别提示使用新的 Claude 3.7 Sonnet 需要先请求模型访问并准备具备相应权限的 AWS 凭证。提供两种认证方式方式一推荐复用宿主机的 AWS 凭证文件与 profileexport AWS_PROFILEyour_aws_profile docker run \ -e API_PROVIDERbedrock \ -e AWS_PROFILE$AWS_PROFILE \ -e AWS_REGIONus-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_PROVIDERbedrock \ -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_REGIONus-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.pyBedrock 路径下若无可用 boto3 凭证界面会提示先配置 AWS 凭证。4.3 VertexGoogle CloudVertex 需要本地先构建镜像并使用 Google Cloud 应用默认凭证ADCdocker 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_PROVIDERvertex \ -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-demoVertex 路径的认证校验要求设置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仅桌面视图noVNChttp://localhost:6080/vnc.htmlVNC 客户端直连vnc://localhost:5900容器会把 API Key、自定义系统提示词等设置存放在~/.anthropic/目录挂载该目录即可在多次容器运行之间持久化这些设置。对应的读写实现是 streamlit.pyapi_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 WIDTH1920 \ -e HEIGHT1080 \ -it ghcr.io/anthropics/anthropic-quickstarts:computer-use-demo-latestDockerfile 中镜像默认参数为DISPLAY_NUM1、WIDTH1024、HEIGHT768computer.py 通过os.getenv(WIDTH)/os.getenv(HEIGHT)读取未设置时会断言报错WIDTH, HEIGHT must be set。5.2 为什么建议 XGA/WXGA以及官方推荐做法README 明确不建议发送高于 XGA/WXGA 分辨率的截图原因有两个依赖 API 侧的图像 resize 行为会导致模型准确率下降、速度变慢正确的做法是在工具内部自行实现缩放。本项目computer工具正是在工具内缩放图像与坐标的参考实现。当实现自己的 computer use 时官方推荐高分辨率场景先把图像缩小到 XGA1024×768让模型基于缩放版交互再把坐标按比例映射回原始分辨率低分辨率或小屏幕如移动设备在显示区域四周填充黑色 padding直到达到 1024×768。源码层面computer.py 定义了三个缩放目标XGA1024×7684:3、WXGA1280×80016:10、FWXGA1366×768约 16:9。scale_coordinatescomputer.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 的核心其工作流程根据工具版本取工具组实例化ToolCollection拼装系统提示词内置SYSTEM_PROMPT描述了 Ubuntu 虚拟机环境、firefox-esr、DISPLAY:1启动 GUI 的注意事项、用str_replace_based_edit_tool或grep -n -B/-A查看大输出、建议尽量把多个工具调用合并到一次请求等行为准则按 provider 构造客户端Anthropic 路径注入prompt-caching-2024-07-31beta 头并调用_inject_prompt_caching为最近 3 轮用户消息设置cache_control断点若开启token-efficient-toolsbetatoken-efficient-tools-2025-02-19则追加对应 beta 头若启用图像裁剪则调用_maybe_filter_to_n_most_recent_images只保留最近 N 张截图按min_removal_threshold整块删除以不破坏隐式缓存调用client.beta.messages.with_raw_response.create(...)发送请求betas为空时用omit省略该字段避免发送空头解析响应中的 text / thinking / tool_use 块逐块执行工具、收集tool_resulttoolset 成员调用串行执行、失败即停若本轮无工具调用则返回消息列表否则把tool_result追加为新的 user 消息后进入下一轮循环。调用失败处理也相当完备APIStatusError、APIResponseValidationError、APIError均会被捕获并回调渲染不会让会话崩溃。6.2 工具系统computer / bash / editcomputer前面已详述动作全部经由 xdotool 落盘到 X11 显示left_click_drag用mousemove --sync ... mousedown 1 ... mouseup 1组合type按 50 字符一组、12ms 延迟分批输入并最终截图scroll映射到鼠标滚轮按钮 4/5/6/7hold_key与wait限制时长不超过 100 秒详见 computer.pybash基于/bin/bash的常驻 asyncio 子进程会话preexec_fnos.setsid保证进程组独立单条命令超时 120 秒、以exit哨兵界定输出见 tools/bash.py并支持用DISPLAY:1前缀启动 GUI 应用edit对应str_replace_based_edit_tool用于精确的字符串替换式文件编辑如 README 系统提示词中所建议的读取大文件 / PDF 转换文本的方式。工具基类BaseAnthropicTool定义了__call__与to_params抽象方法ToolResultoutput/error/base64_image/system统一承载执行结果支持拼接与replace派生见 tools/base.py。6.3 容器环境与桌面栈Dockerfile 基于 Ubuntu 22.04 构建关键组件桌面与显示xvfb虚拟帧缓冲、mutter窗口管理器、x11vncVNC 服务、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.6computeruse非 root 用户可免密 sudo入口为./entrypoint.sh见 image/entrypoint.sh默认DISPLAY_NUM1。七、开发模式本地改代码 热重载对于希望二次开发的读者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.shsetup.sh会校验两点Python 必须 ≤ 3.12高于 3.12 会退出并提示改用python3.12 -m venv .venv且系统需安装 CargoRust 工具链——这是某个 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 给出的风险缓解建议使用最小权限的专用虚拟机或容器防止直接的系统攻击或误操作不要让模型接触敏感数据如账户登录信息防止信息窃取将互联网访问限制在白名单域名减少恶意内容暴露面对会产生真实世界后果的决策、以及需要肯定性同意的事项接受 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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考