weboperator

WebOperator — 用于 Chrome 自动化的 AI 浏览器 Agent 和 MCP 服务

用通俗的英语告诉 Chrome 你想完成什么，然后让 Agent 来处理。

大多数浏览器 Agent 都会自带浏览器。WebOperator 则直接操作你正在使用的浏览器：当前标签页，以及其中完整保留的会话和登录状态——无需单独的配置文件、重新登录或来回复制 Cookie。它背后的模型可以在本地运行，由 Ollama 或 MLX 提供服务，因此你浏览的网页无需离开设备。它也支持双向使用：本地桥接程序会通过 MCP 暴露同一个实时标签页，让 Hermes、OpenClaw 或其他 Agent 客户端都能将你的浏览器用作工具。

git clone https://github.com/KazKozDev/WebOperator.git
npm --prefix WebOperator/core ci
npm --prefix WebOperator/core run build

只需输入一次目标 · Agent 负责规划、操作、验证 · 每个步骤都清晰可见

快速开始

有两种安装方式。如果你不想使用 Node，可以从最新版本下载 weboperator-1.5.0-chrome.zip 压缩包并解压——解压后的文件夹就是构建好的扩展程序。

如果你执行了上面的命令，构建产物会放在 core/dist 中，并且不到一秒就能完成：

vite v8.0.11 building client environment for production...
✓ 101 modules transformed.
✓ built in 189ms

无论选择哪种方式，打开 chrome://extensions，启用开发者模式，点击 Load unpacked，然后选择刚刚得到的文件夹。按 Cmd+Shift+K（Linux 上按 Ctrl+Shift+K）打开侧边栏，在 Settings 中选择提供商，然后输入目标。

默认情况下，Agent 会连接到 Ollama 的 http://127.0.0.1:11434，因此请在首次执行任务前启动一个支持工具调用的本地模型——或者粘贴 API 密钥，改用远程提供商。

跨多个已打开的 Chrome 标签页自动完成多步骤任务

WebOperator 会以“规划 → 操作 → 验证”的循环处理你正在查看的标签页：先写出可供你查看的计划，每次调用一个浏览器工具，并在继续之前根据页面的最新快照检查每个结果。

Summarize the current page

它可以导航、点击、输入文字、按键、滚动、切换标签页、截屏并提取结构化文本——因此，即使答案分散在六七个已打开的标签页中，同样的循环也能正常完成任务。

Compare info across tabs

侧边栏会实时显示计划、每项操作和最终答案，并保留完整的执行记录；历史记录、检查点和计划运行各自拥有独立的标签页。另一方面，Agent 只能了解它在浏览器中实际可见的内容，因此隐藏、付费墙后或受地理位置限制的内容不会出现在答案中。

• Agent 工程——规划、操作和验证循环，29 个浏览器工具，6 个循环防护机制
• 大模型安全——在 9 个对抗性测试样例中，提示词注入攻击率从 44.4% 降至 0.0%
• 大模型评估——在确定性测试框架中使用 AssistantBench 和 24 个测试样例，参见 docs/evals.md
• MCP——将浏览器作为 MCP 服务暴露，提供 10 个工具，供任何 Agent 客户端使用

在 Chrome 中安排定期浏览器自动化任务

有些任务即使你不在电脑前，也希望它们照常完成。为计划指定起始 URL、目标和执行频率——once、hourly、daily 或 weekly——Chrome 闹钟便会准时唤醒 Agent，即使侧边栏已关闭也不例外。

Task name:  Morning release check
Start URL:  https://github.com/KazKozDev/WebOperator/releases
Repeat:     daily
Goal:       Tell me if a new version was published since yesterday

每次运行都会连同执行记录一起保存到“历史记录”中，方便你事后查看具体执行过程。如果运行遇到需要你亲自处理的问题——例如登录页面或验证挑战——Agent 会停止运行并标记为 needs_user，而不是悄无声息地失败。

连接 Hermes、OpenClaw 或其他 MCP Agent

你的实时浏览器可以成为别人的工具。本地桥接程序通过 stdio 使用 MCP，并提供十个工具：browser_snapshot、browser_navigate、browser_click、browser_type、browser_press、browser_scroll、browser_screenshot、browser_extract、browser_solve_captcha 和 weboperator_execute_goal。

cd weboperator-bridge
./install.sh
node mcp-server.js

install.sh 会注册 Native Messaging 主机，将这些调用连接到当前活动的 Chrome 或 Brave 标签页。weboperator-bridge/ 中已提供可直接使用的 Hermes 和 OpenClaw 配置。

工作原理

目标可以来自侧边栏，也可以来自外部 MCP Agent。之后，服务工作线程负责统筹一切——模型调用、任务状态、重试、验证、计划安排和存储。内容脚本负责实际操作：它会将页面转换为包含稳定元素引用的无障碍快照，然后针对这些引用执行 DOM 操作。页面上的任何内容都只会被视为数据，绝不会被当作需要遵循的指令。内置的十二项技能是面向特定领域的操作手册；当 Agent 识别出匹配的网站或任务时，这些技能就会启动。

goal → page snapshot → model tool call → verified action → trace

权限

为了读取和操作你指定的页面，扩展需要 <all_urls> 以及 activeTab/tabs/scripting 权限；还需要 debugger 权限，以调用纯 DOM API 无法实现的 DevTools Protocol 操作。其余权限用于日常功能：sidePanel 用于界面，storage 用于设置和历史记录，alarms 用于计划任务，downloads 用于文件下载技能，nativeMessaging 用于 MCP 桥接。bookmarks 和 tabGroups 是可选权限，只有在实际需要时才会请求。

debugger 权限会使 Chrome 在操作运行期间显示黄色的“WebOperator started debugging this browser”提示栏。该提示栏属于 Chrome，而非扩展；Agent 断开调试器后，提示栏便会消失。

配置和要求

配置

选项	默认值	作用
Provider	ollama	选择 Ollama、Anthropic、DeepSeek、Gemini、MLX、OpenAI、自建的 OpenAI 兼容端点、OpenRouter、SiliconFlow 或 xAI
Base URL (OpenAI-compatible)	http://127.0.0.1:8080/v1	将 OpenAI 兼容的 Provider 指向 llama.cpp、LM Studio、vLLM、LiteLLM 或任意网关
Ollama URL	http://127.0.0.1:11434	设置本地 Ollama 端点
截图策略	auto	控制视觉功能的自动启用、始终启用或禁用
操作超时	10000 ms	限制单次浏览器操作尝试的时长
域名允许列表 / 阻止列表	空	设置后，按域名限制或拒绝任务

桥接身份验证

桥接程序监听 127.0.0.1:8765，在设置 WEBOPERATOR_API_TOKEN 之前会接受未经身份验证的调用。请设置该变量。所有桥接变量——绑定主机、端口、套接字和日志 路径——均记录在 docs/api.md 中。

### 要求

• Chrome 120 或更高版本，或同一代的 Chromium 浏览器
• 如果自行构建扩展，需要 Node.js 和 npm
• 一个能够调用工具的模型，由 Ollama 或 MLX 在本地提供服务，或通过上表中的远程服务提供商访问。工具调用是唯一的硬性要求，因为 Agent 只能通过工具调用来执行操作。推理和视觉能力是加分项——即使没有这些能力，Agent 仍然可以运行，步骤跟踪会告诉你它缺少哪一项
• 该扩展未上架 Chrome 网上应用店，因此需要以未打包扩展的方式加载
• 安装 MCP 桥接程序需要 macOS 或 Linux
• 仅当运行完整的本地检查门禁时才需要 shellcheck

限制

• 动态页面、画布内容繁多的页面或无限滚动页面，可能会导致元素引用在 Agent 查看页面和执行操作之间失效。
• 启用了机器人检测或采用特殊焦点处理方式的网站可能会彻底无法使用。
• 长时间任务容易偏离方向。检查点和上下文压缩能缓解这个问题，但无法根除。
• 如果将其指向远程服务提供商，该提供商就能看到你对页面的观察结果，包括文本和截图。
• 我们测试的浏览器是 Chrome 和 Brave。其他 Chromium 构建版本和 Windows 均未经测试，而且桥接程序安装器会直接拒绝在 macOS 和 Linux 以外的系统上运行。

故障排除

• Ollama 403 —— Ollama 拒绝了扩展的来源。使用以下命令重启： OLLAMA_ORIGINS="chrome-extension://phbohkmfojcjbmgfnaikenmgemgckdpg,http://localhost:*" ollama serve。必须明确写出该来源：Ollama 会接受将 chrome-extension://* 加入列表，但之后仍会返回 403。上方的 ID 由 manifest key 固定，侧边栏自身的错误消息也会重复显示该 ID。
• “模型停止发出工具调用” —— 模型无法调用工具，或者模型太小，无法可靠地执行工具调用。请更换模型；工具调用是唯一的硬性要求。
• Chrome 在点击 Load unpacked 时拒绝该文件夹 —— 请将其指向 core/dist 或解压后的发布文件夹，而不是仓库根目录。
• 桥接程序返回 401 —— 你在桥接程序上设置了 WEBOPERATOR_API_TOKEN，但客户端没有发送该令牌。请在请求中添加 Authorization: Bearer $WEBOPERATOR_API_TOKEN。
• 任务在看起来正常的页面上失败 —— 首先检查侧边栏中的步骤跟踪；过期的元素引用或机器人检测拦截页会显示为失败操作。

贡献

欢迎提交 Bug 报告、功能请求和拉取请求。 CONTRIBUTING.md 介绍了设置步骤、每项更改都必须通过的八步检查门禁，以及提交约定。已发布的版本列在 CHANGELOG.md 中。

发现安全问题？请不要公开提交 issue——请按照 SECURITY.md 中的说明私下报告。

手动安装、Docker、开发环境设置

从发布版本安装

releases page 上的每个压缩包旁边都附有一个 .sha256 文件；完整检查门禁通过后，release 工作流会根据已标记的提交构建并发布这些压缩包。

从源代码构建

运行 npm --prefix core ci && npm --prefix core run build，然后将生成结果作为未打包扩展加载。

Docker

没有 Dockerfile 或 Compose 配置。

### 开发 `npm --prefix core run dev` 可启用监听构建。`./scripts/check.sh` 会运行完整检查：fixture 评估、桥接冒烟测试、类型检查、lint、单元测试、死代码扫描、shellcheck 和构建。