在 Codex 中接入 Chrome DevTools MCP：连接现有 Chrome、移动设备模拟与排错

平时让 Codex 检查网页，我最先想到的是打开浏览器、截张图。截图适合确认布局，却解释不了接口为什么失败、控制台在报什么错，也看不到页面真实的视口和触控状态。

Chrome DevTools MCP 补上了这一段。它把页面操作、控制台、网络、性能和设备模拟接到编码智能体上。Chrome 团队最初在Chrome DevTools (MCP) for your AI agent中介绍了这些用法，随后在 2026 年 5 月发布了稳定的 Chrome DevTools for agents 1.0。

这篇文章记录我在 Windows 和 Codex 桌面端上的配置过程。安装很快，连接正在使用的 Chrome 才费时间。默认配置会启动一套独立浏览器，那里当然没有当前标签页和手动设置好的手机模拟。

准备环境

Chrome DevTools MCP 仓库列出的基础环境是当前稳定版 Chrome、Node.js LTS 和 npm。先检查命令：

node --version
npm --version
npx --version

后文使用 --autoConnect 连接现有浏览器。这种方式要求 Chrome 144 或更高版本，并且要先在 Chrome 中打开：

chrome://inspect/#remote-debugging

启用远程调试后，Chrome 会在 MCP 请求连接时弹出确认框。具体流程见 Chrome 官方文章让编码智能体调试当前浏览器会话。

这里有个容易混淆的地方：F12 开发者工具、设备工具栏和远程调试是三件事。打开前两项不会自动允许 MCP 连接。

添加到 Codex

Codex 可以用 STDIO 启动本地 MCP 服务。按照 Codex MCP 文档，可以用 CLI 添加：

codex mcp add chrome-devtools -- npx -y chrome-devtools-mcp@latest

也可以直接编辑用户配置：

C:\Users\TARGET_USER\.codex\config.toml

基础配置如下：

[mcp_servers.chrome-devtools]
command = "npx"
args = ["-y", "chrome-devtools-mcp@latest"]

用户级配置会被本机的 Codex 桌面端、CLI 和 IDE 扩展共用。如果只想在一个可信仓库中启用，可以把配置放进项目的 .codex/config.toml。

到这里 MCP 已经能用，但它会启动自己的 Chrome。这适合隔离测试，不适合接手我正在调试的页面。

连接当前 Chrome

我把配置改成：

[mcp_servers.chrome-devtools]
command = "npx"
args = ["-y", "chrome-devtools-mcp@latest", "--autoConnect"]

--autoConnect 和 --auto-connect 都能识别。它们会连接本机正在运行的 Chrome，而不是创建新的用户数据目录。官方自动连接说明也把这种方式列为共享手动调试状态的首选方案。

保存配置后要重启 Codex。已经启动的 MCP 进程不会读取新参数。我第一次修改后马上重试，结果依然只有 about:blank；完整退出并重新打开 Codex 后，现有标签页才出现在 list_pages 结果中。

如果 Windows 找不到 npx，或者 MCP 在默认时间内没有启动，可以采用仓库给出的 Windows 11 兼容写法：

[mcp_servers.chrome-devtools]
command = "cmd"
args = [
  "/c",
  "npx",
  "-y",
  "chrome-devtools-mcp@latest",
  "--autoConnect",
]
env = { SystemRoot = "C:\\Windows", PROGRAMFILES = "C:\\Program Files" }
startup_timeout_ms = 20_000

我的环境可以直接运行 npx，没有使用这段备用配置。

怎么确认连接正确

不要把“MCP 已加载”当成浏览器已经连对了。最简单的检查是让 Codex 调用 list_pages。

初次使用基础配置时，结果只有：

about:blank

加上 --autoConnect、开启 Chrome 远程调试并重启 Codex 后，结果列出了当前 Chrome 中的三个标签页，本地预览页也在其中。这才算真正接管了现有会话。

我又读取了活动页面的运行环境：

{
  "innerWidth": 932,
  "innerHeight": 430,
  "devicePixelRatio": 3,
  "maxTouchPoints": 1,
  "coarsePointer": true,
  "orientation": {
    "type": "landscape-primary",
    "angle": 90
  }
}

这段输出确认了视口、DPR、触控和横屏状态。单看截图只能猜页面像不像手机，运行时数据更直接。

这次碰到的几个问题

改了配置，仍然只有 about:blank

先分清两种情况。

基础配置下只有空白页，通常是 MCP 启动了独立 Chrome。已经加上 --autoConnect 但结果没变化，通常是 Codex 还在使用旧进程。

我的处理顺序是：

1. 保存 config.toml。
2. 在 chrome://inspect/#remote-debugging 启用远程调试。
3. 退出并重新打开 Codex。
4. 接受 Chrome 的连接确认。
5. 再调用 list_pages。

如果这里出现超时或连接关闭，再按官方故障排查文档检查 Chrome 版本、授权提示和重复连接。Chrome 144 到 149 还可能受到冻结标签页影响，开着大量标签页时尤其容易出问题。

在 DevTools 中打开了手机模拟，MCP 却读不到

当 MCP 连到独立 Chrome 时，它读不到日常浏览器里的设备模拟。先检查标签页，再读取：

() => ({
  width: window.innerWidth,
  height: window.innerHeight,
  dpr: window.devicePixelRatio,
  touchPoints: navigator.maxTouchPoints,
  coarsePointer: matchMedia("(pointer: coarse)").matches,
  orientation: screen.orientation?.type,
})

这些值比浏览器窗口大小有用。窗口缩小不等于手机模拟，触控、DPR、User-Agent 和媒体查询可能仍然是桌面状态。

设备工具栏总是回到 Responsive

Chrome Device Mode 文档明确写着，设备工具栏默认以 Responsive 打开。Chrome 没有提供一个可靠的全局开关，让所有新调试目标固定使用同一台设备。

经常测试同一尺寸时，可以在设备下拉框中选择 Edit，按自定义设备文档添加预设：

Name: Mobile Landscape
Width: 932
Height: 430
Device pixel ratio: 3
Type: Mobile

Chrome 有时会记住最近一次选择，重开 DevTools 或切换目标后仍可能回到 Responsive。自动检查时，我会让 MCP 在开始前调用 emulate，把视口、横屏和触控写清楚。

--viewport 只处理由 MCP 自己启动的 Chrome。使用 --autoConnect 时，现有浏览器的设备状态仍由 DevTools 或 emulate 控制。

npx 报 npm 缓存 EPERM

为了确认当前版本有哪些参数，我运行：

npx -y chrome-devtools-mcp@latest --help

命令在受限沙箱中第一次失败：

EPERM: operation not permitted, open
'%LOCALAPPDATA%\npm-cache\_cacache\tmp\...'

npm 需要写用户缓存，而当前命令没有这个权限。允许这条命令访问 npm 缓存，或者在普通 PowerShell 中执行即可。放宽权限后，--help 正常输出，--autoConnect 也确实是当前版本支持的参数。

截图指定路径被拒绝

我第一次调用截图工具时传了一个本地文件路径，MCP 返回：

Access denied: path ... is not within any of the configured workspace roots.

省略 filePath 后，截图直接返回成功。需要保存文件时，应使用 MCP 客户端声明的工作区根目录。

--allowUnrestrictedPaths 可以取消路径限制，但为了一张截图开放所有本地路径不合算。我没有启用它。

浏览器调试时怎么用

Chrome 官方的入门文档把主要能力分成页面交互、实时调试和质量检查。实际使用时，我通常从页面状态开始，不会一上来就跑完整性能分析。

先用 list_pages 和 select_page 确认目标，再取页面快照。普通 DOM 页面可以从快照中读到链接、按钮、表单和文本；遇到 Canvas、WebGL 或纯视觉动画，再补截图。

页面操作失败时看控制台和网络请求。这样能分清是点击没有触发、前端脚本报错，还是接口返回了错误。布局问题则读取元素尺寸、计算样式和视口参数，不靠截图估算像素。

性能问题另开一轮 trace。Chrome DevTools MCP 可以记录并分析性能轨迹，但录制前要先固定页面状态和测试步骤，否则每次结果没有可比性。

截图仍然有用。它负责回答“现在画面是什么样”，DevTools 数据负责回答“为什么会这样”。两者放在一起，比只看其中一个省时间。

当前边界

--autoConnect 会把当前 Chrome 配置中的所有已打开窗口交给 MCP。官方安全说明提醒得很直接：智能体可以读取、检查和修改浏览器及 DevTools 中的数据。

我只在调试时开启远程调试，并先关闭无关的登录页面。需要隔离时就去掉 --autoConnect，让 MCP 使用自己的浏览器配置。

性能工具可能把被分析页面的 URL 发送给 Google CrUX API。无需真实用户体验数据时，可以关闭：

args = [
  "-y",
  "chrome-devtools-mcp@latest",
  "--autoConnect",
  "--no-performance-crux",
]

Chrome DevTools MCP 还会默认收集工具调用成功率、延迟和环境信息。使用 --no-usage-statistics 可以停用这部分统计。

我现在的检查顺序

我保留用户级 --autoConnect 配置。每次调试先确认 list_pages 中有目标页面，再读取视口和设备状态。DOM 结构用快照，视觉结果用截图；控制台和网络请求在复现问题后检查，性能 trace 放到最后。

这次配置在 Windows、Chrome 150 和 Codex 桌面端上实际跑通。以后升级 Chrome DevTools MCP，如果连接方式有变化，我会先运行：

npx -y chrome-devtools-mcp@latest --help

README 和 --help 比旧教程可靠。尤其是 --autoConnect 这类依赖 Chrome 版本的参数，照抄早期配置很容易重新回到独立浏览器。

参考文章

• Chrome DevTools (MCP) for your AI agent：Chrome 团队最初发布 MCP 时给出的使用场景，包括控制台、网络、布局和性能排查。
• Streamline your AI coding workflow with Chrome DevTools for agents 1.0：稳定版 1.0 的发布说明。
• 让编码智能体使用 Chrome DevTools MCP 调试您的浏览器会话：--autoConnect、Chrome 144 和远程调试授权流程。
• Get started with Chrome DevTools for agents：当前安装方式、能力范围和安全提醒。
• Chrome DevTools MCP README：参数、Codex 配置示例和连接现有浏览器的方法。
• Chrome DevTools MCP troubleshooting：自动连接超时、沙箱和远程调试问题。
• Codex MCP：Codex 的 STDIO MCP、用户配置和项目配置说明。
• 在 Device Mode 下模拟移动设备：Responsive 默认行为和设备模拟范围。