如何用 Tool Panel 脱离模型手动调试 Computer Use Agent 的工具调用？

如何用 Tool Panel 脱离模型手动调试 Computer 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在调试 computer use agent 时工具调用出了问题往往难以判断是工具实现有 bug、参数没传对还是坐标缩放算错了claude-quickstarts仓库里的 computer-use-best-practices 项目提供了一个 Tool Panel——一个 FastAPI 调试页面可以脱离模型不发起任何 API 调用手动逐个触发 agent 的每一个工具查看返回的 JSON 和截图。本文基于该项目文档介绍如何启动 Tool Panel、手动触发工具调用以及用截图点击功能核对坐标换算。适用前提该项目面向macOS关键处理、pyautogui后端和sandbox-exec都是 Mac 专属Linux 变体不在范围内需要Python 3.11macOS 自带的python3是 3.9不可用需先安装如brew install python3.13之类的更新解释器。准备工作装好依赖并授予 macOS 权限Tool Panel 复用了 agent 的工具集合所以依赖安装与跑 agent 本身相同在项目根目录computer-use-best-practices/下执行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 chromium后续命令可加uv run前缀代替激活 venv。权限方面工具真正跑起来需要终端拥有两项 macOS 权限在System Settings → Privacy Security中授予Screen Recording截图用的没有它截图会是黑屏Accessibility模拟鼠标键盘输入用的没有它点击和按键会被静默丢弃。授予后需要完全退出并重新打开终端macOS 只在应用启动时重新读取这些权限。文档指出缺权限时的典型症状——截图返回黑屏、点击/按键被静默丢掉——看起来像是模型的失败这正是 Tool Panel 的价值把模型环节去掉后这类现象可以直接归因到权限或工具本身。启动 Tool Panel在项目根目录下执行命令来自 README 的 Tool panel 一节python -m uvicorn dev_ui.tool_panel.server:app --reload然后打开http://127.0.0.1:8000。服务端逻辑很短在 server.py 中可以完整看到四个端点GET /返回静态页面GET /tools返回工具参数调用build_tools().to_params()即 agent 实际使用的工具集GET /preflight返回权限状态POST /run接收{tool, input, delay}并执行对应工具。页面加载时会请求/tools为每个工具自动生成一张表单卡片表单字段直接来自工具的input_schema——所以你看到的每个输入框就是模型发起调用时要填的字段包括 enum 下拉、数字输入和需要填 JSON 的数组字段。按 build_tools() 的默认配置computer 和 browser 工具均开启面板上会列出computer、computer_batch、open_application、browser、browser_batch、bash、python等工具editor工具因为需要按运行分配的 scratch 目录才启用在面板里不会出现。工具列表可通过config.toml或CU_FIELD环境变量调整README 的 Configuration 一节有开关说明如enable_computer_use_tools、enable_browser_use_tools两者至少一个为 true否则启动时抛ValueError。手动触发一次工具调用页面左侧是每个工具的表单右侧是结果区。操作路径在对应工具的卡片里填写输入字段。空字段不会出现在提交的input中。设置delay秒数页面上默认是 3点击 Run 后先倒计时给你时间把焦点切换到目标窗口倒计时结束动作才真正执行。只想验证screenshot这类无副作用的动作时delay 可以设 0。点击Run请求会发到/run页面在结果区展示返回内容{ ms: 123, error: null, meta: { } }其中ms是执行耗时error非空说明工具执行失败content块文本和截图会追加渲染在 JSON 下方——截图直接内联显示在结果区。这个 JSON 结构对应 server.py 中/run的返回值{ms, error, content, meta}。如果你不用浏览器也可以直接对端点发请求。文档中模型侧的调用形如computer({action: screenshot})对应的/run请求体就是curl -X POST http://127.0.0.1:8000/run \ -H content-type: application/json \ -d {tool: computer, input: {action: screenshot}, delay: 0}成功条件返回 JSON 中error为空且结果区出现截图图像或对应工具的文本输出。用截图点击核对坐标换算computer use 工具的一个高频问题点是坐标空间不一致模型看到的是缩放后的截图像素坐标执行时需要换算回屏幕像素。Tool Panel 内置了最快的检查方式README 原话the fastest way to sanity-check coordinate scaling先跑一次会返回截图的工具例如computer的screenshot截图显示在右侧结果区把某个coordinate输入框点击聚焦页面记住最后聚焦的坐标字段直接点击结果区的截图任意位置。顶部的坐标栏会显示两条信息image px: [x, y]你点击的图像像素位置同时会自动填进坐标输入框和screen px: [x, y]换算到屏幕像素的位置。换算依据meta里的sent_size和screen_size即发送给 API 的图像尺寸和真实屏幕尺寸这一对值由 computer.py 在截图时写入。如果你发现换算后的屏幕坐标与预期不符问题就出在缩放链路上而不是模型。权限缺失时面板给出的提示打开页面后若/preflight报告权限缺失页面顶部会出现一个红色横幅列出缺少的权限Screen Recording 和/或 Accessibility并提示 Grant them in System Settings Privacy Security, then restart this server。处理方式是到对应设置面板开启终端的权限开关完全退出终端后重开再重启面板或让--reload之外的进程重启横幅本身不会刷新权限状态因为权限是进程启动时读取的。另注意 macOS 15Sequoia及以上还会在首次截图时弹出独立的 bypass the system private window picker 系统对话框之后大约每月一次点Allow即可它是 macOS 层的重新授权与上面的开关相互独立。限制与下一步Tool Panel 与 agent 共用同一套工具实现computer工具执行时会操作你真实的鼠标键盘、bash/python会在本机跑命令。README 开头明确警告agent 拥有对屏幕、鼠标、键盘的完全控制权且无防护强烈建议在一次性 macOS VM 中运行。调试无副作用的工具screenshot、browser可以在本机进行但触发点击、输入前确认当前桌面状态。面板不包含advisor等纯服务端工具也不产生runs/轨迹记录——轨迹记录是 agent 会话python -m computer_use ...的行为。确认某个工具单独执行没问题之后下一步是回到完整的 agent 会话验证同一工具在模型调用下是否表现一致并用文档给出的轨迹查看器复盘python -m computer_use open TextEdit and type hello world python -m streamlit run dev_ui/trajectory_viewer/app.pyviewer 会把每次运行的工具调用和截图按对话形式渲染出来便于对照面板手动执行时的结果。【免费下载链接】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），仅供参考