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：
   ```json
   {
     "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` 读写，结构示例：

```json
{
  "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` 的脚本，容易在模糊点步骤卡住；这类任务应提前评估是否需要人工兜底。