clawdbot正确使用需严格遵循五步顺序：一、安装指定版本并校验环境与配置；二、定义符合uri规范及参数绑定的任务；三、用xpath或css显式声明提取字段及类型；四、通过调试模式验证匹配结果；五、导出为jsonl或tsv格式。
如果您刚接触Clawdbot，但不确定如何启动基础任务、配置目标或解析返回数据，则可能是由于未按核心模块逻辑顺序执行操作。以下是Clawdbot核心功能的正确使用步骤：
一、安装与环境初始化
Clawdbot依赖Python 3.9+及特定底层库，需先完成运行时环境校验与基础组件注入，避免后续任务因环境缺失而静默失败。
1、执行pip install clawdbot==2026.1.0命令安装指定版本包。
2、运行clawdbot --check-env验证系统是否具备libcurl、openssl 3.0.12及以上版本支持。
3、创建~/.clawdbot/config.yaml，写入default_timeout: 8与max_concurrent: 4两项必需参数。
二、定义合法抓取任务结构
Clawdbot拒绝执行无schema约束的任务声明，所有target必须符合URI规范且携带显式协议标识与路径占位符，否则触发schema validation error。
1、新建task.yaml文件，键名必须为targets，值为列表。
2、每个列表项包含url（格式为https://example.com/{id}/detail）、method（仅允许GET或HEAD）和params（键值对，值不可含空格）。
3、在url中出现的{id}必须在params中存在同名键，例如params: {id: "1024"}。
三、启用数据提取规则引擎
Clawdbot不自动推断字段位置，所有输出字段必须通过XPath 2.0语法或CSS选择器显式绑定，且每个field需声明type为text、attr或html之一。
1、在task.yaml中添加extract:区块，下设fields:子项。
2、每个字段条目格式为title: {selector: "//h1[@class='post-title']", type: text}，其中selector值不得为空字符串。
3、若需提取属性值，type设为attr，且selector末尾须带/@src或/@data-id等合法属性引用路径。
四、执行单次调试模式运行
调试模式强制启用响应体完整缓存与字段匹配日志输出，禁用并发与重试，用于验证提取逻辑是否与实际HTML结构对齐。
1、执行clawdbot run task.yaml --debug --limit 1启动单目标调试。
2、观察终端输出中的[MATCH]行，确认每项field后跟随✓ 3 nodes或✗ 0 nodes标记。
3、若出现✗，立即检查页面源码中对应元素是否存在、class名是否动态生成、是否被noscript包裹。
五、导出结构化结果至标准格式
Clawdbot仅支持JSON Lines（.jsonl）与TSV两种导出格式，不支持CSV或Excel直出；输出文件名由--output参数决定，扩展名必须与格式严格匹配。
1、添加--output results.jsonl参数，确保文件后缀为.jsonl。
2、若需制表符分隔，使用--output data.tsv，此时每行字段按extract.fields中定义顺序排列，空值输出为\N。
3、执行前确认目标目录具有写权限，禁止将输出路径设为根目录或系统关键路径。
