一句话总结
OpenClaw 最新版本（#58645）正式将 TinyFish 作为内置浏览器自动化插件捆绑发布，让 AI Agent 能够安全、可靠地执行复杂的公共网页自动化任务，无需额外安装即可通过配置快速启用。
为什么需要 TinyFish？
在 AI Agent 的实际应用中，简单的 HTTP 请求（web_fetch）和 搜索引擎调用（web_search）往往无法满足需求——现代网站大量使用 JavaScript 渲染、需要用户登录态、或包含复杂的交互流程。传统方案需要开发者自行搭建浏览器集群，而 TinyFish 提供了托管式的浏览器自动化能力，直接集成到 OpenClaw 的插件架构中。
本文将详细介绍 TinyFish 的功能特性、配置方法，以及如何在实际工作流中正确使用。
—
TinyFish 核心功能解析
1. 托管式浏览器自动化
TinyFish 提供云端托管的浏览器环境，支持执行复杂的网页操作：
| 能力 | 说明 |
|:—|:—|
| JavaScript 渲染 | 完整执行页面脚本，获取动态内容 |
| 登录态保持 | 支持 Cookie 和凭证注入 |
| 多步骤交互 | 点击、表单填写、滚动等操作链 |
| 流式响应 | 通过 SSE 实时返回执行进度 |
与本地 Playwright 或 Selenium 相比，TinyFish 免去了基础设施维护成本，且与 OpenClaw 的权限系统深度集成。
2. 四层安全防护机制
TinyFish 内置了严格的安全策略，防止恶意利用：
安全配置示例（config.yaml）
tinyfish:
enabled: true
# SSRF 防护：限制内网地址访问
ssrf_guard: true
# 凭证拒绝：防止敏感信息泄露到日志
credential_rejection: true
# 仅允许特定域名（可选）
allowed_domains:
- "example.com"
- "api.service.org"
关键安全特性：
- SSRF 防护：阻止访问私有 IP 段和元数据服务
- 凭证隔离：自动过滤请求/响应中的敏感字段
- COMPLETE 终端校验：SSE 流必须正常结束，防止数据截断攻击
- SecretRef 支持：API 密钥通过引用注入，不硬编码
3. 智能技能升级路径
TinyFish 被设计为 OpenClaw 技能体系的”最终手段”，遵循明确的升级路径：
web_fetch（简单静态页面）
↓ 失败或需要 JS
web_search（获取相关链接）
↓ 需要深度交互
tinyfish_automation（复杂工作流）
↓ 需要精确控制
browser（本地浏览器直连）
这种分层设计确保资源高效利用——仅在必要时才调用成本较高的浏览器自动化。
—
快速配置指南
步骤一：启用插件
TinyFish 默认为关闭状态，需显式启用：
编辑 OpenClaw 配置文件
$ openclaw config edit
添加以下配置
plugins:
tinyfish:
enabled: true
api_key:
$secretRef: "tinyfish-api-key" # 使用 SecretRef 引用
步骤二：配置 API 凭证
添加 API 密钥到密钥管理
$ openclaw secret set tinyfish-api-key "tf_live_xxxxxxxxxxxx"
验证配置
$ openclaw plugin verify tinyfish
✓ Plugin manifest valid
✓ API connectivity check passed
✓ SSE parser test passed
步骤三：在工作流中使用
// 示例：自动化获取电商产品价格
{
"tool": "tinyfish_automation",
"params": {
"url": "https://example-shop.com/products/12345",
"workflow": [
{ "action": "waitForSelector", "selector": ".price-display" },
{ "action": "click", "selector": "#currency-selector" },
{ "action": "select", "selector": "#currency-usd" },
{ "action": "extract", "selector": ".final-price", "as": "price_usd" }
],
"timeout": 30000
}
}
—
技术实现亮点
SSE 流解析与错误处理
TinyFish 采用 Server-Sent Events (SSE) 实现实时进度反馈，解析器经过专门加固：
// 核心解析逻辑（简化示意）
async function* parseEventBlock(stream: ReadableStream) {
try {
for await (const event of stream) {
yield validateAndParse(event);
if (event.type === 'COMPLETE') {
return; // 正常终止
}
}
// 流结束但未收到 COMPLETE — 异常
throw new StreamTerminatedError('Stream ended before COMPLETE');
} catch (err) {
// 关键修复：后置 finally 中的解析错误不会掩盖主错误
try {
await cleanupParseState();
} catch (cleanupErr) {
logger.warn('Cleanup error suppressed', cleanupErr);
}
throw err;
}
}
语义化的集成类型
代码审查中，将模糊的 API_INTEGRATION 拆分为更精确的类型：
| 类型 | 用途 |
|:—|:—|
| TINYFISH_API_INTEGRATION | TinyFish 服务端的 API 调用 |
| CLIENT_SOURCE | 客户端来源标识（用于审计和限流） |
这种区分提升了日志可读性和问题排查效率。
—
实际应用场景
场景一：竞品价格监控
// 定时任务配置
{
"schedule": "0 /6 ",
"workflow": {
"tool": "tinyfish_automation",
"params": {
"url": "{{competitor_url}}",
"workflow": [
{ "action": "bypassCloudflare", "mode": "stealth" },
{ "action": "extract", "selector": "[data-testid='price']" }
]
}
}
}
场景二：政府公开数据抓取
需要处理复杂的表单提交和分页：
{
"tool": "tinyfish_automation",
"params": {
"url": "https://data.gov.cn/search",
"workflow": [
{ "action": "fill", "selector": "#keyword", "value": "{{query}}" },
{ "action": "click", "selector": "#search-btn" },
{ "action": "waitForNavigation" },
{ "action": "extractAll", "selector": ".result-item", "pagination": ".next-page" }
],
"maxPages": 5
}
}
场景三：SaaS 平台数据导出
处理需要登录的私有数据（配合 SecretRef）：
{
"tool": "tinyfish_automation",
"params": {
"url": "https://crm.internal.com/reports",
"cookies": {
$secretRef: "crm-session-cookies"
},
"workflow": [
{ "action": "click", "selector": "#export-csv" },
{ "action": "waitForDownload", "timeout": 60000 }
]
}
}
—
FAQ
Q1: TinyFish 与 OpenClaw 原有的 browser 工具有什么区别？
browser 工具需要本地安装浏览器驱动（如 Chrome + ChromeDriver），适合开发环境和对延迟敏感的场景。TinyFish 是托管服务，无需本地基础设施，更适合生产环境的弹性扩展和团队协作。两者在 OpenClaw 的技能体系中属于同一层级，可根据需求选择。
Q2: 启用 TinyFish 会产生额外费用吗？
TinyFish 作为捆绑插件本身免费，但实际调用 TinyFish 云服务时，会根据使用时长和并发量计费。建议先在 TinyFish 定价页面 了解费率，并在 OpenClaw 配置中设置 maxConcurrentSessions 和 monthlyBudgetLimit 进行成本控制。
Q3: 如何处理需要二次验证的网站？
对于 MFA/2FA 场景，TinyFish 支持两种模式：
1. 预置凭证模式：提前获取并注入长期有效的 session cookie（推荐）
2. 人工介入模式：工作流暂停，通过 webhook 通知人工完成验证后继续
具体配置参考 OpenClaw 文档 – 高级认证流程。
Q4: SSE 流解析失败如何排查？
常见原因及解决方法：
| 错误信息 | 原因 | 解决 |
|:—|:—|:—|
| Stream ended before COMPLETE | 服务端异常终止 | 检查 TinyFish 服务状态，增大 timeout |
| Malformed event data | 网络中断导致数据截断 | 启用重试机制 retry: { maxAttempts: 3 } |
| SSRF guard triggered | 目标地址被安全策略拦截 | 确认目标域名在 allowed_domains 列表中 |
Q5: 如何为 TinyFish 编写自定义工作流？
OpenClaw 提供了工作流 DSL 验证工具：
验证工作流语法
$ openclaw tinyfish validate-workflow workflow.json
本地调试（模拟执行，不消耗配额）
$ openclaw tinyfish simulate --workflow workflow.json --mock-url https://httpbin.org
详细 DSL 规范见 TinyFish 工作流文档。
—
总结与下一步
TinyFish 的集成标志着 OpenClaw 在浏览器自动化领域的重大进展——开发者现在可以在统一的插件架构中，根据任务复杂度灵活选择 web_fetch、web_search、tinyfish_automation 或 browser，实现成本与能力的最佳平衡。
建议行动：
1. 升级至 OpenClaw 最新版本（≥ #58645）
2. 在 TinyFish 官网 注册获取 API 密钥
3. 参考本文配置启用插件，从简单的价格监控任务开始尝试
4. 关注后续版本对 Playwright 脚本导入 的支持（路线图 #42100）
—
相关阅读
—
参考来源
| 来源 | 链接 |
|:—|:—|
| 本次功能更新 Commit | https://github.com/openclaw/openclaw/commit/b880118d2dd64f45d768228d9e917d10ab99f92a |
| 关联 Issue #41300 | https://github.com/openclaw/openclaw/issues/41300 |
| OpenClaw 官方文档 | https://docs.openclaw.dev |
| TinyFish 官方网站 | https://tinyfish.dev |
