Zerotoken Openclaw

ZeroToken 浏览器自动化（OpenClaw）

教会 Agent 使用 ZeroToken MCP 做浏览器自动化、轨迹录制与脚本重放。旨在让 OpenClaw 执行定时/重复任务时尽量少消耗 Token。

ZeroToken 项目主页：https://github.com/AMOS144/zerotoken

何时使用 / 何时不该用

• 适合使用：
  • 需要通过 OpenClaw + ZeroToken MCP 做浏览器自动化，并且未来会 重复 / 定时执行 的任务。
  • 已经有一次完整的浏览器操作轨迹，希望将其 转成低 Token 消耗的脚本 来复用。
• 不适合使用：
  • 只想临时操作一次、没有复用需求的场景（直接用 ZeroToken MCP 即可）。
  • 页面强依赖人工决策，大量步骤都需要 fuzzy_point 介入、无人值守难以兜底的任务。

前置条件

• 当前环境中已能通过 MCP 访问名为 zerotoken 的服务器（或等价的 MCP server id）。
• 执行浏览器操作前需先调用 browser_init；完成后可选调用 browser_close。

OpenClaw 使用前准备（HTTP 模式）

当通过 OpenClaw / MCPorter 使用 ZeroToken 时，因其每次调用会新建进程，导致 browser 状态丢失。需改用 Streamable HTTP 传输模式，服务常驻：

1. 手动启动 HTTP 服务（在后台常驻）：
   • zerotoken-mcp-http，或
   • zerotoken-mcp --transport streamable-http
   • 默认端口 8000，可用 --port 或环境变量 ZEROTOKEN_HTTP_PORT 覆盖。
2. OpenClaw 配置：在 openclaw.json 的 mcpServers.zerotoken 中，使用 URL 而非 command：

   {
     "mcpServers": {
       "zerotoken": {
         "url": "http://localhost:8000/mcp"
       }
     }
   }

   具体字段名以 OpenClaw 文档为准（可能为 streamable-http 或 url）。

MCP 未配置 / 未安装 ZeroToken 时的处理

当调用 ZeroToken 相关 MCP 工具失败，并出现类似以下症状时：

• 找不到名为 zerotoken 的 MCP server；
• browser_init / trajectory_start 等工具报「tool not found」「MCP server unavailable」或 import 相关错误；

Agent 应按以下顺序处理：

1. 明确告知用户：ZeroToken MCP 尚未在当前环境安装或启用，暂时无法使用浏览器自动化脚本能力。
2. 询问用户当前所用平台（如「Cursor / OpenClaw / 其他支持 MCP 的客户端」），并指导用户安装 ZeroToken 及浏览器依赖：
   • OpenClaw + MCPorter：mcporter install zerotoken --target openclaw --configure。重要：OpenClaw 需用 HTTP 模式，先在后台运行 zerotoken-mcp-http，再在 openclaw.json 中将 mcpServers.zerotoken 配置为 {"url": "http://localhost:8000/mcp"}（见上文「OpenClaw 使用前准备」）。
   • 如果平台有 MCP Marketplace / 插件市场：
     提示用户在市场中搜索并启用 zerotoken MCP。
   • 如果是本地 Python 环境（如命令行 / 开发机）：
     提示用户依次执行：
     1. 安装包：pip install zerotoken
     2. 安装 Playwright 浏览器依赖（否则浏览器工具会报错）：
        • 普通环境：playwright install chromium
        • 如使用 uv：uv run playwright install chromium --with-deps
     3. 启动 MCP Server：OpenClaw 在后台运行 zerotoken-mcp-http；Cursor 等 IDE 运行 zerotoken-mcp（或由客户端自动拉起）。
     4. 在客户端中，将该 MCP server 注册为 id 为 zerotoken 的 MCP；OpenClaw 需在 openclaw.json 中配置 URL（见「OpenClaw 使用前准备」）。
3. 在用户确认 ZeroToken 已安装并启用后，Agent 再次从 browser_init 开始执行 ZeroToken 相关步骤。

MCP 工具与流程

工具清单（与 MCP 对齐）

• browser：browser_init（可选 stealth: true 反爬）、browser_close、browser_open、browser_click、browser_input、browser_get_text、browser_get_html、browser_screenshot、browser_wait_for、browser_extract_data
• trajectory：trajectory_start、trajectory_complete、trajectory_get、trajectory_list、trajectory_load、trajectory_delete、trajectory_to_script（轨迹转脚本并保存到数据库）
• script：
  • script_save、script_list、script_load、script_delete
  • run_script：无 LLM 回放脚本执行
    • Start 模式：{ "task_id": "...", "vars"?: {...} }
    • Resume 模式（高级用法）：{ "session_id": "...", "resolution": {...} }（由上层编排器在 DFU/模糊点暂停后恢复）
  • run_script_by_job_id：定时任务一步执行，{ "binding_key": "job_id", "vars"?: {...} }，内部查绑定并执行
• session：session_list、session_get(session_id)：查询录制 / 回放会话明细，用于 debug、审计、定时任务复盘

脚本、轨迹与会话均由 MCP 后端存储在 SQLite 数据库 中，通过上述工具访问，不依赖本地文件路径。

可选参数：include_screenshot: false 减少响应体积；auto_save: true / adaptive: true 用于自适应元素定位。

Quick Reference

典型流程

• 录制：trajectory_start(task_id, goal) → browser_init → browser_open / browser_click / browser_input 等 → trajectory_complete(export_for_ai: true)
• 复用：trajectory_list 查 task_id → trajectory_load(task_id, format) 获取轨迹
• 管理：trajectory_delete(task_id) 删除；browser 工具可传 include_screenshot: false
• 错误：失败时返回 success: false、code、retryable，可按 retryable 决定是否重试

何时才生成脚本

仅在以下情况根据轨迹生成可复用脚本（避免徒增 Token）：

1. 重复任务：用户明确说会多次执行（如「以后每天跑」「定时执行」「重复任务」），或 cron/上下文表明是定时/周期任务。
2. 用户明确要求：用户说「生成可复用脚本」「保存成脚本下次用」「导出为脚本」等。

不主动生成：未提复用、未提定时/重复时，只做轨迹录制与保存。若用户后续要脚本再生成。

定时任务如何找到对应脚本（基于 job_id 绑定）

当 OpenClaw 以定时任务触发本 Skill 时，事件参数中会携带该任务的 job_id。ZeroToken 使用 job_id 作为绑定键（binding_key），并在 MCP 数据库的 script_bindings 表中维护「job_id ↔ 脚本」关系。

Agent 必须遵守以下约定：

1. 优先使用 run_script_by_job_id(binding_key=job_id, vars?) 一步执行：MCP 内部查绑定、合并 default_vars、执行脚本。
2. 若需分步控制，可调用 script_binding_get(binding_key=job_id)，再 run_script(task_id, vars=merged_vars)。
3. 若 run_script_by_job_id 或 script_binding_get(job_id) 返回「未找到」：
   • 提示用户「当前 job_id 尚未绑定 ZeroToken 脚本」；
   • 不要随意尝试其他脚本或自动新建脚本。
4. 对于没有 job_id 或未标记为定时任务的场景：
   • 视为「一次性任务」，只使用 browser_* + trajectory_* 完成当前需求，不主动查找/执行脚本。

开发者应在 ZeroToken 侧或 OpenClaw 的集成层中，使用 script_binding_set(binding_key=job_id, script_task_id=..., default_vars?, description?) 预先将定时任务 job_id 与脚本 task_id 明确绑定。本 Skill 仅通过 job_id 查询绑定，不对映射关系做额外推断。

配置定时任务（完整流程）

当 Agent 收到带 job_id 的定时任务配置请求（如用户说「设为每日执行」「把这个任务设为定时」），且 OpenClaw 已传入 job_id 时，必须完成以下端到端流程：

1. 确定 task_id：用户指定、或最近录制的 trajectory 的 task_id（如 trajectory_list 取最新）。
2. 检查轨迹：trajectory_load(task_id) 检查轨迹是否存在；若无则提示用户先录制。
3. 生成脚本：script_load(task_id) 检查脚本是否存在；若无则调用 trajectory_to_script(task_id, stealth?) 根据轨迹生成并保存。
4. 绑定：script_binding_set(binding_key=job_id, script_task_id=task_id, default_vars?, description?) 将 job_id 与脚本绑定。

重要：task_id 贯穿 trajectory → script → binding，三者必须一致。录制时用的 task_id 即脚本的 task_id，也是 binding 的 script_task_id。

若 script_binding_set 返回 SCRIPT_NOT_FOUND，说明脚本不存在，应先 trajectory_to_script(task_id) 再绑定。

反爬应对（易被云盾/反爬拦截的站点）

若目标站点（如 B 站、小红书等）易被检测为自动化并拦截，需：

1. 录制时：browser_init 传 stealth: true，降低被识别概率。
2. 生成脚本时：trajectory_to_script(task_id, stealth=true) 使生成的脚本中 browser_init 包含 stealth: true。
3. 执行时：run_script 会按脚本中的 browser_init 参数执行，若脚本含 stealth: true 则自动启用反检测。

stealth 模式会启用：启动参数伪装、navigator 指纹伪装、Sec-CH-UA 头、WebGL 指纹伪装等。