zerotoken-openclaw

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

ZeroToken 浏览器自动化（OpenClaw）

ZeroToken Browser Automation (OpenClaw)

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

ZeroToken 项目主页：

https://github.com/AMOS144/zerotoken

Teach Agents to use ZeroToken MCP for browser automation, trajectory recording, and script replay. The goal is to minimize Token consumption when OpenClaw executes scheduled/recurring tasks.

ZeroToken Project Homepage:

https://github.com/AMOS144/zerotoken

何时使用 / 何时不该用

When to Use / When Not to Use

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

Recommended Scenarios:
- Tasks requiring browser automation via OpenClaw + ZeroToken MCP that will be executed repeatedly or on a schedule in the future.
- You already have a complete browser operation trajectory and want to convert it into a low-Token-consumption script for reuse.
Not Recommended Scenarios:
- One-time temporary operations with no reuse requirements (just use ZeroToken MCP directly).
- Tasks where the page heavily relies on manual decisions, with numerous steps requiring
```
fuzzy_point
```
  intervention, making unattended execution difficult to guarantee.

前置条件

Prerequisites

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

The current environment can access the MCP server named
```
zerotoken
```
(or equivalent MCP server id).
Call
```
browser_init
```
before performing browser operations; optionally call
```
browser_close
```
after completion.

OpenClaw 使用前准备（HTTP 模式）

Preparations for OpenClaw (HTTP Mode)

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

手动启动 HTTP 服务（在后台常驻）：
- ```
zerotoken-mcp-http
```
  ，或
- ```
zerotoken-mcp --transport streamable-http
```
- 默认端口 8000，可用
```
--port
```
  或环境变量
```
ZEROTOKEN_HTTP_PORT
```
  覆盖。

OpenClaw 配置：在

openclaw.json

的

mcpServers.zerotoken

中，使用 URL 而非 command：

json

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

具体字段名以 OpenClaw 文档为准（可能为

streamable-http

或

url

）。

When using ZeroToken via OpenClaw / MCPorter, each call creates a new process, causing browser state loss. You need to switch to Streamable HTTP Transport Mode to keep the service resident:

Manually start the HTTP service (run in the background):
- ```
zerotoken-mcp-http
```
  , or
- ```
zerotoken-mcp --transport streamable-http
```
- Default port is 8000, which can be overridden with
```
--port
```
  or the environment variable
```
ZEROTOKEN_HTTP_PORT
```
  .

OpenClaw Configuration: In

openclaw.json

under

mcpServers.zerotoken

, use a URL instead of a command:

json

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

Refer to OpenClaw documentation for the exact field name (may be

streamable-http

url

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

Handling Unconfigured/Uninstalled ZeroToken MCP

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

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

Agent 应按以下顺序处理：

明确告知用户：ZeroToken MCP 尚未在当前环境安装或启用，暂时无法使用浏览器自动化脚本能力。
询问用户当前所用平台（如「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 使用前准备」）。
在用户确认 ZeroToken 已安装并启用后，Agent 再次从
```
browser_init
```
开始执行 ZeroToken 相关步骤。

If calling ZeroToken-related MCP tools fails with symptoms like:

Cannot find the MCP server named
```
zerotoken
```
;
Tools like
```
browser_init
```
/
```
trajectory_start
```
report "tool not found", "MCP server unavailable", or import-related errors;

The Agent should follow these steps:

Clearly inform the user: ZeroToken MCP is not yet installed or enabled in the current environment, so browser automation script capabilities are temporarily unavailable.
Ask the user about their current platform (e.g., "Cursor / OpenClaw / other MCP-supported clients") and guide them to install ZeroToken and browser dependencies:
- OpenClaw + MCPorter:
```
mcporter install zerotoken --target openclaw --configure
```
  . Important: OpenClaw must use HTTP mode; run
```
zerotoken-mcp-http
```
  in the background first, then configure
```
mcpServers.zerotoken
```
  in
```
openclaw.json
```
  as
```
{"url": "http://localhost:8000/mcp"}
```
  (see "Preparations for OpenClaw" above).
- If the platform has an MCP Marketplace / Plugin Store:
  Prompt the user to search for and enable the
```
zerotoken
```
  MCP in the marketplace.
- If using a local Python environment (e.g., command line / development machine):
  Prompt the user to execute the following steps in order:
  1. Install the package:
```
pip install zerotoken
```
  2. Install Playwright browser dependencies (otherwise browser tools will throw errors):
    - Regular environment:
      playwright install chromium
    - If using uv:
      uv run playwright install chromium --with-deps
  3. Start the MCP Server: OpenClaw runs
```
zerotoken-mcp-http
```
    in the background; IDEs like Cursor run
```
zerotoken-mcp
```
    (or it is automatically launched by the client).
  4. In the client, register this MCP server as an MCP with id
```
zerotoken
```
    ; OpenClaw needs to configure the URL in
```
openclaw.json
```
    (see "Preparations for OpenClaw").
After the user confirms ZeroToken is installed and enabled, the Agent resumes ZeroToken-related steps starting from
```
browser_init
```
.

MCP 工具与流程

MCP Tools and Workflows

工具清单（与 MCP 对齐）

Tool List (Aligned with 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

用于自适应元素定位。

browser:

browser_init

(optional

stealth: true

for anti-scraping),

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

(convert trajectory to script and save to database)

script:
- ```
script_save
```
  ,
```
script_list
```
  ,
```
script_load
```
  ,
```
script_delete
```
- ```
run_script
```
  : Execute script replay without LLM
  - Start Mode:
```
{ "task_id": "...", "vars"?: {...} }
```
  - Resume Mode (Advanced):
```
{ "session_id": "...", "resolution": {...} }
```
    (resumed by upper orchestrator after DFU/fuzzy point pause)
- ```
run_script_by_job_id
```
  : One-step execution for scheduled tasks,
```
{ "binding_key": "job_id", "vars"?: {...} }
```
  , which internally queries bindings and executes
session:
```
session_list
```
,
```
session_get(session_id)
```
: Query details of recording/replay sessions for debugging, auditing, and scheduled task review

Scripts, trajectories, and sessions are stored in the SQLite database by the MCP backend and accessed via the above tools, with no dependency on local file paths.

Optional parameters:

include_screenshot: false

to reduce response size;

auto_save: true

adaptive: true

for adaptive element positioning.

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	录制一次完整的浏览器操作轨迹

Tool / action	Typical Use Case
browser_init	Initialize browser session (optional headless/stealth mode)
browser_open	Open login page or any target page
browser_click	Click buttons, links, tabs, etc.
browser_input	Enter username, password, search keywords, etc. into input boxes
browser_get_text/get_html	Read text or entire HTML segments for subsequent parsing
browser_wait_for	Wait for specific text to appear/disappear to avoid premature operations before page loading completes
browser_screenshot	Take screenshots for archiving or debugging
browser_extract_data	Extract data from lists / tables
trajectory_start/complete	Record a complete browser operation trajectory

典型流程

Typical Workflows

录制：

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
```
决定是否重试

Recording:

trajectory_start(task_id, goal)

→

browser_init

→

browser_open

browser_click

browser_input

, etc. →

trajectory_complete(export_for_ai: true)

Reuse:
```
trajectory_list
```
to find the task_id →
```
trajectory_load(task_id, format)
```
to retrieve the trajectory

Management:

trajectory_delete(task_id)

to delete; pass

include_screenshot: false

to browser tools

Error Handling: Return
```
success: false
```
,
```
code
```
,
```
retryable
```
on failure; decide whether to retry based on
```
retryable
```

何时才生成脚本

When to Generate Scripts

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

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

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

Only generate reusable scripts from trajectories in the following cases (to avoid unnecessary Token consumption):

Recurring Tasks: The user explicitly states the task will be executed multiple times (e.g., "run daily from now on", "scheduled execution", "recurring task"), or the context/cron indicates it is a scheduled/periodic task.
Explicit User Request: The user says "generate a reusable script", "save as a script for next time", "export as a script", etc.

Do not generate scripts proactively: If no reuse or scheduled/recurring requirement is mentioned, only perform trajectory recording and saving. Generate scripts later if the user requests it.

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

How to Locate Corresponding Scripts for Scheduled Tasks (Based on job_id Binding)

当 OpenClaw 以定时任务触发本 Skill 时，事件参数中会携带该任务的

job_id

。ZeroToken 使用

job_id

作为绑定键（

binding_key

），并在 MCP 数据库的

script_bindings

表中维护「job_id ↔ 脚本」关系。

Agent 必须遵守以下约定：

优先使用
run_script_by_job_id(binding_key=job_id, vars?)
一步执行：MCP 内部查绑定、合并 default_vars、执行脚本。

若需分步控制，可调用

script_binding_get(binding_key=job_id)

，再

run_script(task_id, vars=merged_vars)

。

若
```
run_script_by_job_id
```
或
```
script_binding_get(job_id)
```
返回「未找到」：
- 提示用户「当前 job_id 尚未绑定 ZeroToken 脚本」；
- 不要随意尝试其他脚本或自动新建脚本。
对于没有
```
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

查询绑定，不对映射关系做额外推断。

When OpenClaw triggers this Skill via a scheduled task, the event parameters will carry the task's

job_id

. ZeroToken uses

job_id

as the binding key (

binding_key

) and maintains the "job_id ↔ script" relationship in the

script_bindings

table of the MCP database.

Agents must follow these conventions:

Prioritize using
run_script_by_job_id(binding_key=job_id, vars?)
for one-step execution: The MCP internally queries the binding, merges default_vars, and executes the script.

If step-by-step control is needed, call

script_binding_get(binding_key=job_id)

, then

run_script(task_id, vars=merged_vars)

If
```
run_script_by_job_id
```
or
```
script_binding_get(job_id)
```
returns "not found":
- Prompt the user: "The current job_id is not yet bound to a ZeroToken script";
- Do not randomly attempt other scripts or automatically create new scripts.
For scenarios without a
```
job_id
```
or not marked as a scheduled task:
- Treat it as a one-time task, only use
```
browser_*
```
  +
```
trajectory_*
```
  to complete the current request, and do not proactively search for/execute scripts.

Developers should use

script_binding_set(binding_key=job_id, script_task_id=..., default_vars?, description?)

in ZeroToken or the OpenClaw integration layer to explicitly bind scheduled task job_ids to script

task_id

s in advance. This Skill only queries bindings via

job_id

and does not make additional inferences about the mapping relationship.

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

Configuring Scheduled Tasks (Complete Workflow)

当 Agent 收到带

job_id

的定时任务配置请求（如用户说「设为每日执行」「把这个任务设为定时」），且 OpenClaw 已传入

job_id

时，必须完成以下端到端流程：

确定 task_id：用户指定、或最近录制的 trajectory 的 task_id（如
```
trajectory_list
```
取最新）。
检查轨迹：
```
trajectory_load(task_id)
```
检查轨迹是否存在；若无则提示用户先录制。
生成脚本：
```
script_load(task_id)
```
检查脚本是否存在；若无则调用
```
trajectory_to_script(task_id, stealth?)
```
根据轨迹生成并保存。

绑定：

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)

再绑定。

When the Agent receives a scheduled task configuration request with a

job_id

(e.g., the user says "set to run daily", "schedule this task"), and OpenClaw has passed in the

job_id

, it must complete the following end-to-end workflow:

Determine task_id: Specified by the user, or the task_id of the most recently recorded trajectory (e.g., retrieve the latest via
```
trajectory_list
```
).
Check Trajectory:
```
trajectory_load(task_id)
```
to check if the trajectory exists; if not, prompt the user to record it first.
Generate Script:
```
script_load(task_id)
```
to check if the script exists; if not, call
```
trajectory_to_script(task_id, stealth?)
```
to generate and save the script from the trajectory.

Bind:

script_binding_set(binding_key=job_id, script_task_id=task_id, default_vars?, description?)

to bind the job_id to the script.

Important: The

task_id

must be consistent across trajectory → script → binding. The

task_id

used during recording is the script's

task_id

and also the

script_task_id

in the binding.

script_binding_set

returns

SCRIPT_NOT_FOUND

, it means the script does not exist; call

trajectory_to_script(task_id)

first before binding.

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

Anti-Scraping Countermeasures (Sites Prone to Cloud Shield/Anti-Scraping Interception)

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

录制时：
```
browser_init
```
传
```
stealth: true
```
，降低被识别概率。

生成脚本时：

trajectory_to_script(task_id, stealth=true)

使生成的脚本中

browser_init

包含

stealth: true

。

执行时：
```
run_script
```
会按脚本中的
```
browser_init
```
参数执行，若脚本含
```
stealth: true
```
则自动启用反检测。

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

If the target site (e.g., Bilibili, Xiaohongshu, etc.) is prone to being detected as automation and blocked:

During Recording: Pass
```
stealth: true
```
to
```
browser_init
```
to reduce detection probability.
When Generating Scripts: Call
```
trajectory_to_script(task_id, stealth=true)
```
to include
```
stealth: true
```
in the
```
browser_init
```
of the generated script.
During Execution:
```
run_script
```
will execute according to the
```
browser_init
```
parameters in the script; if the script includes
```
stealth: true
```
, anti-detection mode will be automatically enabled.

Stealth mode enables: startup parameter camouflage, navigator fingerprint camouflage, Sec-CH-UA headers, WebGL fingerprint camouflage, etc.

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

Recovery from Scheduled Task Execution Failures

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

SCRIPT_BINDING_NOT_FOUND: Prompt the user "The current job_id is not yet bound to a ZeroToken script" and guide them to complete the configuration workflow.
SCRIPT_NOT_FOUND (binding exists but script is deleted): If a
```
hint
```
field is returned, follow the prompt to execute
```
trajectory_to_script(script_task_id)
```
to regenerate the script (if the trajectory still exists), then retry
```
run_script_by_job_id
```
.

脚本格式与执行方式

Script Format and Execution Method

格式（存于 MCP 数据库）

Format (Stored in MCP Database)

脚本通过

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
```
），否则占位符会保留字面量，可能导致无效输入。

Scripts are read/written via

script_save

script_load

, with a sample structure:

json

{
  "task_id": "login_daily",
  "goal": "Daily login and report retrieval",
  "steps": [
    { "action": "browser_init", "params": { "headless": true, "stealth": true } },
    { "action": "trajectory_start", "params": { "task_id": "login_daily", "goal": "Daily login and report retrieval" } },
    { "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": "Captcha recognition required", "hint": "Call browser_extract_data or wait for manual input" } },
    { "action": "browser_get_text", "params": { "selector": ".report" } }
  ]
}

```
steps
```
: An ordered array; each step's
```
action
```
corresponds to an MCP tool name, and
```
params
```
are the input parameters for that tool.
Optional
```
fuzzy_point
```
: Records semantic information about "needing AI/human intervention" for this step (
```
reason
```
,
```
hint
```
), which does not automatically pause the ScriptEngine; only when a matching DFU / execution point is configured for this step will
```
run_script
```
return
```
status="paused"
```
when executing this step.
Optional Parameterization: Use
```
{{varname}}
```
in
```
params
```
, which can be replaced by the Agent or configuration before execution (e.g., environment variables, user input), or merged into the runtime variable environment via
```
resolution.vars
```
generated by the upper layer when paused at an ExecutionPoint/DFU. Scripts containing
{{varname}}
must provide corresponding vars before execution (via
```
vars
```
in
```
run_script
```
or
```
vars
```
/binding's
```
default_vars
```
in
```
run_script_by_job_id
```
), otherwise the placeholder will remain as a literal value, potentially causing invalid input.

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

Executing Scripts (Only in Scheduled / Recurring Task Scenarios)

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

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

在这些情况下：

调用
```
script_load(task_id)
```
从 MCP 数据库读取脚本；若无则调用
```
trajectory_to_script(task_id)
```
根据轨迹生成并保存（否则不要擅自造脚本）。
调用
```
run_script(task_id, vars?)
```
由 MCP 内的 ScriptEngine 自动按
steps
顺序执行脚本，无需 LLM，执行过程写入 session；返回形如
```
{"success": ..., "status": "success|paused|failed", "session_id": ...}
```
。
若返回
```
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 追踪每次执行。

Only locate and execute scripts in the following two cases:

The context/cron clearly indicates a "scheduled / periodic / recurring" task (e.g., daily comments, hourly report scraping).
The user explicitly says "execute the ZeroToken script <task_id>", "run the script for <task_id>", etc.

In these cases:

Call
```
script_load(task_id)
```
to read the script from the MCP database; if it does not exist, call
```
trajectory_to_script(task_id)
```
to generate and save it from the trajectory (do not create scripts without authorization otherwise).
Call
```
run_script(task_id, vars?)
```
to let the ScriptEngine inside MCP automatically execute the script in the order of
steps
without LLM; the execution process is written to the session; returns a result like
```
{"success": ..., "status": "success|paused|failed", "session_id": ...}
```
.
If
```
status="paused"
```
is returned (e.g., hitting a DFU / execution point / failure retry limit):
- The upper Agent reads the
```
pause_event
```
  (including step_index, dfu_id, prompt text, and required vars to generate), makes a decision or generates vars;
- Then call
```
run_script(session_id=..., resolution={...})
```
  to resume execution, and the ScriptEngine will continue executing subsequent steps in order.

For non-scheduled/one-time tasks: Prioritize using only
browser_*
+
trajectory_*
to record and complete the current task, and do not proactively search for/execute scripts.

Scripts are "data-driven MCP call sequences", stored in the MCP database and automatically replayed by the ScriptEngine, with low Token consumption and session-based execution tracking.

模糊点 / DFU 执行约定

Fuzzy Point / DFU Execution Conventions

*有 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 结果+日志事后审计。

When an Agent is present (manual
browser_*
calls): When encountering an OperationRecord / step with
```
fuzzy_point
```
, treat
```
reason
```
and
```
hint
```
as prompts, and decide whether to additionally call
```
browser_extract_data
```
,
```
browser_input
```
, etc., based on the current page before proceeding.
When using
run_script
(ScriptEngine automatic replay): Whether to pause is determined by DFU/execution point rules (
```
dfu_*
```
configuration + trigger matching), not solely by
```
fuzzy_point
```
. If a step has both
```
fuzzy_point
```
and hits a DFU, the ScriptEngine will return
```
status="paused"
```
+
```
pause_event
```
when executing this step, and the upper Agent decides the
```
resolution
```
before resuming.
Unattended Scenarios: Avoid relying on scripts with numerous steps requiring strong manual judgment; scripts with fuzzy points but no configured DFU will run directly in pure
```
run_script
```
mode, and may require post-execution auditing via session results + logs.

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

Generating Scripts from Trajectories (Workflow)

轨迹 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

Trajectory action	Script/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

保存位置与复用查找

Storage Location and Reuse Lookup

脚本与轨迹：均由 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)
```
查看。

Scripts and Trajectories: Both are stored in the database (SQLite) by the MCP backend, with no dependency on local file paths.
Lookup: When executing/reusing a task, use
```
trajectory_list
```
or
```
script_list
```
to get the task_id, then
```
script_load(task_id)
```
to retrieve the script; if it does not exist, prompt "No script exists for this task, would you like to generate it from the trajectory?" and directly call
```
trajectory_to_script(task_id)
```
to generate and save it.
Sessions: Each
```
run_script
```
or recording generates a session; use
```
session_list
```
and
```
session_get(session_id)
```
to view details.

安装

Installation

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

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

从本仓库安装示例：克隆后复制

skills/zerotoken-openclaw/

到上述路径之一。

Place this Skill in one of OpenClaw's skills directories:

Workspace:
```
./skills/zerotoken-openclaw/
```
(current project only)
Local Shared:
```
~/.openclaw/skills/zerotoken-openclaw/
```
Or via ClawHub:
```
clawhub install zerotoken-openclaw
```
(if published)

Example installation from this repository: Clone the repo and copy

skills/zerotoken-openclaw/

to one of the above paths.

常见坑

Common Pitfalls

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

OpenClaw: Not running
```
zerotoken-mcp-http
```
in the background or still using command instead of url in
```
openclaw.json
```
, causing new processes to be created on each call and browser state loss.
Forgetting to call
```
browser_init
```
before using
```
browser_open
```
/
```
browser_click
```
, leading to first-call failures or exceptions.
Not using
```
export_for_ai: true
```
when recording trajectories, requiring additional processing of trajectory data when generating scripts later.
Inconsistent
```
task_id
```
between trajectory and script, causing
```
script_load(task_id)
```
to fail to find the corresponding script.
Still relying on scripts with numerous
```
fuzzy_point
```
steps in unattended scenarios, which are prone to getting stuck at fuzzy points; such tasks should be evaluated in advance to determine if manual fallback is needed.