AI Agent 浏览器任务失败时，先看故障发生在哪一层：网页无法建立连接或出口 IP 不对，检查代理连接；网页能打开但登录丢失或账号不对，检查浏览器会话；登录和页面都正确却无法点击、读取或进入下一步，检查页面交互。
这三类问题会互相影响，但处理方法完全不同。代理没有生效时继续改选择器没有用；加载了错误的 Profile 时反复登录也可能跑到错误账号；页面元素位于 iframe 内时，换 IP 更不会让按钮自动出现。排查时一次只验证一层，保留错误、最终 URL、页面截图和会话标记，才能知道是哪项修改真正有效。
一、先用页面现象判断故障层
不要只记录“Agent 失败”或“页面超时”。同一个 timeout 可能出现在建立代理连接、等待页面响应、查找元素或等待新窗口等不同阶段。下面这张表可以先把范围缩小。
进入三层排查前，先确认 Agent 确实调用了浏览器工具。如果工具调用记录中根本没有浏览器动作，应先检查权限、工具配置和任务编排；只有浏览器已经启动并执行网页任务后，再进入下面的代理连接、登录会话与页面交互排查。
| 你看到的现象 | 更接近哪一层 | 先保存什么证据 | 暂时不要做什么 |
|---|---|---|---|
| 页面完全打不开，出现代理连接或认证错误 | 代理连接层 | 错误原文、代理协议、服务器与端口、发生时间 | 反复修改页面选择器 |
| 页面能打开，但检测到的出口 IP 或地区不符合配置 | 代理连接层（路由/出口） | 同一浏览器上下文中的出口检测结果、代理绕过规则 | 只看本机命令行的出口 IP |
| 进入了登录页、错误账号或新的空白环境 | 登录会话层 | 最终 URL、当前账号标记、使用的 Profile 或 storageState | 把 Cookie、令牌或状态文件内容贴进公开日志 |
| 页面与账号正确，但按钮找不到、点不动或点击后无跳转 | 页面交互层 | 截图、DOM状态、iframe列表、控制台和页面错误 | 直接更换代理 IP |
如果问题只发生在 Codex 登录、浏览器授权返回或 Reconnecting，而其他浏览器自动化任务正常，应转到Codex登录与连接问题的专项排查，不要在通用 Agent 流程里重复修改所有设置。
二、代理连接层：浏览器到底有没有走代理
第一步不是问“代理能不能用”，而是确认正在执行任务的那个浏览器实例和 BrowserContext 是否使用了这条代理。浏览器扩展、系统代理、命令行请求和 Agent 启动的隔离浏览器可能走不同网络；其中一个入口成功，不代表另一个入口已经继承相同配置。
Playwright 官方网络文档说明，HTTP(S) 和 SOCKS5 代理可以配置在整个浏览器，也可以单独配置到 BrowserContext；其中 HTTP(S)代理可配置用户名和密码，并支持通过 bypass 排除指定域名。这意味着排查至少要核对四项：
- 代理服务器、端口和协议是否与服务端提供的信息一致；
- 认证信息是否传给真正运行任务的浏览器，而不是另一个客户端；
- bypass列表是否意外让目标域名或本地地址绕过代理；
- 出口检测是否就在同一个BrowserContext中完成。
连接错误、认证错误和出口不符要分开
代理服务器无法连接，说明浏览器还没有建立可用通道；407通常指向代理认证环节；页面已经打开但出口不符合预期，则更像是代理未应用到当前上下文或命中了绕过规则。保存错误原文比只写“代理失败”更有用，因为三种情况的下一步完全不同。
出口验证也必须在目标 Agent 实际控制的页面中进行。若只在终端运行一次 IP 查询，再让另一个隔离浏览器执行任务，两次结果不能互相证明。测试时保持浏览器实例、上下文、代理和检测地址不变，只替换其中一项做对照。
三、登录会话层：页面能开，为什么还是掉登录或跑错账号
网页能够加载，只能证明网络链路基本可用，不能证明 Agent 使用了正确登录会话。登录状态可能分布在 Cookie、LocalStorage、IndexedDB、SessionStorage或浏览器Profile中；新建隔离上下文时，其中一部分状态可能不会自动继承。
Playwright 的认证状态说明显示，storageState可以复用 Cookie 和 LocalStorage 等认证状态；如果应用把认证信息保存在 IndexedDB 中，按照BrowserContext 的 storageState API，保存状态时还需要启用 indexedDB: true。SessionStorage不会自动持久化，需要另行处理。官方同时提醒，保存的状态文件可能包含可用于登录的敏感 Cookie 和请求头，不应提交到公开或私有代码仓库。
会话排查应确认四个对象
- 浏览器实例：Agent启动的是新浏览器，还是连接到已经登录的浏览器；
- Profile或Context：当前页面是否来自预期的用户目录和隔离环境；
- 状态文件：
storageState是否存在、是否过期、是否属于正确账号； - 页面身份：不要只看“没有出现登录框”，还要读取一个不敏感的账号标记确认身份。
Chrome 的AI Agent 自动连接现有浏览器说明指出，连接到活动浏览器后，Agent会接触现有标签页、SessionStorage、LocalStorage和Cookie等Profile数据。这种方式适合调试已经复现的登录态问题，但也扩大了可访问的数据范围，只应交给可信Agent，并避免让无关账号和页面同时暴露在该环境中。
如果某次更换出口后恰好发生掉登录，只能把网络变化列为排查线索，不能立刻断定两者存在因果关系。应在同一账号、同一Profile和相同页面流程下做对照，查看问题是否稳定跟随出口变化。
四、页面交互层：网页正常，Agent为什么仍然点不动
确认出口和登录身份都正确后，才进入页面交互排查。按钮找不到或点击失败，常见原因包括元素尚未出现、页面重新渲染、元素位于iframe、弹窗打开了新页面、遮罩层挡住操作，或者目标页面已经进入与预期不同的流程。
先确认最终页面，再改定位方式
记录导航后的最终 URL、页面标题和截图。如果预期进入订单页，实际却停在安全验证页，继续优化“提交订单”按钮的选择器没有意义。若页面地址正确，再检查定位器是否依赖易变化的层级或随机class。
Playwright 的Locator指南建议优先使用角色、可见文本、标签和明确的测试标识。Locator会在每次操作时重新定位当前DOM元素，比长期保存一个已经失效的元素引用更适合动态页面。
主页面找不到元素时检查iframe和新窗口
Playwright 的Frames文档说明，页面级操作默认发生在主Frame中；如果登录框、支付组件或嵌入式后台位于iframe，需要通过 frameLocator或对应Frame进入后再定位。点击后打开新标签页的流程，则应监听popup或BrowserContext中新建的Page，而不是继续在原页面等待。
部分网站会明确限制自动化浏览器访问。OpenAI关于云端浏览器的使用说明也提示，即使网站能在个人浏览器正常打开，也可能不允许自动化浏览器完成任务。遇到这类限制时，应遵守目标网站规则，使用其提供的API、人工流程或其他受支持入口，不把更换IP当作规避限制的方法。
五、保留一份最小诊断记录，再开始修改
同一个任务同时更换代理、清空Cookie、重写Locator并调大timeout，最后即使恢复，也无法知道哪一步有效。更稳妥的方法是先跑一次不执行提交、发布、删除或付款的只读诊断，至少保存下面六项：
- 任务时间、浏览器类型，以及使用的是新实例还是已有Profile；
- 代理服务器和协议，账号与密码只记录是否已配置，不记录明文；
- 同一BrowserContext中的出口IP或地区检测结果；
- 目标页面的初始URL、最终URL、主导航响应状态与请求失败原因；
- 当前账号的非敏感标记、页面标题、iframe URL和截图；
- 失败动作、预期结果、实际结果、控制台错误和页面异常。
使用 Playwright 的团队，可以通过 requestfailed、pageerror、page.frames() 和 page.screenshot() 等事件与接口采集请求失败原因、页面异常、Frame列表和截图；最终URL、页面标题与主导航响应状态也应一并记录。
出口 IP 检测应在同一个 BrowserContext 中通过可信的检测页单独完成；账号标记则需要根据目标系统选择不敏感的用户名、租户名或页面标识读取。这两项无法用一套通用选择器覆盖所有网站。
诊断只应针对自有系统、测试环境或已经获得授权的页面，并限制为读取状态、记录错误和截图等必要动作。日志中不要输出代理密码、Cookie、令牌、storageState内容或完整个人信息；截图也要遮住账号、订单和客户资料等敏感内容。
六、什么情况下才需要调整代理方案
代理IP与第一层直接相关，也可能影响需要持续登录的多步骤会话；它不会修复错误Locator、iframe定位、工具权限或页面流程变化。只有出现下面这些可重复证据时，才值得继续调整代理：
- 当前BrowserContext检测到的出口与配置不一致；
- 同一任务在网络A稳定失败、网络B稳定恢复，且其他变量保持不变；
- 多步骤任务的问题稳定发生在出口切换之后，而固定出口后能够复现改善；
- 代理认证、地区或会话时长确实不满足已经确认的业务要求。
如果证据指向代理与会话策略，再查看站内的AI Agent网页任务代理与长会话配置指南，根据任务是否登录、是否跨多个页面以及需要保持多久选择方案。在网络层问题尚未证实前，不应因为一次点击失败就更换产品或出口。
七、AI Agent浏览器故障常见问题
1. AI Agent打不开网页，首先就应该换代理IP吗？
不应该。先保存错误原文并确认代理是否应用到实际BrowserContext。认证错误、代理服务器无法连接、目标页面限制和Agent没有调用浏览器工具，需要不同处理。
2. 命令行查询到代理出口，为什么Agent页面还是原IP？
命令行和Agent控制的浏览器可能使用不同网络设置。应在同一浏览器实例和同一Context内检测出口，同时检查全局代理、Context代理与bypass规则。
3. 出口IP正确，页面却一直要求重新登录，说明代理质量差吗？
不能据此判断。还要检查Profile、storageState、Cookie有效期、SessionStorage和账号身份。只有控制其他变量后，问题仍稳定跟随某条网络变化，才能把出口列为主要原因。
4. storageState可以保存所有登录状态吗？
不能笼统这样理解。Playwright可复用Cookie和LocalStorage等状态；如果认证信息保存在IndexedDB中，保存状态时还要启用indexedDB: true。SessionStorage需要单独处理。状态文件可能包含敏感凭证，应从版本库排除并限制访问。
5. 页面已经打开，Agent为什么提示找不到按钮？
先核对最终URL和截图，再检查元素是否位于iframe、是否尚未渲染、是否被遮罩，或定位器是否依赖易变化的DOM结构。页面处于错误流程时，不应继续调按钮选择器。
6. 遇到403、验证码或自动化限制，换IP能解决吗？
不能把换IP当作通用答案。先确认这是代理连接问题、会话变化还是网站明确限制自动化访问；应遵守网站规则，并优先使用公开API、人工处理或受支持的访问方式。
7. 哪类Agent任务更需要稳定会话和固定出口？
需要登录并连续完成多个页面步骤、而且已验证网络变化会中断会话的任务，更重视出口与会话连续性。无登录的单次页面读取则应根据请求方式和实际测试决定，不必默认固定IP。
排查结束后，至少应能回答三个问题：任务页面是否通过预期出口访问、Agent是否处在正确账号和会话中、失败动作是否发生在正确页面与Frame里。只要这三项证据齐全，下一步该改代理、恢复会话还是修页面交互，通常就不会再混在一起。
