zerotoken-openclaw

# 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**：`mcport...