Codeg 浏览器智能体：如何让 AI Agent 读取并操作网页的完整指南

Codeg 浏览器智能体如何让 AI Agent 读取并操作网页的完整指南【免费下载链接】codegCollaborative multi-agent AI coding workspace: aggregate sessions from Claude Code, Codex, OpenCode, Pi, Grok Build, etc. Desktop app, self-hosted server, or Docker.项目地址: https://gitcode.com/gh_mirrors/co/codegCodeg 浏览器智能体让 AI 编程助手直接读取你内置浏览器里的网页、并按需执行点击、输入、按键等操作。这篇完整指南会带新手从零理解Agent 如何看见页面、如何拿到操作权限、每一步操作如何被审计以及常见问题的最快解决办法。为什么 AI Agent 需要浏览器智能体普通的 AI 编程助手如 Claude Code、Codex、OpenCode 等擅长读写代码但常常看不见网页。Codeg 聚合了这些智能体会话并内置了一个浏览器智能体可以在其中打开页面然后像人一样去读取和操作它。典型场景️ 让 Agent 查看你本地开发服务器如localhost:3000的渲染效果验证前端修改是否生效 让 Agent 读取某个网页的结构与文案据此生成代码或文档️ 让 Agent 代替你完成点击按钮、填写表单、选择下拉项等重复性网页操作核心机制概括为一句话Agent 不直接摸 DOM而是先拍照快照拿到元素的引用ref再凭 ref 去点击或输入——这正是 Playwright 生态通用的做法源码说明见 browser-agent/README.md。一页纸看懂Agent 读取网页的完整流程整个流程分四步每步都对应一个内置工具列出标签页—browser_list_tabs告诉 Agent 当前有哪些页面可看抓取页面快照—browser_snapshot把页面变成一棵带编号元素e1、e2…的无障碍树执行操作—browser_click/browser_type/browser_press_key/browser_hover/browser_select_option按 ref 定位并操作核对结果— 再次快照或browser_screenshot/browser_console_messages确认页面变化这些工具由内置的 codeg-mcp 服务承载权限判断统一走 src-tauri/src/browser/agent.rs工具定义见 src-tauri/src/acp/browser_tools.rs。关键权限模型先共享后操作Codeg 的设计原则非常强硬没有任何页面是被默认开放的。Agent 要读一页唯一的路径是你主动共享这个标签页给它。在浏览器标签页的工具栏中点击机器人图标即可打开共享菜单提供两个层级权限级别中文名称Agent 能做什么read读取权限快照、截图、读控制台control读取并操作权限在读取基础上可点击、输入、按键、选择none不共享默认一律拒绝并提示你共享标签页几个值得记住的细节按站点生效共享只覆盖该网址origin页面一旦跳转到别的站点共享自动结束️本地端口防串门如果你共享的是localhost:3000Codeg 会记住当时是哪个程序含工作目录在监听换一个程序占用该端口共享同样失效全程留痕每次读取/操作都会在地址栏右侧的活动记录中显示读取了页面点击了 ××已拒绝此页面未共享等条目界面实现见 src/components/browser/browser-agent-access.tsx❌拒绝也是一种答案没有共享时工具返回的不是报错而是一条可读的说明browser_grant_requiredAgent 会转告你请共享这个标签页快照与操作AI 如何看见并动手页面脚本运行在与 Agent 隔离的独立环境中注入脚本由 esbuild 构建为 src-tauri/src/browser/js/agent.bundle.js源码在 browser-agent/src/ 目录。读取页面快照快照采用 Playwright 的 ai 模式所有可见且能接收指针事件的元素都会拿到一个 ref——连没有 ARIA 角色、只挂了点击事件的div也能被点名快照默认有 4 万字符上限可在请求中调整超出会标注truncated提醒 Agent 缩小提问范围而不是误以为页面到底了操作页面动作动作工具在一次求值内完成解析 ref → 执行动作中间页面不可能变化避免点对了元素名、点错了元素️点击被遮挡的元素会被拒绝并告诉你谁挡在前面比如弹窗遮罩⌨️输入优先走浏览器原生beforeinput/input事件保证 Vue、React 这类框架能收到滚动没有单独的滚动工具PageDown/PageUp 按键就是唯一的滚动方式Agent 会收到实际滚动了多少、还能滚多少的真实反馈⚠️陈旧 ref页面跳转后旧快照里的 ref 一律作废browser_stale_refAgent 必须重新快照——宁可多问一次也不点错东西常见提示与最快排查方法提示含义最快解决browser_grant_required页面未共享给 Agent在标签页工具栏点机器人图标选择共享browser_control_required已共享但只有读权限Agent 想操作把共享升级为读取并操作权限browser_stale_ref引用的元素已随页面变化失效无需处理Agent 会自动重新快照browser_eval_declined你拒绝了在页面上运行一段代码这是逐条审批制重新允许即可browser_unavailable当前构建/模式下没有内置浏览器注意服务端模式下浏览器工具组不启用另外Agent 若在页面上运行自定义 JavaScriptbrowser_eval会先弹出确认框向你展示完整代码逐条审批、可随时拒绝——你有权知道它在页面上跑什么。适合新手的起步清单✅ 安装并打开 Codeg 桌面版确认内置浏览器可用浏览器功能相关设置位于设置 → 内置浏览器前端代码在 src/settings/browser/ 目录✅ 在内置浏览器中打开任意页面点击工具栏机器人图标选择读取权限完成第一次共享✅ 在对话中让 Agent 描述当前页面观察地址栏右侧出现的读取了页面活动记录✅ 需要操作时升级为读取并操作权限试试让它点击一个按钮✅ 阅读 browser-agent/README.md 了解 ref 失效、遮挡拒绝等设计细节总结Codeg 的浏览器智能体把AI 看网页、操作网页变成了一件权限清晰、过程可审计、失败方向安全的事没有自动授权、每个标签页独立控制、每次动作都有记录。对新手来说只需要记住三个词——共享、快照、按 ref 操作——就能安全地让 AI 助手替你读懂网页、动手点击。【免费下载链接】codegCollaborative multi-agent AI coding workspace: aggregate sessions from Claude Code, Codex, OpenCode, Pi, Grok Build, etc. Desktop app, self-hosted server, or Docker.项目地址: https://gitcode.com/gh_mirrors/co/codeg创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考