@iflow-ai/iflow-plugin

iFlow Search (心流搜索) plugin for OpenClaw.

Three agent tools backed by iFlow's /api/search/* endpoints:

| Tool | Purpose | |---|---| | iflow_web_search | Public web search with structured results (title / url / snippet / position / date). | | iflow_image_search | Image search with source-page attribution. | | iflow_web_fetch | Read the clean content of a single web page. |

The plugin also registers iflow as a web_search provider so users can route the managed web_search tool through iFlow with one config line — this is best-effort and activates only if the running OpenClaw exposes the provider-registration API; otherwise the plugin runs in tools-only mode.

Install

openclaw plugins install @iflow-ai/iflow-plugin
openclaw gateway restart

Or from a local checkout (during development):

git clone <repo> ~/.openclaw/extensions/iflow-plugin
cd ~/.openclaw/extensions/iflow-plugin
npm install --omit=dev
openclaw gateway restart

Configuration

1. API key

Get one from the iFlow Open Platform.

Either set the env var:

export IFLOW_API_KEY=sk-...

Or put it in ~/.openclaw/openclaw.json:

{
  plugins: {
    entries: {
      iflow: {
        enabled: true,
        config: {
          webSearch: {
            apiKey: "sk-...",     // sensitive; can also be a SecretRef object
            baseUrl: "https://platform.iflow.cn",  // optional override
            timeoutSeconds: 30,    // optional, default 30
            cacheTtlMinutes: 15    // optional, default 15; set 0 to disable
          }
        }
      }
    }
  }
}

2. Route managed web_search through iFlow (optional)

{
  tools: {
    web: {
      search: {
        provider: "iflow"
      }
    }
  }
}

If your OpenClaw runtime does not support third-party web_search providers, this line has no effect — the explicit tools below still work.

Tools

iflow_web_search

| Param | Type | Required | Default | Notes | |---|---|---|---|---| | query | string | yes | — | Sent as iFlow keywords | | count | number | no | 10 | Clamped to [1, 10]. Sent as iFlow num |

Returns:

{
  "query": "...",
  "provider": "iflow",
  "count": 3,
  "tookMs": 1383,
  "results": [
    { "title": "...", "url": "...", "snippet": "...", "position": 1, "date": null }
  ]
}

iflow_image_search

| Param | Type | Required | Default | Notes | |---|---|---|---|---| | query | string | yes | — | Sent as iFlow keywords | | count | number | no | 10 | Clamped to [1, 20]. Sent as iFlow num |

Returns:

{
  "query": "...",
  "provider": "iflow",
  "count": 3,
  "tookMs": 1715,
  "images": [
    { "url": "...jpg", "title": "...", "sourceUrl": "..." }
  ]
}

iflow_web_fetch

| Param | Type | Required | Notes | |---|---|---|---| | url | string | yes | Must be an http(s) URL |

Returns:

{
  "title": "...",
  "url": "...",
  "content": "...",
  "fromCache": true,
  "provider": "iflow",
  "tookMs": 335
}

Local development

npm install
npm run typecheck     # tsc --noEmit
npm test              # vitest (uses mocked fetch, no live API calls)

# Optional: live probe of all three endpoints.
# Reads IFLOW_API_KEY from the env. Does NOT log the key.
IFLOW_API_KEY=sk-... npm run smoke
IFLOW_API_KEY=sk-... npm run smoke web     # web only
IFLOW_API_KEY=sk-... npm run smoke image
IFLOW_API_KEY=sk-... npm run smoke fetch

To exercise the plugin inside a real OpenClaw gateway:

# 1. Pack and install from the local build
npm pack
openclaw plugins install npm-pack:./iflow-ai-iflow-plugin-0.1.0.tgz
openclaw gateway restart

# 2. Verify what was registered
openclaw plugins inspect iflow --runtime --json

Troubleshooting

| Symptom | Likely cause | Fix | |---|---|---| | Every call returns missing_api_key | Env var not loaded by the gateway | Restart gateway after exporting IFLOW_API_KEY, or put the key in openclaw.json | | api_error with status: 401 | Wrong / revoked key | Rotate the key on the iFlow platform | | api_error with status: 403 | Account not entitled to this endpoint | Check the iFlow plan / contact iFlow support | | api_error with status: 429 | Rate limit | Lower request rate; the plugin caches identical queries for cacheTtlMinutes | | network_timeout | Slow upstream / cold cache | Increase timeoutSeconds; retry | | api_business_error with code 4xxx | iFlow returned success: false | Inspect message / code in the error payload | | Results have a url field on iFlow but show as empty | iFlow renamed link → url (or similar) | Update src/normalize.ts mapping; tests in src/__tests__/normalize.test.ts show where | | Plugin loads but web_search doesn't route through iFlow | OpenClaw runtime doesn't expose registerWebSearchProvider (info log will say so) | Use the explicit iflow_web_search tool instead, or upgrade OpenClaw |

Compatibility

• peerDependency: openclaw >= 2025.0.0 (optional)
• Tools mode (3 explicit tools): always on.
• Provider mode (managed web_search routing): activates only when the runtime exposes api.registerWebSearchProvider AND the SDK subpath openclaw/plugin-sdk/provider-web-search-config-contract is importable. Failure is logged at info level; the plugin keeps working in tools mode.

Acknowledgements

This plugin includes an OpenClaw-specific skill definition under skills/iflow-search/SKILL.md. It is adapted from the official iFlow skill catalog, but uses OpenClaw tool names and normalized parameters / return fields instead of the upstream shell-script interface.

Official iFlow skill reference: https://github.com/iflow-ai/iflow-skills/tree/main/skills/iflow-search

Attribution headers

The plugin sends non-sensitive attribution headers on every outbound request to the iFlow API so iFlow can identify requests coming from the OpenClaw integration:

• IFlow-Source: openclaw
• IFlow-Integration: @iflow-ai/iflow-plugin
• IFlow-Integration-Version: <plugin version>

No API key or user query content is added to these headers.

License

MIT