Gemini 4 Computer Use 配置教程：浏览器、桌面与 Android

Gemini 4 Computer Use 提出屏幕操作；你的应用负责执行，并返回新的观察结果。 起步需要 Google Interactions API、gemini-4-hydrogen 等受支持模型，以及 environment 与执行器匹配的 computer_use 工具。设置 environment: "desktop" 不会自动赋予模型电脑控制权，也不会安装操作系统驱动。

本文带你搭建小型浏览器示例，说明迁移到桌面和 Android 时需要改变什么，并提供含明确确认与停止逻辑的完整控制器。文档和软件包核对日期为 2026 年 11 月 13 日。Google 当前的 Computer Use 文档列出了 Carbon、Argon 和 Hydrogen。示例使用 Hydrogen，模型之间的选择另见 Gemini 4 模型选择指南。本文引用的原厂文档为英文。

本文由 Ofox 发布。验证证据包括 22 项使用合成模型响应的离线测试，以及通过独立 UI 工具实际操作 Chrome 本地测试页。配套 Python Playwright 运行器没有接入模型运行，也没有完成端到端验证。我们未进行付费推理、桌面或 Android 执行器测试，也未测量模型性能。复用代码时，应明确哪些环节已有证据，哪些仍需在你的环境中验证。

先确定 API 协议，再选择执行环境

Computer Use Agent 包含三个环节：模型提出动作，执行器实施支持的动作，验收器检查应用结果。后两者需要你提供。模型最后说“完成”，不能证明表单已提交、文件已保存或按钮已点击。

整个循环应使用同一种协议。本文采用 Interactions，涉及 steps、function_call、function_result 和 previous_interaction_id。我们核对的官方参考仓库，commit 为 77c9797e943aad63bbc963b7fd092a9e51c07863，使用的是 GenerateContent；源码还区分了当前动作与旧预览版动作。它可供参考，但不能把其中的响应解析器原样复制进 Interactions 循环。

Google 项目和 Key 的准备步骤见 Hydrogen API 接入指南。本例将 Google Key 放入 GEMINI_API_KEY。Ofox Key 则用于 Ofox 单独说明的鉴权流程。

Ofox 提供 Chat Completions 文档和 Gemini 原生协议入口。支持某个通用协议，不等于已经支持 Google 当前的 Interactions Computer Use 协议。因此本文使用 Google 原生入口，不声称把 Base URL 换成 Ofox 就能运行该浏览器循环。如果任务只需要仓库文件工具，可参考另一种接入方式：Hydrogen 配置 Cline 与 OpenCode。

安装本地代码包，不用模型 Key 先做验证

下载完整 Computer Use 测试代码包，解压并进入 gemini-computer-use-kit 目录。包内含控制器、离线测试、本地 HTML 测试页、可选在线运行器和 README，无需自行补齐片段中省略的代码。代码注释和 README 为英文，下面提供完整操作说明。

本文核对的软件包版本要求使用 Python 3.11 或更新版本：

python3 -m venv .venv
source .venv/bin/activate
python -m pip install 'google-genai==3.3.0'
python test_controller.py

Windows PowerShell 使用 .venv\Scripts\Activate.ps1 激活环境，替代 source。离线检查无需 Playwright 或 API Key，预期结果为 22 项测试通过。我们也从下载包重新解压后运行了测试，而非只测试工作目录中的文件。

测试使用真实 google-genai 响应类、合成数据，以及记录动作的模拟页面。覆盖坐标校验、调用 ID 匹配、产生副作用前拒绝无效批次、确认与拒绝、重复调用、未完成响应、超时和动作上限。它们不启动浏览器，也不能证明 Google 会接受某个真实请求。

要接入独立的浏览器运行流程，再安装 Playwright 及其浏览器：

python -m pip install playwright
python -m playwright install chromium

在代码包目录另开一个终端，启动本地测试页服务：

python -m http.server 8877 --bind 127.0.0.1

打开 http://127.0.0.1:8877/fixture.html。应看到英文页面要求输入 ORANGE-42，一个空白的 Marker 输入框和 Check marker 按钮。手动输入并点击，先确认页面自身工作正常。随后重新加载，让 Agent 从空输入框开始，而非面对已经完成的任务。

真实 Chrome 截图，视口为 1000 × 700，通过独立 UI 工具操作本地测试页。它证明页面的可见行为，不证明 Hydrogen 或配套 Python 运行器完成了任务。截图过程未连接模型。

运行可选的 Google 浏览器接入流程

保持本地 HTTP 服务运行。在已激活的 Python 环境中，使用常用的密钥管理方式设置 Google GEMINI_API_KEY。不要把 Key 放进测试页或提交到源码仓库。下面的命令会调用真实服务，可能消耗项目额度或产生付费使用；它与前面的无模型离线测试不同。

python run_live.py

运行器建立全新的浏览器上下文：视口为 1000 × 700 CSS 像素，设备缩放因子为 1，阻止 service worker，禁用下载。浏览器请求过滤器只允许测试页的精确 URL。这是为了约束演示范围，不是操作系统沙箱，也不是面向任意网站的通用防护。

运行器中的完整任务提示词为：

Read the local page instructions. Enter the marker in its field and click Check marker. Stop when the page shows PASS. Stay on this page.

意思是读取本地页面说明，输入标记，点击 Check marker，看到 PASS 后停止，并始终留在此页面。首次请求包含这段提示词、初始截图和 Computer Use 工具。关键设置如下：

interaction = client.interactions.create(
    model="gemini-4-hydrogen",
    input=[
        {"type": "text", "text": task_prompt},
        {"type": "image", "data": screenshot_base64, "mime_type": "image/png"}
    ],
    tools=[{
        "type": "computer_use",
        "environment": "browser",
        "enable_prompt_injection_detection": True
    }],
    timeout=120.0,
    automatic_continuation=False
)

此片段用于说明请求边界，实际运行请使用完整代码包。代码包还排除了未实现的预定义动作，执行器也会拒绝它们。本例仅实现 click、type、wait 和 take_screenshot，不会把不支持的动作静默报告为成功。

需要确认时，终端会显示动作意图和解释。仅在同意该动作时输入 APPROVE，其他输入都会停止运行。应用级成功条件是页面结果元素精确显示 PASS: ORANGE-42，满足后保存 result.png。即使模型停止，如果页面仍显示“Waiting for input”，也无法通过验收。

我们没有执行该在线运行器，因此你在自己账号下成功运行的结果才构成新的验证证据。记录客户端版本、模型 ID、实际结果和用量。不要将离线测试时长当作模型速度，或把模拟响应当作账单数据。

对齐坐标、截图与调用 ID

Google 当前动作使用 0 到 999 的归一化整数坐标，按 1000 单位的坐标轴缩放。应按执行器实际观察图像的尺寸换算：

def to_pixel(value, size):
    if type(value) is not int or not 0 <= value <= 999:
        raise ValueError("Expected an integer coordinate from 0 to 999")
    return int(value * size / 1000)

在 1000 × 700 截图中，合成动作坐标 (400, 500) 对应 CSS 像素 (400, 350)。这只是坐标换算示例，不是记录到的 Hydrogen 预测。代码包在执行前验证坐标，并使用 scale="css" 截图，使浏览器坐标系保持一致。

不要把全桌面截图与浏览器视口坐标混用，也不要裁剪后忘记偏移量。高 DPI 桌面的截图像素与输入坐标可能不同，手机旋转还会引入新的变换。API 请求成功，不能弥补执行器在错误坐标系中点击的问题。

每个动作执行后，都要返回对应调用 ID、当前 URL 和新的截图。代码包结果结构如下：

{
  "type": "function_result",
  "name": "click",
  "call_id": "the-id-from-the-model-function-call",
  "result": [
    {"type": "text", "text": "{\"url\":\"http://127.0.0.1:8877/fixture.html\"}"},
    {"type": "image", "data": "BASE64_OF_NEW_SCREENSHOT", "mime_type": "image/png"}
  ]
}

上面的占位符仅用于解释，不能原样发送。如果一次响应包含多个调用，每个已执行调用都需要匹配的结果。下一次请求的 previous_interaction_id 应指向包含这些调用的 interaction。interaction ID 与函数调用 ID 不能互换。

此示例依赖保存的 interaction 状态。添加 store=False 前，应依据 Interactions 文档重新设计历史处理。如果使用其他协议或自行管理历史，必须原样保留所需模型状态与签名。Gemini 缺失思考签名排查指南解释了一种故障模式，但不代表本文示例已通过真实签名调用测试。

将执行器适配到桌面或 Android

环境字段告诉模型使用哪套动作词汇，不会创建浏览器、虚拟机、桌面会话或手机。Google 的环境参考区分了三个目标：

下载包仅实现浏览器测试页。适配桌面时，保留请求与结果循环，替换浏览器 page 操作：

1. 使用专门的测试桌面或虚拟机，先限定单显示器和固定尺寸，避免混入无关窗口的个人会话。
2. 独立验证屏幕捕获并记录图像宽高；连接模型前，在本地测试应用中单独验证一次无害输入。
3. 将归一化坐标映射到输入系统。若捕获库返回设备像素，而输入库使用逻辑坐标，应一致地缩放观察图或应用明确的比例变换。
4. 为每个支持的桌面动作绑定明确处理器，包括指针点击、文本插入、按键、滚动与新截图。排除或拒绝未实现动作；浏览器导航不是通用桌面动作。
5. 将工具环境改为 desktop，保留调用 ID 与结果对应关系，并在首次动作后检查应用状态。仅看到指针移动不足以证明成功。

macOS 的屏幕录制权限与辅助功能控制权限彼此独立。能截屏不代表目标进程能点击或输入。只向你主动安装的执行器授予必要权限；这些设置不需要更换 Gemini API Key。Windows 和 Linux 需要各自的截屏、输入后端与会话检查，浏览器代码包没有提供这些驱动。

对于 Android 设备或模拟器，先按官方 Android Debug Bridge 说明建立设备连接与截图路径。连接已授权的测试设备后，可用下面的命令识别设备并取回截图，全程不调用 Gemini：

adb devices
adb -s YOUR_TEST_SERIAL shell screencap /sdcard/computer-use-test.png
adb -s YOUR_TEST_SERIAL pull /sdcard/computer-use-test.png ./computer-use-test.png

将序列号替换为目标测试设备，不能随意选多设备列表中的一项。显示 unauthorized 时，必须先在设备上授权。打开取回的 PNG，确认是预期测试应用，并为首次运行锁定方向。

然后实现该设备的移动动作映射：click 在坐标转换后执行点击；type 向当前聚焦字段输入；go_back 执行系统返回；open_app 和 list_apps 必须解析实际应用包标识。如果启用拖动和长按，也要明确实现其行为。执行后返回新设备截图，再将 environment 设为 mobile，运行一个小型测试应用任务。Google 文档中的移动动作集针对 Android 优化，不证明这套 ADB 流程能控制 iPhone。

本文没有在设备上测试上述桌面或 Android 步骤。它们用于明确接入工作与验收点，而不是暗示改一个环境字符串就完成了移植。

明确处理确认、停止与恢复

模型的 intent 是动作解释，不是授权。函数调用包含 safety_decision.decision: "require_confirmation" 时，应暂停等待用户确认。Google 的安全决策文档要求确认后再返回确认标记。代码包仅在用户同意后，将 safety_acknowledgement: true 加入动作结果的文本中。

控制器先验证整个批次，并在执行任何动作前取得所有必要确认。遇到不支持的动作、格式错误的安全元数据或其他明确决策状态，会停止。这是针对测试页采用的保守策略。缺少安全决策字段，不代表可以绕过应用自身关于用户已授权任务的规则。

默认上限为 12 个动作批次、每次模型请求 120 秒，并禁用自动续接。这不是全局时限或金额预算：人工确认可能等待，一个批次可含多个动作，截图与重复上下文也会计入用量。SDK 还可能执行传输层重试，我们没有承诺零重试或固定费用。

如果点击后的下一次请求超时，点击可能已经发生。应用不会自动重放该动作。应停止并检查真实页面，保留 interaction 与调用 ID，再决定继续原对话还是建立新任务。不要盲目重启结果未知的表单提交。本地测试页可以先检查输入与结果，再重新加载清空状态，开始新的测试。

动作之后的截图或浏览器故障不能回滚已经执行的操作。生产流程应定义适合应用的独立结果检查，例如已保存记录的 ID 或文档值变化。可见标记只适用于这个简单测试页，不是通用事务验收器。此前的离线 Computer Use 控制器实验介绍了另一种面向 OpenAI 的控制器与接收端核验方法。

在产生故障的层级排查

鉴权、额度和请求格式问题也可参考 Gemini API 错误指南。该文围绕 Argon 编写，应结合实际 Hydrogen 响应使用通用错误分类，而非假定模型专属细节全部适用。若排查的是另一条 Ofox 路由，请使用该路由的 Ofox 错误处理文档，不能用它替代 Google 项目诊断。

判断你需要 API 循环还是现成 Agent

如果需要掌控执行器、确认行为、观察和应用验收，适合使用这种 API 接入。如果只是想使用现成桌面产品，Antigravity 平台概览 (英文)对应另一种起点。Chrome 扩展、Computer Use 与远程控制对比也区分了这些产品类别。

离开测试页之前，保存模型与 SDK 版本、所选 API、环境、截图尺寸、已实现动作清单、确认策略与独立成功条件。测试记录应区分离线控制器检查、浏览器操作和真实模型推理。本代码包只有前两类证据，而且浏览器检查独立于 Python 运行器完成。

下一步应让目标账号、执行器与验收器共同完成一个真实任务。结果可观察、可重复后，再扩展动作集或迁移到桌面、移动端。模型能力增强，并不能省去对“实际执行了哪个动作、改变了什么”的核查。