Xpersona
Claim this agent
agentCLAWHUBUnverified

web-tools-guide

MANDATORY before calling web_search, web_fetch, browser, or opencli. Contains required error-handling procedures (web_search failure → must guide user to con...

OpenClaw
View on ClawHubHomepage

Rank

62

Safety

84

Downloads

5.5k

Updated

Oct 9, 2026

Version

1.0.2

Source

CLAWHUB

About

What it does, and when to use it.

Capability contract not published. No trust telemetry is available yet. 5.5K downloads reported by the source. Last updated 10/9/2026.

Avoid when

  • Contract metadata is missing or unavailable for deterministic execution.

Risk flags: missing_or_unavailable_contract, trust_data_unavailable, schema_references_missing

Public facts

Every fact links back to the source it came from.

Vendor
Clawhubvendor · observed Oct 9, 2026
Protocol compatibility
OpenClawcompatibility · observed Oct 9, 2026
Adoption signal
5.5K downloadsadoption · observed Oct 9, 2026
Latest release
1.0.2release · observed Apr 14, 2026
Handshake status
UNKNOWNsecurity

Install and run

Setup complexity: low.

clawhub skill install s178hjnqgjn4ng01wyttsvdzx583hfaw:web-tools-guide
  1. Install using `clawhub skill install s178hjnqgjn4ng01wyttsvdzx583hfaw:web-tools-guide` in an isolated environment before connecting it to live workloads.
  2. No published capability contract is available yet, so validate auth and request/response behavior manually.
  3. Review the upstream CLAWHUB listing at https://clawhub.ai/fmls/web-tools-guide before using production credentials.

Contract: missing

curl -s "https://www.xpersona.co/api/v1/agents/clawhub-fmls-web-tools-guide/snapshot"

Documentation

CLAWHUB

45,598 characters of source documentation, loaded on request.

Extracted files

5 files captured from the source.

SKILL.md

---
name: web-tools-guide
description: "MANDATORY before calling web_search, web_fetch, browser, or opencli. Contains required error-handling procedures (web_search failure → must guide user to configure API), fallback chain (opencli CLI covers 70+ sites as structured fallback before browser), and site-specific login URLs. Without reading this skill, you WILL handle failures incorrectly and miss available tools. Trigger on: 搜索/上网/查资料/打开网站/抓取网页/新闻/热点/web search/fetch/browser/opencli."
---

<!-- baseDir = /root/.openclaw/workspace/skills/web-tools-guide -->

# Web 工具策略

遵循 ReAct 范式。**四个工具不是层级关系，是分支决策**：

```
┌─ 没有 URL，需要搜索 ──────→ web_search   （关键词搜索）
│
├─ 已知 URL，静态内容 ──────→ web_fetch    （直取页面）
│
├─ 以上失败 / 不适用 ──────→ opencli      （CLI 结构化访问，70+ 站点）
│
└─ 全都不行 ───────────────→ browser      （浏览器自动化，兜底）
```

先按场景选 web_search 或 web_fetch；失败时先试 opencli，最后才上 browser。
每次切换工具告知用户原因，不要静默降级。

---

## 决策流程

```
有明确 URL？
├─ YES → 静态内容（文章/文档/API/RSS）？
│        ├─ YES → web_fetch
│        │        失败（空白/403/CAPTCHA）？→ opencli → browser
│        └─ NO（需要 JS/登录/交互/截图）→ opencli → browser
└─ NO  → web_search
         ├─ 成功 → 对结果 URL 按上述逻辑选 fetch/opencli/browser
         ├─ 失败（API 错误）→ 引导配置（见"web_search 失败处理"）
         └─ 无结果/不适用 → opencli → browser
```

---

## web_search

**何时用**：没有明确 URL，需要搜索信息（新闻、热点、查资料、比较信息）。

**怎么用**：直接调用 `web_search`，传入搜索关键词。

**结果处理**：返回的 URL 按决策流程选 `web_fetch`、`opencli` 或 `browser` 深入获取。

**失败时**：见下方"web_search 失败处理"。

---

## web_fetch

**何时用**：已知 URL，页面为静态内容——新闻文章、博客、技术文档、API 端点、RSS 源。

**怎么用**：直接调用 `web_fetch`，传入 URL。

**失败信号**：返回空白页、403、CAPTCHA、骨架 HTML → 尝试 `opencli`，仍不行再升级到 `browser`。

---

## opencli（Fallback，优先于 browser）

**何时用**：web_search / web_fetch 失败或不适用时，先试 opencli 再考虑 browser。覆盖 70+ 主流网站，秒级返回结构化数据。

**首次使用前**：如果执行 `opencli` 提示 command not found，需要先运行安装脚本（幂等，可重复运行）：
```bash
bash {baseDir}/scripts/setup-opencli.sh
```
该脚本会自动完成：安装 opencli CLI → 编译 Browser Bridge 插件 → 重启浏览器加载插件。

**渐进式发现（不需要记命令）**：
```bash
opencli --help                    # 有没有这个站？
opencli <site> --help             # 这个站能做什么？
opencli <site> <command> --help   # 这个命令怎么用？
```

**详细用法**：`read {baseDir}/references/opencli-guide.md`

**失败时**：告知用户 opencli 失败原因，降级到 browser。

---

## browser（最后手段）

这是最重量级的工具，也是当前问题最多的场景。以下是详细操作指引。

### 何时用

- **JS 渲染页面**：SPA、动态加载内容（微博 feed、知乎回答、小红书瀑布流）
- **需要登录态**：登录后才可见的内容、管理后台
- **页面交互**：点击按钮、填写表单、翻页、滚动加载更多
- **截图需求**：需要页面视觉信息
- **其他工具全部失败的兜底**

### 操作流程

**信息获取（只读）：**
1. 导航到目标 URL
2. 等待关键元素出现（不要用固定时间等待）
3. 提取所需内容（文本、链接、图片等）
4. 返回结果给用户

**登录操作：**
1. 查找登录页 URL → `read {baseDir}/references/well-known-sites.json`
2. **告知用户即将执行登录操作，获取确认**
3. 导航到登录页
4. 填写凭证（用户提供）或提示用户扫码
5. 等待登录成功，确认后继续后续操作

**页面交互：**
1. 导航到目标页面
2. 使用 CSS 选择器定位元素（辅以文本内容匹配）
3. 执行交互：点击、输入、选择、滚动
4. 等待响应/页面变化
5. 提取结果或截图

### 关键注意事项

- **登录操作必须获得用户授权** — 任何涉及账号登录的操作前，先告知用户并等待确认
- **敏感操作必须二次确认** — 发帖、删除、支付等不可逆操作
- **优先 CSS 选择器** — 比 XPath 更稳定，辅以文本匹配
- **智能等待** — 等待目标元素出现，而非 `sleep(3)` 式固定等待
- **CAPTCHA/验证码** — 无法自动处理时告知用户需手动介入
- **页面加载超时** — 设置合理超时，失败时告知用户并建议重试
- **多步操作保持状态** — 登录

_meta.json

{
  "ownerId": "kn7ekx2kqw6f5krp4yb0qfex5n831k1k",
  "slug": "web-tools-guide",
  "version": "1.0.2",
  "publishedAt": 1776138900895
}

references/opencli-guide.md

# opencli 使用指引

`opencli` 是一个命令行工具，将 70+ 主流网站封装为 CLI 命令。相比 browser 自动化，它更快（秒级）、更精准（结构化数据）、更稳定（不依赖 DOM 变化）。

## 核心理念

不需要记住任何命令。通过 `--help` 逐层探索即可：

```bash
opencli --help                         # 我能操作哪些网站？
opencli <site> --help                  # 这个网站有哪些操作？
opencli <site> <command> --help        # 这个操作怎么用？
```

## 典型场景映射

以下是常见用户需求到 opencli 命令的映射示例（不完整，遇到新场景先 `--help` 探索）：

| 用户需求 | opencli 命令 |
|---------|-------------|
| 看微博热搜 | `opencli weibo hot` |
| 搜索小红书笔记 | `opencli xiaohongshu search <关键词>` |
| 看知乎热榜 | `opencli zhihu hot` |
| B站热门视频 | `opencli bilibili hot` |
| 搜索 Twitter | `opencli twitter search <关键词>` |
| 看 HackerNews 头条 | `opencli hackernews top` |
| GitHub trending | `opencli gh trending` |
| 获取笔记详情/评论 | `opencli xiaohongshu note <note-id>` |
| 获取 YouTube 字幕 | `opencli youtube transcript <video-id>` |
| 读取任意网页为 Markdown | `opencli web read --url <URL>` |

## 输出格式

所有命令支持 `-f` / `--format` 选项：

| 格式 | 用途 |
|------|------|
| `table` | 默认，终端可读 |
| `json` | 程序化处理、需要完整结构化数据 |
| `yaml` | 人类可读的结构化数据 |
| `md` | Markdown 格式 |
| `csv` | 表格导出 |
| `plain` | 纯文本 |

推荐：给用户展示时用 `table` 或 `md`，需要后续处理时用 `-f json`。

## 常见参数

- `--limit <N>`：限制返回条数
- `-f <format>`：输出格式
- `-v` / `--verbose`：调试输出

## 覆盖的网站类别

以下是 opencli 覆盖的主要网站类别（可通过 `opencli --help` 查看完整列表）：

- **中文社交**：微博、小红书、知乎、豆瓣、即刻、V2EX、贴吧
- **中文视频**：B站、抖音
- **中文资讯**：36氪、雪球、什么值得买
- **阅读**：微信读书、知识星球
- **国际社交**：Twitter/X、Reddit、LinkedIn、Instagram、Facebook、Bluesky
- **国际视频**：YouTube、TikTok
- **国际资讯**：HackerNews、ProductHunt、Medium、Substack、BBC、Bloomberg、Reuters
- **开发者**：GitHub (gh)、StackOverflow、Dev.to、ArXiv、HuggingFace
- **AI 工具**：ChatGPT、Gemini、Grok、Doubao
- **购物**：JD、Amazon、Coupang、Steam
- **播客**：Apple Podcasts、小宇宙、Spotify
- **通用**：`opencli web read` — 任意网页转 Markdown

## 写操作注意

部分命令支持写操作（发帖、关注、点赞等），执行前必须告知用户并获取确认：

- `opencli twitter post <text>` — 发推文
- `opencli xiaohongshu publish <content>` — 发小红书笔记
- `opencli twitter follow/block/like` — 关注/拉黑/点赞
- 其他涉及修改数据的操作

## 故障排查

如果 opencli 命令执行失败：

1. **检查 daemon 状态**：`opencli doctor` — 诊断浏览器桥接连接
2. **查看详细错误**：加 `-v` 参数获取调试信息
3. **降级处理**：告知用户 opencli 失败原因，降级到 web_search/web_fetch/browser

references/web-search-config.md

# Web Search API 配置流程

当 `web_search` 返回错误后，Agent 读取此文件并按步骤执行。

---

## Step 1: 初始引导（检测到未配置状态）

**⚠️ 关键约束**：停止 fallback 链。将下方引用块（`>` 开头的部分）**原样输出**给用户。不要重新组织、改写表格结构、或编造额外信息（如"无需绑定信用卡"）。直接复制粘贴：

> 搜索功能需要配置 API Key 才能使用。
>
> **推荐方案**（二选一）：
> - **Tavily**: https://app.tavily.com — 国际内容效果好，每月 1000 免费积分
> - **Kimi**: https://platform.moonshot.cn — 中文内容效果佳
>
> **计费对比**：
>
> | 对比维度 | Tavily | Kimi |
> |---------|--------|------|
> | **免费额度** | 每月 1000 次基础搜索免费 | 无免费额度，每次≈0.03元 |
> | **计费模式** | 失败不收费 | 固定0.03元/次+Token费 |
>
> 请提供您的 API Key（格式：`tvly-xxx...` 或 `sk-xxx...`），或回复"暂不配置"使用备选方案。

**如果用户选择"暂不配置"：**
1. 回到 SKILL.md 的降级决策流程（使用 web_fetch 配合搜索引擎 URL，或 browser）
2. 告知用户："已切换到备选方案。如需更好体验，可随时配置 API Key。"

---

## Step 2: 接收 API Key 并分析

**⚠️ 收到用户的 Key 后，必须先执行本步骤。禁止跳过分析和确认直接进入 Step 3 配置。**

**当用户提供 API Key 时：**

1. **通过前缀自动检测提供商**：
   - `tvly-*` → Tavily
   - `sk-*` → Kimi
   - 未知前缀 → 询问用户使用哪个提供商

2. **分析并告知用户**（先不配置）：
   - 如果 `tvly-*`："检测到您提供的是 **Tavily** 的 API Key ✅"
   - 如果 `sk-*`："检测到您提供的是 **Kimi** 的 API Key ✅"

3. **在操作前请求确认**（原样输出以下内容）：
   > 接下来我将进行以下操作：
   > 1. 配置 API Key 到 openclaw.json
   > 2. 重启 gateway 以应用配置
   >
   > ⚠️ **重要提示**：
   > - 稍待片刻，请主动发送消息（如"继续"）唤醒会话
   > - 我将继续为您执行搜索
   >
   > 请回复"确认"开始配置，或回复"取消"放弃配置。

4. **等待用户确认** — 用户回复前不要继续操作

---

## Step 3: 执行配置（用户确认后）

**仅在用户确认后执行（如"确认"、"好"、"开始"）：**

1. **配置 openclaw.json**：
   ```bash
   # Tavily（tvly-* 前缀）
   openclaw config set plugins.entries.tavily.enabled true
   openclaw config set plugins.entries.tavily.config.webSearch.apiKey <user-provided-key>

   # Kimi（sk-* 前缀）
   openclaw config set plugins.entries.kimi.enabled true
   openclaw config set plugins.entries.kimi.config.webSearch.apiKey <user-provided-key>
   ```

2. **告知用户配置完成**：
   > ✅ API Key 已保存！

---

## Step 4: 重启 Gateway

1. **执行重启**：
   ```bash
   # 重启 gateway 以应用配置变更
   openclaw restart gateway
   # 或使用 Docker
   docker restart openclaw-gateway
   # 或查找并重启 gateway 进程
   pkill -f "openclaw-gateway" || pkill -f "gateway"
   ```

2. **告知用户等待并唤醒会话**：
   > 正在重启 gateway 以应用配置...
   >
   > ⏳ 稍待片刻，请发送任意消息（如"继续"）唤醒会话，我将继续为您搜索。

---

## Step 5: 等待用户唤醒会话

**停止并等待用户消息。**

当用户发送任意消息（如"继续"、"已重启"、"好了"、"在吗"）后：

1. **验证 API Key 是否配置成功**：
   ```bash
   # 检查 Tavily
   openclaw config get plugins.entries.tavily.config.webSearch.apiKey
   # 检查 Kimi
   openclaw config get plugins.entries.kimi.config.webSearch.apiKey
   ```

2. 如果已配置 → 执行用户原始搜索请求（使用 `web_search` 工具）
3. 如果未配置 → 重新进入配置流程

---

## 快速参考

| 提供商 | 网站 | Key 前缀 | 中文支持 |
|--------|------|---------|---------|
| Tavily | https://app.tavily.com | `tvly-` | 良好 |
| Kimi/Moonshot | https://platform.moonshot.cn | `sk-` | 优秀 |

**自动检测规则**：系统通过 Key 前缀自动识别提供商。

references/well-known-sites.json

{
  "_description": "常用网站地址索引 — 供 Agent 快速定位目标地址，按类别组织。key 为语义化标识，value 包含 url / description / category。",

  "search.baidu": {
    "url": "https://www.baidu.com/s?wd={query}",
    "description": "百度搜索（中文首选），{query} 替换为搜索关键词",
    "category": "search_engine"
  },
  "search.google": {
    "url": "https://www.google.com/search?q={query}",
    "description": "Google 搜索（英文/国际首选），{query} 替换为搜索关键词",
    "category": "search_engine"
  },
  "search.bing": {
    "url": "https://www.bing.com/search?q={query}",
    "description": "Bing 搜索（中英文均可），{query} 替换为搜索关键词",
    "category": "search_engine"
  },
  "search.duckduckgo": {
    "url": "https://duckduckgo.com/?q={query}",
    "description": "DuckDuckGo 搜索（隐私友好），{query} 替换为搜索关键词",
    "category": "search_engine"
  },
  "search.sogou": {
    "url": "https://www.sogou.com/web?query={query}",
    "description": "搜狗搜索，{query} 替换为搜索关键词",
    "category": "search_engine"
  },

  "social.weibo.login": {
    "url": "https://passport.weibo.com/sso/signin?entry=miniblog&source=miniblog&disp=popup&url=https%3A%2F%2Fweibo.com%2Fnewlogin%3Ftabtype%3Dweibo%26gid%3D102803%26openLoginLayer%3D0%26url%3Dhttps%3A%2F%2Fweibo.com%2F&from=weibopro",
    "description": "微博登录页面（SSO 单点登录入口）,注意在此页面截图时不要使用全页截图，fullpage:false",
    "category": "social_platform"
  },
  "social.weibo.home": {
    "url": "https://weibo.com/",
    "description": "微博首页",
    "category": "social_platform"
  },
  "social.weibo.hot": {
    "url": "https://s.weibo.com/top/summary",
    "description": "微博热搜榜",
    "category": "social_platform"
  },
  "social.zhihu.home": {
    "url": "https://www.zhihu.com/",
    "description": "知乎首页",
    "category": "social_platform"
  },
  "social.zhihu.hot": {
    "url": "https://www.zhihu.com/hot",
    "description": "知乎热榜",
    "category": "social_platform"
  },
  "social.zhihu.search": {
    "url": "https://www.zhihu.com/search?type=content&q={query}",
    "description": "知乎搜索，{query} 替换为搜索关键词",
    "category": "social_platform"
  },
  "social.douyin.home": {
    "url": "https://www.douyin.com/",
    "description": "抖音首页（Web 版）",
    "category": "social_platform"
  },
  "social.xiaohongshu.home": {
    "url": "https://www.xiaohongshu.com/",
    "description": "小红书首页（Web 版）",
    "category": "social_platform"
  },
  "social.twitter.home": {
    "url": "https://x.com/",
    "description": "X (Twitter) 首页",
    "category": "social_platform"
  },

  "video.bilibili.home": {
    "url": "https://www.bilibili.com/",
    "description": "哔哩哔哩首页",
    "category": "video_platform"
  },
  "video.bilibili.hot": {
    "url": "https://www.bilibili.com/v/popular/rank/all",
    "description": "哔哩哔哩全站排行榜",
    "category": "video_platform"
  },
  "video.bilibili.search": {
    "url": "https://search.bilibili.com/all?keyword={query}",
    "description": "哔哩哔哩搜索，{query} 替换为搜索关键词",
    "category": "video_platform"
  },
  "video.youtube.home": {
    "url": "https://www.youtube.com/",
    "description": "YouTube 首页",
    "category": "video_platfor

Related agents

Same protocol, similar job.

Github ReposUpdated 6mo agoRank 70

activepieces

AI Agents & MCPs & AI Workflow Automation • (~400 MCP servers for AI agents) • AI Automation / AI Agent with MCPs • AI Workflows & AI Agents • MCPs for AI Agents

OPENCLAW
Github ReposUpdated 6mo agoRank 70

cherry-studio

AI productivity studio with smart chat, autonomous agents, and 300+ assistants.

MCPOPENCLAW
Github ReposUpdated 6mo agoRank 70

AionUi

Free, local, open-source 24/7 Cowork app and OpenClaw for Gemini CLI, Claude Code, Codex, OpenCode, Qwen Code, Goose CLI, Auggie, and more | 🌟 Star if you like it!

MCPOPENCLAW
Github ReposUpdated 7mo agoRank 70

CopilotKit

The Frontend for Agents & Generative UI. React + Angular

OPENCLAW

Machine-readable data

The same record, as JSON, for agents and crawlers.

{
  "facts": [
    {
      "factKey": "vendor",
      "category": "vendor",
      "label": "Vendor",
      "value": "Clawhub",
      "href": "https://clawhub.ai/fmls/skills/web-tools-guide",
      "sourceUrl": "https://clawhub.ai/fmls/skills/web-tools-guide",
      "sourceType": "profile",
      "confidence": "medium",
      "observedAt": "2026-10-09T03:59:13.030Z",
      "isPublic": true
    },
    {
      "factKey": "protocols",
      "category": "compatibility",
      "label": "Protocol compatibility",
      "value": "OpenClaw",
      "href": "https://www.xpersona.co/api/v1/agents/clawhub-fmls-web-tools-guide/contract",
      "sourceUrl": "https://www.xpersona.co/api/v1/agents/clawhub-fmls-web-tools-guide/contract",
      "sourceType": "contract",
      "confidence": "medium",
      "observedAt": "2026-10-09T03:59:13.030Z",
      "isPublic": true
    },
    {
      "factKey": "traction",
      "category": "adoption",
      "label": "Adoption signal",
      "value": "5.5K downloads",
      "href": "https://clawhub.ai/fmls/web-tools-guide",
      "sourceUrl": "https://clawhub.ai/fmls/web-tools-guide",
      "sourceType": "profile",
      "confidence": "medium",
      "observedAt": "2026-10-09T03:59:13.030Z",
      "isPublic": true
    },
    {
      "factKey": "latest_release",
      "category": "release",
      "label": "Latest release",
      "value": "1.0.2",
      "href": "https://clawhub.ai/fmls/web-tools-guide",
      "sourceUrl": "https://clawhub.ai/fmls/web-tools-guide",
      "sourceType": "release",
      "confidence": "medium",
      "observedAt": "2026-04-14T03:55:00.895Z",
      "isPublic": true
    },
    {
      "factKey": "handshake_status",
      "category": "security",
      "label": "Handshake status",
      "value": "UNKNOWN",
      "href": "https://www.xpersona.co/api/v1/agents/clawhub-fmls-web-tools-guide/trust",
      "sourceUrl": "https://www.xpersona.co/api/v1/agents/clawhub-fmls-web-tools-guide/trust",
      "sourceType": "trust",
      "confidence": "medium",
      "observedAt": null,
      "isPublic": true
    }
  ],
  "events": [
    {
      "eventType": "release",
      "title": "Release 1.0.2",
      "description": "- Added OpenCLI integration as a fallback tool (covering 70+ sites) between web_fetch and browser, with setup script and user guidance. - Updated decision process: tools are now parallel branches—not a strict escalation—to choose the most efficient path based on scenario. - Enhanced error handling: failures in web_search or web_fetch now require explicit configuration guidance and OpenCLI fallback before using the browser. - Expanded documentation: included references to opencli usage guide and setup instructions for smoother onboarding. - Modified skill to be MANDATORY before using web_search, web_fetch, browser, or opencli, emphasizing correct fallback and error procedures.",
      "href": "https://clawhub.ai/fmls/web-tools-guide",
      "sourceUrl": "https://clawhub.ai/fmls/web-tools-guide",
      "sourceType": "release",
      "confidence": "medium",
      "observedAt": "2026-04-14T03:55:00.895Z",
      "isPublic": true
    }
  ]
}

Record generated Oct 9, 2026.

Sponsored

Ads related to web-tools-guide and adjacent AI workflows.