# 给 Agent 接入 Playwright MCP + CloakBrowser


不少 Agent 内置的 `browser_*` 工具，拿来读个网页还行，但需要交互登录、填表提交的时候就不好用了。Playwright MCP 是微软维护的 MCP server，能把 Playwright 的浏览器自动化能力暴露给 Agent。

裸 Playwright 碰上现代网站的 anti-bot 检测很容易出问题。`navigator.webdriver = true`、空插件列表、TLS 指纹不对，这些都是自动化浏览器常见信号。解决思路是把 Playwright MCP 仍然作为 Agent 入口，但把底层浏览器换成 CloakBrowser，或者在 WSL 场景下直接调 Windows 宿主机的浏览器环境。

## 通用部分

通用部分只做一件事：安装 CloakBrowser，并确认它的浏览器二进制路径。Hermes 的 MCP 配置不要写在这里，因为 Linux 和 Windows / WSL 的启动方式不一样。

CloakBrowser 可以通过 Python 包安装。用 `uv` 时：

```shell
uv tool install cloakbrowser

# 如果需要把 uv tool 的命令写入 PATH
# uv tool update-shell

cloakbrowser install
cloakbrowser info
```

`cloakbrowser install` 会下载浏览器二进制。`cloakbrowser info` 可以看到浏览器安装的具体路径。

## Linux 配置

Linux 场景里，Agent、Playwright MCP、CloakBrowser 都在同一个 Linux 环境里。配置分成两个文件：Playwright MCP 自己的 `config.json`，以及 Agent 的 MCP 配置。

Playwright MCP 配置文件，例如：

`/home/<username>/.hermes/playwright-mcp/config.json`：

```json
{
  "browser": {
    "browserName": "chromium",
    "launchOptions": {
      "executablePath": "/home/<username>/.cloakbrowser/chromium-{version}/chrome"
    }
  },
  "outputDir": "/tmp/playwright-mcp"
}
```

`executablePath` 换成 `cloakbrowser info` 看到的真实路径。

Hermes 的 `~/.hermes/config.yaml`：

```yaml
mcp_servers:
  playwright-cloak:
    enabled: true
    command: npx
    args:
      - "@playwright/mcp@latest"
      - "--caps=storage"
      - "--config"
      - "/home/<username>/.hermes/playwright-mcp/config.json"
      - "--headless"
```

`--caps=storage` 会额外提供 cookie 和 localStorage 相关工具，例如：

| 工具                                       | 作用                               |
| ------------------------------------------ | ---------------------------------- |
| `browser_storage_state`                    | 保存 cookies + localStorage 到文件 |
| `browser_set_storage_state`                | 从文件恢复                         |
| `browser_cookie_list/get/set/delete/clear` | 精细操作单个 cookie                |

如果需要显式加载登录状态，可以用 `--storage-state`：

```yaml
mcp_servers:
  playwright-cloak:
    enabled: true
    command: npx
    args:
      - "@playwright/mcp@latest"
      - "--caps=storage"
      - "--config"
      - "/home/<username>/.hermes/playwright-mcp/config.json"
      - "--headless"
      - "--isolated"
      - "--storage-state=/home/<username>/.hermes/playwright-mcp/storage-state.json"
```

验证：

```shell
hermes mcp test playwright-cloak
```

正常会看到类似输出：

```text
✓ Connected
✓ Tools discovered
```

## Windows / WSL 配置

这个场景是：Hermes 跑在 WSL 里，但希望 Playwright MCP 用 Windows 宿主机上的 Node.js 和浏览器。这样可以避开 WSL 里图形环境、GPU、Turnstile 等问题。

Playwright MCP 的 `config.json` 放在 Windows 侧，例如：

`C:\Users\<username>\.hermes\playwright-mcp\config.json`：

```json
{
  "browser": {
    "launchOptions": {
      "executablePath": "C:/Users/<username>/.cloakbrowser/chromium-{version}/chrome.exe"
    },
    "contextOptions": {
      "viewport": { "width": 1280, "height": 720 }
    }
  },
  "outputDir": "C:/Users/<username>/.hermes/playwright-mcp/output"
}
```

WSL 里的 `~/.hermes/config.yaml`：

不要直接把 Hermes 的 `command` 写成 `/mnt/c/Program Files/nodejs/npx`。从 WSL 启动 Windows 程序时，子进程可能拿到 `\\wsl.localhost\...` 这种 UNC 工作目录，CMD / Node 链路不稳定。

更稳的做法是让 Hermes 调 `powershell.exe`，先进入 Windows 用户目录，再启动 `npx.cmd`。

```yaml
mcp_servers:
  playwright-cloak:
    enabled: true
    command: powershell.exe
    args:
      - -NoProfile
      - -ExecutionPolicy
      - Bypass
      - -Command
      - >-
        Set-Location $env:USERPROFILE;
        & "C:\Program Files\nodejs\npx.cmd"
        @playwright/mcp@latest
        --caps=storage
        --config "C:\Users\<username>\.hermes\playwright-mcp\config.json"
        --headless
    connect_timeout: 90.0
```

几个点：

- `Set-Location $env:USERPROFILE` 是为了避开 WSL UNC 工作目录。
- `connect_timeout` 可以稍微调大。第一次启动 `npx` 或下载包时会慢一点。

验证命令：

```shell
hermes mcp test playwright-cloak
```

这套配置验证成功时，输出大概是：

```text
Testing 'playwright-cloak'...
  Transport: stdio → powershell.exe
  Auth: none
  ✓ Connected
  ✓ Tools discovered
```

## 配置代理

修改 playwright 的 config.json 来设置代理服务器：

```json
{
  "browser": {
    "launchOptions": {
      "executablePath": "...",
      "proxy": {
        "server": "http://127.0.0.1:7900"
      }
    }
  },
  "outputDir": "..."
}
```

## 相关链接

- [Playwright MCP](https://github.com/microsoft/playwright-mcp)
- [CloakBrowser](https://github.com/CloakHQ/CloakBrowser)
- [Playwright MCP Storage Tools 文档](https://playwright.dev/mcp/tools/storage)
- [Hermes Agent MCP 配置文档](https://hermes-agent.nousresearch.com/docs/user-guide/features/mcp)


---

> 作者: Nite  
> URL: https://www.nite07.com/zh-cn/posts/agent-playwright-cloak/