计算机使用预览

快速入门

本节将指导您设置并运行计算机使用预览模型，可以是 Gemini 开发者 API 或 Vertex AI。请按照以下步骤开始。

1. 安装

克隆仓库

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

设置 Python 虚拟环境并安装依赖

python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt

安装 Playwright 和浏览器依赖

# 安装 Playwright 对于 Chrome 所需的系统依赖
playwright install-deps chrome

# 安装 Playwright 的 Chrome 浏览器
playwright install chrome

2. 配置

您可以选择使用 Gemini 开发者 API 或 Vertex AI 来开始。

A. 如果使用 Gemini 开发者 API：

您需要一个 Gemini API 密钥才能使用该代理：

export GEMINI_API_KEY="YOUR_GEMINI_API_KEY"

或者将其添加到您的虚拟环境中：

echo 'export GEMINI_API_KEY="YOUR_GEMINI_API_KEY"' >> .venv/bin/activate
# 编辑后，如果虚拟环境已激活，需要先停用再重新激活：
deactivate
source .venv/bin/activate

将 YOUR_GEMINI_API_KEY 替换为您的实际密钥。

B. 如果使用 Vertex AI 客户端：

您需要明确启用 Vertex AI，并提供项目和位置信息才能使用该代理：

export USE_VERTEXAI=true
export VERTEXAI_PROJECT="YOUR_PROJECT_ID"
export VERTEXAI_LOCATION="YOUR_LOCATION"

或者将其添加到您的虚拟环境中：

echo 'export USE_VERTEXAI=true' >> .venv/bin/activate
echo 'export VERTEXAI_PROJECT="your-project-id"' >> .venv/bin/activate
echo 'export VERTEXAI_LOCATION="your-location"' >> .venv/bin/activate
# 编辑后，如果虚拟环境已激活，需要先停用再重新激活：
deactivate
source .venv/bin/activate

将 YOUR_PROJECT_ID 和 YOUR_LOCATION 替换为您的实际项目和位置。

3. 运行工具

使用该工具的主要方式是通过 main.py 脚本。

通用命令结构：

python main.py --query "前往 Google，在搜索栏中输入 'Hello World'"

可用环境：

您可以通过 --env <environment> 标志指定特定环境。可选值如下：

• playwright: 使用 Playwright 在本地运行浏览器。
• browserbase: 连接到 Browserbase 实例。

本地 Playwright

使用 Playwright 控制的本地 Chrome 浏览器实例运行代理。

python main.py --query="前往 Google，在搜索栏中输入 'Hello World'" --env="playwright"

您还可以为 Playwright 环境指定初始 URL：

python main.py --query="前往 Google，在搜索栏中输入 'Hello World'" --env="playwright" --initial_url="https://www.google.com/search?q=latest+AI+news"

Browserbase

使用 Browserbase 作为浏览器后端运行代理。请确保已正确设置 Browserbase 的环境变量：BROWSERBASE_API_KEY 和 BROWSERBASE_PROJECT_ID。

python main.py --query="前往 Google，在搜索栏中输入 'Hello World'" --env="browserbase"

可用模型：

您可以通过指定 --model <model name> 标志来选择要使用的模型。Gemini 开发者 API 和 Vertex AI 客户端支持的选项如下：

• gemini-2.5-computer-use-preview-10-2025：这是默认模型。

仅 Gemini 开发者 API 支持的选项：

• gemini-3-flash-preview：Gemini 3 Flash 的预览版。
• gemini-3-pro-preview：Gemini 3 Pro 的预览版。

代理 CLI

main.py 脚本是用于运行浏览器代理的命令行界面 (CLI)。

命令行参数

参数	描述	是否必填	默认值	支持的环境
--query	浏览器代理要执行的自然语言查询。	是	无	全部
--env	要使用的计算机使用环境。必须是以下之一：playwright 或 browserbase	否	无	全部
--initial_url	浏览器启动时要加载的初始 URL。	否	https://www.google.com	全部
--highlight_mouse	如果指定，代理会尝试在截图中高亮显示鼠标光标的位置。这有助于可视化调试。	否	假（不高亮）	playwright
--model	要使用的模型。更多信息请参阅“可用模型”部分。	否	gemini-2.5-computer-use-preview-10-2025	全部

环境变量

变量	描述	是否必填
GEMINI_API_KEY	您用于 Gemini 模型的 API 密钥。	是
BROWSERBASE_API_KEY	您用于 Browserbase 的 API 密钥。	是（使用 browserbase 环境时）
BROWSERBASE_PROJECT_ID	您用于 Browserbase 的项目 ID。	是（使用 browserbase 环境时）

已知问题

Playwright 下拉菜单

在某些操作系统上，Playwright 浏览器无法捕获 <select> 元素，因为它们是由操作系统渲染的。因此，代理无法将正确的截图发送给模型。

有几种方法可以缓解这个问题：

1. 使用 Browserbase 选项代替 Playwright。
2. 注入类似 proxy-select 的脚本，以渲染自定义的 <select> 元素。您必须将 proxy-select.css 和 proxy-select.js 注入到每个包含非自定义 <select> 元素的页面中。您可以在 Playwright.__enter__ 方法中添加几行代码来实现这一点，例如：

self._page.add_init_script(PROXY_SELECT_JS)
def inject_style(page):
    try:
        page.add_style_tag(content=PROXY_SELECT_CSS)
    except Exception as e:
        print(f"注入样式时出错：{e}")

self._page.on('domcontentloaded', inject_style)

请注意，方法 2 并非总是有效，但它可以作为某些网站的临时解决方案。更好的选择是使用 Browserbase。

Computer Use Preview 快速上手指南

本指南将帮助中国开发者快速配置并运行 Google 的 Computer Use Preview 模型，支持通过 Gemini Developer API 或 Vertex AI 驱动浏览器代理执行自然语言指令。

环境准备

在开始之前，请确保您的系统满足以下要求：

• 操作系统：Linux, macOS 或 Windows (WSL2 推荐)
• Python 版本：Python 3.8 或更高版本
• Git：已安装并配置好
• 网络环境：由于依赖 Google 服务及 Playwright 下载，建议确保网络通畅，或在配置中使用国内镜像源（如针对 pip 使用清华/阿里源）。

安装步骤

1. 克隆项目与配置虚拟环境

首先克隆仓库并创建独立的 Python 虚拟环境：

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

# 创建虚拟环境
python3 -m venv .venv

# 激活虚拟环境
# Linux/macOS:
source .venv/bin/activate
# Windows (PowerShell):
.\.venv\Scripts\Activate.ps1

2. 安装依赖

安装 Python 依赖包（推荐使用国内镜像加速）：

# 使用清华源加速安装
pip install -r requirements.txt -i https://pypi.tuna.tsinghua.edu.cn/simple

安装 Playwright 及其所需的浏览器内核（Chrome）：

# 安装 Playwright 系统依赖 (仅限 Linux，Windows/macOS 通常无需此步或自动处理)
playwright install-deps chrome

# 安装 Chrome 浏览器供 Playwright 使用
playwright install chrome

基本使用

1. 配置 API 密钥

您需要配置 Google Gemini API 密钥才能运行代理。

临时配置（当前终端会话有效）：

export GEMINI_API_KEY="YOUR_GEMINI_API_KEY"

永久配置（写入虚拟环境激活脚本）：

echo 'export GEMINI_API_KEY="YOUR_GEMINI_API_KEY"' >> .venv/bin/activate
# 重新激活环境以生效
deactivate
source .venv/bin/activate

注意：请将 YOUR_GEMINI_API_KEY 替换为您实际的 API 密钥。如果您使用的是 Vertex AI，请参考原文档配置 USE_VERTEXAI, VERTEXAI_PROJECT 和 VERTEXAI_LOCATION 环境变量。

2. 运行示例

使用 main.py 脚本即可启动浏览器代理。以下是最简单的本地运行示例，它将打开 Chrome 浏览器并在 Google 搜索框中输入内容：

python main.py --query "Go to Google and type 'Hello World' into the search bar" --env="playwright"

常用参数说明：

• --query: （必填）自然语言指令，描述您希望浏览器执行的操作。
• --env: 运行环境，默认可选 playwright (本地浏览器) 或 browserbase (云端浏览器)。
• --initial_url: 指定浏览器启动时的初始网址。
• --model: 指定使用的模型，默认为 gemini-2.5-computer-use-preview-10-2025。

带初始网址的示例：

python main.py --query="Search for latest AI news" --env="playwright" --initial_url="https://www.google.com"