html

在 cherryStudio MCP 控制台中，用户常观察到三类强关联异常信号：ERR_CONNECTION_REFUSED（网络层拒绝）、Failed to fetch manifest（应用层资源加载失败），以及 MCP 面板持续显示“未检测到活跃客户端”。这并非孤立前端报错，而是端到端调试链路断裂的综合体现。需注意：该问题 不触发 Chrome 自身崩溃日志，但会在 cherryStudio 后台服务日志中高频出现 WebSocket connection to 'ws://127.0.0.1:9222/devtools/browser/...' failed 类型条目。

cherryStudio MCP 客户端依赖 Chrome DevTools Protocol (CDP) v1.3+ 的稳定 WebSocket endpoint。关键约束如下：

• 地址绑定必须为 IPv4 loopback 显式地址：127.0.0.1:9222（非 localhost:9222 或 0.0.0.0:9222），因 cherryStudio 内置校验器调用 net.isIP('127.0.0.1') 且严格比对字符串字面量；
• CDP 版本兼容性门槛为 Chrome v115+（对应 CDP v1.3），v114 及以下版本缺失 Browser.setDownloadBehavior 等 MCP 必需方法；
• Chrome 启动时若已存在活动调试实例，新进程将复用 /devtools/browser/... endpoint，导致 MCP 获取到陈旧或冲突的 session ID。

以下启动方式将导致 MCP 连接失败：

cherryStudio 读取 mcp.client.chrome.path 配置项后，执行两级验证：

1. 文件可执行性校验（fs.accessSync(path, fs.constants.X_OK)）；
2. 内核指纹识别：通过 spawnSync(path, ['--version'], { encoding: 'utf8' }) 提取输出，正则匹配 /Chromium|Chrome/(d+)/，并要求 parseInt(version) >= 115。

常见误配路径示例：/Applications/Brave Browser.app/Contents/MacOS/Brave Browser（虽为 Chromium 内核但 CDP 接口有定制裁剪）、/usr/bin/google-chrome-stable（Ubuntu 默认包可能为 v112）。

在 macOS Sonoma+ 系统中，即使启用 SIP（System Integrity Protection），Chrome 进程仍需显式授予「全盘访问」权限才能成功 bind 到 loopback 端口。验证方法：

lsof -i :9222 | grep LISTEN # 若无输出，说明端口监听失败 # 检查权限：System Settings → Privacy & Security → Full Disk Access → + 添加 Chrome.app 

推荐在 ~/.cherrystudio/config.json 中设置：

{ "mcp": { "client": { "chrome": { "path": "/Applications/Google Chrome.app/Contents/MacOS/Google Chrome", "args": [ "--remote-debugging-port=9222", "--headless=new", "--no-sandbox", "--disable-gpu", "--disable-extensions", "--disable-dev-shm-usage", "--remote-allow-origins=*" ] } } } } 

注：Windows 用户需将路径改为 C:\Program Files\Google\Chrome\Application\chrome.exe，Linux 用户建议使用 /opt/google/chrome/chrome 并确保 chrome-sandbox 文件存在。

绕过 cherryStudio，直接验证 CDP 健康度：

1. 启动 Chrome：google-chrome –remote-debugging-port=9222 –headless=new –remote-allow-origins=*；
2. 获取浏览器会话：curl http://127.0.0.1:9222/json/version → 应返回 Protocol-Version 字段；
3. 创建新目标页：curl -X POST http://127.0.0.1:9222/json/new -H “Content-Type: application/json” -d ‘{“url”:“about:blank”}’；
4. 提取返回的 webSocketDebuggerUrl，用 wscat -c “ws://127.0.0.1:9222/devtools/page/…” 建立连接并发送 {“id”:1,“method”:“Page.navigate”,“params”:{“url”:“data:text/html,”}}。

将以下 Bash 脚本加入 cron（macOS/Linux）或 Task Scheduler（Windows）：

#!/bin/bash PORT=9222 if ! lsof -i :\(PORT | grep LISTEN >/dev/null; then echo "[\)(date)] ERROR: Chrome debug port \(PORT not listening" | tee -a /var/log/cherrystudio-chrome-health.log open -a "Google Chrome" --args --remote-debugging-port=\)PORT –no-first-run fi

验证 CDP version endpoint

if ! curl -sf http://127.0.0.1:$PORT/json/version | grep -q ‘“Protocol-Version”’; then echo “[$(date)] CRITICAL: CDP endpoint unreachable” | tee -a /var/log/cherrystudio-chrome-health.log fi

cherryStudio MCP 对浏览器的兼容性并非仅取决于内核，更受 CDP 接口演进影响。下表为实测支持状态：