zerotoken-openclaw

Name: zerotoken-openclaw
Author: amos144

github.com/amos144エージェントワークフロー45237 回インストール25 週間前に更新

リポジトリ

zerotoken-openclaw について

OpenClaw エージェント向けに、ZeroToken でブラウザー操作を記録し、再利用可能なスクリプトに変換して定期タスクで再生する方法を案内します。

主な機能

01ブラウザー操作の軌跡を記録・管理
02必要に応じて軌跡をスクリプト化
03ScriptEngine による LLM 不使用の再生
04job_id による定期スクリプトの紐付けと実行
05デバッグや監査のためのセッション確認

活用シーン

01繰り返すブラウザー操作をスクリプト化
02OpenClaw の定期タスクにスクリプトを紐付け
03実行セッションから問題を調査

MCP 対応

ZeroToken MCP のブラウザー、軌跡、スクリプト、セッションの各ツールを使う手順を示します。ブラウザー状態を維持するため、OpenClaw は Streamable HTTP で常駐サービスに接続します。

インストール

コマンドをコピーしてターミナルで実行します。

$npx skills add https://github.com/amos144/zerotoken --skill zerotoken-openclaw

インストール後、Claude Code で/zerotoken-openclawを入力して読み込まれたか確認します。

詳細

ZeroToken ブラウザー自動化（OpenClaw）

Agent に ZeroToken MCP を使ったブラウザー自動化、軌跡の記録、スクリプトの再生を教えます。OpenClaw で定期的なタスクや繰り返しタスクを実行する際の Token 消費をできるだけ抑えることを目的としています。

ZeroToken プロジェクトのホームページ：https://github.com/AMOS144/zerotoken

使用する場合／使用すべきでない場合

使用に適しています：
- OpenClaw + ZeroToken MCP を使ったブラウザー自動化が必要で、今後 繰り返し実行／定期実行 するタスク。
- ブラウザー操作の一連の軌跡がすでにあり、それを Token 消費の少ないスクリプトに変換 して再利用したい場合。
使用に適していません：
- 一度だけの一時的な操作で、再利用の必要がない場合（ZeroToken MCP をそのまま使用してください）。
- ページ上で人による判断が頻繁に必要で、多くの手順で fuzzy_point による介入が必要となり、無人でのフォールバックが難しいタスク。

前提条件

現在の環境から、zerotoken という名前のサーバー（または同等の MCP server id）に MCP 経由でアクセスできること。
ブラウザー操作の実行前に browser_init を呼び出してください。完了後、必要に応じて browser_close を呼び出せます。

OpenClaw の使用前の準備（HTTP モード）

OpenClaw / MCPorter 経由で ZeroToken を使用する場合、呼び出しのたびに新しいプロセスが起動するため、ブラウザーの状態が失われます。サービスを常駐させるために、Streamable HTTP トランスポートモードに切り替える必要があります。

HTTP サービスを手動で起動する（バックグラウンドで常駐させます）：
- zerotoken-mcp-http、または
- zerotoken-mcp --transport streamable-http
- デフォルトのポートは 8000 です。--port または環境変数 ZEROTOKEN_HTTP_PORT で上書きできます。
OpenClaw の設定：openclaw.json の mcpServers.zerotoken で、command ではなく URL を使用します：
```
{
  "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 は次の順序で対応してください：

ユーザーに 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 関連の手順を再開します。

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)：記録／再生セッションの詳細を照会します。デバッグ、監査、定期タスクの振り返りに使用します。

スクリプト、軌跡、セッションはすべて 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）：

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

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

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

当 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 查询绑定，不对映射关系做额外推断。

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

当 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) 再绑定。

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

若目标站点（如 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 指纹伪装等。

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

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> 的脚本」等。

在这些情况下：

调用 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 追踪每次执行。

模糊点 / 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。

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

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

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 开头补上这两步（若需录制回放）。

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

Markdown 対応

ログインしてコメント

基本情報

作者: amos144
リポジトリ: amos144/zerotoken
カテゴリ: エージェントワークフロー
インストール数: 37
GitHub スター: 452

問題を報告