官方 Browser 文档实际说明了什么
官方资料里有几个容易被忽略的信号：
| 主题 | 官方资料里的含义 | 对你的实操影响 |
|---|---|---|
openclaw profile | OpenClaw 管理的专用浏览器配置，与个人浏览器隔离 | 默认先用它做低风险测试，不要误以为它天然有你的个人登录态 |
user profile | 连接真实已登录 Chrome 会话的内置配置 | 只有在登录态确实必要、且你能在电脑前批准时才用 |
| loopback 控制服务 | Gateway 内本地控制服务管理浏览器 | 默认更偏本机受控，不要随意暴露给公网 |
| SSRF 策略 | 导航和远程 CDP 探测有私网访问边界 | 访问内网、代理、远程浏览器时要显式判断风险 |
| tab cleanup | OpenClaw 会尽力清理空闲或超量标签页 | 长任务要保存关键结果，不要假设标签页永远保留 |
| node browser proxy | 节点主机可代理本地浏览器能力 | 适合远程 Gateway，但要限制可用 profiles |
这意味着你不能只写一句“让 Agent 打开网页”。成熟的 Browser 工作流一定要回答：用哪个 profile、谁来登录、结果怎么验证、失败怎么恢复、哪些页面不能自动点。
什么时候用隔离的 openclaw profile
优先从 openclaw profile 开始，适合这些场景：
- 打开公开页面并读取内容。
- 对网页做截图、PDF、结构检查。
- 在测试账号里填写低风险表单。
- 检查登录前页面、文档站、状态页、公开控制台。
- 给 Agent 一个干净环境，避免污染你的日常浏览器。
示例验证命令：
openclaw browser --browser-profile openclaw doctor
openclaw browser --browser-profile openclaw doctor --deep
openclaw browser --browser-profile openclaw status
openclaw browser --browser-profile openclaw start
openclaw browser --browser-profile openclaw open https://example.com
openclaw browser --browser-profile openclaw snapshot如果你只是验证 Browser 能否运行，不要一开始就拿银行、社交账号、生产后台来测。先用公开页面或测试环境确认：浏览器能启动、标签页能打开、快照能返回、Agent 能在同一个 tab 上持续操作。
什么时候显式使用 user 或 existing-session profile
有些任务绕不开真实登录态：
- 已登录后台才能看到订单、工单、报表。
- 网站对新浏览器频繁触发 2FA。
- Cookie、设备信任、SSO 会话决定任务能否继续。
- 你需要在已有 Chrome 里手动确认某个授权弹窗。
这时可以考虑 profile="user" 或自定义 existing-session profile。关键边界是：不要让 Agent 猜测你的浏览器环境，也不要把账号密码交给模型。
推荐流程：
- 先确认任务是否真的必须使用已有登录态。
- 打开目标页面，自己完成登录、2FA、验证码或设备确认。
- 让 OpenClaw 使用明确的 Browser profile 继续后续低风险步骤。
- 遇到付款、发布、删除、授权、导出等动作时，切回人工确认或审批。
- 任务结束后，记录哪些页面、账号、profile 和数据被使用过。
如果你有多个 Chrome / Brave / Edge 配置文件，就把配置写清楚。不要让 Agent “自己找一个看起来像已登录的浏览器”。
一个可复用的网页任务设计
假设你要让 OpenClaw 每天检查一个 SaaS 后台的异常订单，推荐拆成 6 步：
- 定义任务结果：只需要读取异常数，还是要导出 CSV？只读任务和写入任务风险完全不同。
- 选择 profile：公开页面用
openclaw；必须复用登录态时才用user。 - 人工完成登录：账号、密码、2FA、验证码都由人完成，不写进 prompt 和配置文件。
- 让 Agent 只做可验证操作：打开指定 URL、筛选日期、读取数量、截图留证。
- 设置敏感动作停止点：导出、删除、提交、付款、发布前必须停下等待确认。
- 把结果交给下一步：需要周期运行时，再看 OpenClaw automation。
表面上这是网页自动化，本质上是风险分层。真正稳定的 Browser 任务，不是尽量少让人参与，而是在正确的位置让人参与。
配置示例：默认用隔离浏览器
下面是偏保守的 Browser 配置骨架，适合先让团队建立共识：
{
browser: {
enabled: true,
defaultProfile: "openclaw",
actionTimeoutMs: 60000,
tabCleanup: {
enabled: true,
idleMinutes: 120,
maxTabsPerSession: 8
},
profiles: {
openclaw: {
color: "#FF4500"
},
user: {
driver: "existing-session",
attachOnly: true,
color: "#00AA00"
}
}
},
tools: {
alsoAllow: ["browser"]
}
}这段配置表达的是：
- 默认走隔离的
openclawprofile。 - 需要已有登录态时，才明确切到
user。 user不负责启动浏览器，只负责连接已有会话。- Browser 工具要在 tools allowlist 中被显式允许。
- 标签页清理策略保持开启，避免长期任务留下过多浏览器状态。
远程 CDP 和 Browserless 要怎么想
官方文档也覆盖远程 CDP、Browserless、Browserbase 和节点浏览器代理。不要把这些当成“更高级就更好”的选项。
| 方案 | 适合场景 | 主要风险 |
|---|---|---|
本地 openclaw profile | 日常网页任务、测试账号、公开页面 | 需要本机浏览器环境，登录态与个人浏览器隔离 |
user existing-session | 必须复用已有 Chrome 登录态 | 会接近真实账号操作，必须有人在场确认 |
| 远程 CDP | 浏览器跑在另一台主机或托管服务 | CDP URL、token、网络可达性和私网访问边界要管好 |
| node browser proxy | Gateway 在远端，浏览器在节点机器 | 要限制可代理的 profiles，避免节点暴露过多浏览器能力 |
远程浏览器配置里的 token、Basic Auth、Browserless API key 都应该按密钥处理。不要把这些值提交到仓库，也不要把公网可访问的 CDP endpoint 暴露给不可信调用方。
Browser 与安全审批怎么配合
Browser 很容易让人兴奋，因为它看起来接近“真人上网”。但越像真人，越要给它边界。
建议把网页动作分为 4 类：
| 动作类型 | 例子 | 推荐处理 |
|---|---|---|
| 只读 | 打开页面、搜索、截图、读取表格 | 可自动执行，但要记录 URL 和结果 |
| 低风险写入 | 填测试表单、保存草稿 | 允许前先限定测试环境和账号 |
| 高风险写入 | 发布、删除、邀请成员、改权限 | 必须人工确认或走 Control UI 审批 |
| 不可逆/敏感 | 付款、转账、导出客户数据、改账单 | 默认禁止自动完成，只能人工操作 |
这不是保守，而是让 Browser 真正可长期使用。没有边界的网页自动化，很快会变成事故来源。
常见坑
- 拿匿名页面测试成功，就误以为登录型网页任务也会稳定。
- 把
openclawprofile 和个人 Chrome profile 混为一谈。 - 遇到验证码就让 Agent 反复重试，导致账号触发更多风控。
- 远程 CDP URL 带 token，却被写进仓库或日志。
- 只开启 Browser 工具，却忘了给 agent 或 subagent 的 tools profile 放行。
- 高风险网页动作没有审批，也没有截图、日志或回滚策略。
- 任务跑完后没有清理标签页、会话或测试数据。
排错顺序
Browser 不工作时，按这个顺序排查，比反复重装更快：
- 命令是否存在：
openclaw browser是否可用；如果缺失，检查 Browser 插件和工具 allowlist。 - Gateway 是否 ready：Browser 控制服务跟 Gateway 运行态有关，不要只看进程是否存在。
- profile 是否选对：公开任务看
openclaw；已有登录态看user或自定义 existing-session。 - 浏览器是否能启动/附加：本地托管、attachOnly、远程 CDP 是三种不同问题。
- 页面是否真的可自动化：2FA、验证码、风控弹窗、权限弹窗都可能要求人工介入。
- 动作是否越界：如果任务涉及高风险写入，失败可能不是技术问题，而是流程设计不该自动执行。
OpenClaw Browser 登录流
推荐流程：手动登录 + Agent 继续
最稳的网页登录流不是“自动登录”，而是下面这条路径：
- Agent 打开目标页面，判断是否已经登录。
- 如果出现登录墙，Agent 明确报告需要人工登录。
- 用户在浏览器里手动完成账号、密码、2FA、验证码或 SSO。
- 登录完成后，Agent 重新获取页面快照，确认进入目标区域。
- Agent 继续执行低风险、可验证、可回滚的页面步骤。
- 一旦出现发布、删除、付款、授权、导出等敏感动作，重新交给人工或审批。
这个流程看似多一步，其实比自动输入密码更快。反机器人保护、设备信任、验证码和登录异常处理，本来就更适合人来完成。
openclaw 和 user 怎么选
先看这个判断表：
| 任务情况 | 推荐 profile | 原因 |
|---|---|---|
| 公开页面、文档页、搜索页 | openclaw | 隔离、干净、风险低 |
| 测试账号后台 | openclaw | 可单独手动登录，不污染个人浏览器 |
| 已有 Chrome 登录态必须复用 | user 或 existing-session | 任务依赖你的真实会话 |
| 多个工作浏览器配置文件 | 显式命名的 custom profile | 避免 Agent 猜错账号 |
| 远程浏览器或托管 CDP | remote profile | 需要额外处理 token、网络和私网边界 |
如果你不确定，就先用 openclaw。只有当“没有现有 session 就无法完成任务”时，才升级到 user。
登录墙处理清单
遇到登录墙时，不要急着让 Agent 继续点。先问 5 个问题：
- 这个网站是否允许自动化访问，是否有账号使用条款限制？
- 是否可以使用测试账号，而不是个人主账号或生产管理员账号？
- 登录是否需要 2FA、验证码、Passkey、设备确认或 SSO？
- 登录后要做的是只读任务，还是会写入、发布、删除或付款？
- 登录完成后，如何判断任务真正成功，而不是只是进了首页？
只有这些问题有答案，网页登录任务才适合继续。
验证码和 2FA 怎么处理
验证码和 2FA 不是“工具失败”，而是系统在提醒你进入人机协作。
推荐做法：
- Agent 看到验证码、短信码、邮箱码、Passkey、扫码登录或安全问题时，立即停下。
- Agent 用短句说明当前页面需要人工验证，不猜测、不绕过。
- 用户完成验证后，Agent 重新获取页面快照。
- Agent 检查 URL、页面标题、关键元素或预期数据，确认真的进入目标状态。
- 如果验证反复失败，终止任务并记录原因，不要循环重试。
反复重试验证码通常只会让账号进入更严格的风控。成熟流程的目标不是“永远自动完成”，而是“该停的时候停得及时”。
已有 session 的边界
使用已有 Chrome session 很方便，但它会把 Agent 放到更接近真实账号的位置。建议设置这些规则：
- 只在用户在电脑前时使用
user或 existing-session profile。 - 不允许 Agent 自己切换账号、创建新会话或保存新密码。
- 高权限后台优先用低权限账号，避免管理员账号直接暴露给自动化流程。
- 如果浏览器提示连接、扩展、权限或设备确认，由人决定是否批准。
- 每次任务结束后，记录使用了哪个 profile、哪个账号范围和哪些页面。
如果你准备把这个流程交给 cron 或 webhook 周期运行，先问一句：这个任务离开人以后还安全吗？如果答案不明确，就不要后台化。
示例：检查 SaaS 后台工单
一个可执行的网页登录流可以这样写：
任务：检查 SaaS 后台今天是否有 P0 工单。
Profile:
- 默认使用 openclaw。
- 如果出现 SSO 登录墙，等待人工登录。
Agent 允许做：
- 打开指定 URL。
- 读取筛选后的工单数量。
- 截图关键状态。
- 汇总标题、严重级别和创建时间。
Agent 必须停止：
- 修改工单状态。
- 指派人员。
- 导出客户数据。
- 进入账单、成员、权限页面。
成功标准：
- 页面处于已登录状态。
- 日期筛选为今天。
- P0 工单数量、列表和截图可核验。这比一句“登录后台帮我看看工单”更可靠。Agent 需要的不是更多自由，而是更清楚的边界。
示例：社交平台发布前检查
社交平台更容易触发风控，所以不要设计成完全自动发布。推荐流程：
- 人先在主机浏览器里完成登录。
- Agent 打开草稿页或发布页。
- Agent 检查文案、链接、图片预览、可见范围。
- 如果需要发布，Agent 停在最终确认前。
- 人点击发布，或通过审批流程确认后再继续。
这类任务适合“检查和准备”，不适合默认“最终提交”。尤其是 X/Twitter、LinkedIn、广告后台、邮件群发系统，都应该把最后一步留给人。
和 Dashboard / Control UI 怎么配合
网页登录任务一旦涉及高风险动作，就应该接到审批：
| 场景 | 建议 |
|---|---|
| 只读检查 | Browser 可直接执行，保留截图或摘要 |
| 测试环境写入 | 可执行，但记录环境和账号 |
| 生产后台修改 | 进入 Dashboard / Control UI 审批 |
| 客户数据导出 | 默认人工确认，必要时双人复核 |
| 公开发布 | Agent 准备草稿，人做最终确认 |
审批不是为了降低效率，而是为了让可逆和不可逆动作分开。网页登录任务一旦跑进真实系统，少一个确认点就可能多一个事故点。
常见坑
- 把密码写进 prompt、配置文件或截图说明里。
- 让 Agent 反复尝试验证码，导致账号被限制。
- 用生产管理员账号测试 Browser 能力。
- 没有区分“登录成功”和“任务成功”。
- 让后台任务使用
usersession，但运行时根本没有人在场。 - 最终提交、发布、删除、付款没有人工确认。
- 使用多个浏览器 profile，却没有显式指定账号环境。
排错顺序
网页登录流程卡住时，按这个顺序判断：
- 是否真的需要登录：目标页面是否可以用公开或测试环境替代。
- profile 是否正确：
openclaw没有你的个人登录态，user才可能接入已有 session。 - 是否需要人工动作：验证码、2FA、SSO、Passkey 都不应该让模型猜。
- 登录后是否到达目标页：看 URL、标题、关键元素和预期数据。
- 动作是否过高风险：如果到了发布、删除、付款这类页面，停止并审批。
- 是否适合自动化：如果每次都强风控，可能这个任务只适合半自动。