openclaw/docs/tools/tinyfish.md at b880118d2dd64f45d768228d9e917d10ab99f92a

mirror of https://github.com/openclaw/openclaw.git synced 2026-04-03 21:31:26 +00:00

Files

Simantak Dabhade b880118d2d feat: add TinyFish as bundled browser automation plugin (#58645 )

* feat: add TinyFish as bundled browser automation plugin

Add a default-off bundled `tinyfish` plugin with one tool
(`tinyfish_automation`) for hosted browser automation of complex public
web workflows. Follows the existing plugin architecture pattern.

- Plugin entry, manifest with contracts, config schema, SecretRef support
- SSE stream parser with COMPLETE-terminal, SSRF guards, credential rejection
- Bundled skill with escalation guidance (web_fetch -> web_search -> tinyfish -> browser)
- Docs page, labeler rule, glossary entry, changelog entry
- 21 tests covering request serialization, auth, security, streaming, and error paths

Closes #41300

* plugins: address review feedback and regenerate baselines

- Split API_INTEGRATION into TINYFISH_API_INTEGRATION and CLIENT_SOURCE
  for semantic clarity (Greptile P2)
- Wrap post-finally parseEventBlock in try/catch so trailing malformed
  data does not mask "stream ended before COMPLETE" error (Greptile P2)
- Regenerate config-baseline and plugin-sdk-api-baseline for new plugin

---------

Co-authored-by: Simantak Dabhade <simantak@mac.local>

2026-04-02 01:46:05 -04:00

4.0 KiB

Raw Blame History

summary, read_when, title

summary

read_when

title

TinyFish plugin: hosted browser automation for public multi-step workflows

You want hosted browser automation from OpenClaw

You are configuring or developing the TinyFish plugin

TinyFish

TinyFish adds a hosted browser automation tool to OpenClaw for complex public web workflows: multi-step navigation, forms, JS-heavy pages, geo-aware proxy routing, and structured extraction.

Quick mental model:

Enable the bundled plugin
Configure plugins.entries.tinyfish.config
Use the tinyfish_automation tool for public browser workflows
Get back run_id, status, result, and a live streaming_url when TinyFish provides one

Where it runs

The TinyFish plugin runs inside the Gateway process, but the browser automation it triggers runs on TinyFish's hosted infrastructure.

If you use a remote Gateway, enable and configure the plugin on the machine running the Gateway.

Enable

TinyFish ships as a bundled plugin and is disabled by default.

{
  plugins: {
    entries: {
      tinyfish: {
        enabled: true,
      },
    },
  },
}

Restart the Gateway after enabling it.

Config

Set config under plugins.entries.tinyfish.config:

{
  plugins: {
    entries: {
      tinyfish: {
        enabled: true,
        config: {
          apiKey: "tf_live_...",
          // Optional; defaults to https://agent.tinyfish.ai
          baseUrl: "https://agent.tinyfish.ai",
        },
      },
    },
  },
}

You can also supply the API key through TINYFISH_API_KEY.

Tool

The plugin registers one tool:

tinyfish_automation

Run hosted browser automation against a public website.

Parameter	Required	Description
`url`	Yes	Target public website URL
`goal`	Yes	Natural-language description of what to accomplish
`browser_profile`	No	`lite` (default) or `stealth` (anti-bot mode)
`proxy_config`	No	Object with `enabled` (boolean) and `country_code` (2-letter ISO)

Return shape:

Field	Description
`run_id`	TinyFish run identifier
`status`	`COMPLETED`, `FAILED`, or other terminal status
`result`	Structured extraction result (when successful)
`error`	Error details (when failed)
`streaming_url`	Live browser session URL (when TinyFish provides one)
`help_url`	Link to relevant TinyFish docs (on error)
`help_message`	Human-readable help hint (on error)

Good fits

Use TinyFish when the built-in browser is not the best surface:

Complex public forms with multiple steps
JS-heavy pages that need real browser rendering
Multi-step workflows with many clicks and navigation
Region-sensitive browsing that benefits from proxy routing
Structured extraction from live browser sessions

Prefer other tools when:

A simple HTTP fetch or search is enough (web_fetch, web_search)
You want direct local or remote CDP control with the built-in Browser
You need persistent authenticated browser sessions

Limitations

TinyFish targets public web workflows; persistent authenticated sessions are out of scope
CAPTCHA solving is not supported
Browser session state does not persist across runs
Batch and parallel runs are out of scope for the initial bundled plugin

Example prompts

"Open example.com/pricing and extract every plan name and price as JSON."
"Go to example.com/contact, fill the public inquiry form, and summarize what happened."
"Visit example.com/search, switch the region to Canada, and extract the top five public listings."

4.0 KiB Raw Blame History