ZeroToken Browser Automation (OpenClaw)

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

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

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.

Preparations for OpenClaw (HTTP Mode)

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

Handling Unconfigured/Uninstalled ZeroToken MCP

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 Tools and Workflows

Tool List (Aligned with MCP)

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

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

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

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.

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

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)

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)

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: 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

Format (Stored in MCP Database)

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)

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.

Fuzzy Point / DFU Execution Conventions

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)

Recommended: Directly call

trajectory_to_script(task_id, script_task_id?, prepend_init?, stealth?)

; the MCP will load the trajectory from the database, convert it to a script, save it, and return the

task_id

. If the target site is prone to anti-scraping interception, pass

stealth=true

to include

stealth: true

in the

browser_init

of the generated script.

If manual control is required, refer to the following workflow:

Input:

trajectory_load(task_id, format="json")

format="ai_prompt"

; optionally use

trajectory_list

first to select the task_id.

Action Mapping: The

operations[].action

in the trajectory is an internal name; it must be mapped to the MCP tool name when generating the script; call the MCP tool name during execution.

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

The trajectory does not include

browser_init

trajectory_start

; add these two steps at the beginning of

steps

when generating the script (if recording and replay are needed).

Output: Call
```
script_save(task_id, goal, steps)
```
to write to the MCP database; use the mapped MCP names for
```
action
```
in
```
steps
```
, keep
```
params
```
consistent with the trajectory, and carry over
```
selector_candidates
```
and
```
fuzzy_point
```
from the trajectory.

Storage Location and Reuse Lookup

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

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: 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.

zerotoken-openclaw

NPX Install

Tags

SKILL.md Content (Chinese)