用 Gemini Computer Use 跑通一个浏览器智能体

Computer Use 不是托管浏览器，而是「模型提议动作、你的代码负责执行」的循环。这篇按 Google 官方参考实现，在隔离环境里跑通一个能按自然语言操作浏览器的智能体，并给出一份上线前的护栏清单。

这篇教程解决什么

目标：用 Google 官方参考实现，在一个隔离环境里跑出一个能按自然语言操作浏览器的智能体 —— 你给它一句话，它读截图、决定点哪里，由你的代码真的点下去，循环到任务完成。

读完你会得到三样东西：一套能照做的命令行步骤；一张「谁提议、谁执行」的责任边界表；一份上线前建议装齐的护栏清单。

本文明确不覆盖：不做效果评测，不与其他厂商横比，不给具体金额；也不替你判断「该不该让 AI 碰真实账号」—— 那是你的风险管理，本文只给可执行的缓解手段。

先说清一个口径问题。Computer Use 此前长期处于预览状态，多家第三方在 2026 年 10 月 30 日报道它转为正式可用；本文写作时本机无法直读官方文档页（ai.google.dev 连接超时），所以凡涉及支持状态、模型清单、字段名与默认值，一律以官方文档当期页面为准。这不是客套：第 8 步就会遇到「仓库 README 与官方文档口径不一致」的真实例子。

开始前的准备

• 隔离环境：沙箱虚拟机、容器，或一个权限受限的专用浏览器配置。不要用日常登录着个人账号的浏览器跑 —— 智能体看到的截图里可能带着你的会话状态，而它会据此提议动作。
• Python 环境：能用虚拟环境隔离依赖的版本；版本要求以仓库当期的依赖清单为准。
• 凭据：Gemini Developer API 需要接口密钥；走 Vertex AI 则需要项目 ID 与区域。两者的环境变量不同（见第 4 步）。
• Playwright：负责真实点击与输入，浏览器由它启动。
• 官方参考实现：仓库 google-gemini/computer-use-preview，Apache-2.0 许可，默认分支 main，GitHub 公开数据显示最近一次推送是 2026 年 7 月 28 日 —— 这意味着仓库可能滞后于官方文档，别只看一边。
• 成本认知：调用按所用模型的 token 计费，价格以官网为准。跑在你自己机器上的浏览器与 Playwright 不收费，收费的是每次带着截图往返的那部分调用。
• 心态：你正在给一个会点鼠标的程序开窗口。它不会替你承担后果，后果由你的护栏承担。

步骤详解

第 1 步：先把隔离环境做好

做什么：准备一个沙箱容器或虚拟机，也可以是一个干净且权限受限的浏览器配置。让它只跑这一次任务，不要用你日常登录着邮箱与支付账号的那一个。

看到什么算成功：环境启动后是一个干净的系统与干净的浏览器，没有你的个人会话、没有可随手访问的宿主机敏感目录，网络访问可控（必要时只允许特定域名）。

为什么把它放在第一步：官方文档把这个要求放在代码实现之前。模型提议的每个动作都由你的客户端执行，隔离层是你在「由自己执行」这件事上仅有的止损线。

第 2 步：拿到官方参考实现

做什么：克隆仓库并进入目录。

git clone https://github.com/google-gemini/computer-use-preview.git

cd computer-use-preview

看到什么算成功：目录里有 main.py、requirements.txt 与 computers/ 目录。建议先看一遍仓库内的说明文件 —— 它与官方文档并不完全同步，两边都要看。

第 3 步：建虚拟环境并安装依赖

做什么：隔离 Python 依赖，再安装浏览器。

python3 -m venv .venv

source .venv/bin/activate

pip install -r requirements.txt

playwright install-deps chrome

playwright install chrome

看到什么算成功：依赖安装完成且没有编译错误；后两条命令执行完后，Playwright 所需的系统依赖与 Chrome 都已就位。常见的失败是缺系统级依赖导致浏览器起不来，这时 playwright install-deps 通常能补齐。

第 4 步：配置凭据

做什么：两种方式二选一。用 Gemini Developer API：

export GEMINI_API_KEY="YOUR_GEMINI_API_KEY"

用 Vertex AI 则要显式声明，并提供项目与区域：

export USE_VERTEXAI=true

export VERTEXAI_PROJECT="YOUR_PROJECT_ID"

export VERTEXAI_LOCATION="YOUR_LOCATION"

仓库也提供了以文件方式配置的路径，适合本地长期使用：

cp .env.example .env

看到什么算成功：不必把密钥打印出来，也能跑通第一条指令。建议把环境变量写进虚拟环境的激活脚本，或直接用环境文件，避免每次手动导出 —— 但不要把它们提交进版本库。

第 5 步：跑第一条指令

做什么：先跑仓库给出的最小任务，不要一上来就换成自己的业务网址。

python main.py --query="Go to Google and type 'Hello World' into the search bar" --env="playwright" --initial_url="https://www.google.com" --highlight_mouse

看到什么算成功：浏览器被拉起并停在初始页面，终端里出现来回若干轮的动作记录（提议动作、真实执行、回传截图），最后停在任务完成或被拦下。加上 --highlight_mouse 之后，截图里会高亮标出鼠标位置，调试第一阶段很有用。

这一步的目的不是完成任务，而是确认整条链路是通的：网络、密钥、浏览器、截图往返都在里面。

第 6 步：看懂这轮循环到底发生了什么

做什么：把刚才那几轮拆开看。循环只有四步：

1. 发出：客户端把自然语言指令、当前截图、目标环境一起发给模型
2. 收回：模型不直接操作系统，它返回一个 function_call（一次点击、一次输入或一次滚动），并附一个 intent 字段说明它为什么这样提议；同时可能附带一个 safety_decision
3. 执行：客户端解析这个调用，把归一化坐标换算成自己视口的像素（模型给出的坐标通常是 0–999 的整数网格，不是真实像素），再用 Playwright 真的去做这个动作
4. 回传：动作做完后重新截图，作为结果回传给模型，回到第 2 步

循环一直持续到任务完成、命中终止条件、被安全机制拦下，或你手动停掉。safety_decision 通常把动作分成允许、需要确认、阻断三类 —— 需要确认的那一类，你的代码必须自己实现「问人 → 收到回执再继续」这一段，否则循环会卡在那里。

看到什么算成功：你能对着日志说出「这一轮它提议了什么、我执行了什么、下一轮截图里画面变了吗」。说不出来就还没搞懂，先别接真实页面。

第 7 步：给它的手脚上锁

做什么：在接真实任务之前装护栏，四道都要有。

• 允许与禁止清单：明确它能访问哪些域名、哪些域名绝不能去。禁止清单是及格线，允许清单更稳。
• 动作裁剪：用不上的预置动作就排除掉（官方文档给出了排除预置动作的做法），可动的范围越小越好。
• 人工接管：注册一个「把控制权交回人类」的自定义动作，需要人来拍板的环节从这里走。
• 输入处理与留痕：对进入模型可见范围的文本做必要的清理；同时把指令、截图、模型提议的动作、安全判定与最终真正执行的动作都记录下来。

看到什么算成功：随便挑一个越界的指令（比如让它去一个不在允许清单里的域名），它会被挡住并留下记录，而不是照做。

第 8 步：显式指定模型，不要依赖默认值

做什么：在主命令里写明要用的模型。仓库说明里列出的可选项包括 gemini-3.6-flash（仓库默认）、gemini-3.5-flash-lite、gemini-3.5-flash、gemini-2.5-computer-use-preview-10-2025 与 gemini-3-flash-preview：

python main.py --query="..." --env="playwright" --model="gemini-3.6-flash"

看到什么算成功：日志里出现的模型与你指定的是同一个。

为什么这一步单独成节：仓库说明与官方文档在「哪些模型支持 Computer Use」这件事上口径不一致，官方文档侧对各模型的推荐角色另有说法，而仓库停在 7 月底。别替它们统一口径 —— 显式写明模型，自己去对一次当期的官方文档页。

第 9 步：切换到云浏览器环境

做什么：除本地浏览器外，仓库支持把浏览器放在云端。准备好对应凭据后切换参数：

export BROWSERBASE_API_KEY="..."

export BROWSERBASE_PROJECT_ID="..."

python main.py --query="..." --env="browserbase"

看到什么算成功：浏览器由云端实例提供，本地不再拉起 Chrome。它的实际用途有两个：把执行环境真正隔离出去，以及绕开下一步里那个常见故障。

第 10 步：留下可回看的记录

做什么：把每一轮的指令、截图、提议动作、安全判定与实际执行的动作落到日志里，按任务维度归档。

看到什么算成功：任意一个失败的任务，你都能事后复盘出「它在第几轮、看到了什么画面、提议了什么、我们有没有拦住」，而不是只剩一句报错。

常见坑与排错

• Playwright 抓不到原生下拉框：仓库把它列为已知问题 —— 部分操作系统下 select 元素由系统渲染，截图里拿不到，智能体因此不知道该怎么选。官方给出的两条解法是改用云浏览器环境，或注入一段把原生控件替换成自定义控件的脚本；后者并不总能生效，官方也把它写成权宜之计。
• 把归一化坐标当成像素用：模型给的是 0–999 网格上的坐标，必须自己换算到实际视口。直接当像素点，点击位置会偏，而且偏移随窗口大小变化。
• 需要确认的动作被忽略：当 safety_decision 属于需要确认那一类时，如果客户端没有回执，循环会原地卡住。字段名以官方文档为准，但这一段逻辑必须自己写。
• 两个入口的写法互相抄：Interactions 一侧与 GenerateContent 一侧对这个工具的声明写法不同（工具名、环境字段的取值写法都不一样），软件开发工具包的版本要求也不同。照你实际使用的那个入口的官方文档写，不要跨入口抄示例。
• 界面漂移：弹窗、通知、动态加载导致的布局变化会让它「看不懂」。每个任务尽量从干净、已知的页面状态开始，并事先关掉干扰源。
• 截图里的提示注入：页面上隐藏的文字可能试图指挥它。官方文档把针对截图的注入检测列为可选项；涉及真实账号或真实数据的任务，落地前应确认该项是否已开启，字段名与默认值以官方文档为准。
• 凭据出现在画面里：不要把密码与令牌写进提示词，也不要让它们出现在可能被截图的页面上。给它一个专用账号，权限按最小必要原则给。

进阶用法

三条值得往下做的事：

把确定的部分交回给脚本。 路径固定、每天都跑的流程，用普通自动化脚本更稳；让模型介入的是「路径不确定、界面会变、需要看画面再判断」的那一段。混用比全程交给模型更靠谱。

用自定义动作实现人工接管。 除了默认的界面动作，还可以注册自定义动作。把一个「把控制权交回人类」的动作放进可用清单，是做人工兜底的自然做法。

按目标环境而不是按习惯选用写法。 官方文档区分浏览器、移动与桌面三类环境，各自可用的动作集合不同：移动环境没有精细的鼠标控制，换成打开应用、列出已安装应用这类动作。写任务之前先看清目标环境支持哪些动作。

常见问题

它会自己点下付款按钮吗？

每一次动作都要经过你的客户端执行，模型单方面改不了这一点 —— 这是它的设计前提。但不要因此放松：真正起作用的是安全策略类别是否保留、需要确认的动作有没有人介入，以及你给它的是不是一个有支付权限的账号。涉及交易与敏感数据修改的策略类别建议全部保留，除非你有明确且验证过的理由。

需要付费吗？多少用量够？

调用按所用模型的 token 计费，价格以官网为准。用量取决于步数与截图往返次数：界面每变化一次就要重新截图回传，页面越复杂、步数越多，消耗越大。先用几个固定任务跑几天，摸出单次任务的平均水平再估总量，不要一开始就假设它便宜。

能操作公司内网系统吗？

技术上可以，前提是你的执行环境能访问、账号也有权限。落地前先把三件事定下来：允许访问的域名清单、专用账号与最小权限、哪些动作必须人工确认。内网系统没有公开文档可供模型参考，界面变化也更频繁，比公开页面更需要护栏。

和写死的自动化脚本比，什么时候用不到它？

路径固定、每天跑、失败要立刻告警的流程，脚本更合适：确定性高、成本低、好排查。它的价值在「没人愿意为一次性流程写脚本」和「界面会变、需要看完画面再决定」这两类场景。两者不是替代关系，很多团队是把固定步骤写成脚本、把判断环节交给模型。

境内站点与验证码怎么处理？

页面能不能打开取决于执行环境的网络，工具本身不负责这件事。需要登录的站点要准备专用账号并处理会话；验证码与人机风控属于站点侧的访问控制，应当在产品协议允许的范围内处理，不要试图绕过。

相关工具与内容

只想用现成产品而不是自己搭，可以看 AI智能体与工作流 里的 Manus 与 AutoGLM，两者都是直接交付结果的路线；若要把工程侧的流程也接起来，可以在 AI编程 分类里挑工具。

本站相关的深度长篇：给智能体装追踪 讲这类多轮循环任务怎么留下可读的追踪数据；长时程任务的上下文与输出预算 讲来回多轮时怎么控住 token；给智能体接联网搜索 是「让它自己去查资料」的另一条思路。