# https://github.com/0xMassi/webclaw 项目说明书

生成时间：2026-06-28 18:08:46 UTC

## 目录

- [项目概述与安装指南](#page-1)
- [Rust 工作空间与 Crate 架构](#page-2)
- [CLI、MCP 工具与已知故障模式](#page-3)
- [自托管服务器与部署](#page-4)

<a id='page-1'></a>

## 项目概述与安装指南

### 相关页面

相关主题：[Rust 工作空间与 Crate 架构](#page-2), [CLI、MCP 工具与已知故障模式](#page-3)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [README.md](https://github.com/0xMassi/webclaw/blob/main/README.md)
- [examples/README.md](https://github.com/0xMassi/webclaw/blob/main/examples/README.md)
- [examples/html-to-markdown-rag/README.md](https://github.com/0xMassi/webclaw/blob/main/examples/html-to-markdown-rag/README.md)
- [crates/webclaw-cli/src/main.rs](https://github.com/0xMassi/webclaw/blob/main/crates/webclaw-cli/src/main.rs)
- [crates/webclaw-cli/src/bench.rs](https://github.com/0xMassi/webclaw/blob/main/crates/webclaw-cli/src/bench.rs)
- [crates/webclaw-mcp/src/server.rs](https://github.com/0xMassi/webclaw/blob/main/crates/webclaw-mcp/src/server.rs)
- [crates/webclaw-mcp/src/tools.rs](https://github.com/0xMassi/webclaw/blob/main/crates/webclaw-mcp/src/tools.rs)
- [crates/webclaw-llm/src/lib.rs](https://github.com/0xMassi/webclaw/blob/main/crates/webclaw-llm/src/lib.rs)
- [crates/webclaw-server/src/routes/crawl.rs](https://github.com/0xMassi/webclaw/blob/main/crates/webclaw-server/src/routes/crawl.rs)
- [crates/webclaw-server/src/routes/extract.rs](https://github.com/0xMassi/webclaw/blob/main/crates/webclaw-server/src/routes/extract.rs)
</details>

# 项目概述与安装指南

## 1. 项目定位与核心价值

`webclaw` 是一个面向 AI Agent 与 RAG 流水线的网页内容提取与转换工具，提供 CLI、MCP 服务器、REST API 及多种语言 SDK 四种接入形态。其核心目标是「把网站变成干净的 Markdown、JSON 与可直接送入 LLM 的上下文」，覆盖从单页抓取、批量提取、整站爬取、品牌资产抽取、结构化字段提取到内容摘要、版本对比等场景 [README.md:1-30](https://github.com/0xMassi/webclaw/blob/main/README.md)。

根据 README 的功能矩阵，`webclaw` 的能力可分为三类：

| 能力类别 | 代表功能 | 是否需要 API Key |
| --- | --- | --- |
| 本地可执行 | `scrape`、`crawl`、`map`、`extract`、`summarize`、`diff`、`brand` | 否（使用本地浏览器指纹） |
| 第三方托管 | `search`（Serper.dev）、`research` | 需要对应第三方 Key |
| 反爬兜底 | `vertical`（amazon、ebay、trustpilot 等） | 命中反爬时自动升级至 webclaw 云端 API |

资料来源：[README.md:1-60](https://github.com/0xMassi/webclaw/blob/main/README.md)

## 2. 系统架构

`webclaw` 采用 Rust 工作区多 crate 结构，按职责拆分如下：

```mermaid
graph LR
    A[webclaw-cli] --> B[webclaw-core]
    A --> C[webclaw-fetch]
    A --> D[webclaw-llm]
    E[webclaw-server] --> B
    E --> C
    E --> D
    F[webclaw-mcp] --> B
    F --> C
    F --> D
    D --> G[Ollama]
    D --> H[OpenAI]
    D --> I[Gemini]
    D --> J[Anthropic]
    C --> K[wreq Chrome/Firefox]
```

各模块职责说明：

- `webclaw-core`：内容清洗、Markdown 转换、LLM 输出格式（`to_llm_text`）等核心管线 [crates/webclaw-cli/src/bench.rs:1-40](https://github.com/0xMassi/webclaw/blob/main/crates/webclaw-cli/src/bench.rs)。
- `webclaw-fetch`：基于 `wreq` 的浏览器指纹客户端，默认 Chrome，针对 Reddit 等站点自动切换为 Firefox 指纹 [crates/webclaw-mcp/src/server.rs:1-30](https://github.com/0xMassi/webclaw/blob/main/crates/webclaw-mcp/src/server.rs)。
- `webclaw-llm`：本地优先的混合 LLM 链路，按 Ollama → OpenAI → Gemini → Anthropic 顺序回退 [crates/webclaw-llm/src/lib.rs:1-10](https://github.com/0xMassi/webclaw/blob/main/crates/webclaw-llm/src/lib.rs)。
- `webclaw-server`：Axum 框架实现的 REST API，对应 `/v1/scrape`、`/v1/crawl`、`/v1/extract`、`/v1/diff` 等路由 [crates/webclaw-server/src/routes/crawl.rs:1-20](https://github.com/0xMassi/webclaw/blob/main/crates/webclaw-server/src/routes/crawl.rs)、[crates/webclaw-server/src/routes/extract.rs:1-20](https://github.com/0xMassi/webclaw/blob/main/crates/webclaw-server/src/routes/extract.rs)。
- `webclaw-mcp`：通过 `rmcp` 暴露给 AI Agent 的 MCP 工具集，使用 `#[tool]` 宏注册 `scrape`、`crawl`、`batch`、`extract` 等工具 [crates/webclaw-mcp/src/tools.rs:1-30](https://github.com/0xMassi/webclaw/blob/main/crates/webclaw-mcp/src/tools.rs)。

## 3. 安装与部署方式

### 3.1 预编译二进制

从 GitHub Releases 下载对应平台的 `webclaw`、`webclaw-mcp`、`webclaw-server` 三个二进制包，解压后即可在终端直接调用。

⚠️ **重要提示**：根据 Issue #73，预编译的 Linux 二进制要求 **glibc 2.38+**，因此在 Debian 12、Ubuntu 22.04 LTS、Amazon Linux 2023、RHEL/Rocky 9 等常见服务器发行版上会启动失败。遇到此问题时，应改用源码编译（见 3.3）或升级基础镜像到 glibc 2.38 以上的发行版（如 Ubuntu 24.04、Debian 13）。

### 3.2 通过 npm 创建 MCP 集成

```bash
npx create-webclaw
```

该命令会生成 `.env` 配置文件并写入 `WEBCLAW_API_KEY`，便于 Claude Code、Claude Desktop、Cursor、Codex CLI 等 MCP 客户端直接接入 [README.md:40-60](https://github.com/0xMassi/webclaw/blob/main/README.md)。

### 3.3 源码编译

克隆仓库后使用 Cargo 工作区构建：

```bash
cargo build --release --workspace
```

各子 crate 可单独构建，例如仅编译 MCP 服务器：

```bash
cargo build --release -p webclaw-mcp
```

### 3.4 SDK 安装

```bash
npm install @webclaw/sdk
pip install webclaw
go get github.com/0xMassi/webclaw-go
```

资料来源：[README.md:50-90](https://github.com/0xMassi/webclaw/blob/main/README.md)

## 4. 快速上手示例

### 4.1 CLI 单页提取

```bash
# 默认 markdown 输出
webclaw https://stripe.com

# 面向 LLM 的紧凑格式（节省约 67% token）
webclaw https://docs.anthropic.com --format llm

# 仅保留正文，跳过导航/侧边栏
webclaw https://example.com/blog/post --only-main-content
```

### 4.2 批量与整站爬取

通过 `urls.txt` 批量处理：

```bash
webclaw --urls-file urls.txt --format llm > corpus.txt
```

⚠️ **已知缺陷**：根据 Issue #3，`--only-main-content` 选项在批处理模式下不会生效，即命令 `webclaw --only-main-content --urls-file URLs.txt` 仍会保留导航与页脚等噪声元素，建议在批处理场景下改用 `--include "article,main,.content"` 或 `--exclude "nav,footer,.sidebar"` 进行显式过滤。

整站爬取示例：

```bash
webclaw https://docs.rust-lang.org --crawl --depth 2 --max-pages 50
```

### 4.3 MCP 服务器调用

```bash
npx create-webclaw
```

启动后 AI Agent 可通过工具调用方式执行 `vertical_scrape`、`summarize` 等操作 [crates/webclaw-mcp/src/server.rs:1-30](https://github.com/0xMassi/webclaw/blob/main/crates/webclaw-mcp/src/server.rs)。

### 4.4 托管 API

```bash
curl https://api.webclaw.io/v1/scrape \
  -H "Authorization: Bearer $WEBCLAW_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"url":"https://docs.anthropic.com","formats":["markdown","llm"],"only_main_content":true}'
```

资料来源：[examples/README.md:1-40](https://github.com/0xMassi/webclaw/blob/main/examples/README.md)、[examples/html-to-markdown-rag/README.md:1-30](https://github.com/0xMassi/webclaw/blob/main/examples/html-to-markdown-rag/README.md)

## 5. 常见问题与故障排查

| 故障现象 | 可能原因 | 解决方法 |
| --- | --- | --- |
| Linux 二进制启动报 `glibc not found` | 系统 glibc < 2.38 | 源码编译或升级至 Ubuntu 24.04+、Debian 13+ |
| `npx create-webclaw` 升级后报错 | 旧版本二进制残留 | 删除 `~/.webclaw/` 后重新运行 |
| 批处理下保留大量噪声 | `--only-main-content` 失效（Issue #3） | 使用 `--include` / `--exclude` 显式过滤 |
| 反爬站点返回空白 | 触发 Cloudflare 或 Bot 防护 | 设置 `WEBCLAW_API_KEY` 触发自动云端升级 |

资料来源：[Issue #73](https://github.com/0xMassi/webclaw/issues/73)、[Issue #3](https://github.com/0xMassi/webclaw/issues/3)、[Issue #30](https://github.com/0xMassi/webclaw/issues/30)

## See Also

- [CLI 命令详解与输出格式](./cli-reference.md)
- [MCP 工具与 AI Agent 集成指南](./mcp-integration.md)
- [REST API 参考（/v1/scrape、/v1/crawl、/v1/extract）](./rest-api-reference.md)
- [LLM Provider Chain 配置（Ollama / OpenAI / Anthropic）](./llm-provider-chain.md)

---

<a id='page-2'></a>

## Rust 工作空间与 Crate 架构

### 相关页面

相关主题：[项目概述与安装指南](#page-1), [CLI、MCP 工具与已知故障模式](#page-3), [自托管服务器与部署](#page-4)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [Cargo.toml](https://github.com/0xMassi/webclaw/blob/main/Cargo.toml)
- [crates/webclaw-cli/src/main.rs](https://github.com/0xMassi/webclaw/blob/main/crates/webclaw-cli/src/main.rs)
- [crates/webclaw-cli/src/bench.rs](https://github.com/0xMassi/webclaw/blob/main/crates/webclaw-cli/src/bench.rs)
- [crates/webclaw-core/src/lib.rs](https://github.com/0xMassi/webclaw/blob/main/crates/webclaw-core/src/lib.rs)
- [crates/webclaw-fetch/src/lib.rs](https://github.com/0xMassi/webclaw/blob/main/crates/webclaw-fetch/src/lib.rs)
- [crates/webclaw-llm/src/lib.rs](https://github.com/0xMassi/webclaw/blob/main/crates/webclaw-llm/src/lib.rs)
- [crates/webclaw-llm/src/summarize.rs](https://github.com/0xMassi/webclaw/blob/main/crates/webclaw-llm/src/summarize.rs)
- [crates/webclaw-llm/src/extract.rs](https://github.com/0xMassi/webclaw/blob/main/crates/webclaw-llm/src/extract.rs)
- [crates/webclaw-server/src/routes/extract.rs](https://github.com/0xMassi/webclaw/blob/main/crates/webclaw-server/src/routes/extract.rs)
- [crates/webclaw-server/src/routes/crawl.rs](https://github.com/0xMassi/webclaw/blob/main/crates/webclaw-server/src/routes/crawl.rs)
- [crates/webclaw-server/src/routes/diff.rs](https://github.com/0xMassi/webclaw/blob/main/crates/webclaw-server/src/routes/diff.rs)
- [crates/webclaw-mcp/src/server.rs](https://github.com/0xMassi/webclaw/blob/main/crates/webclaw-mcp/src/server.rs)
- [README.md](https://github.com/0xMassi/webclaw/blob/main/README.md)
</details>

# Rust 工作空间与 Crate 架构

## 1. 概述

webclaw 是一个面向"网页 → Markdown / JSON / LLM 上下文"转换的多入口工具集，提供 CLI、MCP 服务器、REST API 与 SDK 多种接入形态 [README.md](README.md)。该工程使用 Cargo workspace 把不同关注点拆分为若干 crate，使核心抓取、内容提取、LLM 调度以及对外服务层互不耦合，方便按需组合。

workspace 的设计遵循"底层无依赖、高层组合调用"的分层原则：

- **基础层**：`webclaw-core` 负责 HTML→Markdown 提取、`webclaw-fetch` 负责带 TLS 指纹伪装与代理的 HTTP 获取。
- **能力层**：`webclaw-llm` 提供统一的 LLM 调用链与 JSON / 摘要提取。
- **入口层**：`webclaw-cli`、`webclaw-server`、`webclaw-mcp` 各自面向不同的用户群体。

## 2. Crate 依赖分层

下表列出了主要 crate 的角色与典型依赖方向。`webclaw-cli` 同时引用 `webclaw-core` 与 `webclaw-fetch`，而 `webclaw-server` 与 `webclaw-mcp` 在更高层引入 `webclaw-llm` 等能力。

| Crate | 角色 | 关键依赖 | 入口形态 |
|---|---|---|---|
| `webclaw-core` | 内容提取（HTML→Markdown、LLM 文本） | 无业务上游依赖 | 库 |
| `webclaw-fetch` | HTTP 抓取、TLS 指纹、URL 校验 | 无业务上游依赖 | 库 |
| `webclaw-llm` | LLM 提供方链、抽取、摘要 | 可独立工作，按需组合 | 库 |
| `webclaw-cli` | CLI 命令解析与输出渲染 | `webclaw-core`、`webclaw-fetch` | 二进制 |
| `webclaw-server` | Axum REST 服务（`/v1/extract`、`/v1/crawl`、`/v1/diff` 等） | `webclaw-llm`、`webclaw-fetch` | 二进制 |
| `webclaw-mcp` | MCP 工具服务器 | `webclaw-core`、`webclaw-fetch` 等 | 二进制 |

`webclaw-cli/src/bench.rs` 同时导入 `webclaw_core::{extract, to_llm_text}` 与 `webclaw_fetch::{BrowserProfile, FetchClient, FetchConfig}`，说明 CLI 直接编排"抓取 + 提取"两个基础 crate [bench.rs](crates/webclaw-cli/src/bench.rs)。`webclaw-llm/src/lib.rs` 显式声明了 `chain`、`clean`、`error`、`extract`、`provider`、`providers`、`summarize` 七个模块 [lib.rs](crates/webclaw-llm/src/lib.rs)。

```mermaid
flowchart TB
    CLI["webclaw-cli<br/>(CLI 入口)"]
    Server["webclaw-server<br/>(REST API)"]
    MCP["webclaw-mcp<br/>(MCP 工具)"]
    LLM["webclaw-llm<br/>(LLM 链、抽取、摘要)"]
    Core["webclaw-core<br/>(HTML→Markdown)"]
    Fetch["webclaw-fetch<br/>(HTTP + TLS + URL 校验)"]

    CLI --> Core
    CLI --> Fetch
    Server --> Fetch
    Server --> LLM
    Server --> Core
    MCP --> Core
    MCP --> Fetch
    LLM --> Core
```

## 3. 各 Crate 的职责

### 3.1 webclaw-core：内容提取

作为最底层的纯逻辑 crate，提供 HTML 解析到结构化 `ExtractionResult` 的能力。`webclaw-cli/src/main.rs` 的 diff 输出、`batch` 输出等流程均依赖 `to_llm_text` 与 `extract` 等函数 [main.rs](crates/webclaw-cli/src/main.rs)。该层不持有任何网络或 LLM 客户端，因此可独立测试。

### 3.2 webclaw-fetch：网络与 TLS

封装浏览器指纹（`BrowserProfile`）、抓取客户端（`FetchClient`）与全局配置（`FetchConfig`），并对外暴露 `url_security::validate_public_http_url` 等安全工具。`webclaw-server/src/routes/diff.rs` 在处理 diff 请求前调用 `validate_public_http_url` 校验入站 URL，避免 SSRF [diff.rs](crates/webclaw-server/src/routes/diff.rs)。`webclaw-mcp/src/server.rs` 中的 `vertical_scrape` 工具刻意使用缓存的 Firefox 客户端而非默认 Chrome，以绕过 Reddit 等站点的 TLS 黑名单 [server.rs](crates/webclaw-mcp/src/server.rs)。

### 3.3 webclaw-llm：模型抽象与本地优先链

`ProviderChain` 顺序尝试 Ollama → OpenAI → Gemini → Anthropic，使自托管用户本地模型可用时不必走云端 [lib.rs](crates/webclaw-llm/src/lib.rs)。`summarize.rs` 在每次响应后调用 `strip_thinking_tags` 做防御性清洗，避免推理痕迹泄漏到最终摘要 [summarize.rs](crates/webclaw-llm/src/summarize.rs)。`extract.rs` 同时提供"基于 JSON Schema"和"自然语言 prompt"两种抽取模式，温度分别固定为 `0.0` 与低值以保证稳定输出 [extract.rs](crates/webclaw-llm/src/extract.rs)。

### 3.4 入口 crate：CLI / Server / MCP

- **CLI**：通过 clap 子命令编排 single、batch、crawl、diff、brand、search、vertical、bench 等功能，例如 `vertical` 子命令用于按站点名调用专用抽取器 [main.rs](crates/webclaw-cli/src/main.rs)。
- **Server**：基于 Axum 暴露 `POST /v1/extract` 等路由，`extract.rs` 路由要求请求至少提供 `schema` 或 `prompt` 之一 [extract.rs](crates/webclaw-server/src/routes/extract.rs)；`crawl.rs` 汇总抓取结果为 `{ total, completed, errors, pages }` 结构 [crawl.rs](crates/webclaw-server/src/routes/crawl.rs)。
- **MCP**：在 `server.rs` 中通过 `#[tool]` 宏注册工具给 LLM 代理调用，例如 `vertical_scrape` 在遇到反爬时若设置了 `WEBCLAW_API_KEY`，会自动升级到云端 API [server.rs](crates/webclaw-mcp/src/server.rs)。

## 4. 典型调用链与失败模式

以"通过 REST API 抽取结构化数据"为例的请求路径：

1. 客户端调用 `POST /v1/extract` 并附 `url` + `schema|prompt`。
2. `webclaw-server` 调用 `webclaw_fetch::url_security::validate_public_http_url` 校验地址 [diff.rs](crates/webclaw-server/src/routes/diff.rs)。
3. `state.fetch().fetch_and_extract(...)` 走 `webclaw-fetch` + `webclaw-core` 拿到 `ExtractionResult`。
4. `webclaw_llm::extract::extract_json` 或 `extract_with_prompt` 将结果送入 `ProviderChain` [extract.rs](crates/webclaw-server/src/routes/extract.rs)。
5. 返回清洗后的 JSON。

**已知限制**（与社区问题相关）：

- Linux 预编译二进制需要 glibc 2.38+，导致 Debian 12 / Ubuntu 22.04 / RHEL 9 等发行版无法直接运行 [Issue #73](#)。
- CLI 批量模式下 `--only-main-content` 不会被应用，需作为已知行为规避 [Issue #3](#)。

## See Also

- [README.md](README.md)
- [examples/html-to-markdown-rag/](examples/html-to-markdown-rag/README.md)
- [examples/firecrawl-compatible-api/](examples/firecrawl-compatible-api/README.md)
- [examples/mcp-web-scraping/](examples/mcp-web-scraping/README.md)

---

<a id='page-3'></a>

## CLI、MCP 工具与已知故障模式

### 相关页面

相关主题：[项目概述与安装指南](#page-1), [Rust 工作空间与 Crate 架构](#page-2), [自托管服务器与部署](#page-4)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [crates/webclaw-cli/src/main.rs](https://github.com/0xMassi/webclaw/blob/main/crates/webclaw-cli/src/main.rs)
- [crates/webclaw-mcp/src/main.rs](https://github.com/0xMassi/webclaw/blob/main/crates/webclaw-mcp/src/main.rs)
- [crates/webclaw-mcp/src/server.rs](https://github.com/0xMassi/webclaw/blob/main/crates/webclaw-mcp/src/server.rs)
- [crates/webclaw-mcp/src/tools.rs](https://github.com/0xMassi/webclaw/blob/main/crates/webclaw-mcp/src/tools.rs)
- [crates/webclaw-llm/src/lib.rs](https://github.com/0xMassi/webclaw/blob/main/crates/webclaw-llm/src/lib.rs)
- [crates/webclaw-llm/src/summarize.rs](https://github.com/0xMassi/webclaw/blob/main/crates/webclaw-llm/src/summarize.rs)
- [crates/webclaw-server/src/routes/extract.rs](https://github.com/0xMassi/webclaw/blob/main/crates/webclaw-server/src/routes/extract.rs)
- [crates/webclaw-server/src/routes/diff.rs](https://github.com/0xMassi/webclaw/blob/main/crates/webclaw-server/src/routes/diff.rs)
- [crates/webclaw-server/src/routes/crawl.rs](https://github.com/0xMassi/webclaw/blob/main/crates/webclaw-server/src/routes/crawl.rs)
- [examples/README.md](https://github.com/0xMassi/webclaw/blob/main/examples/README.md)
- [examples/mcp-web-scraping/README.md](https://github.com/0xMassi/webclaw/blob/main/examples/mcp-web-scraping/README.md)
- [examples/html-to-markdown-rag/README.md](https://github.com/0xMassi/webclaw/blob/main/examples/html-to-markdown-rag/README.md)
- [README.md](https://github.com/0xMassi/webclaw/blob/main/README.md)
</details>

# CLI、MCP 工具与已知故障模式

本页面向新用户与运维人员介绍 webclaw 的两条主要交互面——命令行 (`webclaw` 二进制) 与 MCP 服务器 (`webclaw-mcp`)，并整理当前社区中已公开报告的故障模式与规避方法，便于在生产环境与 AI 代理集成中快速排错。

## 1. CLI 子命令与关键参数

`webclaw` CLI 的入口与子命令全部在 [crates/webclaw-cli/src/main.rs](https://github.com/0xMassi/webclaw/blob/main/crates/webclaw-cli/src/main.rs) 中定义。除了默认的「单页抓取」流程外，还包含面向垂直站点的 `vertical` 子命令、基于 Serper.dev 的 `search` 子命令，以及 `crawl`、`map`、`diff`、`brand` 等扩展命令。`Vertical` 子命令接受 `name` 与 `url` 两个位置参数，并提供 `--raw` 选项以输出单行紧凑 JSON ([crates/webclaw-cli/src/main.rs](https://github.com/0xMassi/webclaw/blob/main/crates/webclaw-cli/src/main.rs))。`search` 子命令的 API key 既可通过 `--serper-key` 传入，也会回退到环境变量 `SERPER_API_KEY`，并支持 `--num`、`--country`、`--language` 与 `--scrape` 组合 ([crates/webclaw-cli/src/main.rs](https://github.com/0xMassi/webclaw/blob/main/crates/webclaw-cli/src/main.rs))。

针对内容裁剪，CLI 暴露 `--only-main-content`、`--include`、`--exclude` 等过滤器 ([README.md](https://github.com/0xMassi/webclaw/blob/main/README.md))，并提供 `--format markdown|llm|text|json|html` 等输出格式 ([examples/html-to-markdown-rag/README.md](https://github.com/0xMassi/webclaw/blob/main/examples/html-to-markdown-rag/README.md))。当目标页面是定价、新闻列表等场景时，`--diff-with <file>` 可与 `format json` 配合，生成「人可读摘要 + 文本 diff」 ([crates/webclaw-cli/src/main.rs](https://github.com/0xMassi/webclaw/blob/main/crates/webclaw-cli/src/main.rs))。

## 2. MCP 服务器与工具集

`webclaw-mcp` 通过 `rmcp` 的 stdio transport 暴露给 AI 代理 ([crates/webclaw-mcp/src/main.rs](https://github.com/0xMassi/webclaw/blob/main/crates/webclaw-mcp/src/main.rs))。其核心服务结构在 [crates/webclaw-mcp/src/server.rs](https://github.com/0xMassi/webclaw/blob/main/crates/webclaw-mcp/src/server.rs) 中实现，工具参数结构在 [crates/webclaw-mcp/src/tools.rs](https://github.com/0xMassi/webclaw/blob/main/crates/webclaw-mcp/src/tools.rs) 中定义，涵盖 `scrape`、`crawl`、`map`、`batch`、`extract`、`summarize`、`diff`、`brand`、`research`、`search` 与 `vertical_scrape` ([examples/mcp-web-scraping/README.md](https://github.com/0xMassi/webclaw/blob/main/examples/mcp-web-scraping/README.md))。

为了兼容 Claude Desktop、VS Code 等会把数字/布尔序列化为字符串的客户端，参数解析层引入了 `deser_opt_u32_or_str`、`deser_opt_usize_or_str`、`deser_opt_bool_or_str` 等 coercion 助手 ([crates/webclaw-mcp/src/tools.rs](https://github.com/0xMassi/webclaw/blob/main/crates/webclaw-mcp/src/tools.rs))，避免出现 `invalid type: string "3", expected u32` 这类错误。值得注意的是，`vertical_scrape` 工具强制使用 Firefox 指纹客户端，因为 Reddit 的 `.json` 端点会拒绝常见 Chrome 模拟的 TLS 指纹，即使在住宅代理下也会返回 403 ([crates/webclaw-mcp/src/server.rs](https://github.com/0xMassi/webclaw/blob/main/crates/webclaw-mcp/src/server.rs))。

`WEBCLAW_API_KEY` 是可选的本地提取配置项，但在启用云端回退、JS 渲染或托管 search/research 能力时必须设置 ([examples/mcp-web-scraping/README.md](https://github.com/0xMassi/webclaw/blob/main/examples/mcp-web-scraping/README.md))。LLM 侧的提取与摘要由 [crates/webclaw-llm/src/lib.rs](https://github.com/0xMassi/webclaw/blob/main/crates/webclaw-llm/src/lib.rs) 与 [crates/webclaw-llm/src/summarize.rs](https://github.com/0xMassi/webclaw/blob/main/crates/webclaw-llm/src/summarize.rs) 提供，本地优先采用 Ollama，再回退到 OpenAI、Gemini、Anthropic。

```mermaid
flowchart LR
    A[CLI webclaw] -->|stdout| U1[终端 / 管道]
    B[MCP webclaw-mcp] -->|stdio JSON-RPC| C[Claude Code / Cursor / Codex]
    D[Server webclaw-server] -->|HTTP /v1| E[SDK / curl]
    A -. 复用 .-> F[webclaw-fetch]
    B -. 复用 .-> F
    D -. 复用 .-> F
    F --> G[webclaw-llm]
    F --> H[webclaw-core]
```

## 3. 已知故障模式与社区反馈

**1) `--only-main-content` 在批量模式下失效（Issue #3）**  
当以 `webclaw --only-main-content --urls-file URLs.txt` 形式批量抓取时，参数不会被应用。该问题在社区中被多次复现（两种参数顺序均不生效）。截至 `v0.6.14` 仍需在单页 CLI 调用或 MCP 的 `scrape` 工具中显式带上该参数。

**2) Linux 发布二进制要求 glibc 2.38+（Issue #73）**  
预编译的 `webclaw`、`webclaw-mcp`、`webclaw-server` 链接到了较新的 glibc，无法在 Debian 12、Ubuntu 22.04 LTS、Amazon Linux 2023、RHEL/Rocky 9 等常见服务器发行版上启动。建议的临时方案是从源码 `cargo build --release` 构建，或使用 Docker 镜像。`v0.6.14` 的 changelog 中包含 `fix(create-webclaw): repair binary...` 等修复条目（[README.md](https://github.com/0xMassi/webclaw/blob/main/README.md)），但 glibc 兼容性仍需关注后续 release。

**3) 更新 `webclaw-mcp` 时的告警（Issue #30）**  
`npx create-webclaw` 在升级 `webclaw-mcp` 过程中会输出警告截图，社区已记录但暂未公开根因分析。建议在升级前先备份 `~/.webclaw/` 与各 MCP 客户端的 JSON 配置，更新后再用 `which webclaw-mcp` 与 `webclaw-mcp --version` 验证可执行文件指向。

**4) 抓取为空时的误判规避**  
`detect_empty` 在 [crates/webclaw-cli/src/main.rs](https://github.com/0xMassi/webclaw/blob/main/crates/webclaw-cli/src/main.rs) 的相关测试中区分了 `EmptyReason::ConsentWall` 与真实内容场景，避免将包含「cookie consent」等关键词的长文误判为同意墙。运营上若仍出现空结果，可结合 `--include "article,main,.content"` 与 `examples/cloudflare-diagnostics/` 中提供的诊断清单排查。

## 4. 排错速查表

| 现象 | 可能原因 | 推荐处置 |
| --- | --- | --- |
| 批量模式下过滤参数不生效 | CLI `--only-main-content` 在 batch 路径上未透传（Issue #3） | 改用 MCP `batch` 工具或在循环中逐 URL 调用 |
| `webclaw-mcp` 启动报 `GLIBC_* not found` | 预编译二进制依赖 glibc 2.38+（Issue #73） | 使用源码构建或容器镜像 |
| Claude Desktop 报 `expected u32` | MCP 客户端将数字/布尔序列化为字符串 | 升级至含 coercion helper 的版本（[crates/webclaw-mcp/src/tools.rs](https://github.com/0xMassi/webclaw/blob/main/crates/webclaw-mcp/src/tools.rs)） |
| `vertical_scrape` 命中 Reddit 403 | 默认 Chrome TLS 指纹被屏蔽 | 已在代码中切换到 Firefox 客户端（[crates/webclaw-mcp/src/server.rs](https://github.com/0xMassi/webclaw/blob/main/crates/webclaw-mcp/src/server.rs)） |
| `diff` 文本为空但元数据有变化 | 选用了 `markdown` 而非 `json` | 改用 `format json` 或检查 `text_diff` 字段（[crates/webclaw-server/src/routes/diff.rs](https://github.com/0xMassi/webclaw/blob/main/crates/webclaw-server/src/routes/diff.rs)） |

## See Also

- [HTML to Markdown for RAG 示例](https://github.com/0xMassi/webclaw/blob/main/examples/html-to-markdown-rag/README.md)
- [MCP Web Scraping 集成指南](https://github.com/0xMassi/webclaw/blob/main/examples/mcp-web-scraping/README.md)
- [Examples 总目录](https://github.com/0xMassi/webclaw/blob/main/examples/README.md)
- [主 README](https://github.com/0xMassi/webclaw/blob/main/README.md)

---

<a id='page-4'></a>

## 自托管服务器与部署

### 相关页面

相关主题：[项目概述与安装指南](#page-1), [Rust 工作空间与 Crate 架构](#page-2), [CLI、MCP 工具与已知故障模式](#page-3)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [crates/webclaw-server/src/main.rs](https://github.com/0xMassi/webclaw/blob/main/crates/webclaw-server/src/main.rs)
- [crates/webclaw-server/src/routes/scrape.rs](https://github.com/0xMassi/webclaw/blob/main/crates/webclaw-server/src/routes/scrape.rs)
- [crates/webclaw-server/src/routes/crawl.rs](https://github.com/0xMassi/webclaw/blob/main/crates/webclaw-server/src/routes/crawl.rs)
- [crates/webclaw-server/src/routes/extract.rs](https://github.com/0xMassi/webclaw/blob/main/crates/webclaw-server/src/routes/extract.rs)
- [crates/webclaw-server/src/routes/diff.rs](https://github.com/0xMassi/webclaw/blob/main/crates/webclaw-server/src/routes/diff.rs)
- [crates/webclaw-llm/src/lib.rs](https://github.com/0xMassi/webclaw/blob/main/crates/webclaw-llm/src/lib.rs)
- [crates/webclaw-llm/src/summarize.rs](https://github.com/0xMassi/webclaw/blob/main/crates/webclaw-llm/src/summarize.rs)
- [crates/webclaw-mcp/src/server.rs](https://github.com/0xMassi/webclaw/blob/main/crates/webclaw-mcp/src/server.rs)
- [crates/webclaw-cli/src/main.rs](https://github.com/0xMassi/webclaw/blob/main/crates/webclaw-cli/src/main.rs)
- [examples/README.md](https://github.com/0xMassi/webclaw/blob/main/examples/README.md)
</details>

# 自托管服务器与部署

## 概述

`webclaw` 提供了一整套面向 AI 代理与 RAG 流水线的网页内容抓取与提取能力，核心以 Rust 编写并拆分为多个 crate。用户既可以使用官方托管的 [api.webclaw.io](https://api.webclaw.io) 服务，也可以把整个后端**自托管**在自己的服务器上。自托管入口是 `webclaw-server` 这个二进制 crate——它对外暴露 REST API，对内则复用 `webclaw-fetch` 抓取管线、`webclaw-core` 提取管线与 `webclaw-llm` 的本地优先 LLM 链路。资料来源：[crates/webclaw-llm/src/lib.rs:1-5]()。

自托管部署的意义在于：(1) 完全控制出网流量（便于配合 [ColdProxy](https://coldproxy.com/) 等住宅代理）；(2) 在内网或气隙环境运行 LLM 提取；(3) 把 REST/MCP 接口与已有网关、网关鉴权、审计系统对接。仓库根目录的 [README.md](https://github.com/0xMassi/webclaw) 与 [examples/README.md](https://github.com/0xMassi/webclaw/blob/main/examples/README.md) 都把"CLI、MCP server、REST API 与多语言 SDK"列为同等重要的使用面。

## 架构与组件

```mermaid
graph LR
    Client[CLI / MCP / SDK / cURL] --> Server[webclaw-server<br/>axum]
    Server --> Fetch[webclaw-fetch<br/>wreq TLS 指纹]
    Server --> Core[webclaw-core<br/>提取管线]
    Server --> LLM[webclaw-llm<br/>ProviderChain]
    LLM --> Ollama[Ollama 本地]
    LLM --> OpenAI[OpenAI]
    LLM --> Gemini[Gemini]
    LLM --> Anthropic[Anthropic]
    Server -.可选升级.-> Hosted[api.webclaw.io<br/>WEBCLAW_API_KEY]
```

如架构图所示，服务器本身不直接实现抓取与提取逻辑，而是把请求转交给共享的库 crate。这种"单仓多 crate"的结构让 CLI、MCP server、REST server 共用同一份事实——例如 `--only-main-content`、`--include`、`--exclude` 这类内容过滤逻辑在所有端点上行为一致。资料来源：[crates/webclaw-mcp/src/server.rs:1-10]()。

LLM 链路是**本地优先**（local-first）的回退链：`Ollama -> OpenAI -> Gemini -> Anthropic`。这一策略在 [crates/webclaw-llm/src/lib.rs:1-5]() 的模块文档中有明确说明，意图是让自托管用户在完全没有外网 LLM 凭据时也能跑通 `summarize` 与 `extract` 端点。资料来源：[crates/webclaw-llm/src/lib.rs:1-5]()。

## 部署与配置

仓库提供两条推荐路径。第一条是托管部署：通过 `npx create-webclaw` 一行命令生成 `.env`、配置文件与启动脚本；第二条是手动部署：直接拉取 GitHub Release 中的 `webclaw-server` 二进制并通过 systemd / Docker 运行。两条路径共享同一组环境变量，其中最关键的是 `WEBCLAW_API_KEY`——当本地管线遇到被反爬保护的站点（如 `amazon_product`、`ebay_listing`、`trustpilot_reviews` 等垂直提取器）时，会自动升级到 [api.webclaw.io](https://api.webclaw.io) 处理。资料来源：[crates/webclaw-mcp/src/server.rs:1-15]()。

v0.6.14 的一个重要修复是 `fix(deploy): write WEBCLAW_API_KEY in generated .env`（见 [PR #68](https://github.com/0xMassi/webclaw/pull/68)），它在 `create-webclaw` 生成的 `.env` 中显式写入该键，避免用户运行 `webclaw` 时因为缺少该变量而无法启用托管回退。其他常用键包括 `SERPER_API_KEY`（用于 `search` 子命令，调用 Serper.dev），以及 `OLLAMA_HOST`、`OPENAI_API_KEY`、`GEMINI_API_KEY`、`ANTHROPIC_API_KEY`（按顺序构建 `ProviderChain`）。资料来源：[crates/webclaw-cli/src/main.rs:1-30]()、`[crates/webclaw-llm/src/lib.rs:1-5]()`。

### Linux 兼容性提示

社区已有报告（issue #73）指出预编译 Linux 二进制依赖 **glibc 2.38+**，因此在 Debian 12、Ubuntu 22.04 LTS、Amazon Linux 2023、RHEL/Rocky 9 等 glibc 较旧的系统上会启动失败。在这些环境下自托管有两条可行路径：(a) 用 `cargo install --git https://github.com/0xMassi/webclaw webclaw-server` 从源码构建；(b) 切换到基于 musl 的镜像或 glibc ≥ 2.38 的发行版（如 Debian 13、Ubuntu 24.04）。资料来源：社区 issue #73。

## API 端点速查

| 方法 | 路径 | 用途 | 关键请求字段 |
| --- | --- | --- | --- |
| POST | `/v1/scrape` | 抓取单页并输出 markdown/llm/json | `url`, `formats`, `only_main_content` |
| POST | `/v1/crawl` | 按深度/页面数抓取整站 | `url`, `depth`, `max_pages`, `use_sitemap` |
| POST | `/v1/extract` | LLM 结构化提取 | `url`, `schema` 或 `prompt`（二选一） |
| POST | `/v1/diff` | 与历史快照对比 | `url`, `previous`（旧 ExtractionResult） |

`/v1/extract` 同时支持 `schema`（JSON Schema）与 `prompt`（自然语言）两种模式，但**至少要提供其一**，否则返回 400。资料来源：[crates/webclaw-server/src/routes/extract.rs:1-20]()`。`/v1/diff` 则要求在请求体中带上先前一次抓取的 `ExtractionResult`，服务器会重新抓取当前页面并产出 `status`、`word_count_delta`、`links_added`、`links_removed`、`text_diff` 等字段。资料来源：[crates/webclaw-server/src/routes/diff.rs:1-30]()`。

## 已知问题与故障排查

社区在自托管场景下还反馈过两类问题，部署时应留意：

1. **`--only-main-content` 在批处理模式下失效**（issue #3）：`webclaw --only-main-content --urls-file URLs.txt` 与参数调换顺序的写法都未生效。如需批量过滤主内容，应改用等价的 REST 调用 `POST /v1/scrape` 并在每个 URL 的请求体中显式传 `only_main_content: true`，或者在 MCP 工具 `batch_extract` 中逐条指定。
2. **MCP 更新告警**（issue #30）：通过包管理器升级 `webclaw-mcp` 时会显示一条提示性 warning，建议先停掉当前 MCP 进程再执行升级，避免锁文件冲突。

自托管 webclaw 总体上是"开箱即用"——`npx create-webclaw` 生成 `.env`、拉起 systemd 单元或 Docker 容器后，`/v1/*` 路由立即可用。当需要把整站抓取、品牌资产抽取、搜索与研究工作流接入自家代理或内网 LLM 时，这套架构可以直接复用 CLI 与 SDK 的同一份代码路径。

## 另请参阅

- [MCP Web Scraping 示例](https://github.com/0xMassi/webclaw/blob/main/examples/mcp-web-scraping/)
- [Proxy-Backed Crawling 示例](https://github.com/0xMassi/webclaw/blob/main/examples/proxy-backed-crawling/)
- [Cloudflare Diagnostics 示例](https://github.com/0xMassi/webclaw/blob/main/examples/cloudflare-diagnostics/)
- [HTML to Markdown for RAG 示例](https://github.com/0xMassi/webclaw/blob/main/examples/html-to-markdown-rag/)

---

<!-- evidence_pipeline_checked: true -->
<!-- evidence_injected: true -->

---

## Doramagic 踩坑日志

项目：0xMassi/webclaw

摘要：发现 11 个潜在踩坑项，其中 0 个为 high/blocking；最高优先级：安装坑 - 来源证据：Linux release binaries require glibc 2.38+ — fail on Debian 12 / Ubuntu 22.04 / Amazon Linux 2023。

## 1. 安装坑 · 来源证据：Linux release binaries require glibc 2.38+ — fail on Debian 12 / Ubuntu 22.04 / Amazon Linux 2023

- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Linux release binaries require glibc 2.38+ — fail on Debian 12 / Ubuntu 22.04 / Amazon Linux 2023
- 对用户的影响：可能增加新用户试用和生产接入成本。
- 证据：community_evidence:github | https://github.com/0xMassi/webclaw/issues/73 | 来源讨论提到 node 相关条件，需在安装/试用前复核。

## 2. 安装坑 · 来源证据：`webclaw-server` REST API binary is missing from repo and Docker image

- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：`webclaw-server` REST API binary is missing from repo and Docker image
- 对用户的影响：可能增加新用户试用和生产接入成本。
- 证据：community_evidence:github | https://github.com/0xMassi/webclaw/issues/15 | 来源讨论提到 docker 相关条件，需在安装/试用前复核。

## 3. 配置坑 · 可能修改宿主 AI 配置

- 严重度：medium
- 证据强度：source_linked
- 发现：项目面向 Claude/Cursor/Codex/Gemini/OpenCode 等宿主，或安装命令涉及用户配置目录。
- 对用户的影响：安装可能改变本机 AI 工具行为，用户需要知道写入位置和回滚方法。
- 证据：capability.host_targets | https://github.com/0xMassi/webclaw | host_targets=mcp_host, claude_code, claude, cursor, codex

## 4. 配置坑 · 来源证据：MCP boolean params rejected when sent as strings (follow-up to #58 / #59)

- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个配置相关的待验证问题：MCP boolean params rejected when sent as strings (follow-up to #58 / #59)
- 对用户的影响：可能增加新用户试用和生产接入成本。
- 证据：community_evidence:github | https://github.com/0xMassi/webclaw/issues/62 | 来源讨论提到 windows 相关条件，需在安装/试用前复核。

## 5. 能力坑 · 能力判断依赖假设

- 严重度：medium
- 证据强度：source_linked
- 发现：README/documentation is current enough for a first validation pass.
- 对用户的影响：假设不成立时，用户拿不到承诺的能力。
- 证据：capability.assumptions | https://github.com/0xMassi/webclaw | README/documentation is current enough for a first validation pass.

## 6. 维护坑 · 维护活跃度未知

- 严重度：medium
- 证据强度：source_linked
- 发现：未记录 last_activity_observed。
- 对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。
- 证据：evidence.maintainer_signals | https://github.com/0xMassi/webclaw | last_activity_observed missing

- 严重度：medium
- 证据强度：source_linked
- 发现：no_demo
- 证据：downstream_validation.risk_items | https://github.com/0xMassi/webclaw | no_demo; severity=medium

## 8. 安全/权限坑 · 存在评分风险

- 严重度：medium
- 证据强度：source_linked
- 发现：no_demo
- 对用户的影响：风险会影响是否适合普通用户安装。
- 证据：risks.scoring_risks | https://github.com/0xMassi/webclaw | no_demo; severity=medium

## 9. 安全/权限坑 · 来源证据：create-webclaw fails on Windows: asset name mismatch + uses missing unzip command

- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：create-webclaw fails on Windows: asset name mismatch + uses missing unzip command
- 对用户的影响：可能影响授权、密钥配置或安全边界。
- 证据：community_evidence:github | https://github.com/0xMassi/webclaw/issues/71 | 来源讨论提到 node 相关条件，需在安装/试用前复核。

## 10. 维护坑 · issue/PR 响应质量未知

- 严重度：low
- 证据强度：source_linked
- 发现：issue_or_pr_quality=unknown。
- 对用户的影响：用户无法判断遇到问题后是否有人维护。
- 证据：evidence.maintainer_signals | https://github.com/0xMassi/webclaw | issue_or_pr_quality=unknown

## 11. 维护坑 · 发布节奏不明确

- 严重度：low
- 证据强度：source_linked
- 发现：release_recency=unknown。
- 对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。
- 证据：evidence.maintainer_signals | https://github.com/0xMassi/webclaw | release_recency=unknown

<!-- canonical_name: 0xMassi/webclaw; human_manual_source: deepwiki_human_wiki -->