Clawifi

clawifi

Clawifi 的官方 Python SDK、CLI 和 MCP 服务，为 AI Agent 提供网页搜索和页面读取功能：将多个搜索引擎整合为一个入口，读取网页和 PDF、绘制网站地图并抓取网站，还能只返回回答问题的段落，并为每段附上来源。一个类型化 API 和 MCP 接口即可实现所有这些功能。

此软件包是托管 Clawifi API 的轻量客户端（发布时托管 API 版本为 1.7.2）；不包含 Clawifi 服务端。文档、定价和状态：clawifi.dev/docs · clawifi.dev/pricing · clawifi.dev/status · clawifi.dev/security。

一键安装（托管服务，无需密钥即可试用）

两种方式都会添加托管远程服务 https://api.clawifi.dev/mcp。无需密钥即可试用：4 个工具，每个地址每天可调用 50 次。添加 API 密钥即可使用完整工具集（获取免费密钥）。

安装

pip install clawifi

获取 API 密钥

clawifi signup --email [email protected] --password "a strong password"

此操作会创建账户、赠送 1,000 个免费额度，并打印 API 密钥。导出该密钥：

export CLAWIFI_API_KEY="clawifi_live_..."

快速测试

clawifi quicktest --url https://example.com

设置 MCP 客户端

clawifi init

查找此机器上已安装的 MCP 客户端（Claude Code、Codex、Cursor、Claude Desktop、VS Code），并为每个客户端打印本地服务（clawifi-mcp，stdio）和远程服务的安装命令，以及一个可尝试的首次调用。它只会打印内容；绝不会显示你的密钥，只会显示 $CLAWIFI_API_KEY 或经过遮蔽的 clawifi_live_****。clawifi init --all 会显示所有客户端，无论是否已找到。

如需让它为你编辑配置文件：

clawifi init --write cursor            # ~/.cursor/mcp.json, stdio entry
clawifi init --write cursor --remote   # ~/.cursor/mcp.json, remote entry
clawifi init --write claude-desktop    # claude_desktop_config.json, stdio entry

--write 会在修改前征求同意，并先将现有文件复制为 <file>.bak-<timestamp>。Claude Code、Codex 和 VS Code 有各自的安装命令，init 会打印这些命令。

例如，对于 Claude Code：

# local (stdio)
claude mcp add --env CLAWIFI_API_KEY=$CLAWIFI_API_KEY --transport stdio clawifi -- clawifi-mcp
# remote
claude mcp add --transport http clawifi https://api.clawifi.dev/mcp --header "Authorization: Bearer $CLAWIFI_API_KEY"

用作 MCP 服务

本地 MCP 服务运行命令如下：

clawifi-mcp

从环境变量读取 CLAWIFI_API_KEY。clawifi mcp config 会打印一份最简配置。每个工具都带有标题和 MCP 提示 readOnlyHint、destructiveHint、idempotentHint 和 openWorldHint；没有任何工具具有破坏性。

可计费工具（fetch、scrape、extract、map_site、crawl、search_free）将通用选项作为参数，并将其他 API 字段放入 options，再合并到请求正文中。这些工具不接受 dry_run：请使用 estimate 工具估算调用费用。工具未声明的参数会被拒绝，而不会被忽略。

远程 MCP

Clawifi 也运行托管式 MCP 服务，因此无需安装任何内容：

• URL：https://api.clawifi.dev/mcp（可流式传输的 HTTP）
• 身份验证：Authorization: Bearer <your key>，或使用 X-Clawifi-Api-Key: <your key> 标头

旧主机 api.clawifi.qzz.io（API 和 /mcp）仍可正常使用，因此 CLAWIFI_API_BASE=https://api.clawifi.qzz.io 和现有远程配置都无需更改。

不提供密钥时，远程服务提供包含四个工具的免密层级：search_free、fetch_url、scrape_url 和 map_site，每个地址每分钟可调用 12 次，每天可调用 50 次。提供密钥后，即可使用完整的工具列表。

点数

每次调用按操作收费（普通抓取为 1 点，浏览器渲染为 3 点，爬取按每个页面 1 点计费，依此类推）。请参阅 clawifi.dev/pricing，或打印当前价目表，无需密钥：

clawifi credits

credits MCP 工具和 client.credits() 则会显示你自己的用量和余额。

用作 Python SDK

from clawifi import Clawifi

client = Clawifi()  # reads CLAWIFI_API_KEY from the environment
page = client.fetch("https://example.com")
print(page["success"])

也可使用异步客户端 clawifi.AsyncClawifi。

search_content 会搜索并读取排名靠前的结果；默认返回精简内容，设置 full=True 可返回完整输出：

results = client.search_content("agent memory benchmarks", full=True)

响应会按 API 返回的内容原样传递，因此 published_at、modified_at 和 fetched_at 等字段会保持不变。

费用估算（托管 API 1.7.0 及更高版本）

quote = client.estimate("fetch", url="https://example.com")
# {"dry_run": true, "route": "POST /fetch", "estimate": {"minimum": ..., "maximum": ..., "raises": [...]},
#  "balance": ..., "would_402": ..., "would_429": ..., "binding_limit": ..., "charged": 0}
client.crawl("https://example.com", max_pages=50, dry_run=True)

estimate() 和 dry_run=True 适用于 fetch、scrape、extract、map、crawl、search_free 和 search_content。首次试运行前，客户端会在 /product/manifest 检查 API 版本；如果 API 低于 1.7.0，它会忽略 dry_run 并执行调用（同时计费），因此客户端会抛出 ClawifiDryRunUnsupportedError，且不会发送任何内容。1.7.0rc1 等预发布版本视为低于 1.7.0。

只有当 dry_run 为 True 时才会发送该参数，且只会以 JSON 布尔值 true 发送：普通调用或 dry_run=False 不会在请求正文中包含 dry_run 键；如果该值不是 bool，则会在发送任何内容前引发 TypeError。API 在不支持试运行的路由上收到任何 dry_run 键（即使是 false）都会返回 422，因此 schema_assist 会移除 dry_run=False，并拒绝 dry_run=True。

Agent 也可以使用 estimate MCP 工具执行相同操作：estimate(operation="fetch", args={"url": "https://example.com"})。

速率限制

遇到 429 时，会引发包含 retry_after（从 Retry-After 标头获取的秒数）和 limit_scope（从 details.limit_scope 获取的触发限制类型）的 ClawifiAPIError。可重试的调用会等待 Retry-After 指定的时间后再重试，最长等待 10 秒；超过该时长则立即引发错误。

MCP 工具

工具	功能
fetch	抓取单个 URL 并返回提取出的内容。提供 query 时，仅返回能回答该查询的段落。
scrape	根据来源路由抓取 URL，并返回结构化内容。提供 query 时，仅返回能回答该查询的段落。
search_free	执行免费层级的网页搜索并返回结果。
extract	从 URL 中提取结构化数据。
map_site	从种子 URL 开始，映射网站上可发现的 URL。
crawl	从种子 URL 开始异步爬取；返回用于轮询的 crawl_id。
estimate	估算执行 fetch、scrape、extract、map、crawl、search_free 或 search_content 调用的费用，不实际运行或收费（托管 API 1.7.0+）。
get_crawl	获取爬取任务的当前状态和结果。
create_job	为计费操作创建异步任务；返回用于轮询的 job_id。
get_job	获取任务的当前状态和结果。
account	获取已验证身份的账户资料和套餐信息。
credits	获取已验证身份的账户点数用量和剩余余额。
list_history	列出已验证身份账户的过往请求。
list_monitors	列出已验证身份账户配置的 Evidence Monitor 检查项。

文档

请参阅 clawifi.dev/docs，了解完整的 API 参考、MCP 工具列表和 CLI 命令参考。

License

MIT