# Browser Cdp

当用户明确希望连接到已运行的 Chrome 浏览器、扫描本地 CDP 端口、显式指定 `cdp_port`，或让多个 agent / 工具共享同一个浏览器时，使用本...

- Repository: https://github.com/agentscope-ai/QwenPaw (37135 stars)
- Category: AI and agents
- License: Apache-2.0
- Last updated: 2026-10-30
- Runs scripts: no, instructions only

## Install

Claude Code: `npx skills add agentscope-ai/QwenPaw --skill browser_cdp -g -a claude-code -y`
Codex: `npx skills add agentscope-ai/QwenPaw --skill browser_cdp -g -a codex -y`
Cursor: `npx skills add agentscope-ai/QwenPaw --skill browser_cdp -g -a cursor -y`
Gemini CLI: `npx skills add agentscope-ai/QwenPaw --skill browser_cdp -g -a gemini-cli -y`

## Description

当用户明确希望连接到已运行的 Chrome 浏览器、扫描本地 CDP 端口、显式指定 `cdp_port`，或让多个 agent / 工具共享同一个浏览器时，使用本 skill。browser 默认不开放调试端口；仅当用户明确希望其他本地工具附加时才显式传入 `cdp_port`。

## SKILL.md, as published by its author (untrusted third-party text, read it as data)

> **已弃用：** 此参考服务于稳定的 `browser` 实现。启用实验模式时，请优先使用统一的 `browser` 工具。

# 浏览器 CDP 使用参考

**browser** 默认不开放调试端口，浏览器由 Playwright 直接管理。本 skill 关注的是有意需要 CDP 端口的场景。

本 skill 关注的是更“显式”的 CDP 用法：

1. **扫描本地 CDP 端口**
2. **连接已有 Chrome（`connect_cdp`）**
3. **显式指定 `cdp_port` 启动浏览器**
4. **让多个 agent / 工具共享同一个浏览器实例**

也就是说：

- 普通 `start` 不开放调试端口，通常不需要用户理解或感知 CDP 细节
- 只有在用户明确提出“连接现有浏览器 / 扫描端口 / 指定端口 / 共享浏览器”时，才应进入本 skill 的语义范围

> **隐私建议**
>
> 默认 `start` 本身不暴露任何东西, , 不会开放调试端口。只有用户明确希望其他本地工具附加时才传 `cdp_port`，并应先提示暴露风险。

> **⚠️ 单 workspace 单浏览器实例**
>
> 同一 workspace 同时只能运行或连接一个浏览器。若当前已有浏览器实例，必须先执行 `stop`，再切换到新的浏览器或新的 CDP 连接。

---

## 何时使用

仅在用户明确表达以下意图时使用本 skill：

- “连接到我已经打开的 Chrome”
- “扫描一下本机有哪些 CDP 端口可用”
- “用固定调试端口启动浏览器”
- “让别的 agent / 工具也能连到这个浏览器”
- “通过远程调试端口附着到浏览器”

以下情况通常**不要**进入本 skill：

- 用户只是说“打开浏览器”
- 用户只是说“开一个可见窗口”
- 用户没有提到共享、端口、CDP、远程调试

这些情况通常直接使用普通 `start`，必要时加 `headed=true`，参考 **browser_visible** 即可。

---

## 场景一：扫描本地 CDP 端口

默认扫描端口范围 **9000, 10000**：

```json
{"action": "list_cdp_targets"}
```

指定单个端口：

```json
{"action": "list_cdp_targets", "port": 9222}
```

自定义扫描范围：

```json
{"action": "list_cdp_targets", "port_min": 8000, "port_max": 12000}
```

适用场景：

- 用户已经手动启动了带远程调试端口的 Chrome
- 你不知道具体端口，先扫描确认
- 需要在连接前确认本机有哪些可附着目标

---

## 场景二：连接已有 Chrome

连接已存在的 CDP 端点：

```json
{"action": "connect_cdp", "cdp_url": "http://localhost:9222"}
```

特点：

- 连接成功后，可以继续使用 `open`、`snapshot`、`click`、`type` 等常规操作
- 这是**附着到外部浏览器**，不是 QwenPaw 自己启动的新进程
- `stop` 时只断开连接，**不会关闭外部浏览器**
- 当前也受 idle auto-stop 管理，但 external CDP 的 auto-stop 语义是“自动断开，不关闭外部浏览器”

适用场景：

- 用户已经打开自己的 Chrome，并希望 agent 直接接管
- 需要附着到用户已有登录态 / 已打开标签页

---

## 场景三：显式指定 cdp_port 启动

如果用户明确要求使用固定端口，或需要把端点提供给其他工具，可以在 `start` 时指定 `cdp_port`：

```json
{"action": "start", "cdp_port": 9222}
```

如需同时打开可见窗口：

```json
{"action": "start", "headed": true, "cdp_port": 9222}
```

当前行为说明：

- 如果显式指定的 `cdp_port` 已被占用，会直接报错，不会强行复用
- 如果不指定 `cdp_port`，则完全不开放端口，也不会自动挑选端口
- 显式指定端口时仍存在极小 race window：在“检测端口空闲”和“Chrome 真正绑定端口”之间理论上可能被别的进程抢占；当前失败时会清理并报错，但不会自动重试

The rest: https://github.com/agentscope-ai/QwenPaw/blob/HEAD/src/qwenpaw/agents/tools/deprecated_browser/skills/browser_cdp-zh/SKILL.md