zerotoken-openclaw

name	zerotoken-openclaw
description	Use when using ZeroToken MCP via OpenClaw for browser automation, trajectory recording and low-token replay, especially for recurring or scheduled browser tasks.

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

工具 / action	典型用途
browser_init	初始化浏览器会话（可选 headless/stealth）
browser_open	打开登录页或任意目标页面
browser_click	点击按钮、链接、tab 等
browser_input	在输入框内输入用户名、密码、搜索关键字等
browser_get_text/get_html	读取文本或整段 HTML，用于后续解析
browser_wait_for	等待某段文本出现/消失，避免页面还没加载完
browser_screenshot	截图留档或调试
browser_extract_data	从列表 / 表格中抽数据
trajectory_start/complete	录制一次完整的浏览器操作轨迹

典型流程

• 录制：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 指纹伪装等。

定时任务执行失败时的恢复

• SCRIPT_BINDING_NOT_FOUND：提示用户「当前 job_id 尚未绑定 ZeroToken 脚本」，需先完成配置流程。
• SCRIPT_NOT_FOUND（binding 存在但脚本被删）：若返回 hint 字段，可按提示执行 trajectory_to_script(script_task_id) 重新生成脚本（轨迹仍在时），再重试 run_script_by_job_id。

脚本格式与执行方式

格式（存于 MCP 数据库）

脚本通过 script_save / script_load 读写，结构示例：

{
  "task_id": "login_daily",
  "goal": "每日登录并拉取报表",
  "steps": [
    { "action": "browser_init", "params": { "headless": true, "stealth": true } },
    { "action": "trajectory_start", "params": { "task_id": "login_daily", "goal": "每日登录并拉取报表" } },
    { "action": "browser_open", "params": { "url": "https://example.com/login" } },
    { "action": "browser_input", "params": { "selector": "#user", "text": "{{username}}" } },
    { "action": "browser_click", "params": { "selector": "#submit" },
      "fuzzy_point": { "reason": "验证码需识别", "hint": "可调 browser_extract_data 或等待人工输入" } },
    { "action": "browser_get_text", "params": { "selector": ".report" } }
  ]
}

• steps：有序数组；每步 action 对应 MCP 工具名，params 为该工具入参。
• 可选 fuzzy_point：记录该步「需要 AI/人介入」的语义信息（reason、hint），本身不会让 ScriptEngine 自动暂停；只有当为该步配置了匹配的 DFU / 执行点时，run_script 执行到该步才会返回 status="paused"。
• 可选参数化：params 中可用 {{varname}}，执行前由 Agent 或配置替换（如环境变量、用户输入），或在 ExecutionPoint/DFU 暂停时由上层生成 resolution.vars 合并进运行时变量环境。含 {{varname}} 的脚本，执行前必须提供对应 vars（run_script 的 vars 或 run_script_by_job_id 的 vars/binding 的 default_vars），否则占位符会保留字面量，可能导致无效输入。

执行脚本（仅在定时 / 重复任务场景）

只有在以下两种情况下，才去查找并执行脚本：

• 上下文/cron 明确表明是「定时 / 周期性 / 重复执行」的任务（如每日评论、每小时抓取报表）。
• 用户明确说「执行 ZeroToken 脚本 <task_id>」「跑一下 <task_id> 的脚本」等。

在这些情况下：

1. 调用 script_load(task_id) 从 MCP 数据库读取脚本；若无则调用 trajectory_to_script(task_id) 根据轨迹生成并保存（否则不要擅自造脚本）。
2. 调用 run_script(task_id, vars?) 由 MCP 内的 ScriptEngine 自动按 steps 顺序执行脚本，无需 LLM，执行过程写入 session；返回形如 {"success": ..., "status": "success|paused|failed", "session_id": ...}。
3. 若返回 status="paused"（例如命中 DFU / 执行点 / 失败重试上限）：
   • 上层 Agent 阅读 pause_event（包含 step_index、dfu_id、提示文案与需要生成的 vars），做一次决策或生成 vars；
   • 再调用 run_script(session_id=..., resolution={...}) 恢复执行，由 ScriptEngine 继续顺序执行后续 steps。

非定时/一次性任务：优先只用 browser_ + trajectory_ 录制与完成当前任务，不主动查找/执行脚本。**

脚本是「数据驱动的 MCP 调用序列」，存于 MCP 数据库，由 ScriptEngine 自动化回放，Token 消耗低且可通过 session 追踪每次执行。

模糊点 / DFU 执行约定

• *有 Agent 在场（手动调用 browser_ 时）**：遇到带 fuzzy_point 的 OperationRecord / 步骤时，可把 reason、hint 视作提示，根据当前页面决定是否额外调用 browser_extract_data、browser_input 等，再继续。
• 使用 run_script（ScriptEngine 自动回放）时：是否暂停由 DFU/执行点规则决定（dfu_* 配置 + trigger 匹配），而不是单靠 fuzzy_point。若某步既有 fuzzy_point 又命中 DFU，则 ScriptEngine 会在该步返回 status="paused" + pause_event，由上层 Agent 决定 resolution 后再恢复。
• 无人值守：不建议依赖大量需要强人工判断的步骤；含模糊点但未配置 DFU 的脚本，在纯 run_script 模式下会直接按脚本跑完，可能需要通过 session 结果+日志事后审计。

根据轨迹生成脚本（流程）

推荐：直接调用 trajectory_to_script(task_id, script_task_id?, prepend_init?, stealth?)，MCP 会从数据库加载轨迹、转换为脚本并保存，返回 task_id。若目标站点易被反爬拦截，传 stealth=true 使生成的脚本中 browser_init 包含 stealth: true。

若需手动控制，可参考以下流程：

1. 输入：trajectory_load(task_id, format="json") 或 format="ai_prompt"；必要时先用 trajectory_list 选 task_id。

2. action 映射：轨迹中的 operations[].action 为内部名，生成脚本时必须映射为 MCP 工具名；执行时按 MCP 工具名调用。

   轨迹 action	脚本/MCP action
   open	browser_open
   click	browser_click
   input	browser_input
   get_text	browser_get_text
   get_html	browser_get_html
   screenshot	browser_screenshot
   wait_for	browser_wait_for
   extract_data	browser_extract_data

   轨迹不包含 browser_init、trajectory_start；生成脚本时在 steps 开头补上这两步（若需录制回放）。

3. 输出：调用 script_save(task_id, goal, steps) 写入 MCP 数据库；steps 中 action 用映射后的 MCP 名，params 与轨迹一致，selector_candidates、fuzzy_point 从轨迹带出。

保存位置与复用查找

• 脚本与轨迹：均由 MCP 后端存储在数据库（SQLite）中，不依赖本地文件路径。
• 查找：执行/复用某任务时，用 trajectory_list 或 script_list 得到 task_id，用 script_load(task_id) 取脚本；若无则提示「该任务尚无脚本，是否根据轨迹生成？」并直接调用 trajectory_to_script(task_id) 生成并保存。
• 会话：每次 run_script 或录制产生 session，用 session_list、session_get(session_id) 查看。

安装

将本 Skill 放入 OpenClaw 的 skills 目录之一：

• 工作区：./skills/zerotoken-openclaw/（仅当前项目）
• 本地共享：~/.openclaw/skills/zerotoken-openclaw/
• 或通过 ClawHub：clawhub install zerotoken-openclaw（若已发布）

从本仓库安装示例：克隆后复制 skills/zerotoken-openclaw/ 到上述路径之一。

常见坑

• OpenClaw：未在后台启动 zerotoken-mcp-http 或 openclaw.json 仍用 command 而非 url，导致每次调用新建进程、browser 状态丢失。
• 忘记先调用 browser_init 就直接使用 browser_open / browser_click，导致第一次调用失败或异常。
• 录制轨迹时未使用 export_for_ai: true，后续生成脚本时需要额外处理轨迹数据。
• task_id 在 trajectory 与 script 中不一致，导致 script_load(task_id) 找不到对应脚本。
• 无人值守场景仍然依赖包含大量 fuzzy_point 的脚本，容易在模糊点步骤卡住；这类任务应提前评估是否需要人工兜底。