企业官网建设流程全解析

如何用 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.11+（macOS 自带的python3是 3.9，不可用，需先安装如brew install python@3.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）。

手动触发一次工具调用

页面左侧是每个工具的表单，右侧是结果区。操作路径：

1. 在对应工具的卡片里填写输入字段。空字段不会出现在提交的input中。
2. 设置delay（秒数，页面上默认是 3）：点击 Run 后先倒计时，给你时间把焦点切换到目标窗口，倒计时结束动作才真正执行。只想验证screenshot这类无副作用的动作时，delay 可以设 0。
3. 点击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"）：

1. 先跑一次会返回截图的工具（例如computer的screenshot），截图显示在右侧结果区；
2. 把某个coordinate输入框点击聚焦（页面记住最后聚焦的坐标字段）；
3. 直接点击结果区的截图任意位置。

顶部的坐标栏会显示两条信息：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 15（Sequoia）及以上还会在首次截图时弹出独立的 "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.py

viewer 会把每次运行的工具调用和截图按对话形式渲染出来，便于对照面板手动执行时的结果。

【免费下载链接】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