★ FEATURED ARTICLE 1. 从能点按钮到知道为什么能点浏览器控制这条链路到底怎么走通的很多人第一次接触 OpenClaw 的浏览器操作能力时注意力都放在它居然能自己点按钮、填表单这件事上觉得神奇然后就去研究怎么写更复杂的指令。但真正把项目跑进生产环境之后你会发现卡住你的从来不是能不能点而是为什么这次点得中、下次点不中以及它到底是怎么看见这个页面的。这一篇我想把这条链路从头到尾拆开讲清楚顺带把明文密钥管理这个几乎所有人都会踩的坑一起说了。先把结论摆在前面Agent 操作浏览器本质上不是AI 直接操控鼠标键盘而是感知—决策—执行三段式循环。感知层负责把网页变成模型能理解的结构化信息决策层负责在候选动作里挑一个执行层负责把这个动作落到真实的浏览器实例上。三段里任何一段出问题表现出来都是它不动了或者它点错了但根因完全不同。你要会区分否则排查就是瞎猜。这篇适合两类人看一类是已经把 OpenClaw 跑起来、但一遇到动态页面就翻车的开发者另一类是正准备把浏览器自动化接进自己系统、还没想清楚密钥该怎么放的人。前者我会重点讲感知层和执行层的细节后者我会用一整节讲明文密钥的风险和几种可行的收敛方案。中间穿插的都是我在实际项目里踩出来的经验不是文档里抄的。需要提前说明的是下面涉及的具体实现细节有一部分是基于这类浏览器自动化框架的通用实践做的合理补充因为原始资料里没有展开到代码级别。我会明确标注哪些是通用原理、哪些是我个人的做法你按自己项目的实际情况取舍。2. 感知层Agent 眼里的网页和你眼里的网页根本不是一回事2.1 为什么截图方案和 DOM 方案会得出完全不同的结果先问一个问题你觉得 Agent 是怎么看见网页的大部分人的第一反应是截图然后让多模态模型看图。这个方案直观但实际用下来问题很大。截图丢失了语义信息——一个按钮在图上就是一个色块模型知道那里有个东西但不知道它叫什么、能不能点、点了会跳去哪。而且截图对分辨率、缩放、滚动位置极其敏感页面稍微变一下布局模型就懵了。所以主流做法是走 DOM 路线把页面的 DOM 树抽取出来做一次可交互元素筛选只保留真正能操作的东西——按钮、链接、输入框、下拉框、单选框这些然后把每个元素的标签名、文本内容、可访问性属性、位置信息打包成结构化数据喂给模型。这样模型看到的不是像素而是一份这个页面上有哪些可操作项、它们分别是什么的清单。但这里有个关键细节不是所有 DOM 元素都值得喂给模型。一个复杂页面动辄几千个节点全塞进去既超上下文又干扰判断。所以筛选逻辑很重要通常要过滤掉不可见的display:none、visibility:hidden、尺寸为 0、被遮挡的、纯装饰性的元素。我自己的经验是筛选后保留的元素数量控制在几十到一两百个之间比较合适太多模型会挑花眼太少又会漏掉关键操作项。2.2 可访问性树被大多数人忽略的那把钥匙如果你只抽 DOM会遇到一个很烦的问题很多现代前端框架React、Vue 那一类生成的 DOM 结构又深又乱一层套一层 div真正的语义信息藏在 aria 属性或者 role 里。这时候更靠谱的做法是走可访问性树Accessibility Tree。可访问性树是浏览器专门为辅助技术比如屏幕阅读器维护的一棵树它把 DOM 里那些乱七八糟的容器节点过滤掉只保留有语义的节点并且把 role、name、state 这些信息规整好。对 Agent 来说这简直是量身定做的输入——每个节点天然就是一个可操作项name 就是它的可读名称role 就是它的类型。你不需要自己去猜哪个 div 是按钮可访问性树已经告诉你了。我实测下来基于可访问性树做感知元素定位的准确率比纯 DOM 方案高出一大截尤其是在那些用了组件库的页面上。代价是可访问性树对某些自定义组件支持不好——如果开发没写 aria 属性节点可能就是空的。所以稳妥的做法是可访问性树为主、DOM 属性为辅两者结合着用。2.3 动态渲染页面等还是不等这是个问题现代网页大量使用异步渲染你拿到 DOM 的那一刻页面可能还没渲染完。这时候如果直接抽取元素抽到的是一份残缺的清单Agent 基于残缺清单做决策自然就点空了。常见的处理方式是等待但等这件事很有讲究。无脑 sleep 三秒是最蠢的做法——快的时候浪费三秒慢的时候三秒还不够。更好的方式是等待特定条件等某个关键元素出现、等网络请求静默、等 DOM 不再变化。这类框架一般会提供 waitForSelector、waitForLoadState 之类的原语你要做的是根据页面特点选对等待条件。我踩过的一个坑是页面主体渲染完了但某个下拉框的选项是点击后才异步加载的。Agent 看到下拉框就点了点完立刻去选项列表里找目标项结果列表还没加载出来找不到就报错了。后来改成点击后等待选项容器出现再继续问题解决。这个经验告诉我等待点要设在真正需要数据的地方而不是笼统地等页面加载。3. 决策层模型是怎么从一堆元素里挑出那个对的的3.1 动作空间的设计决定了 Agent 的能力上限感知层给出一份元素清单后决策层要做的就是选一个动作执行。这里有个容易被忽视的设计问题动作空间怎么定义。最朴素的做法是让模型输出点击第 N 个元素但这样模型很容易数错。更稳的做法是给每个元素分配一个稳定的标识比如基于可访问性树的路径或者一个临时 ID让模型输出标识而不是序号。动作类型也要设计好。基础的有点击、输入、选择、滚动、等待复杂一点的有拖拽、悬停、键盘快捷键。动作空间越大Agent 能力越强但模型选错的概率也越高。我的建议是按需扩展先把点击和输入做扎实遇到确实需要的能力再加不要一上来就堆一大堆动作类型。还有一个细节是动作的参数。比如输入动作除了往哪个元素输入还要有输入什么内容。这个内容从哪来通常是从任务描述里提取或者从上一步的结果里推导。这里就涉及到上下文管理——你得把任务目标、历史动作、当前页面状态都组织好喂给模型它才能做出合理决策。3.2 单步决策 vs 多步规划什么时候该让模型想远一点最简单的决策模式是单步看当前页面选一个动作执行再看新页面再选。这种模式实现简单但有个致命问题——短视。有些操作单独看没意义组合起来才能达成目标。比如先点筛选、再选条件、再点确定如果模型只看当前一步可能点完筛选就不知道下一步干嘛了。所以更成熟的做法是引入多步规划让模型先根据任务目标生成一个粗略的行动计划然后逐步执行每执行一步根据实际页面状态调整计划。这有点像人做事——先想个大概边做边修正。规划的好处是 Agent 有全局观不会做着做着跑偏代价是规划本身可能出错而且增加了 token 消耗。我的经验是任务步骤少于五步时用单步决策就够了超过五步或者有明显阶段划分的任务再上规划。别为了炫技硬上规划很多时候单步反而更稳因为每一步都基于真实页面状态不会因为计划本身错了而一路错下去。3.3 失败重试不是所有错误都值得重试Agent 执行动作会失败这太正常了。元素没找到、点击被拦截、输入框只读各种情况都有。关键问题是失败了要不要重试怎么重试。无脑重试是最糟的——同一个动作重试三次三次都失败白白浪费时间。正确的做法是先判断失败类型如果是元素暂时没出现那等一下重试有意义如果是元素根本不存在重试一百次也没用应该重新感知页面、重新决策。如果是点击被遮挡那可能需要先滚动或者关闭弹窗这是要插入新动作不是简单重试。我一般会给每个动作设一个重试上限比如两次超过就触发重新感知。同时记录失败原因如果同一个动作连续失败说明决策本身有问题要回退到上一步重新规划。这套机制听起来复杂但实现起来就是几个 if-else收益却很大——它能把很多卡死的情况自动化解掉。4. 执行层动作是怎么真正落到浏览器上的4.1 浏览器实例的生命周期管理执行层的第一件事是管好浏览器实例。这里有个常见误区很多人以为开一个浏览器就一直用用完关掉。实际项目里浏览器实例的管理要精细得多。首先是隔离。不同任务之间最好用独立的上下文context这样 cookie、localStorage 互不干扰。如果多个任务共用一个上下文A 任务登录了某个站点B 任务访问同一站点时可能带着 A 的登录态行为就乱了。其次是复用。频繁开关浏览器开销很大启动一次 Chromium 动辄一两秒所以通常会维护一个实例池任务来了从池里取用完还回去。还有一个容易被忽略的点是清理。任务跑完不清理上下文时间长了内存会涨而且残留的 cookie 可能影响后续任务。我的做法是每个任务结束后显式关闭它的上下文定期重启整个浏览器实例避免长时间运行积累的隐性状态。4.2 点击为什么点不中坐标、遮挡与事件冒泡元素明明在那里就是点不中——这是浏览器自动化里最经典的疑难杂症。原因通常有三类。第一类是坐标问题。有些框架用元素中心点坐标去点击但如果元素被滚动到视口外或者页面有缩放坐标就偏了。解决办法是点击前先把元素滚动到可视区域并且用元素自身的 bounding box 计算坐标而不是用页面绝对坐标。第二类是遮挡问题。元素在 DOM 里存在但被一个浮层、弹窗、或者透明的 loading 遮罩盖住了。这时候点击事件会被上层元素截获。解决办法是点击前检查元素是否真的可点击很多框架提供 isVisible、isEnabled 之类的判断如果被遮挡先处理遮挡物。第三类是事件冒泡问题。有些前端组件监听的是 mousedown 而不是 click或者需要完整的 mousedown-mouseup-click 序列。这时候用简单的 click 方法可能不触发。解决办法是模拟完整的鼠标事件序列或者直接用框架提供的更底层的点击原语。我遇到过一个特别刁钻的案例一个按钮的点击处理逻辑绑在父元素上通过事件委托实现。直接点按钮本身没反应因为事件冒泡被某个中间层 stopPropagation 了。最后是改成点击父元素才解决。这个案例说明点击不中不一定是坐标问题也可能是事件机制问题排查时要往深了看。4.3 输入框的那些坑清空、粘贴与输入法输入看起来简单其实坑不少。第一个坑是清空。很多输入框有默认值你直接输入会追加而不是替换。正确做法是先清空再输入但清空也有讲究——有些框架的输入框是受控组件直接设 value 不触发 React 的 onChange得模拟键盘操作。第二个坑是粘贴。有些场景下逐字符输入太慢或者会触发输入框的实时校验导致中间状态报错。这时候用剪贴板粘贴更快更稳。但剪贴板操作涉及权限而且不同平台行为不一致要谨慎使用。第三个坑是输入法。如果你的输入内容包含中文而浏览器实例的输入法状态不对可能输入进去的是乱码或者拼音。稳妥的做法是确保输入内容通过剪贴板或者直接设值的方式注入避免依赖输入法。5. 明文密钥管理那个所有人都知道有问题但都在凑合的事5.1 明文密钥到底危险在哪聊完技术链路必须说说密钥管理。我见过太多项目配置文件里明晃晃写着各种密钥——API key、数据库密码、第三方服务的 token全是明文。问起来就是先跑通再说然后这个先就变成了永远。明文密钥的危险不是理论上的是实打实的。第一版本控制泄露。配置文件一旦提交到代码仓库密钥就进了历史记录就算后来删了历史里还在谁 clone 都能翻出来。第二日志泄露。程序出错时经常把配置打出来密钥就进了日志文件日志再被收集到某个平台扩散面就大了。第三权限过大。很多密钥是一把钥匙开所有门泄露一个等于泄露全部。更麻烦的是密钥泄露往往发现不了。不像程序崩溃有报错密钥被人拿去用了你这边可能一点感觉都没有等到账单爆炸或者数据异常才发现那时候已经晚了。5.2 环境变量最基础但也最容易做错的一层最基础的收敛手段是环境变量。把密钥从代码里挪到环境变量代码里只读不写。这一步能挡住大部分顺手提交的泄露。但环境变量也有讲究。第一不要用 .env 文件提交到仓库。.env 文件本身是明文的如果提交了等于没做。正确做法是把 .env 加进 .gitignore只提交一个 .env.example 作为模板。第二环境变量也会泄露。程序崩溃时的 core dump、某些调试接口、子进程继承都可能把环境变量带出去。所以环境变量只是第一层不是终点。第三不同环境用不同密钥。开发、测试、生产必须用不同的密钥这样开发环境泄露了不会影响生产。这一点很多人图省事用一个密钥走天下风险极大。5.3 密钥管理服务什么时候值得上当项目规模上来之后环境变量就不够用了。你需要的是密钥管理服务——把密钥集中存起来程序运行时动态获取而且有审计日志、有权限控制、有轮换机制。这类服务通常提供几个核心能力加密存储密钥在服务端加密不是明文、访问控制哪个服务能读哪个密钥、审计日志谁在什么时候读了什么密钥、自动轮换定期换密钥降低泄露影响。用上之后你的代码里不再有任何密钥只有一个去哪里取密钥的地址。代价是引入了一个依赖而且服务本身要保证高可用——它挂了你的程序也起不来。所以要不要上取决于你的项目规模和密钥敏感度。我的判断标准是如果密钥泄露会造成实际损失钱、数据、声誉那就值得上。如果只是内部工具、密钥权限很小环境变量加严格的 .gitignore 也够用。5.4 我实际项目里的分层做法说说我自己怎么做的供你参考。我把密钥分成三层。第一层是完全公开的配置比如 API 的 base URL、超时时间这些直接写在代码里或者配置文件里无所谓。第二层是敏感但低风险的密钥比如只读的第三方 API key。这类放环境变量配合 .gitignore 和 CI 的 secret 管理够用。第三层是高风险密钥比如能写数据、能扣费的。这类一律走密钥管理服务代码里只存一个引用运行时动态取。而且这类密钥我会设置最小权限——只给需要的操作权限不给全量权限。比如一个只需要读某个表的密钥就绝不给它写权限。还有一条经验密钥要能轮换。设计系统时就要考虑如果这个密钥泄露了我怎么在不停机的情况下换掉它。如果换密钥需要改代码、重新部署那说明设计有问题。好的设计是密钥存在外部程序启动时读取换密钥只需要更新外部存储重启或者热加载即可。6. 把感知、决策、执行串起来一个完整的排查思路6.1 出问题时先定位在哪一层前面把三层拆开讲了实际排查时最重要的是快速定位问题出在哪一层。我的做法是看现象。如果 Agent 完全不动或者报找不到元素那大概率是感知层问题——页面没加载完、元素筛选逻辑漏了、可访问性树没建好。这时候要去看感知层输出的元素清单确认目标元素在不在里面。如果 Agent 动了但点错了那是决策层问题——模型选错了元素或者动作参数不对。这时候要去看模型的决策日志看它为什么选了这个。常见原因是元素清单里有多个相似项模型分不清。如果 Agent 点了但没反应那是执行层问题——坐标偏了、被遮挡了、事件没触发。这时候要去看执行层的详细日志确认点击事件到底有没有发出去、发到哪了。这个分层定位法能帮你省下大量瞎试的时间。很多人一遇到问题就改 prompt其实问题根本不在决策层改 prompt 当然没用。6.2 日志要记到什么粒度排查依赖日志但日志记太粗没用记太细又刷屏。我的经验是关键节点必记中间过程按需记。关键节点包括每次感知后记录元素清单的摘要多少个元素、有哪些关键项、每次决策后记录选了哪个动作、每次执行后记录成功还是失败以及失败原因。这些是必记的。中间过程比如完整的 DOM 快照、完整的模型输入输出这些默认不记出问题时再开。因为完整快照体积很大全记下来存储扛不住而且大部分时候用不上。还有一个技巧是给每次任务分配一个 trace ID所有日志都带上这个 ID。这样排查时一搜就能把一次任务的完整链路拉出来不用在茫茫日志里捞。6.3 那些看起来是 bug 其实是特性的情况最后说几个我踩过的、一开始以为是 bug 后来发现是正常行为的情况帮你少走弯路。第一个是页面加载慢导致的超时。有时候不是 Agent 的问题是目标站点本身慢。这时候调大超时时间就好不用改逻辑。第二个是反自动化检测。有些站点会检测自动化工具检测到了就返回一个假页面或者直接拒绝。这时候 Agent 看到的是假页面自然操作不了。这种情况要具体分析通常需要调整浏览器指纹或者降低操作频率。第三个是动态内容导致的元素失效。页面重新渲染后之前拿到的元素引用就失效了再操作会报错。解决办法是每次操作前重新定位元素不要缓存元素引用。这些情况共同的特点是问题不在你的代码逻辑而在外部环境。识别出这一点你就不会在错误的方向上浪费时间了。7. 关于密钥轮换和权限收敛的一点个人体会写到这里浏览器控制这条链路基本讲完了。最后想单独说说密钥这件事因为它太容易被忽视又太容易出事。我现在的习惯是任何新项目一开始就把密钥管理设计进去而不是等出了问题再补。具体做法是项目初始化时就确定密钥存哪、怎么取、怎么轮换然后写进 README让所有参与的人都清楚规则。这比事后补救省事得多。另一个体会是权限要收得比你以为的还紧。我见过太多为了方便先给全权限最后变成安全隐患的案例。正确的做法是默认最小权限需要什么加什么而不是反过来。加权限麻烦一点但安全。还有一点是定期审计。每隔一段时间检查一下哪些密钥还在用、哪些已经废弃但没删、哪些权限过大。这个习惯能帮你及时发现隐患。密钥管理不是一次性的工作是持续的。浏览器自动化和密钥管理一个是让 Agent 能干活一个是让 Agent 安全地干活。两件事都做好项目才算真正能上生产。希望这篇拆解能帮你把这两块都想清楚。
阅读完成 · 觉得有帮助？
