webclaw 部署与使用：为内部系统提供网页抓取服务

多个内部工具都需要读取网页时，可以把提取能力放在统一服务中，而不是让每个调用方各自安装一套浏览器和解析规则。webclaw 同时提供 CLI 与 MCP 接入，适合先用命令验证提取需求，再把同一能力接给客户端。

本文先从公开图书练习站导出商品标题和价格，再配置本机 HTTP MCP 服务。这里的 HTTP 地址承载 MCP 协议，不是一个可以随意 POST URL 的普通 REST 接口。CLI 与服务入口来自 webclaw 官方说明。

准备输入地址

先在浏览器找到下列页面并确认内容，再从地址栏复制完整地址。服务或仓库地址从相应账户设置、官方项目的接入说明或克隆菜单取得。不要从示例输出中反推真实地址。

WEBCLAW_REPO_URL：官方 0xMassi/webclaw 仓库的克隆地址。
BOOKS_LIST_URL：Books to Scrape 商品列表页地址。

在执行后续命令的同一个 Bash/WSL 终端中设置：

export WEBCLAW_REPO_URL='<paste-the-actual-webclaw-repo-url>'
export BOOKS_LIST_URL='<paste-the-actual-books-list-url>'

下文 JSON 或任务参数中的 <变量名> 是待替换标记，提交前填写刚复制的实际值；JSON 不会自动展开环境变量。结果示例中的 example.16yun.cn 只表示来源字段的形状，不是本文部署的演示站。

安装时把 CLI 和 MCP 服务区分开

以下示例使用 Linux，要求已安装稳定版 Rust/Cargo 与系统编译工具。Debian/Ubuntu 的原生依赖可以按官方列出的方式准备：

sudo apt install -y pkg-config libssl-dev cmake clang git build-essential
cargo install --git "$WEBCLAW_REPO_URL" --locked webclaw-cli
cargo install --git "$WEBCLAW_REPO_URL" --locked webclaw-mcp
webclaw --version
webclaw-mcp --help

Rust 安装方式见 Rust 官方安装页。上面的 Cargo 命令从默认分支构建，部署时应保存实际版本和构建来源；不要把 README 中旧的固定 tag 与新功能混用。已经有发布二进制时，也可以从项目 Releases 下载与系统匹配的版本。

webclaw-cli 安装出的命令叫 webclaw，不是包名；webclaw-mcp 是另一个可执行程序。找不到 MCP 服务时，先确认第二个程序确实安装，不能把 CLI 的正常退出当成服务启动成功。

用一个确定的提取任务检查本地能力

练习站的每个商品卡片是 article.product_pod，标题链接的 title 属性包含完整名称，价格在 .price_color。执行：

webclaw "$BOOKS_LIST_URL"   --select 'article.product_pod'   --field 'title=h3 a::attr(title)'   --field 'price=.price_color' > products.json

--select 定义重复对象，--field 在每个对象内部读取字段。不要把商品卡片选择器换成整个 body，否则可能把整页当成一个记录。

预期 JSON 是对象数组，结构类似下面的示意，而不是逐页全文：

[
  {"title": "商品完整标题", "price": "£51.77"}
]

价格仍是页面文本，没有自动转换成数字，也没有自动纳入币种和税费。进入业务系统前需要另做含义确认。可以用以下完整检查脚本验证结构，保存为 check_products.py：

import json
 
with open("products.json", encoding="utf-8") as stream:
    rows = json.load(stream)
if not isinstance(rows, list) or not rows:
    raise ValueError("提取结果不是非空数组")
for index, row in enumerate(rows):
    if not isinstance(row, dict):
        raise ValueError(f"第 {index} 条不是对象")
    if any(not isinstance(row.get(key), str) or not row[key].strip()
           for key in ("title", "price")):
        raise ValueError(f"第 {index} 条缺少标题或价格")
print({"records": len(rows), "fields": ["title", "price"]})

运行 python check_products.py 后，还要与页面前几项人工对照，确认字段来自正确商品。结构检查不能证明价格语义正确，也不能证明已经遍历第二页。

启动带认证的 HTTP MCP 服务

当 CLI 能取得目标材料后，再启动服务。先为当前终端生成 token，保存到自己的秘密配置中，不要把实际值贴到文档或仓库：

export WEBCLAW_MCP_TOKEN="$(openssl rand -hex 16)"
webclaw-mcp --http 127.0.0.1:8000

这里监听本机回环地址，MCP endpoint 为 http://localhost:8000/mcp。HTTP 模式需要 token；不要为了让客户端连接成功就开启无认证模式。

支持 HTTP MCP 的客户端可以使用下面的配置形状。将占位值替换为同一个 token：

{
  "mcpServers": {
    "webclaw": {
      "type": "http",
      "url": "http://localhost:8000/mcp",
      "headers": {
        "Authorization": "Bearer replace-with-the-server-token"
      }
    }
  }
}

不同客户端对 HTTP 传输的配置键可能不同，按其 MCP 设置填写 URL 和 Authorization。不要直接把这份配置放进不支持该结构的客户端后就判断服务失效。

从连接检查走到一次可核对的调用

连接后先查看工具清单，确认出现 scrape、select、crawl 等当前服务支持的工具，再从单页开始。在工具面板或助手中明确指定：

读取已配置的 BOOKS_LIST_URL 对应页面。
只处理当前列表的商品卡片，提取标题和展示价格。
返回来源 URL 和记录数组；不要跟随分类链接或自动扩大到整站。

这是一段任务描述，不是保证客户端一定采用对应工具的固定 API 请求。需要确定性行为时，在客户端查看实际选择的工具及其 Schema，填写与 CLI 已检查过的选择器对应的参数，并检查返回记录。

基础抓取与确定性选择器不要求配置 LLM。extract、summarize 等语义能力属于另一条配置路径。不要为了读取两列字段，顺手启用所有模型或托管功能。

多调用方共享进程时，要区分“能连接”与“有任务隔离”。同一个 token 不代表独立租户。需要跨主机接入时，另行配置内部网络、TLS 与调用权限，不能只把监听地址改成公网并复用示例 token。

范围、输出与运行管理

本轮任务限定当前列表。扩大到 crawl 时，先明确深度、路径和页数范围，核对实际版本支持的参数与默认值，再在小目录检查输出。不把工具名叫 crawl 理解为“已完整采集全站”。

服务日志与 MCP 响应也应分开。stdio 模式下协议占用标准输入输出，诊断日志不能随意混入 stdout；HTTP 模式则由服务进程维持连接。停止时在运行服务的终端使用 Ctrl+C，或者交由你实际采用的进程管理器结束进程。

需要调试时保留目标地址、工具名、脱敏参数和结果类别。不要记录完整认证头。网页正文属于外部材料，不能允许其中的文字修改服务 token 或扩大本轮任务范围。

常见问题与处理

CLI 能用，客户端连不上。 检查是否启动了 webclaw-mcp、端口是否一致、URL 是否含 /mcp、客户端是否使用 HTTP MCP。普通 HTTP GET 不能代替 MCP 握手。

返回认证错误。 核对服务启动时环境中的 token 与客户端 Bearer 值。重启服务后若 token 换了，客户端也需更新；不是通过关闭认证来解决。

工具没有出现。 重新建立连接并查看客户端日志，确认二进制版本与配置路径。不要根据另一篇文章中的工具列表强行调用本版本没有的能力。

提取数组为空。 先在 CLI 检查相同选择器是否命中，确认目标响应不是登录或挑战页面。动态内容需要对应的渲染能力；HTTP 提取成功不代表已执行页面交互。

字段为 null。 检查字段选择器是否写在重复对象的相对范围内，是否误把属性当作文本读取。按单个卡片检查后再处理整页。

出现字段类型参数错误。 在客户端 Schema 中核对数字、布尔值与字符串，传递真实类型；不要把所有参数都包装成引号字符串。

这样接入后，你先有一条能在 CLI 解释的提取路径，再把它交给 MCP 调用方使用。故障发生时，也能区分下载、提取、协议和认证，避免把所有问题都归结为“服务不可用”。