---
title: "OpenCode Browse 调研：让 coding agent 用你自己的真实浏览器"
author: "陈成"
author_url: "https://research.sorrycc.dev/@sorrycc"
question: "OpenCode Browse 是什么、怎么实现的，和 Tiller、Qoder 桌面端的浏览器实现有什么不同，对 qodercli 和 Tiller 有什么启示？"
url: "https://research.sorrycc.dev/@sorrycc/opencode-browse"
emoji: "🌐"
published: 2026-11-19T11:03:14Z
updated: 2026-11-19T12:21:11Z
version: 8
cite: "https://research.sorrycc.dev/@sorrycc/opencode-browse.bib"
---

# OpenCode Browse 调研：让 coding agent 用你自己的真实浏览器

By [陈成](https://research.sorrycc.dev/@sorrycc) · Published November 19, 2026

> OpenCode Browse 是什么、怎么实现的，和 Tiller、Qoder 桌面端的浏览器实现有什么不同，对 qodercli 和 Tiller 有什么启示？

> 调研日期：2026-11-17。来源：X 书签与评论、X 搜索、opencode.ai、GitHub 源码（anomalyco/browse @ `e2c2877`，anomalyco/opencode 相关 PR，本地 Tiller @ `d7eda90`）、The New Stack 报道。Reddit 上搜索 "opencode browse" 没有相关讨论。
> 标【推测】的是我的判断，文档或代码里没有明说。

## TL;DR

- **它是什么**：OpenCode Browse（下文简称 browse）是 Anomaly（OpenCode 背后的公司）出的独立产品，由**一个 MCP server 和一个 Chromium 扩展**组成，让 agent 驱动**你自己正在用的浏览器**，带着你的标签页、登录态和扩展。它不只给 OpenCode 用：Claude Code、Codex、Cursor、Qoder CLI 等 30 多个 agent 都能接。
- **这次发布了什么**：11-15 发布 0.1.0（推文是 11-17 发的），把 CLI、relay 和 MCP server 用 Rust 重写成一个二进制。官方说内存少 25 倍、体积小 23 倍，去掉了 Playwright。dax 说这次重写只花了 **$60** 的 token（Opus 做主力，DeepSeek 做 subagent）。
- **怎么实现的**：Rust relay 通过扩展的 `chrome.debugger` **直接说 CDP**。选择器和 aria 快照靠注入 Playwright 的 `injectedScript`，反检测照搬 Patchright 的做法（不发 `Runtime.enable`，代码跑在 isolated world 里）。给 OpenCode 的是一组普通工具，由 OpenCode 在 code mode 里自己组合；给其他客户端的是一个 `execute` 工具，在内嵌的 **QuickJS** 里跑带 Playwright 风格 `page` shim 的 JS。
- **对 qodercli 的意义**：browse 的安装器**已经支持 Qoder CLI**（写入 `~/.qoder/settings.json`）。不过 qodercli 只会拿到 `execute` 工具，因为 browse 是按 `clientInfo.name` 是否包含 "opencode" 来决定给哪套工具的。qodercli 1.1.81 已经有 CodeMode，可以考虑让它也拿到普通工具（见第 6 节）。
- **对 Tiller 的意义**：Tiller 本身就是浏览器（CEF），在进程内直接发 CDP，用不着扩展和 relay，调用链路比 browse 短。值得搬过来的是产品能力：handoff、按标签页的 `allowedOrigins`/`readOnly`、`read_page` 支持 iframe 和 shadow DOM（见第 7 节）。
- **Qoder 桌面端怎么做的**：两条路都有。内置浏览器用 Electron 的 `webContents.debugger` 直连 CDP，像 Tiller；外部 Chrome 用扩展加 app 内置 relay，靠 Native Messaging 交换 token，像 browse。两边的工具协议都照抄 `chrome-devtools-mcp`，写操作默认要用户确认。外部 Chrome 那条路已经有 handoff 和按轮次回收标签页；参照 browse，建议给内置浏览器补上 handoff、按页面限定源和只读、网络记录脱敏，并让外部 agent 也能用 Qoder 的浏览器（见第 8 节）。

---

## 1. "OpenCode Browse" 是什么

| 项 | 内容 |
|---|---|
| 形态 | Chrome 扩展（Web Store id `mfnicocicmmlkpjnaffgihfjhdgjkdjg`）+ 本地 `browse` 二进制（CLI / relay / MCP stdio proxy） |
| 仓库 | [github.com/anomalyco/browse](https://github.com/anomalyco/browse)（MIT），**独立于** `anomalyco/opencode` 主仓库 |
| 产品页 | [opencode.ai/product/browse](https://opencode.ai/product/browse) |
| 支持的浏览器 | Chrome、Edge、Brave、Arc、Helium、Vivaldi、Opera、Chromium（**不支持 Firefox**，评论里很多人要） |
| 支持的 agent | OpenCode、Claude Code、Codex、Cursor、VS Code、Gemini CLI、Zed、Qwen Code、Qoder CLI 等 30 多个（见 `rust/crates/browse/src/agents.rs`） |
| 安装 | `npx @opencode/browse install`，或 `curl -fsSL https://opencode.ai/browse/install \| bash`。官方建议先装扩展，扩展会一步步引导 |

产品页列出的核心卖点：

- **真实浏览器**：直接用你已登录的站点，不需要 key 或额外配置。
- **不打扰你**：agent 的标签页在后台打开，收进折叠的 tab group。
- **Handoff（交接）**：碰到登录、2FA、付款时，agent 把标签页交给你，你点 Continue 后它接着干。
- **Lend a tab（借出标签页）**：点工具栏按钮，把你正开着的某个标签页借给 agent。
- 截图、录屏、抓网络流量；`allowedOrigins` 白名单；`readOnly` 只读标签页。

### 时间线

| 日期 | 事件 | 来源 |
|---|---|---|
| 2026-10-18 | 从 opencode 仓库里拆出来，成为独立仓库（第一个 commit：`add OpenCode Browser, an extension agents control over MCP`） | git log |
| 11-03 | 0.0.4：正式改名为 Browse，一条命令完成安装、配对 | `changelog/0.0.4.md` |
| 11-07 | dax 招人试用；@opencode 宣布 "OpenCode Browse is now available" | [dax](https://x.com/thdxr/status/2118878460391137310)、[@opencode](https://x.com/opencode/status/2118895128152621153) |
| 11-07 | dax：支持 agent 和浏览器在不同机器上（他自己用远程服务器） | [dax](https://x.com/thdxr/status/2118973784162238748) |
| 11-14 | 0.0.17：大幅精简，删掉 secrets、flight recorder、ghost cursor、doctor | `changelog/0.0.17.md` |
| 11-15 | PR [#264 rewrite the cli and relay in rust](https://github.com/anomalyco/browse/pull/264) 合并；dax 发推说"只花了 $60" | [dax](https://x.com/thdxr/status/2121692397323350468) |
| 11-16 | 打 tag v0.1.0（changelog 日期写的是 11-15）；随后 v0.1.1 | git tag |
| 11-17 | @opencode 发 0.1.0 推文，27 万浏览、6.6K 赞、1.7K 收藏 | [@opencode](https://x.com/opencode/status/2122377687968678258) |
| 11-17 | opencode 桌面端 PR [#64283](https://github.com/anomalyco/opencode/pull/64283)：在 Settings → Extensions 里一键安装、连接 browse（open，挂在 `browse_setup` flag 后面） | GitHub |

> 注意区分：OpenCode **桌面端**另有一个内置浏览器面板（`packages/plugin-browser`，以及 PR [#63002](https://github.com/anomalyco/opencode/pull/63002) 和 [#59477](https://github.com/anomalyco/opencode/pull/59477)）。它是 Electron 里的 webview，和 browse **不是一回事**。评论里有人问"这和 opencode 内置的 browser 工具是否重复？"，答案是：内置的是桌面应用里的浏览器面板，browse 驱动的是你**外部**真实的 Chrome。【推测】两条线可能长期并存：面板用来预览和做轻量操作，browse 用来带登录态的真实操作。

---

## 2. 0.1.0 的 Rust 重写：数字与取舍

dax 贴出的对比表（[推文截图](https://x.com/thdxr/status/2121692397323350468)）：

| | Rust | Node（0.0.16） |
|---|---|---|
| 二进制 | **4.3 MB**（gzip 后 1.9 MB） | 下载 53–64 MB |
| relay 空闲内存 | **6 MB**（处理过请求后 6.6 MB） | 跑 6 天后 353 MB |
| 每个 OpenCode 会话的连接器 | **3.5 MB** 空闲，调用几次后 5.6 MB | 每个 agent 会话约 190 MB |

PR #264 正文的要点：

- 不再用 Playwright：通过扩展**直接说 CDP**；选择器和快照用 Playwright 的注入脚本；反检测按 Patchright 的路子（不发 `Runtime.enable`，用 isolated world）。
- 删掉的功能：Playwright 版 `execute`、`download`（Chrome 不允许扩展用）、时区和语言区域模拟。
- 遗留问题：一个死循环的 `eval` 没法通过扩展停下来（Node 版也一样）。
- 测试方式：用约 10 个回归 agent 对着真实 Chrome 跑了两轮。**Stealth Bench v2 得分 85%**（Browser Use Cloud 是 90.5%）。
- TS 版 `cli/` 先留在仓库里当"规格"参考。

[The New Stack](https://thenewstack.io/opencode-browse-rust-rewrite/) 的评价：$60 不含人工审查、测试和修 bug 的时间。更大的问题是，以前由 Playwright 和 Patchright 维护的代码（浏览器升级、安全修复）现在要团队自己扛，**AI 生成的代码写起来便宜，维护起来不便宜**。

---

## 3. 架构与实现（看源码）

### 3.1 组件与数据流

```mermaid
flowchart LR
  subgraph Agent机器
    A1[OpenCode] -- stdio MCP --> P1["browse mcp<br/>(~5MB 薄代理)"]
    A2[Claude Code / Codex /<br/>Cursor / Qoder ...] -- stdio MCP --> P2["browse mcp"]
    P1 -- "HTTP 127.0.0.1:19988<br/>GET /tools /instructions<br/>POST /tools/call<br/>Header: OpenCode-Browser-Client" --> R
    P2 --> R
    R["browse serve（relay）<br/>Rust · tokio · hyper<br/>tabs / handoff / capture<br/>QuickJS execute"]
  end
  R <-- "WebSocket<br/>ECDH 配对 + 每次连接证明持有密钥" --> E
  subgraph 用户浏览器
    E["Chromium 扩展<br/>(MV3 service worker)<br/>debugger-hub.ts"] -- "chrome.debugger<br/>sendCommand(CDP)" --> T1[agent 标签页<br/>折叠 tab group]
    E --> T2[用户借出的标签页<br/>badge ON/RUN/WAIT]
  end
```

- agent 启动 `browse mcp`（stdio）。它是个"哑管道"，按需拉起 relay，把 `initialize`、`tools/list`、`tools/call` 转发到 relay 的本地 HTTP 接口（`rust/PLAN.md`）。
- relay 监听 `127.0.0.1:19988`，被占用时退到 19990–19997。每个请求都要带 `~/.local/share/browse/relay-token`。
- 扩展通过 WebSocket 连上 relay，再用 **`chrome.debugger`** 对标签页发 CDP 命令（`src/background/debugger-hub.ts`）。所以浏览器顶部会出现"正在调试此浏览器"的提示条，点 Cancel 会断开所有标签页。
- relay 可以跑在远程机器上（`browse install --remote`、`browse set hostname 0.0.0.0`），驱动你本机的浏览器。

**为什么 agent 不直接连浏览器？** 这几层每一层都是在绕一个限制：

1. **Chrome 不让外部进程碰你的默认 profile**：Chrome 136 起，`--remote-debugging-port` 对默认用户数据目录不再生效（为了防 infostealer 偷 cookie）。换个空 profile 能用，但这样就没了登录态，browse 最大的卖点也就没了。想往日常 profile 里的标签页发 CDP，官方认可的办法只有扩展加 `chrome.debugger`。
2. **扩展只能往外连**：MV3 service worker 监听不了端口，只能主动发 WebSocket 或 fetch，所以本机得有个服务端等它来连，这就是 relay。端口固定，扩展才知道去哪找。
3. **MCP 进程是短命的**：每个 agent 会话各起一个 `browse mcp`，会话结束进程就退出。浏览器连接、配对、标签页注册表（`tabs.json`）、handoff 状态、护栏和 QuickJS 都需要一个长驻进程来管，所以 MCP 那头只做 stdio 到 HTTP 的转发，接入 30 多个 agent 也就是一行 `command` 配置。
4. **顺带支持远程**：relay 和扩展之间走的是网络 socket，所以 relay 可以放到远程开发机上。

【推测】Chrome 144 加了一个需要用户同意的远程调试开关（`chrome-devtools-mcp --autoConnect` 用的就是它），不用扩展也能连上真实 profile，但每次连接都要弹窗确认，也没有 browse relay 那些附加功能。

### 3.2 Rust workspace 分层（`rust/crates/`，共约 3.4 万行）

| crate | 职责 | 关键文件 |
|---|---|---|
| `browse-core` | 共享契约：`Cdp`、`Browser`、`Tool` trait、线上传输类型、`CLIENT_HEADER` | `src/lib.rs:300` |
| `browse-relay` | 扩展 WS 协议、配对、按标签页路由 CDP、agent 标签页注册表（持久化到 `tabs.json`）、handoff、HTTP API，以及按客户端决定给哪套工具 | `tabs.rs`、`relay.rs`、`serve.rs`、`surface.rs`、`guardrails.rs` |
| `browse-page` | 页面交互：isolated world、frame、注入脚本、ref、快照、可操作性检查、拟人输入、stealth | `page.rs`、`snapshot.rs`、`input.rs`、`js/injected-script.js` |
| `browse-capture` | 截图（含 diff）、网络抓包（脱敏）、console、录屏（MJPEG → Matroska） | `network/mod.rs`、`redaction.rs`、`recording.rs` |
| `browse-script` | `execute` 工具：每次运行在独立线程里起 **rquickjs**，提供 Playwright 风格的 `page`/`locator` shim，有 CPU、内存、时间限制 | `Cargo.toml`（`rquickjs 0.14`） |
| `browse` | 二进制入口：CLI 子命令、MCP proxy、安装器（30 多个 agent 的配置，编辑时保留 JSON/TOML/YAML 的注释和格式）、自更新、远程 relay | `install.rs`、`agents.rs`、`update.rs` |

每个 crate 导出 `tools() -> Vec<Arc<dyn Tool>>`，二进制把它们拼起来交给 relay。

### 3.3 关键设计

**① 两套工具：按客户端身份分发**（`browse-relay/src/surface.rs`）

```rust
// OpenCode sends clientInfo { name: "opencode" }.
if client.to_ascii_lowercase().contains("opencode") { Surface::Plain } else { Surface::Execute }
```

- **OpenCode** 拿到普通工具：`navigate`、`snapshot`、`click`、`fill`、`type`、`press`、`screenshot`、`network`、`recording`、`emulate`、`webmcp`、`handoff`……OpenCode 有 code mode，可以把这些工具和其他 MCP 工具写进同一段代码里组合调用。dax 举的例子：打开一个 URL，抓出一个列表，循环对每一项调用你的某个 MCP 工具。
- **其他客户端**只拿到 `execute`、`status`、`tabs`。`execute` 接收一段 JS，在 relay 里的 QuickJS 中运行，可以调用 `page.goto()`、`page.getByRole()`、`snapshot()`、`handoff()`、`browse.<tool>()`。这其实就是给没有 code mode 的客户端补上的一层 code mode。
- 可以用环境变量 `OPENCODE_BROWSER_TOOLS=plain|execute|all` 覆盖这个判断。

**② 以标签页为句柄，不再有会话**：`navigate` 不带 `tab` 参数时会开一个后台标签页并返回 id，之后每次调用都带上这个 `tab`。标签页的选项在打开时固定：`group`、`allowedOrigins`、`readOnly`、`keepVisible`、`browser`。也可以用 `tabs new --id work-mail` 指定一个稳定的名字。relay 重启后会重新接管这些标签页。

**③ 不用 Playwright，但借用它的"脑子"**：底层直接走 CDP，复用 Playwright 的 `injectedScriptSource`（Apache-2.0），所以 `getByRole`、`ariaSnapshot` 的质量和以前一样。快照给出带 ref（如 `e12`）的精简页面大纲，包含 iframe 内容，页面只有一个 main 区域时会只截取那部分。

**④ Stealth**：默认不开启页面能察觉的 CDP 域（`Runtime.enable`、`Console.enable`），测试里专门断言了这一点（`browse-page/tests/chromium.rs:95`）。页面里不留全局变量、binding 或 sourceURL。输入模拟真人：鼠标走曲线、打字有节奏、滚动平滑。

**⑤ 安全模型**（README 的 Security 一节）：

- relay token 只有本人可读；只接受官方发布的扩展 id；配对用一次性码加 ECDH，之后每次连接都要证明持有密钥。
- CDP 护栏：拒绝清 cookie、清缓存、关浏览器、改站点权限；cookie 和存储只限当前标签页自己的 host。
- `execute` 跑在沙箱里，但**沙箱不是安全边界**；`allowedOrigins` 和 `readOnly` 是"防跑偏"用的护栏，**不是数据边界**。比如 `eval` 和 `webmcp` 照样能在页面里做任何事。
- 只有真实点击才能完成 handoff，页面没法伪造。

### 3.4 一次调用的时序（非 OpenCode 客户端）

```mermaid
sequenceDiagram
  participant C as Claude Code
  participant M as browse mcp
  participant R as relay
  participant Q as QuickJS
  participant X as 扩展
  participant T as Chrome 标签页
  C->>M: tools/call execute {code}
  M->>R: POST /tools/call (+client 名, pid, token)
  R->>Q: 运行脚本
  Q->>R: page.goto(url) → browse.navigate
  R->>X: WS: 新建后台 tab
  X->>T: chrome.tabs.create + debugger.attach
  Q->>R: snapshot()
  R->>X: CDP: isolated world + injectedScript.ariaSnapshot
  X->>T: Runtime.evaluate (隔离世界)
  T-->>X: 带 ref 的大纲
  X-->>R: 结果
  R-->>M: "tab: <id>" + 输出
  M-->>C: result
```

---

## 4. 社区反馈（X）

**正面**

- "Possibly the best browser use tool I've used so far, most accurate and fast"（@thesobercoder）
- "most nights i'm the one screenshotting the browser back to the agent. giving it the browser directly cuts me out of that loop"（@AndrewBuilds98）
- 跑定时任务的人看重内存：一台机器上 98 个任务，每条浏览器通道省 25 倍内存，就能多塞几条（@petrusenko_max）
- 中文圈转述很多（@meow2149、@wlzh、@NFT_Chen、@chengzhx、@terry_yhl），主要都在讲"Rust 重写，内存降 25 倍"

**质疑与问题**

- **安全**："This is incredibly dangerous…"（@algoretic）。@david1989_zhu 说得更具体：网页内容不可信，agent 又能操作已登录的页面，页面里藏的诱导指令就可能变成真实的点击，问高风险操作有没有确认和权限隔离。（官方的回答是 allowedOrigins、readOnly 和 handoff，但它们只是护栏，见 3.3 ⑤）
- **数字的口径**："please dont claim 25 times less, especially when it is likely a runtime is removed"（@trifazor）：省下来的主要是 Node 运行时本身。
- "so does it or does it not use playwright?"：不依赖 Playwright 这个库，但复用了它的注入脚本。
- "does the agent get the page as an accessibility tree or as screenshots?"：两种都有，主要用 aria 快照加 ref，截图是辅助。
- 想要 Firefox 版（好几条）；有人问能不能被网站检测到、会不会封号（官方说法是"难以发现，并非无法发现"，调试提示条一直在）。
- @aylleenx 想看和 Codex、Claude 浏览器工具的横向 benchmark，目前官方没给。
- @haniffacodes 提到 tabs-as-handles：用户在 handoff 期间关掉标签页，agent 会不会收到 stale handle 错误？（代码里 refs 过期会快速失败，见 0.0.17 changelog）

**Reddit**：r/opencodeCLI 和全站搜 "opencode browse" 都没有相关帖子，目前讨论集中在 X。

---

## 5. 与 Claude Code / Codex / Cursor 的浏览器能力对比

| | **OpenCode Browse** | **Claude Code**（Claude in Chrome） | **Codex** | **Cursor** |
|---|---|---|---|---|
| 驱动谁的浏览器 | 用户真实的 Chromium 系浏览器（扩展） | 用户真实的 Chrome（扩展），另有 Claude 桌面端内置浏览器面板 | in-app browser，另有 Chrome 扩展和 Computer Use（[7-10 公告](https://x.com/OpenAIDevs/status/2075275868268789885)） | 2025-09 起"Cursor can now control your browser"（[推文](https://x.com/cursor_ai/status/1972778817854067188)），编辑器内置浏览器 |
| 接入方式 | **开放 MCP**，任何 agent 都能用 | 绑定 Claude 产品 | 绑定 Codex/ChatGPT 产品 | 绑定 Cursor |
| 开源 | ✅ MIT，可审计 | ❌ | ❌ | ❌ |
| 底层 | 扩展 `chrome.debugger` → CDP，Rust relay | 【推测】也是扩展加 CDP 或 DOM 操作 | 支持 CDP 的开发者模式（[6-12 公告](https://x.com/OpenAIDevs/status/2065226355495895521)） | 【推测】Electron/Chromium webview 加 CDP |
| 特色 | handoff、借出标签页、多浏览器和远程 relay、code mode 组合、stealth | 和 Claude 深度整合、站点权限 | DevTools 调试、性能 profile | 和编辑器预览、调试 UI 结合紧 |

【推测】browse 的差异化主要不在能力，而在于**中立和开放**：一个开源 MCP，接任何 agent，用户也不用换浏览器。这和 OpenCode "不绑定模型和厂商"的定位一致。同时 Anomaly 用它给 OpenCode 的 code mode 引流（只有 OpenCode 拿到普通工具，体验最好）。

---

## 6. 对 qodercli 的启示

现状（看的是本地 `~/Projects/qodercli` @ `2a935f1df0`）：

- qodercli **没有内置浏览器工具**，文档建议的是 `qoder mcp add playwright -- npx -y @playwright/mcp@latest` 或 `chrome-devtools-mcp`（`docs/public/global/zh/cli/mcp-servers.mdx:12,76`）。
- qodercli 1.1.81 已经有 **CodeMode**（`QODER_ENABLE_CODE_MODE=1`，在 MCP 工具上做多步编排）。
- browse 的安装器**已经能装到 qodercli**：`agents.rs:46,214` 有 `("qoder", "Qoder CLI")`，写的是 `~/.qoder/settings.json`。

可以做的事（按投入从小到大）：

1. **零成本**：在 qodercli 的 MCP 文档里加一节 browse（`npx @opencode/browse install -a qoder`），让需要"真实登录态"的用户有官方推荐的路。Playwright MCP 每次起一个干净浏览器，碰到需要登录的内部系统（钉钉、阿里内网之类）就很难用，browse 正好补上这块。
2. **低成本**：qodercli 开 CodeMode 时，让 browse 提供普通工具，而不是 `execute`。用户侧现在就能设 `OPENCODE_BROWSER_TOOLS=plain`。【推测】更干净的做法是给上游提 PR，把 `surface.rs` 的判断从硬编码 "opencode" 改成看客户端能力（比如 MCP capability 或一个 header），这样 qodercli、Claude Code 等有 code mode 的客户端都能受益。
3. **中等成本**：参考 browse 的**两层工具设计**。对没有 code mode 的模型（比如上下文小的 Qwen）给一个 `execute` 加脚本沙箱，对有 code mode 的给细粒度工具，按模型或设置切换。
4. **值得借鉴的产品细节**：handoff（遇到 2FA、验证码交给人）、后台折叠 tab group、借出标签页、按标签页的 `allowedOrigins` 和 `readOnly`、网络抓包自动脱敏，这些都直接对应企业用户的顾虑。
5. **风险提醒**：prompt injection 到真实登录态的风险是实打实的（社区质疑最多的就是这一点）。如果 qodercli 官方推荐 browse，要在 permission/classifier（`schemas/settings.schema.json` 里已经有针对 MCP chrome-devtools 的例外规则示例）里给 browse 的写操作类工具设默认 ask。

【推测】从 "$60 用 AI 重写 + 自研 CDP 层" 这件事看，团队愿意自己维护 Playwright 的子集来换体积和隐蔽性。qodercli 如果走 bun 单二进制路线，没必要跟着用 Rust 重写，但"薄 MCP 代理 + 常驻 relay + 只在需要时启动"这套进程模型值得参考。

---

## 7. 对 Tiller 的启示

现状（看的是本地 `~/Projects/tiller` @ `d7eda90`，v0.5.4 之后）：Tiller 是一个基于 CEF 的 macOS 浏览器，原生 AppKit 界面，自带 agent 面板，并通过 `tiller_mcp`（stdio MCP）和 `tiller` CLI 对外提供浏览器工具。

### 7.1 架构差异

```mermaid
flowchart LR
  subgraph B["browse"]
    direction LR
    A1[agent] -- stdio --> M1[browse mcp]
    M1 -- "HTTP :19988" --> R1[relay]
    X1[扩展 SW] -- "WS（主动连出）" --> R1
    X1 -- chrome.debugger --> T1[Chrome 标签页]
  end
  subgraph TL["Tiller"]
    direction LR
    A2[agent] -- stdio --> M2[tiller_mcp]
    M2 -- "Unix socket<br/>control.sock" --> C2["Tiller.app<br/>Rust core + Swift"]
    C2 -- "进程内 DevTools" --> T2[CEF 标签页]
  end
```

- `tiller_mcp` 连的是 profile 目录下的 `control.sock`（`mcp/src/browser.rs:497`）。涉及页面的操作由 Rust core 按标签页 id 直接发 CDP（`core/src/browser.rs`、`core/src/ipc.rs`），标签页操作由 Swift 端（`ControlServer.swift`）处理。

```rust
// mcp/src/browser.rs:494 —— MCP 端只是连本地 socket，没有端口、token 或配对
fn try_request(&mut self, method: &str, params: &Value) -> Result<Value, Failure> {
    if self.conn.is_none() {
        let path = socket_path(self.profile.as_deref()).map_err(Failure::App)?;
        let stream = UnixStream::connect(path).map_err(|e| Failure::Connection(e.to_string()))?;
        // ...
    }
```

app 收到页面类请求后，Rust core 直接调 CEF 的 `host.send_dev_tools_message(...)` 把 CDP 消息发给对应标签页（`core/src/browser.rs:493`），没有扩展这一跳。
- 没有扩展、没有"正在调试此浏览器"提示条，也不用配对或常驻 relay，socket 文件权限就起到了 relay token 的作用。

| | browse | Tiller |
|---|---|---|
| 驱动谁的浏览器 | 用户现有的 Chrome/Arc/Edge，原样使用 | 用户得换用 Tiller（可以从 Chrome 导入 cookie、密码和扩展） |
| 安装 | 扩展 + 二进制 + 配对 | 一个 app |
| 扩展支持 | 原生 Chrome | 能跑，但要打 CEF 补丁扩展才看得到标签页 |
| 远程 agent 驱动本机浏览器 | 支持（远程 relay） | 不支持（本地 Unix socket） |
| 反检测 | 要专门处理（不发 `Runtime.enable`、用 isolated world） | 引擎是自己的，更容易控制页面能看到什么 |
| 调试提示条 | 有 | 无 |

**速度**：【推测】单次调用的传输开销，Tiller 更低：browse 要过三跳 IPC（HTTP、WS、扩展转进浏览器进程），Tiller 只有一跳；browse 的 MV3 service worker 空闲时还会被挂起，再次调用要先唤醒、重连。不过差距大概只有几毫秒（未实测），和模型延迟比不算什么。真正决定 agent 快慢的是来回几轮：Tiller 靠 `read: true` 和 `run_task`（Jev）减少轮数，browse 靠 `execute` 在一次调用里跑完多步。

### 7.2 值得搬到 Tiller 的功能

Tiller 已经有的不再列：每个 agent 用自己的后台标签页、ref 稳定且失效时报错、`read: true` 省一轮。

**先做**

1. **Handoff 给用户**：agent 遇到 2FA、验证码或付款确认时调用 `handoff(tab, reason)` 并等待，用户处理完点"完成"，agent 接着跑。Tiller 拥有自己的 UI，可以在标签页上放原生提示条或在 agent 面板里放卡片，页面没法伪造这次点击；browse 只能靠"必须是真实点击"来保证。这也是回应"太危险"这类质疑最直接的办法。
2. **按标签页设护栏：`allowedOrigins` 和 `readOnly`**：和 browse 一样，开标签页时固定下来。`readOnly` 拒绝 `click`/`type`/`select`/`run_task`，`allowedOrigins` 拦截跳到别的源的导航。Tiller 能做得比 browse 更硬：CEF 的 `OnBeforeBrowse` 能拿到每一次导航，所以是真拦截，不只是"防跑偏"。前提是这类标签页上也要限制 `eval_js`，否则护栏形同虚设。
3. **`read_page` 支持 iframe 和 shadow DOM**：`mcp/src/page.js` 里没有出现 `iframe`、`contentDocument` 或 `shadowRoot`，而 browse 的快照包含 iframe 内容。嵌在页面里的登录框、Stripe 或结账组件、Web Components 应用，Tiller 现在都读不到。这一项对准确率的影响可能最大。

**其次**

4. **给没有 code mode 的 agent 批量执行**：browse 给非 OpenCode 客户端一个 `execute`，用 `page` shim 跑 JS。Tiller 可以先做个便宜版：一个 `batch` 工具，接收一串工具调用，按顺序执行，遇到第一个错误就停。效果好的话再嵌 `rquickjs`，反正 MCP 端已经是 Rust。
5. **核实反检测**：browse 保证页面察觉不到它：不发 `Runtime.enable`、不留全局变量、全部跑在 isolated world，还有测试断言这一点。【推测】还没确认 Tiller 怎么跑 `page.js`；如果是通过 `Runtime.evaluate` 注入 main world，页面就能看到它的全局变量和存 ref 的结构。改用 `Page.createIsolatedWorld`，再照 browse 加一个测试，就能堵上。
6. **补齐交互原语**：
   - `press`（按键和快捷键；`type` 内部已经在用 `Input.dispatchKeyEvent`）
   - `scroll`、`hover`（悬停才展开的菜单）
   - `upload`（`DOM.setFileInputFiles`），Jev 目前也做不了文件上传
   - JS 对话框（`alert`/`confirm`/`beforeunload`）：接受或关掉，而不是卡住
7. **网络抓包**：记录一个标签页的请求和响应，自动脱敏 token 和 cookie。agent 调试你自己的 web 应用时用得上。

**以后再说**

- **有稳定名字的标签页**，比如 `new_tab --id work-mail`，让定时任务每次复用同一个标签页。和 Tiller 的定时 prompt 很搭。
- **agent 标签页分组**：把 agent 开的标签页折叠或染色，不和你自己的混在一起。
- **`emulate`**（视口、设备）和录屏。

**不用做**

这些只是 browse 为了绕开自身架构才有的：远程 relay、多浏览器支持、扩展配对和 ECDH、Rust 重写、针对原始 CDP 命令的护栏（Tiller 不暴露原始 CDP）。

建议先把 handoff 和护栏当一件事做：两者都是为了让 agent 在已登录的页面上更安全。

---

## 8. Qoder 桌面端的浏览器实现

Qoder 同时有 browse 和 Tiller 两种做法：一条路驱动 app 自带的内置浏览器（类似 Tiller），一条路通过扩展驱动用户自己的 Chrome（类似 browse）。两条路对外是同一套工具。

### 8.1 三条链路

```mermaid
flowchart LR
  subgraph Main["Qoder Electron 主进程"]
    BU["内置浏览器工具<br/>进程内 MCP"] --> DRV[浏览器自动化服务]
    BRG["本地鉴权 HTTP 接口"] --> CCS["Chrome 连接器<br/>（relay，WebSocket）"]
    RBU[远程浏览器转发]
  end
  AG[Qoder agent] --> BU
  REPL["脚本 + Browser SDK"] --> BRG
  DRV -- "webContents.debugger<br/>CDP" --> WCV["内置浏览器<br/>WebContentsView"]
  EXT[Qoder 浏览器扩展] -- "WebSocket + token" --> CCS
  EXT --> TAB[用户的 Chrome/Edge 标签页]
  W["Peer 设备上的 agent"] -- Peer 通道 --> RBU --> DRV
```

**① 内置浏览器**

- 每个聊天会话的页面是一个 Electron `WebContentsView`，自动化直接 attach 这个视图的 `webContents.debugger` 发 CDP，不启动 Puppeteer，也不开放 Electron 全局 CDP 端口。思路和 Tiller 一样：浏览器在自己进程里，CDP 直连。
- 工具名和参数**对齐 `chrome-devtools-mcp`**：`list_pages`、`select_page`、`close_page`、`navigate_page`、`click`、`hover`、`fill`、`drag`、`upload_file`、`press_key`、`handle_dialog`、`take_snapshot`、`wait_for`、`take_screenshot`、`evaluate_script`、`list_network_requests`、`list_console_messages`。只对齐协议，不引入它的 Puppeteer 运行时；工具表固定了版本，有漂移就拒绝启动。
- 快照用 CDP 的 `Accessibility.getFullAXTree`，有节点数和字符预算。点击前先滚入视口并做命中测试，坐标取自 `DOM.getBoxModel`。
- 页面归属由主进程决定：工具只能看到当前会话的页面，模型不能传任意 target id。
- **权限分层**：只读工具（列页面、快照等）直接放行，导航、点击、填写、上传等写操作默认要用户确认。这正是 browse 社区质疑"高风险操作没确认"时缺的那一层。
- **企业联网策略**：企业后台可以关掉内置浏览器的联网，关掉后只允许 localhost 和本地文件，导航和网络请求两处都会拦。
- **反检测基本不做**：第一次操作就启用 `Runtime`、`Network`、`Log`、`Debugger` 等 CDP domain，和 browse 刻意不发 `Runtime.enable` 正好相反。内置浏览器的主要用途是预览本地开发服务，这个取舍说得通。

**② 外部 Chrome（浏览器连接器）**

- 用户安装 Qoder 的浏览器扩展，支持 Chrome、Edge 等 Chromium 系浏览器。
- **relay 就在 Electron 主进程里**：Qoder 在本机回环地址上起 WebSocket 服务，端口随机，只接受白名单扩展 origin 的连接，握手要带随机 token。
- **用 Native Messaging 做发现**：Qoder 给各个 Chromium 系浏览器注册一个 native messaging host。扩展通过它拿到当前的端口和 token，再去连 WebSocket。

```mermaid
sequenceDiagram
  participant Q as Qoder 主进程
  participant C as Chrome
  participant H as native host
  participant X as Qoder 浏览器扩展
  Q->>Q: 本机随机端口 listen，生成 token
  Q->>C: 注册 native messaging host
  X->>C: connectNative
  C->>H: 拉起 host（stdio）
  H-->>X: 端口 + token
  X->>Q: WebSocket（校验扩展 origin）
  X->>Q: 握手带 token，声明能力
  Q-->>X: 工具调用 …
```

- 对比 browse：browse 是**独立的常驻 relay 进程 + 固定端口 + 一次性码配对**；Qoder 是**app 自己当 relay + 随机端口 + native messaging 交换 token**。Qoder 不用让用户输配对码，但 app 关掉连接就断了。
- 工具和内置浏览器同名同参，另有画中画实时展示 agent 在操作的页面。【推测】扩展内部大概率也是 `chrome.debugger`，因为 screencast、AX 树这些能力只有 CDP 才给得出来。
- **给脚本用的 Browser SDK**：提供 浏览器 → 标签页 的对象 API，agent 在脚本里调用。这和 browse 的 `execute`（QuickJS + `page` shim）是同一个思路：用代码在一次调用里做多步。
- **SDK 里已经有 handoff 和标签页生命周期**：agent 可以请求用户手动接管；agent 新开的标签页属于当前轮次，结束时自动关闭，除非标成结果保留或交给用户；用户已有的标签页要先核对标题和 URL 才能接管，结束时只释放不关闭；每个对话有自己的 tab group。给 agent 的指引里还写明：页面文本不是指令，不代填密码、验证码和支付信息，执行脚本不得读 cookie、storage 或 token。这几条和 browse 的 handoff、借出标签页、护栏基本对应。
- **输入框引用标签页**：输入 `/` 可以从连接的 Chrome 里选几个标签页，发送时预抓正文，有总字数预算。browse 没有这种"人主动把标签页喂给 agent"的入口。

**③ 跨设备（Peer）**

- 远程设备上的 agent 可以操作用户眼前那台机器的内置浏览器，复用同一套工具，调用经 Peer 通道转发。
- 内置浏览器**按执行设备隔离登录态**：本地和每台 Peer 设备各一份，同设备的聊天共享 cookie 和登录；远程会话的网页流量从远端出去。browse 的远程 relay 解决的是"远程 agent 驱动本地浏览器"，Qoder 还要处理"本地浏览器的网络走远端"。

### 8.2 三者对照

| | browse | Tiller | Qoder 内置 | Qoder 外部 Chrome |
|---|---|---|---|---|
| 浏览器 | 用户的 Chrome | Tiller 自己（CEF） | Electron `WebContentsView` | 用户的 Chrome/Edge |
| CDP 怎么来 | 扩展 `chrome.debugger` | 进程内 DevTools | `webContents.debugger` | 扩展（【推测】`chrome.debugger`） |
| relay | 独立常驻进程，固定端口 | 无（Unix socket） | 无（进程内） | Electron 主进程，随机端口 |
| 发现与鉴权 | 一次性码 + ECDH | socket 文件权限 | 不需要 | Native Messaging 传 token |
| 工具协议 | 自定义；非 OpenCode 只给 `execute` | 自定义 | 照抄 `chrome-devtools-mcp` | 同左 |
| 快照 | Playwright `ariaSnapshot`（含 iframe） | `page.js` 自写（无 iframe） | `Accessibility.getFullAXTree` | 扩展侧 |
| 代码组合 | QuickJS `execute` | 无（`run_task` 交给 Jev） | 无 | Browser SDK |
| 写操作确认 | 无（只有护栏） | 交给 agent 自己的权限 | 默认要确认 | 执行脚本逐次确认，其余【未核实】 |
| handoff 给用户 | 有 | 无 | 无 | 有 |
| 按标签页限定源 / 只读 | `allowedOrigins`、`readOnly` | 无 | 无（只有企业级联网开关） | 无 |
| agent 标签页生命周期 | 后台 tab group，可借出用户标签页 | 后台标签页 | 按会话归属 | 按轮次自动关闭，可接管用户标签页 |
| 反检测 | 刻意做 | 未核实 | 不做 | 未知 |
| 远程 | 远程 relay | 无 | Peer 设备转发 | 无 |

### 8.3 对 Tiller 的补充

在第 7 节的清单上，Qoder 还多给了几个参考：

1. **对齐 `chrome-devtools-mcp` 的工具名**：Qoder 用一张固定表守住协议，模型对这套名字更熟，也方便和其他实现对比。Tiller 的 `read_page`/`type` 比它省 token，不一定要换名字，但可以参照它的工具覆盖面补缺：`hover`、`drag`、`upload_file`、`press_key`、`handle_dialog`、`wait_for`、`list_network_requests`、`list_console_messages`，和第 7 节第 6、7 项基本重合。
2. **`Accessibility.getFullAXTree` 作为快照的另一条路**：AX 树由浏览器直接算，不用在页面里跑脚本，页面也察觉不到，正好能顺带解决第 7 节第 3 项（iframe）和第 5 项（反检测）的一部分。代价是 AX 树比 Tiller 现在的输出噪声大，需要像 Qoder 那样做节点、深度和字符预算。
3. **按工具分级确认**：只读工具直接放行，写操作默认询问。Tiller 的 agent 面板可以给 MCP 工具加同样的默认策略，比单纯依赖各个 CLI 的权限设置更统一。
4. **用户主动把标签页引用进对话**：在 agent 面板输入框里 `@` 或 `/` 选标签页，发送时预抓正文，省掉一次 `read_page`。Tiller 本来就拥有所有标签页，做起来比 Qoder 走扩展简单。
5. **agent 标签页按任务回收**：照 Qoder SDK 的做法，agent 开的标签页在任务结束时自动关闭，除非标记为结果或交给用户。比第 7 节"以后再说"里的分组更进一步，能避免定时任务跑久了堆一屏标签页。

### 8.4 给 Qoder 的建议（参照 browse）

Qoder 的外部 Chrome 路径已经覆盖了 browse 的大部分产品能力（handoff、按轮次管标签页、tab group、代码组合）。差距主要在内置浏览器，以及"别的 agent 能不能用 Qoder 的浏览器"。

**先做**

1. **内置浏览器也要有 handoff**：handoff 目前只在外部 Chrome 的 SDK 里有，内置浏览器的工具里没有，跨设备操作也没有人工接管。可内置浏览器同样会碰到登录、2FA 和验证码，尤其是预览需要登录的开发环境时。建议加一个 `request_handoff(reason)` 工具：在页面上方显示原生提示条，用户点"完成"后工具才返回。提示条在 Qoder 自己的 UI 里，页面没法伪造这次点击。跨设备时把提示条显示在用户眼前那台机器上。
2. **按页面限定源和只读**：现在只有企业级的联网开关，要么全开要么只剩 localhost。可以参照 browse 的 `allowedOrigins` 和 `readOnly`，在页面创建时固定下来，例如"这一轮只能访问 `localhost:3000` 和 `*.example.com`"、"这个页面只读"。内置浏览器的每个请求本来就经过主进程拦截，按页面加一张 origin 表成本很低，而且是真拦截，比 browse 的"防跑偏"护栏更硬。`readOnly` 页面只放行只读工具，再拒绝 `evaluate_script`。
3. **网络记录脱敏**：`list_network_requests` 返回完整 URL，查询串里的 `token`、`code`、`signature` 会原样交给模型，进入上下文，还可能进日志。browse 的网络抓包默认脱敏。建议对常见敏感参数名和 `Authorization`、`Cookie` 一类的头统一打码，要原值时再显式确认。

**其次**

4. **用一套 SDK 驱动两种浏览器**：Browser SDK 只能连外部 Chrome，内置浏览器只能一次一个工具地调。browse 给非 code mode 客户端的就是 `execute`，在一次调用里跑完"打开、读列表、逐项点击"。建议 SDK 把内置浏览器也列为一种浏览器，这样 Skill 只要写一份，agent 也能用代码批量操作本地预览页面。
5. **按需启用 CDP domain**：内置浏览器第一次操作就打开 `Runtime`、`Network`、`Log`、`Debugger` 等 domain。browse 默认不开 `Runtime.enable` 和 `Console.enable`，一是避免被页面察觉，二是省开销。Qoder 可以只在第一次调 `list_network_requests` 或 `list_console_messages` 时再开对应 domain。内置浏览器开始访问公网（企业允许联网时）之后，这一点更要紧。
6. **快照覆盖跨源 iframe**：【推测】只对根 frame 取 `Accessibility.getFullAXTree` 时，跨进程的 OOPIF（第三方登录框、支付组件、嵌入的文档）内容拿不到。browse 的快照包含 iframe。可以用 `Page.getFrameTree` 加 `Target.setAutoAttach` 拿到子 frame 的 session，分别取 AX 树再拼起来。
7. **让外部 agent 也能用 Qoder 的浏览器**：browse 一个安装器能接 30 多个 agent。Qoder 的浏览器工具是进程内 MCP，只有 Qoder 自己的 agent 能用。但 app 已经给 Browser SDK 开了一个本地鉴权接口，只要再加一个 browse 那种"哑管道"stdio MCP，qodercli、Claude Code 就能驱动用户已连接的 Chrome。这也正好回应第 6 节里 qodercli 没有内置浏览器工具的问题：qodercli 可以优先用 Qoder 桌面端的浏览器，桌面端没开再回退到 Playwright MCP。

**以后再说**

- **可复用的具名标签页**：外部 Chrome 上 agent 开的标签页在每轮结束时会自动关闭，定时任务每次都要重新登录、重新导航。可以参照 browse 的 `tabs new --id work-mail`，允许给标签页一个稳定名字跨轮次复用，用现有的"标成结果保留"那套生命周期管起来。
- **拟人输入**：在用户登录态下操作外部网站时，可以像 browse 那样让鼠标走曲线、打字有节奏，降低被风控识别的概率。内置浏览器只用来预览本地服务，可以不做。
- **`emulate`（视口、设备）**：前端预览常要看移动端效果，内置浏览器加个视口模拟比调整窗口方便。

**不用做**

- browse 那种独立常驻 relay 加一次性码和 ECDH 配对：Qoder 的 Native Messaging 交换 token 不用用户手动配对，体验更好。代价是 app 关掉连接就断，对桌面产品来说可以接受。
- 远程 relay：Peer 设备转发加上按设备隔离的登录态已经覆盖了这个场景，而且做得更完整。

---

## 参考链接

**官方**
- 0.1.0 发布推文：https://x.com/opencode/status/2122377687968678258
- 产品页链接回复：https://x.com/opencode/status/2122377719048519773
- 11-07 首发：https://x.com/opencode/status/2118895128152621153
- dax："$60 Rust 重写"（含对比表）：https://x.com/thdxr/status/2121692397323350468
- dax：招测试：https://x.com/thdxr/status/2118878460391137310
- dax：远程浏览器：https://x.com/thdxr/status/2118973784162238748
- 产品页：https://opencode.ai/product/browse
- 源码：https://github.com/anomalyco/browse （`README.md`、`rust/PLAN.md`、`changelog/0.1.0.md`）
- Rust 重写 PR：https://github.com/anomalyco/browse/pull/264
- Chrome Web Store：https://chromewebstore.google.com/detail/mfnicocicmmlkpjnaffgihfjhdgjkdjg
- opencode 桌面端集成 browse：https://github.com/anomalyco/opencode/pull/64283
- opencode 桌面内置浏览器面板：https://github.com/anomalyco/opencode/pull/63002 、https://github.com/anomalyco/opencode/pull/59477

**报道与社区**
- The New Stack：https://thenewstack.io/opencode-browse-rust-rewrite/
- 中文转述：https://x.com/wlzh/status/2122489820249538670 、https://x.com/meow2149/status/2122384994345902514 、https://x.com/terry_yhl/status/2122600353837596984 、https://x.com/chengzhx/status/2122453749339959433
- Grok 关于接入 OpenClaw 的回答：https://x.com/grok/status/2119652022488109106

**对比**
- Codex 浏览器 CDP 开发者模式：https://x.com/OpenAIDevs/status/2065226355495895521
- Codex 新 Chrome 扩展与 in-app browser：https://x.com/OpenAIDevs/status/2075275868268789885
- Cursor 控制浏览器：https://x.com/cursor_ai/status/1972778817854067188
