Claude 计算机与浏览器操控实战指南macOS 本地运行 computer-use-best-practices 参考实现【免费下载链接】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-best-practices 为蓝本系统讲解如何在本机 macOS 上以零 Docker、纯本地的方式搭建一个基于 Claude API 的计算机操控computer use与浏览器操控browser useAgent从环境安装、权限授予、命令行运行到显式工具定义、截图尺寸换算、显式工具与托管工具二选一、多 Provider 切换、提示缓存与截图裁剪策略、服务端 Advisor 工具等核心机制一应俱全。读完本文你将掌握该参考实现从跑通 Hello World到按自己的需求修改配置与工具的完整链路并能借助其内置的轨迹回放、工具面板与定位演示快速验证自己的改动。项目定位与安全须知先读这一节computer-use-best-practices是一个教学型参考实现reference implementation它的设计意图是被阅读、理解、并按你的用途修改而不是作为库被导入或当作生产级 SDK 使用。它配套官方发布的computer-use best-practices最佳实践指南两者建议对照阅读。平台约束仅支持 macOS。键盘处理、pyautogui后端、sandbox-exec沙箱都是 Mac 专有的容器化或 Linux 变体不在本模块范围内。如果你想要一个最小的容器化起点可以转向本仓库中的 computer-use-demoDocker X11 桌面或 browser-use-demoDocker Playwright、仅浏览器。[!CAUTION] 这是一个仅供教学用途的参考实现。强烈不推荐在虚拟机之外运行此 Agent。该 Agent 拥有对你鼠标、键盘和屏幕的完全控制权且没有任何防护机制防止它截取包含敏感信息的截图并上传到 API、删除或覆盖重要数据、或打开并操作你机器上的任何应用。请在一个一次性的 macOS 虚拟机中运行它UTM、Parallels 均支持 macOS 来宾系统本仓库作者内部使用这些工具但与其无任何关联也不对其背书。如果你需要内置安全防护与人在回路控制的 computer-use 能力而不是教学脚手架请使用 Cowork。核心特性一览在进入安装步骤前先概览这个参考实现的四大设计要点均可在源码中逐一印证显式定义工具Explicit tools模型看到的每一个 computer-use / browser-use 工具都在 computer_use/tools/ 中完整定义了名称、描述与 JSON Schema你可以精确阅读进入 API 调用的内容这正是参考实现的意义所在。正确的截图尺寸computer_use/image.py 移植了 API 的参考缩放算法保证模型看到的就是你发送的像素点击坐标因此保持精确。批量工具Batch toolscomputer_batch/browser_batch让模型在一轮内串联多个可预测的动作。在模型能自信地提前规划多步的场景下批处理可以显著降低延迟与成本当模型只发出单个动作调用时demo 会通过追加BATCH_REMINDER提示它改用批量工具。沙箱化的 bash / python通过sandbox-exec配置在 sandbox/限制 shell 与 python 的权限。此外还有轨迹录制runs/…目录 Streamlit 查看器、FastAPI 调试面板脱离模型手工演练各工具等配套设施。快速开始三条命令跑通 Hello World如果你在使用 Claude Code直接在此文件夹中打开并运行/first-run即可获得引导式教程。否则只需要三条命令python -m pip install -r requirements.txt python -m playwright install chromium echo ANTHROPIC_API_KEYYOUR API KEY HERE .env python -m computer_use open TextEdit and type hello world注意这个任务会真实移动你的鼠标和键盘运行前务必先阅读上文的安全警告。完整的安装流程见下一节含 Python 3.11 的要求。安装与前置条件环境要求Python 3.11macOS 自带的是 Python 3.9无法工作。请先安装更新的解释器例如brew install python3.13或使用 python.org 的安装包并用它创建虚拟环境# 将 python3.13 替换为你安装的任意 3.11 解释器 python3.13 -m venv .venv source .venv/bin/activate python -m pip install --upgrade pip python -m pip install -r requirements.txt # 为 browser 工具下载无头 Chromium一次性约 150 MB python -m playwright install chromium使用 uv更快uv sync uv run playwright install chromiumREADME 其余部分展示的是普通python ...命令装了 uv 后可以用uv run前缀替代激活 venv。授予 macOS 权限在系统设置 → 隐私与安全性中为你的终端授予屏幕录制用于截图和辅助功能用于鼠标/键盘控制然后完全退出并重新打开终端让 macOS 生效。Agent 的 preflight 检查会在首次运行时为你打开这两个面板想手动跳转可执行open x-apple.systempreferences:com.apple.preference.security?Privacy_ScreenCapture open x-apple.systempreferences:com.apple.preference.security?Privacy_Accessibility两个权限面板的界面如下在 macOS 15Sequoia及更高版本上Agent 首次截图时还会弹出一个独立的bypass the system private window picker绕过系统私有窗口选择器对话框之后大约每月出现一次。这是 macOS 对旧版屏幕捕获 API 的重新授权与上面的开关相互独立请点击Allow。配置 API Key将 Key 导出为环境变量或写入仓库根目录的.env文件复制 .env.examplecp .env.example .env # 然后编辑 .env # 或export ANTHROPIC_API_KEY...运行 Agentpython -m computer_use open TextEdit and type hello world一个仅浏览器的例子当你不想让 Agent 触碰桌面时很方便这会完全禁用computer工具CU_ENABLE_COMPUTER_USE_TOOLSfalse python -m computer_use \ Navigate to https://en.wikipedia.org/wiki/Special:Random three times, \ take a screenshot each time, then summarize what you saw.交互会话循环命令启动后会进入交互式会话先打印安全横幅并检查 macOS 权限随后进入循环模型的响应实时流式打印到终端思考内容以暗灰色显示、助手文本为常规字重、每个工具调用以青色→ computer({action: screenshot})行呈现。循环在真实机器上执行请求的工具截图、移动鼠标、打字、启动应用等并以黄色← computer: [image 105KB]行打印结果。暗色[usage] in… cache_read… out… | cache_eff…% | 12.3s行显示当轮的 token 数与提示缓存效率。重复 1-3 步直到模型停止调用工具此时出现you 提示符等待后续消息。随时按 Ctrl-C可中断当前回合并回到该提示符输入空行退出。Agent 发送与接收的所有内容也会写入runs/timestamp/包含 JSONL 转录与 JPEG 截图之后可在查看器中回放。常用命令行参数参数说明--model {claude-haiku-4-5,claude-sonnet-4-6,claude-opus-4-6,claude-opus-4-7}选择模型--thinking {off,low,medium,high,max}推理努力程度--max-iters N单条用户消息的最大模型回合数默认 200见cfg.default_max_iters--skip-preflight跳过 macOS 权限预检查看轨迹Streamlit 回放器python -m streamlit run dev_ui/trajectory_viewer/app.py会打开一个浏览器标签页侧边栏按最新优先列出每次运行。主面板将所选运行渲染为聊天记录用户消息、助手思考可折叠、助手文本、每个工具调用代码块形式、以及每个工具结果展开面板内联展示文本输出与截图。这是事后检查模型实际看到了什么、做出了什么决策的最便捷方式。定位演示理解 resize/rescale 坐标系python -m uvicorn dev_ui.localization_demo.server:app --reload --port 8001 # 打开 http://127.0.0.1:8001这是一个用于理解点击式定位的最小启动器目的是把缩放/回缩放流水线具象化。上传任意图片、输入一段描述如the blue Submit button服务端会用target_image_size()缩放图片确保 API 不会再缩放一次附带单个point_at工具并用tool_choice强制调用发送取模型返回的(x, y)注意这是在缩放后图片坐标系中的值用x * orig_w / sent_w回缩放到你的原始坐标。页面并排展示两张图片并各打一个标记让你直观看到两个坐标系。整个流程约 100 行代码在 dev_ui/localization_demo/server.py 中。工具面板脱离模型手工演练python -m uvicorn dev_ui.tool_panel.server:app --reload # 打开 http://127.0.0.1:8000单页工具测试台每个工具都根据其input_schema自动生成表单。填写字段、设置倒计时延迟留出时间把焦点切到目标窗口然后点 Run。结果面板展示返回的 JSON 与内联截图。点击截图会以图像像素填充最近的coordinate字段并显示对应的屏幕像素位置——这是快速 sanity-check 坐标缩放的最快方式。若缺少屏幕录制或辅助功能权限页面会出现红色横幅。配置体系Config 数据类与三级覆盖所有可调旋钮都集中在 constants.py 的Configdataclass 上活跃实例为constants.cfg其余代码统一读取cfg.field做到单一事实来源。覆盖优先级为后写者胜TOML 文件复制 config.example.toml设置所需字段并将CU_CONFIG指向该文件。按字段的环境变量CU_FIELD_NAMEvalue叠加在 TOML 之上。CLI 的--set FIELDVALUE。两者都可放在.env或 shell 中。示例# 一次性关闭浏览器工具并提高 JPEG 质量 CU_ENABLE_BROWSER_USE_TOOLSfalse CU_JPEG_QUALITY85 \ python -m computer_use open Notes and type hello # 通过环境变量钉住视口字符串会被强制转换为元组 CU_BROWSER_VIEWPORT1280x720 python -m computer_use ... # 或保留一个 config.toml 并从 .env 指向它 # .env: CU_CONFIGconfig.toml # config.toml: # enable_advisor_tool true # image_prune_strategy none # extra_models [some-beta-model]字符串值会被强制转换为声明字段类型true→True、80→80、1280x720→(1280, 720)、可选 int 的none→None。从源码看这一强制转换由 constants.py 的_coerce()实现支持 bool / int / float / tuple以x或,分隔等dict 类型字段不能从字符串设置必须走 TOML会显式抛ValueError。功能开关速查表字段默认值作用enable_computer_use_toolstruecomputer、computer_batch、open_applicationpyautogui 屏幕控制。此项与 browser 至少开一个。enable_browser_use_toolstruebrowser、browser_batch无头 Playwright。enable_editor_tooltrueeditorview/create/str_replace/insert限定在每次运行的 scratch 目录内bash/python 共享同一工作区。同时向系统提示词追加 TODO.md 指引。enable_advisor_toolfalse服务端 Advisor 工具执行模型在生成过程中可咨询更强大的advisor_model默认 Opus。enable_autocompactiontrue服务端compact_20260112输入 token 超过autocompaction_trigger_tokens时服务端总结较早的上下文。仅对支持的模型Sonnet/Opus生效。image_prune_strategyintervalnone保留全部截图simple只保留最近 N 张对缓存不友好interval在image_prune_interval轮内保持前缀稳定。详见下文。print_usagetrue每轮打印[usage]行含 token 数与缓存效率。extra_models()--model额外接受的模型 ID内置枚举之外的旧版或 beta 模型。其余Config字段都是数值型可调项重试次数、JPEG 质量、视口尺寸、advisor 上限等每个字段的注释都在 constants.py 中。几个值得注意的默认值jpeg_quality75与桌面应用 Swift 编码器一致是大小/保真度的良好折中、browser_viewport(1456, 819)截图天然落在视觉 token 预算内、无需缩放、max_shell_output_bytes64KB防止yes之类的命令在 30 秒超时前撑爆内存、api_retry_max_attempts5指数退避重试可恢复错误4xx 直接抛出。显式工具 vs. 托管 computer 工具默认情况下本 demo显式定义每个工具computer工具的名称、描述与 JSON Schema 全部在 computer_use/tools/computer.py 中你可以直接阅读并编辑模型看到的内容不受任何服务端默认值干扰——这正是参考实现的要义。代价是安全分类器的覆盖范围。API 的 computer-use 专用安全分类器包括对截图内容的提示注入检测仅在请求声明 Anthropic 定义的 computer 工具时才运行。使用显式 Schema 时请求走的是通用安全路径你必须依赖自己的提示注入缓解措施系统提示词的指令、本 README 顶部推荐的 VM 隔离以及你自己的监控。若希望在保留其余 demo 功能的同时启用这些分类器设置cfg.use_hosted_computer_tool True或CU_USE_HOSTED_COMPUTER_TOOLtrue。只有computer工具的定义声明会变computer_batch、browser、bash等仍是显式的且所有工具仍在本地执行。在第一方 API 上托管声明是 computer工具集toolset{type: computer_toolset_20260801}—— 一个无名条目为每个动作声明一个成员工具无需 beta 头、无显示尺寸坐标一律是截图像素由你发送的截图确立坐标系。自己写循环时工具集有三点值得了解本仓库的 loop.py 逐一示范了成员调用是普通的tool_use块以动作命名left_click、zoom…带toolset_name: computer输入中无action字段。ToolCollection.run按(toolset_name, name)路由并把名称折回action因此显式的ComputerTool同时服务两种声明。每个成员——包括工具集默认启用的zoom——都有实现。一轮可能携带多个成员调用。它们按块顺序串行执行第一个失败后其余调用以is_error: true和约定的Not executed: …文本应答而不执行因为后面的动作都假设前面的成功了。这正是显式工具下computer_batch提供的能力工具集原生实现了它。每个成员的tool_result必须携带与其tool_use相同的toolset_name普通工具的结果则不能带。_tool_result_block负责打上该标记包括 Ctrl-C 填充的[interrupted by user]结果。Vertex 和 Bedrock 尚未提供工具集因此在这些 Provider 上托管模式回退到带日期的computer_20250124工具及 beta 头Config.hosted_computer自动选择此时模型以name: computerinput.action调用即显式工具自身的外形。从 computer.py 可以看到两种托管声明的生成代码。显式工具的内部实现要点在 computer.py 中可以读到几个值得注意的实现细节动作全集screenshot、单/双/三击、左右中键点击、mouse_move、left_click_drag、scroll、type、key、hold_key、left_mouse_down/up、cursor_position、剪贴板读写、wait、zoom共 19 个动作input_schema中全部有枚举与参数描述。坐标缩放模型看到的是缩放后的截图模型发出坐标后_scale_to_screen()用x * screen_w / sent_w将其换算回逻辑屏幕像素并对 retina 屏先降采样pyautogui 截图是物理像素、鼠标函数接收逻辑像素。键名别名模型习惯发 xdotool 风格键名工具内置_KEY_ALIASES映射如control→ctrl、super/cmd/meta→command、return→enter、win→command尤其注意delete→backspace的映射——macOS 上 pyautogui 的 delete 是 Forward-Delete模型说 delete 时几乎总是指退格键。布局无关输入_type_text()不用 pyautogui 的write()它会发送 ANSI 虚拟键码在 Dvorak/AZERTY 等布局下打出错误字符而是通过CGEventKeyboardSetUnicodeString直接投递 Unicode 字符串事件任何布局都逐字插入。Schema 与实现防漂移base.py 的__init_subclass__在导入时校验input_schema声明的每个属性都必须是execute()的关键字参数required字段不得有默认值——schema 与实现无法静默分叉。Provideranthropic / vertex / bedrockcfg.provider选择 API 表面anthropic默认第一方 API、vertexGoogle Cloud经AnthropicVertex、bedrockAWS经AnthropicBedrock。各 Provider 所需的凭据见.env.example。Vertex 和 Bedrock 有第一方 API 没有的请求体大小上限。demo 在图片裁剪器中强制执行保守阈值Vertex 18 MB、Bedrock 11 MB见 constants.py 的PROVIDER_MAX_MESSAGE_MB序列化消息列表超过上限时强制裁剪到cfg.image_prune_min张并重置间隔周期使后续轮次从小的状态开始。Advisor 工具与服务端自动压缩是第一方专属 beta 功能。在provider ! anthropic时启用任一项启动即抛ValueError并指名冲突配置见 constants.py 的__post_init__将其设为False或切换 provider即可继续。有效的缓存与上下文裁剪computer-use 轨迹几乎每轮都会新增一张截图而每张截图约1,500 输入 token。30 轮后仅图片历史就有约 45k token且每次 API 调用都要重新发送并付费。本仓库用两个机制控制这一点提示缓存Prompt cachingloop.py 在系统提示词上放置一个cache_control: {type: ephemeral}断点并在最近用户回合的最后一个 tool-result 块上放置另一个。下一次调用时API 可以从缓存提供该断点之前的所有内容约为输入 token 价格的 10%且延迟明显更低。每轮打印的[usage]行显示cache_read与in的对比便于观察命中率。源码中还做了缓存断点阶梯处理_MAX_BODY_CACHE_BREAKPOINTS 3在偶尔前缀移位例如裁剪间隔回滚的回合较早的断点仍能命中。图片裁剪Image pruninginterval 策略为何对缓存友好提示缓存仅在请求前缀逐字节相同时才有用。朴素的保留最近 N 张、更旧的替换为占位符方案一旦超过 N每轮被替换的旧图都不同前缀每轮都变、缓存每轮都 miss。cfg.image_prune_strategy interval默认值实现在 computer_use/formatters.py 的StripImagesAtIntervals通过让保留数量从cfg.image_prune_min阶梯式爬到cfg.image_prune_min cfg.image_prune_interval - 1再回落来规避在连续image_prune_interval轮内相同的旧图映射到相同的占位文本前缀保持一致缓存持续命中。你每image_prune_interval轮付一次缓存写入而不是每轮一次。策略设为none完全禁用裁剪simple则用于对比观察缓存不友好的行为StripOldestImages。此外该裁剪器还内建请求体大小兜底超出max_message_mb时强制裁剪并重置周期formatters.py。裁剪 vs. 服务端上下文总结cfg.enable_autocompaction开启 API 的服务端上下文管理编辑总输入 token 越过cfg.autocompaction_trigger_tokens后服务端用一次独立子调用把迄今对话浓缩成简短摘要块客户端下一轮丢弃该块之前的全部内容loop.py 的_truncate_to_last_compaction还会主动截断以让裁剪器在模型实际看到的切片上工作。两者都限制上下文规模但权衡不同总结是更昂贵的事件。它是完整的一次额外 API 回合整个对话进、多段摘要出且下一轮因前缀全新而冷缓存。相比之下interval 裁剪回滚只重新处理变化的尾部、不产生输出 token。短期内裁剪更快更便宜但长期跨越很多未来回合可能更贵且图片裁剪永远不会删除用户/助手消息这些文本会随时间累积。总结保留更多信息。摘要保留了发生了什么的文本记录裁剪直接删除旧截图。这就是cfg.image_prune_min重要的原因设得足够高让模型在回滚后仍有需要的视觉上下文。只有当裁剪确实避免了一次总结时才值得。缓存读取比未缓存输入便宜约一个数量级因此多携带一张已缓存的截图成本几乎为零而丢弃它会强制重新缓存其后的所有内容。在短小、截图少的任务上最便宜的设置反而是完全不裁剪。长截图重任务上裁剪胜出。当仅图片就会越过触发阈值时每image_prune_interval张一次的低成本回滚远便宜于让对话命中总结这也是延迟分歧最大的地方——总结子调用的输出 token 生成缓慢即使美元成本接近回滚也快得多。默认值image_prune_min3、image_prune_interval40、autocompaction_trigger_tokens150_000后者的 API 下限为 50k低于下限会被钳制并打印提示经过调优截图重的运行在到达总结触发前先裁剪截图轻的运行两者都不做。如果你的负载持续很短设image_prune_strategynone、让总结充当罕见的兜底若持续很长且视觉密集降低image_prune_interval、把总结留给裁剪无法移除的文本。Advisor 工具实验性这不是通用推荐请在自己的负载上试用以判断质量提升是否值得额外成本与延迟。设置enable_advisor_tool trueCU_ENABLE_ADVISOR_TOOLtrue或config.toml执行模型即可在生成过程中咨询更强大的 advisor 模型默认 Opus获取策略性指导。这是本仓库中唯一不在computer_use/tools/中定义的工具它完全运行在 Anthropic 侧没有客户端execute()。循环将其声明在tools数组中、向系统提示词追加 advisor 使用指引时机建议与如何权衡建议、在建议到达时以暗色文本渲染并在后续回合回传结果块。每cfg.advisor_reminder_interval轮若没有 advisor 调用会向工具结果追加一条简短提醒。相关配置字段advisor_model、advisor_max_uses每请求上限、advisor_max_conversation_uses达到后循环丢弃 advisor 并从历史中剥离其结果块因为 API 会拒绝孤儿结果、advisor_cachingadvisor 侧提示缓存大约每会话 3 次 advisor 调用即可回本因此默认5m适合 agent 循环、advisor_reminder_interval。每轮[usage]行会为每次 advisor 调用增加一行显示 advisor 模型的 token与执行模型分开计费。系统提示词中的 advisor 使用指引全文包括实质性工作前先调用、任务完成前先保存成果再调用、卡住或更换方案时调用等策略见 constants.py 的ADVISOR_PROMPT_ADDENDUM。运行测试与源码布局python -m pytest仓库目录结构节选constants.py Config dataclass cfg 实例、提示词、派生集合 config.example.toml CU_CONFIG 覆盖的模板 computer_use/ __main__.py CLI 入口、build_tools()、build_system_prompt() loop.py 流式采样循环、重试、advisor/compaction 接线 image.py target_image_size JPEG 编码 尺寸 sanity 检查 formatters.py 缓存感知的截图裁剪interval/simple render.py 终端输出回合头、增量、usage、横幅 preflight.py macOS 屏幕录制 / 辅助功能权限检查 trajectory.py 磁盘转录 图片 每次运行的 scratch 目录 tools/ base.py Tool 抽象基类 ToolCollection result.py ToolResult image/document 内容块辅助 computer.py pyautogui 屏幕控制含 zoom、键名别名 browser.py playwright 无头 chromium batch.py computer_batch / browser_batch editor.py scratch 目录中的 view/create/str_replace/insert shell.py 沙箱化 bash python带输出上限 open_app.py open -a ... sandbox/default.sb sandbox-exec 配置文件 dev_ui/ assets/anthropic.css 所有 dev UI 的共享设计令牌 trajectory_viewer/ streamlit 转录查看器 tool_panel/ FastAPI 工具测试台每工具表单、点击取坐标 localization_demo/ 标签定位演示缩放/回缩放往返小结computer-use-best-practices的核心价值在于透明工具定义显式可见、截图缩放算法精确可查、缓存与裁剪策略在 formatters.py 中可直接阅读、批量工具、沙箱 shell、轨迹回放与手工调试面板一应俱全。把它当作一个可阅读、可修改的教学脚手架在一次性 macOS 虚拟机中运行配合本仓库的 computer-use-demoDocker X11与 browser-use-demoDocker Playwright即可从零搭建并逐步打磨你自己的 Claude computer-use / browser-use 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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 Claude 计算机与浏览器操控实战指南：macOS 本地运行 computer-use-best-practices 参考实现
Claude 计算机与浏览器操控实战指南macOS 本地运行 computer-use-best-practices 参考实现【免费下载链接】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-best-practices 为蓝本系统讲解如何在本机 macOS 上以零 Docker、纯本地的方式搭建一个基于 Claude API 的计算机操控computer use与浏览器操控browser useAgent从环境安装、权限授予、命令行运行到显式工具定义、截图尺寸换算、显式工具与托管工具二选一、多 Provider 切换、提示缓存与截图裁剪策略、服务端 Advisor 工具等核心机制一应俱全。读完本文你将掌握该参考实现从跑通 Hello World到按自己的需求修改配置与工具的完整链路并能借助其内置的轨迹回放、工具面板与定位演示快速验证自己的改动。项目定位与安全须知先读这一节computer-use-best-practices是一个教学型参考实现reference implementation它的设计意图是被阅读、理解、并按你的用途修改而不是作为库被导入或当作生产级 SDK 使用。它配套官方发布的computer-use best-practices最佳实践指南两者建议对照阅读。平台约束仅支持 macOS。键盘处理、pyautogui后端、sandbox-exec沙箱都是 Mac 专有的容器化或 Linux 变体不在本模块范围内。如果你想要一个最小的容器化起点可以转向本仓库中的 computer-use-demoDocker X11 桌面或 browser-use-demoDocker Playwright、仅浏览器。[!CAUTION] 这是一个仅供教学用途的参考实现。强烈不推荐在虚拟机之外运行此 Agent。该 Agent 拥有对你鼠标、键盘和屏幕的完全控制权且没有任何防护机制防止它截取包含敏感信息的截图并上传到 API、删除或覆盖重要数据、或打开并操作你机器上的任何应用。请在一个一次性的 macOS 虚拟机中运行它UTM、Parallels 均支持 macOS 来宾系统本仓库作者内部使用这些工具但与其无任何关联也不对其背书。如果你需要内置安全防护与人在回路控制的 computer-use 能力而不是教学脚手架请使用 Cowork。核心特性一览在进入安装步骤前先概览这个参考实现的四大设计要点均可在源码中逐一印证显式定义工具Explicit tools模型看到的每一个 computer-use / browser-use 工具都在 computer_use/tools/ 中完整定义了名称、描述与 JSON Schema你可以精确阅读进入 API 调用的内容这正是参考实现的意义所在。正确的截图尺寸computer_use/image.py 移植了 API 的参考缩放算法保证模型看到的就是你发送的像素点击坐标因此保持精确。批量工具Batch toolscomputer_batch/browser_batch让模型在一轮内串联多个可预测的动作。在模型能自信地提前规划多步的场景下批处理可以显著降低延迟与成本当模型只发出单个动作调用时demo 会通过追加BATCH_REMINDER提示它改用批量工具。沙箱化的 bash / python通过sandbox-exec配置在 sandbox/限制 shell 与 python 的权限。此外还有轨迹录制runs/…目录 Streamlit 查看器、FastAPI 调试面板脱离模型手工演练各工具等配套设施。快速开始三条命令跑通 Hello World如果你在使用 Claude Code直接在此文件夹中打开并运行/first-run即可获得引导式教程。否则只需要三条命令python -m pip install -r requirements.txt python -m playwright install chromium echo ANTHROPIC_API_KEYYOUR API KEY HERE .env python -m computer_use open TextEdit and type hello world注意这个任务会真实移动你的鼠标和键盘运行前务必先阅读上文的安全警告。完整的安装流程见下一节含 Python 3.11 的要求。安装与前置条件环境要求Python 3.11macOS 自带的是 Python 3.9无法工作。请先安装更新的解释器例如brew install python3.13或使用 python.org 的安装包并用它创建虚拟环境# 将 python3.13 替换为你安装的任意 3.11 解释器 python3.13 -m venv .venv source .venv/bin/activate python -m pip install --upgrade pip python -m pip install -r requirements.txt # 为 browser 工具下载无头 Chromium一次性约 150 MB python -m playwright install chromium使用 uv更快uv sync uv run playwright install chromiumREADME 其余部分展示的是普通python ...命令装了 uv 后可以用uv run前缀替代激活 venv。授予 macOS 权限在系统设置 → 隐私与安全性中为你的终端授予屏幕录制用于截图和辅助功能用于鼠标/键盘控制然后完全退出并重新打开终端让 macOS 生效。Agent 的 preflight 检查会在首次运行时为你打开这两个面板想手动跳转可执行open x-apple.systempreferences:com.apple.preference.security?Privacy_ScreenCapture open x-apple.systempreferences:com.apple.preference.security?Privacy_Accessibility两个权限面板的界面如下在 macOS 15Sequoia及更高版本上Agent 首次截图时还会弹出一个独立的bypass the system private window picker绕过系统私有窗口选择器对话框之后大约每月出现一次。这是 macOS 对旧版屏幕捕获 API 的重新授权与上面的开关相互独立请点击Allow。配置 API Key将 Key 导出为环境变量或写入仓库根目录的.env文件复制 .env.examplecp .env.example .env # 然后编辑 .env # 或export ANTHROPIC_API_KEY...运行 Agentpython -m computer_use open TextEdit and type hello world一个仅浏览器的例子当你不想让 Agent 触碰桌面时很方便这会完全禁用computer工具CU_ENABLE_COMPUTER_USE_TOOLSfalse python -m computer_use \ Navigate to https://en.wikipedia.org/wiki/Special:Random three times, \ take a screenshot each time, then summarize what you saw.交互会话循环命令启动后会进入交互式会话先打印安全横幅并检查 macOS 权限随后进入循环模型的响应实时流式打印到终端思考内容以暗灰色显示、助手文本为常规字重、每个工具调用以青色→ computer({action: screenshot})行呈现。循环在真实机器上执行请求的工具截图、移动鼠标、打字、启动应用等并以黄色← computer: [image 105KB]行打印结果。暗色[usage] in… cache_read… out… | cache_eff…% | 12.3s行显示当轮的 token 数与提示缓存效率。重复 1-3 步直到模型停止调用工具此时出现you 提示符等待后续消息。随时按 Ctrl-C可中断当前回合并回到该提示符输入空行退出。Agent 发送与接收的所有内容也会写入runs/timestamp/包含 JSONL 转录与 JPEG 截图之后可在查看器中回放。常用命令行参数参数说明--model {claude-haiku-4-5,claude-sonnet-4-6,claude-opus-4-6,claude-opus-4-7}选择模型--thinking {off,low,medium,high,max}推理努力程度--max-iters N单条用户消息的最大模型回合数默认 200见cfg.default_max_iters--skip-preflight跳过 macOS 权限预检查看轨迹Streamlit 回放器python -m streamlit run dev_ui/trajectory_viewer/app.py会打开一个浏览器标签页侧边栏按最新优先列出每次运行。主面板将所选运行渲染为聊天记录用户消息、助手思考可折叠、助手文本、每个工具调用代码块形式、以及每个工具结果展开面板内联展示文本输出与截图。这是事后检查模型实际看到了什么、做出了什么决策的最便捷方式。定位演示理解 resize/rescale 坐标系python -m uvicorn dev_ui.localization_demo.server:app --reload --port 8001 # 打开 http://127.0.0.1:8001这是一个用于理解点击式定位的最小启动器目的是把缩放/回缩放流水线具象化。上传任意图片、输入一段描述如the blue Submit button服务端会用target_image_size()缩放图片确保 API 不会再缩放一次附带单个point_at工具并用tool_choice强制调用发送取模型返回的(x, y)注意这是在缩放后图片坐标系中的值用x * orig_w / sent_w回缩放到你的原始坐标。页面并排展示两张图片并各打一个标记让你直观看到两个坐标系。整个流程约 100 行代码在 dev_ui/localization_demo/server.py 中。工具面板脱离模型手工演练python -m uvicorn dev_ui.tool_panel.server:app --reload # 打开 http://127.0.0.1:8000单页工具测试台每个工具都根据其input_schema自动生成表单。填写字段、设置倒计时延迟留出时间把焦点切到目标窗口然后点 Run。结果面板展示返回的 JSON 与内联截图。点击截图会以图像像素填充最近的coordinate字段并显示对应的屏幕像素位置——这是快速 sanity-check 坐标缩放的最快方式。若缺少屏幕录制或辅助功能权限页面会出现红色横幅。配置体系Config 数据类与三级覆盖所有可调旋钮都集中在 constants.py 的Configdataclass 上活跃实例为constants.cfg其余代码统一读取cfg.field做到单一事实来源。覆盖优先级为后写者胜TOML 文件复制 config.example.toml设置所需字段并将CU_CONFIG指向该文件。按字段的环境变量CU_FIELD_NAMEvalue叠加在 TOML 之上。CLI 的--set FIELDVALUE。两者都可放在.env或 shell 中。示例# 一次性关闭浏览器工具并提高 JPEG 质量 CU_ENABLE_BROWSER_USE_TOOLSfalse CU_JPEG_QUALITY85 \ python -m computer_use open Notes and type hello # 通过环境变量钉住视口字符串会被强制转换为元组 CU_BROWSER_VIEWPORT1280x720 python -m computer_use ... # 或保留一个 config.toml 并从 .env 指向它 # .env: CU_CONFIGconfig.toml # config.toml: # enable_advisor_tool true # image_prune_strategy none # extra_models [some-beta-model]字符串值会被强制转换为声明字段类型true→True、80→80、1280x720→(1280, 720)、可选 int 的none→None。从源码看这一强制转换由 constants.py 的_coerce()实现支持 bool / int / float / tuple以x或,分隔等dict 类型字段不能从字符串设置必须走 TOML会显式抛ValueError。功能开关速查表字段默认值作用enable_computer_use_toolstruecomputer、computer_batch、open_applicationpyautogui 屏幕控制。此项与 browser 至少开一个。enable_browser_use_toolstruebrowser、browser_batch无头 Playwright。enable_editor_tooltrueeditorview/create/str_replace/insert限定在每次运行的 scratch 目录内bash/python 共享同一工作区。同时向系统提示词追加 TODO.md 指引。enable_advisor_toolfalse服务端 Advisor 工具执行模型在生成过程中可咨询更强大的advisor_model默认 Opus。enable_autocompactiontrue服务端compact_20260112输入 token 超过autocompaction_trigger_tokens时服务端总结较早的上下文。仅对支持的模型Sonnet/Opus生效。image_prune_strategyintervalnone保留全部截图simple只保留最近 N 张对缓存不友好interval在image_prune_interval轮内保持前缀稳定。详见下文。print_usagetrue每轮打印[usage]行含 token 数与缓存效率。extra_models()--model额外接受的模型 ID内置枚举之外的旧版或 beta 模型。其余Config字段都是数值型可调项重试次数、JPEG 质量、视口尺寸、advisor 上限等每个字段的注释都在 constants.py 中。几个值得注意的默认值jpeg_quality75与桌面应用 Swift 编码器一致是大小/保真度的良好折中、browser_viewport(1456, 819)截图天然落在视觉 token 预算内、无需缩放、max_shell_output_bytes64KB防止yes之类的命令在 30 秒超时前撑爆内存、api_retry_max_attempts5指数退避重试可恢复错误4xx 直接抛出。显式工具 vs. 托管 computer 工具默认情况下本 demo显式定义每个工具computer工具的名称、描述与 JSON Schema 全部在 computer_use/tools/computer.py 中你可以直接阅读并编辑模型看到的内容不受任何服务端默认值干扰——这正是参考实现的要义。代价是安全分类器的覆盖范围。API 的 computer-use 专用安全分类器包括对截图内容的提示注入检测仅在请求声明 Anthropic 定义的 computer 工具时才运行。使用显式 Schema 时请求走的是通用安全路径你必须依赖自己的提示注入缓解措施系统提示词的指令、本 README 顶部推荐的 VM 隔离以及你自己的监控。若希望在保留其余 demo 功能的同时启用这些分类器设置cfg.use_hosted_computer_tool True或CU_USE_HOSTED_COMPUTER_TOOLtrue。只有computer工具的定义声明会变computer_batch、browser、bash等仍是显式的且所有工具仍在本地执行。在第一方 API 上托管声明是 computer工具集toolset{type: computer_toolset_20260801}—— 一个无名条目为每个动作声明一个成员工具无需 beta 头、无显示尺寸坐标一律是截图像素由你发送的截图确立坐标系。自己写循环时工具集有三点值得了解本仓库的 loop.py 逐一示范了成员调用是普通的tool_use块以动作命名left_click、zoom…带toolset_name: computer输入中无action字段。ToolCollection.run按(toolset_name, name)路由并把名称折回action因此显式的ComputerTool同时服务两种声明。每个成员——包括工具集默认启用的zoom——都有实现。一轮可能携带多个成员调用。它们按块顺序串行执行第一个失败后其余调用以is_error: true和约定的Not executed: …文本应答而不执行因为后面的动作都假设前面的成功了。这正是显式工具下computer_batch提供的能力工具集原生实现了它。每个成员的tool_result必须携带与其tool_use相同的toolset_name普通工具的结果则不能带。_tool_result_block负责打上该标记包括 Ctrl-C 填充的[interrupted by user]结果。Vertex 和 Bedrock 尚未提供工具集因此在这些 Provider 上托管模式回退到带日期的computer_20250124工具及 beta 头Config.hosted_computer自动选择此时模型以name: computerinput.action调用即显式工具自身的外形。从 computer.py 可以看到两种托管声明的生成代码。显式工具的内部实现要点在 computer.py 中可以读到几个值得注意的实现细节动作全集screenshot、单/双/三击、左右中键点击、mouse_move、left_click_drag、scroll、type、key、hold_key、left_mouse_down/up、cursor_position、剪贴板读写、wait、zoom共 19 个动作input_schema中全部有枚举与参数描述。坐标缩放模型看到的是缩放后的截图模型发出坐标后_scale_to_screen()用x * screen_w / sent_w将其换算回逻辑屏幕像素并对 retina 屏先降采样pyautogui 截图是物理像素、鼠标函数接收逻辑像素。键名别名模型习惯发 xdotool 风格键名工具内置_KEY_ALIASES映射如control→ctrl、super/cmd/meta→command、return→enter、win→command尤其注意delete→backspace的映射——macOS 上 pyautogui 的 delete 是 Forward-Delete模型说 delete 时几乎总是指退格键。布局无关输入_type_text()不用 pyautogui 的write()它会发送 ANSI 虚拟键码在 Dvorak/AZERTY 等布局下打出错误字符而是通过CGEventKeyboardSetUnicodeString直接投递 Unicode 字符串事件任何布局都逐字插入。Schema 与实现防漂移base.py 的__init_subclass__在导入时校验input_schema声明的每个属性都必须是execute()的关键字参数required字段不得有默认值——schema 与实现无法静默分叉。Provideranthropic / vertex / bedrockcfg.provider选择 API 表面anthropic默认第一方 API、vertexGoogle Cloud经AnthropicVertex、bedrockAWS经AnthropicBedrock。各 Provider 所需的凭据见.env.example。Vertex 和 Bedrock 有第一方 API 没有的请求体大小上限。demo 在图片裁剪器中强制执行保守阈值Vertex 18 MB、Bedrock 11 MB见 constants.py 的PROVIDER_MAX_MESSAGE_MB序列化消息列表超过上限时强制裁剪到cfg.image_prune_min张并重置间隔周期使后续轮次从小的状态开始。Advisor 工具与服务端自动压缩是第一方专属 beta 功能。在provider ! anthropic时启用任一项启动即抛ValueError并指名冲突配置见 constants.py 的__post_init__将其设为False或切换 provider即可继续。有效的缓存与上下文裁剪computer-use 轨迹几乎每轮都会新增一张截图而每张截图约1,500 输入 token。30 轮后仅图片历史就有约 45k token且每次 API 调用都要重新发送并付费。本仓库用两个机制控制这一点提示缓存Prompt cachingloop.py 在系统提示词上放置一个cache_control: {type: ephemeral}断点并在最近用户回合的最后一个 tool-result 块上放置另一个。下一次调用时API 可以从缓存提供该断点之前的所有内容约为输入 token 价格的 10%且延迟明显更低。每轮打印的[usage]行显示cache_read与in的对比便于观察命中率。源码中还做了缓存断点阶梯处理_MAX_BODY_CACHE_BREAKPOINTS 3在偶尔前缀移位例如裁剪间隔回滚的回合较早的断点仍能命中。图片裁剪Image pruninginterval 策略为何对缓存友好提示缓存仅在请求前缀逐字节相同时才有用。朴素的保留最近 N 张、更旧的替换为占位符方案一旦超过 N每轮被替换的旧图都不同前缀每轮都变、缓存每轮都 miss。cfg.image_prune_strategy interval默认值实现在 computer_use/formatters.py 的StripImagesAtIntervals通过让保留数量从cfg.image_prune_min阶梯式爬到cfg.image_prune_min cfg.image_prune_interval - 1再回落来规避在连续image_prune_interval轮内相同的旧图映射到相同的占位文本前缀保持一致缓存持续命中。你每image_prune_interval轮付一次缓存写入而不是每轮一次。策略设为none完全禁用裁剪simple则用于对比观察缓存不友好的行为StripOldestImages。此外该裁剪器还内建请求体大小兜底超出max_message_mb时强制裁剪并重置周期formatters.py。裁剪 vs. 服务端上下文总结cfg.enable_autocompaction开启 API 的服务端上下文管理编辑总输入 token 越过cfg.autocompaction_trigger_tokens后服务端用一次独立子调用把迄今对话浓缩成简短摘要块客户端下一轮丢弃该块之前的全部内容loop.py 的_truncate_to_last_compaction还会主动截断以让裁剪器在模型实际看到的切片上工作。两者都限制上下文规模但权衡不同总结是更昂贵的事件。它是完整的一次额外 API 回合整个对话进、多段摘要出且下一轮因前缀全新而冷缓存。相比之下interval 裁剪回滚只重新处理变化的尾部、不产生输出 token。短期内裁剪更快更便宜但长期跨越很多未来回合可能更贵且图片裁剪永远不会删除用户/助手消息这些文本会随时间累积。总结保留更多信息。摘要保留了发生了什么的文本记录裁剪直接删除旧截图。这就是cfg.image_prune_min重要的原因设得足够高让模型在回滚后仍有需要的视觉上下文。只有当裁剪确实避免了一次总结时才值得。缓存读取比未缓存输入便宜约一个数量级因此多携带一张已缓存的截图成本几乎为零而丢弃它会强制重新缓存其后的所有内容。在短小、截图少的任务上最便宜的设置反而是完全不裁剪。长截图重任务上裁剪胜出。当仅图片就会越过触发阈值时每image_prune_interval张一次的低成本回滚远便宜于让对话命中总结这也是延迟分歧最大的地方——总结子调用的输出 token 生成缓慢即使美元成本接近回滚也快得多。默认值image_prune_min3、image_prune_interval40、autocompaction_trigger_tokens150_000后者的 API 下限为 50k低于下限会被钳制并打印提示经过调优截图重的运行在到达总结触发前先裁剪截图轻的运行两者都不做。如果你的负载持续很短设image_prune_strategynone、让总结充当罕见的兜底若持续很长且视觉密集降低image_prune_interval、把总结留给裁剪无法移除的文本。Advisor 工具实验性这不是通用推荐请在自己的负载上试用以判断质量提升是否值得额外成本与延迟。设置enable_advisor_tool trueCU_ENABLE_ADVISOR_TOOLtrue或config.toml执行模型即可在生成过程中咨询更强大的 advisor 模型默认 Opus获取策略性指导。这是本仓库中唯一不在computer_use/tools/中定义的工具它完全运行在 Anthropic 侧没有客户端execute()。循环将其声明在tools数组中、向系统提示词追加 advisor 使用指引时机建议与如何权衡建议、在建议到达时以暗色文本渲染并在后续回合回传结果块。每cfg.advisor_reminder_interval轮若没有 advisor 调用会向工具结果追加一条简短提醒。相关配置字段advisor_model、advisor_max_uses每请求上限、advisor_max_conversation_uses达到后循环丢弃 advisor 并从历史中剥离其结果块因为 API 会拒绝孤儿结果、advisor_cachingadvisor 侧提示缓存大约每会话 3 次 advisor 调用即可回本因此默认5m适合 agent 循环、advisor_reminder_interval。每轮[usage]行会为每次 advisor 调用增加一行显示 advisor 模型的 token与执行模型分开计费。系统提示词中的 advisor 使用指引全文包括实质性工作前先调用、任务完成前先保存成果再调用、卡住或更换方案时调用等策略见 constants.py 的ADVISOR_PROMPT_ADDENDUM。运行测试与源码布局python -m pytest仓库目录结构节选constants.py Config dataclass cfg 实例、提示词、派生集合 config.example.toml CU_CONFIG 覆盖的模板 computer_use/ __main__.py CLI 入口、build_tools()、build_system_prompt() loop.py 流式采样循环、重试、advisor/compaction 接线 image.py target_image_size JPEG 编码 尺寸 sanity 检查 formatters.py 缓存感知的截图裁剪interval/simple render.py 终端输出回合头、增量、usage、横幅 preflight.py macOS 屏幕录制 / 辅助功能权限检查 trajectory.py 磁盘转录 图片 每次运行的 scratch 目录 tools/ base.py Tool 抽象基类 ToolCollection result.py ToolResult image/document 内容块辅助 computer.py pyautogui 屏幕控制含 zoom、键名别名 browser.py playwright 无头 chromium batch.py computer_batch / browser_batch editor.py scratch 目录中的 view/create/str_replace/insert shell.py 沙箱化 bash python带输出上限 open_app.py open -a ... sandbox/default.sb sandbox-exec 配置文件 dev_ui/ assets/anthropic.css 所有 dev UI 的共享设计令牌 trajectory_viewer/ streamlit 转录查看器 tool_panel/ FastAPI 工具测试台每工具表单、点击取坐标 localization_demo/ 标签定位演示缩放/回缩放往返小结computer-use-best-practices的核心价值在于透明工具定义显式可见、截图缩放算法精确可查、缓存与裁剪策略在 formatters.py 中可直接阅读、批量工具、沙箱 shell、轨迹回放与手工调试面板一应俱全。把它当作一个可阅读、可修改的教学脚手架在一次性 macOS 虚拟机中运行配合本仓库的 computer-use-demoDocker X11与 browser-use-demoDocker Playwright即可从零搭建并逐步打磨你自己的 Claude computer-use / browser-use 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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考