chrome-fleet

Chrome Fleet 是一个自托管的浏览器工作台。 为不同账号保留独立的 Chrome 环境，在中文界面中管理账号、代理、远程桌面和任务。通过 Chrome Fleet Skill，在 Codex 或 Claude Code 中部署或接入服务；完成网站登录并启用自动化后，用自然语言选择指定账号的浏览器，执行网页操作。

账号资料、浏览器用户目录和备份保存在你管理的服务器上。既可以打开桌面亲自操作，也可以通过 MCP 或 REST 执行自动化任务，遇到登录验证时再人工接管。

产品概览

实例总览：右上角查看宿主机资源，每张卡片显示对应 Chrome 的状态、资源用量和桌面入口。

让智能体帮你安装

在 Codex 或 Claude Code 中复制以下提示词，让智能体安装 Skill：

请为当前使用的智能体安装 Chrome Fleet Skill。
项目仓库：https://github.com/Scisaga/chrome-fleet
Skill 目录：skills/chrome-fleet

请先阅读该目录的 SKILL.md 和 references/setup.md，检查 Python 3.10+ 和当前客户端 CLI，
使用随附的 scripts/fleet_skill.py install 安装到当前用户，并从已安装副本进行后续操作。
完成后告诉我安装位置，以及连接 MCP 服务还需要哪些信息。

如需同时部署或接入服务，可在提示词末尾追加以下内容。将 fleet-host 替换为已配置的 SSH 主机别名；本机 Linux 部署则将目标改为「当前主机」。

同时在 SSH 主机 fleet-host 上接入 Chrome Fleet：优先复用已有服务；若尚未部署，按项目说明完成首次部署。
使用已安装的 Skill 为当前客户端注册 MCP 并验证连接，告诉我是否需要重新加载会话，并提供管理界面入口。

安装命令与平台要求见安装 Chrome Fleet Skill。接入后，可以继续让智能体「使用 sales@example.test 对应的浏览器打开 https://example.com 并提取标题」。

Related MCP server: MultiZen MCP Server

界面预览

以下截图由当前前端生成，使用示例账号和演示数据，密码保持遮挡。点击图片可查看原图。

账号管理

集中查看邮箱、辅助邮箱、关联实例与登录确认状态。已确认登录的账号显示“打开桌面”，未确认账号保留登录入口。人工确认后，确认按钮改为“更新登录确认”，用于重新核对后更新记录和时间。

任务中心

查看任务状态、按小时汇总的任务分布和执行记录，按时间范围定位操作，继续查看对应任务的进度与结果。

账号绑定与登录确认

在实例页查看、复制已绑定邮箱和密码，进入普通 Chrome 桌面完成登录，再保存人工确认。需要网页任务时，可在实例设置中单独启用自动化。

实例设置

按实例调整浏览器模式、启动策略、资源与网络代理，查看或管理远程桌面密码。

浏览器受控更新

先验证候选版本，再备份并逐个升级。查看每个实例的升级结果，必要时按配对恢复点回滚。

部署与快速开始

需要 Linux x86_64、Docker Engine（非 rootless）、Docker Compose 和 Python 3。先启动 Docker，并确保当前用户有 Docker 访问权限；宿主需提供 iptables、iptables-restore、flock 和 DOCKER-USER 链。

git clone https://github.com/Scisaga/chrome-fleet.git
cd chrome-fleet
sudo ./scripts/fleet init
sudo ./scripts/fleet firewall
docker compose --profile build build
docker compose up -d
sudo ./scripts/fleet doctor

首次 init 会创建 .env 和独立的数据目录。默认管理地址是 http://127.0.0.1:8080，数据目录是 /var/lib/chrome-fleet。

首次登录使用初始化输出的平台令牌文件，默认位于：

/var/lib/chrome-fleet/secrets/admin-token

在服务器本地读取该文件，将令牌填入登录页面。如果修改了 FLEET_DATA_ROOT，令牌路径随数据目录变化。

需要从其他设备访问时，在初始化后、启动服务前调整 .env 中的 FLEET_BIND_ADDRESS、FLEET_PUBLIC_URL 和 FLEET_ALLOWED_ORIGINS。完整配置、HTTPS、重启后的防火墙恢复与排错见部署与运维。

从第一个账号开始

1. 在“账号管理”新增已有账号的邮箱、密码和选填辅助邮箱。

2. 从该账号行点击“创建 Chrome 实例”，配置名称、代理及资源。

3. 新实例默认使用普通 Chrome / VNC。打开 Google 登录桌面，人工完成登录和验证。

4. 回到账号状态或账号管理，点击“确认已登录”。系统保存人工记录，浏览器模式和桌面会话保持不变。需要自动化时，在实例设置中单独切换；Google 可能要求重新验证登录。

5. 日常使用时点击“打开桌面”，或通过 MCP 向这个实例提交网页任务。

账号绑定、人工确认与网站实际登录状态分别记录。首次登录、验证码和二次验证需要人工完成；保留用户目录也不保证网站永远不要求重新登录。详细流程见账号登录与会话恢复。

需要管理通过 Google 首次创建的平台账号时，先在“平台管理”配置平台地址，再到实例“账号状态”登记关联并人工确认。Bilibili、GitHub 的地址示例及操作说明见关联平台与人工确认。

通过 MCP 让 AI 操作浏览器

MCP 已集成在管理服务中。使用 Streamable HTTP 时，直接填写以下信息，无需额外启动 MCP 进程；下方 Skill 接入则通过 stdio 桥接同一服务，支持 SSH 远端，令牌留在服务端。

如果客户端使用请求头配置，填写 Authorization: Bearer <平台访问令牌>。

管理页面左侧的“MCP”提供服务地址复制、搜索以及 6 类、34 个工具的说明和权限标记。

按账号选择浏览器

连接后，可以对 AI 说：

找到 sales@example.test 对应的 Chrome，打开 https://example.com，提取页面标题。只操作这个账号对应的实例，完成后返回结果。

对应的调用流程是：

1. profiles_list 分页查询实例，根据 googleBinding.email 或 accounts[].expectedIdentity 找到账号绑定。

2. profiles_get 确认目标 profileId、浏览器模式和账号记录。

3. 使用 browser_navigate、browser_click、browser_fill、browser_extract 等单步工具，或用 jobs_submit 提交多步任务。

4. 根据返回的 jobId，通过 jobs_get 查询进度与结果。

网页自动化需要目标实例处于自动化模式。工具操作继续使用该实例的用户目录和网站会话；有人工接管时，先完成人工操作并结束接管，再继续自动化。

简单例子：打开网页并提取标题

以下 JSON 是 MCP tools/call 的 params，由已连接的客户端发送。也可以直接使用上面的自然语言指令，让 AI 完成这些调用。ID 均为示例，请替换为查询返回的实际值。

{
  "name": "jobs_submit",
  "arguments": {
    "profileId": "cf_00000000-0000-4000-8000-000000000001",
    "steps": [
      { "action": "goto", "url": "https://example.com" },
      { "action": "extractText", "locator": { "css": "h1" } }
    ],
    "timeoutMs": 60000
  }
}

提交后取得 jobId，再查询执行结果：

{
  "name": "jobs_get",
  "arguments": {
    "jobId": "job_00000000-0000-4000-8000-000000000002"
  }
}

需要在执行前要求账号已人工确认时，为 jobs_submit 或单步网页工具增加 expectedAccountId，取目标实例的 accounts[].id。它与目录绑定中的 googleBinding.accountId 不同，不能互换；尚未人工确认时，任务会等待人工处理；系统不访问账户页面。

常用操作

工具按令牌权限和实例范围校验。网页操作返回任务编号，断开 MCP 不会取消已提交任务；若结果未知，应先核查实际页面，避免重复提交。网站密码、验证码和二次验证通过人工桌面处理。

当前 MCP 使用适用于本机及显式授权 LAN / WireGuard 的 Bearer 模式，尚未提供完整公网 OAuth。完整工具表、客户端代码与可选 stdio 接入见 MCP 使用文档。

安装 Chrome Fleet Skill

chrome-fleet Skill 将首次部署、MCP 配置和日常账号浏览器操作放在同一工作流中。支持 Codex 与 Claude Code，客户端可运行在 Linux、macOS、WSL 或原生 Windows；macOS、Windows 通过 SSH 连接 Linux 服务。

客户端先准备 Python 3.10+、对应 AI 客户端 CLI；远程使用还需 OpenSSH、已配置的 SSH 密钥和已核实的主机记录。无需在客户端安装 Node.js。

从源码目录安装 Skill，选择 codex、claude 或 both：

python3 skills/chrome-fleet/scripts/fleet_skill.py install --client codex

随后用已安装副本接入，避免 MCP 配置依赖源码目录。Codex 本机 Linux 示例：

python3 ~/.agents/skills/chrome-fleet/scripts/fleet_skill.py setup --client codex --target local

Claude Code 的 SSH 远端示例，fleet-host 替换为你的 SSH 主机别名：

python3 skills/chrome-fleet/scripts/fleet_skill.py install --client claude
python3 ~/.claude/skills/chrome-fleet/scripts/fleet_skill.py setup --client claude --target ssh --ssh-host fleet-host

原生 Windows PowerShell 在源码目录中使用 py -3 安装，然后运行已安装副本：

py -3 .\skills\chrome-fleet\scripts\fleet_skill.py install --client codex
py -3 "$HOME\.agents\skills\chrome-fleet\scripts\fleet_skill.py" setup --client codex --target ssh --ssh-host fleet-host

setup 先识别并复用已有服务。新部署支持 Ubuntu 22.04/24.04/26.04 LTS、Debian 12/13 amd64，要求 systemd、rootful Docker 和 root 或免交互 sudo；会补齐缺失依赖，使用固定服务提交，并通过临时空白 Chrome 完成运行验收。已有服务不会被初始化、升级或重启。

配置自动注册到当前用户，保留其他 MCP 配置；按输出提示重新加载客户端会话后使用。Windows 与 WSL 需分别注册。连接元数据位于 ~/.chrome-fleet/skill/，不保存 Token；SSH 接入使用服务端现有凭据，默认与管理页相同的管理员身份。

接入后可以对 AI 说：

使用 chrome-fleet，找到 sales@example.test 对应的浏览器，打开 https://example.com 并提取主标题。只操作这个账号，查询任务完成后返回结果。

需要人工登录或验证码时，在同一实例的桌面完成，结束人工接管后继续原任务。管理页与 MCP 应使用相同平台凭据。查看连接或打开管理入口：

python3 ~/.agents/skills/chrome-fleet/scripts/fleet_skill.py doctor --name chrome-fleet
python3 ~/.agents/skills/chrome-fleet/scripts/fleet_skill.py desktop --name chrome-fleet

desktop 为 SSH 目标维持前台转发；Ctrl+C 只关闭本次转发。doctor 默认只诊断，显式添加 --runtime 才创建空白验收浏览器。详细参数、人工接管与故障处理见 Skill 安装接入、按账号操作、排错指南。

技术栈与架构

面向 Linux 单机自托管，管理界面、REST 和 MCP 共用账号权限与持久任务队列。

flowchart LR
  Web[Web / REST] --> Control[Control Plane]
  AI[AI / MCP] --> Control
  Control -->|生命周期| Runner
  Control -->|网页任务与桌面| Agent[Browser Agent]
  Runner --> Chrome[独立 Chrome 实例]
  Agent --> Chrome

组件关系、固定依赖版本与数据布局见架构与版本。

更多文档

本地开发使用 Node.js 24，具体依赖版本见锁文件与架构文档。

npm ci
npm run build
npm test

npm run dev 启动控制服务；需要先初始化运行数据并准备 Runner 与浏览器镜像。前端开发可运行 npm run dev -w @chrome-fleet/web。

Skill 使用 Python 标准库，可单独运行隔离测试，不需要启动 Docker、连接真实账号或安装 AI 客户端：

python3 -W error::ResourceWarning -m unittest discover -s skills/chrome-fleet/tests -v

GitHub Actions 在 Linux、macOS、Windows 上运行客户端辅助脚本检查；真实服务部署与 Chrome 运行时验收需另在专用 Ubuntu/Debian 主机执行，不能用这些隔离测试代替。

README 截图使用真实前端和独立的合成数据生成，不连接运行中的账号或浏览器：

npm run build -w @chrome-fleet/web
node scripts/capture-readme-screenshots.mjs

截图脚本需要可用的 Chromium、系统浏览器依赖及中文字体；也可通过 FLEET_QA_CHROME 指定 Chrome 可执行文件。脚本同时生成中文截图和英文标签的文档预览，分别位于 docs/images/screenshots/ 和其中的 en/ 目录。当前产品管理界面仍为中文。

原始需求见 BUILD_PROMPT.md。

许可证与第三方声明

本项目采用 Apache License 2.0，版权声明见 NOTICE。允许商业使用、修改与分发，并包含明确的专利授权条款；再分发时需保留许可证及适用声明，并标注修改。

第三方依赖和素材保留各自许可证及版权声明：

• MCP Logo：MIT 许可及来源。

• DejaVu Sans Mono 字体：Bitstream Vera / DejaVu 许可。

Google Chrome、noVNC 和其他第三方组件的许可由各自项目提供。