diff --git a/sources/platform/integrations/ai/openclaw.md b/sources/platform/integrations/ai/openclaw.md new file mode 100644 index 0000000000..46857bd402 --- /dev/null +++ b/sources/platform/integrations/ai/openclaw.md @@ -0,0 +1,191 @@ +--- +title: OpenClaw integration +sidebar_label: OpenClaw +description: Learn how to integrate Apify with OpenClaw to give your AI agents access to web scraping, data extraction, and automation using pre-built Actors. +sidebar_position: 14 +slug: /integrations/openclaw +toc_min_heading_level: 2 +--- + +import ThirdPartyDisclaimer from '@site/sources/_partials/_third-party-integration.mdx'; + +[OpenClaw](https://openclaw.io) is an open-source AI agent orchestration platform that enables you to build, deploy, and manage autonomous AI agents. The Apify plugin for OpenClaw gives your agents access to thousands of pre-built Actors for web scraping, data extraction, and automation through a single `apify` tool. + +For more details about OpenClaw, refer to the [official documentation](https://docs.openclaw.ai/). + + + +## Quick start + +Install the plugin, run the setup wizard, and restart the gateway: + +```bash +openclaw plugins install @apify/apify-openclaw-plugin +openclaw apify setup +openclaw gateway restart +``` + +Watch a quick demo of the Apify plugin for OpenClaw: + + + +## Prerequisites + +Before integrating Apify with OpenClaw, you'll need: + +- _An Apify account_ - If you don't have one, [sign up here](https://console.apify.com/sign-up). +- _Apify API token_ - Get your token from the **API & Integrations** section in [Apify Console](https://console.apify.com/settings/integrations). +- _OpenClaw_ - Version 2026.1.0 or later. Install from the [OpenClaw website](https://openclaw.io/). +- _Node.js 22+_ - Required to run the plugin. Install from [nodejs.org](https://nodejs.org/en/download/). + +## Set up the Apify plugin + +Setting up the plugin involves three steps: + +1. [Install the plugin](#install-the-plugin) +1. [Configure your API token](#configure-with-interactive-setup-recommended) (interactively or [manually](#configure-manually)) +1. [Verify the setup](#verify-the-setup) + +### Install the plugin + +Use the OpenClaw CLI to install the Apify plugin from the plugin registry: + +```bash +openclaw plugins install @apify/apify-openclaw-plugin +``` + +This downloads the plugin and registers it with your OpenClaw installation. + +### Configure with interactive setup (recommended) + +Run the setup wizard to configure your API key: + +```bash +openclaw apify setup +``` + +The wizard prompts you for your Apify API token, verifies the connection, and writes the configuration to your OpenClaw config file. You can find your token in the **API & Integrations** section of [Apify Console](https://console.apify.com/settings/integrations). + +After setup, restart the gateway to load the plugin: + +```bash +openclaw gateway restart +``` + +### Configure manually + +If you prefer to skip the wizard, add the plugin configuration directly to your `~/.openclaw/config.json`: + +```json +{ + "plugins": { + "entries": { + "apify": { + "enabled": true, + "config": { + "apiKey": "apify_api_..." + } + } + } + }, + "tools": { + "alsoAllow": ["apify"] + } +} +``` + +Then restart the gateway: + +```bash +openclaw gateway restart +``` + +:::caution Tool allowlisting required + +The `apify` tool must be listed in `tools.alsoAllow` in your config, or you can use `"group:plugins"` to allow all plugin tools. Without this, the tool won't be available to your agents. + +::: + +### Verify the setup + +Check your configuration: + +```bash +openclaw apify status +``` + +## Apify tool overview + +The plugin registers a single `apify` tool with three actions: + +| Action | Purpose | +| ------ | ------- | +| `discover` | Search Apify Store for Actors by keyword, or fetch an Actor's input schema | +| `start` | Run an Actor asynchronously and get a `runId` back | +| `collect` | Retrieve results from completed Actor runs | + +### Two-phase async pattern + +The tool uses an asynchronous workflow. Your agent starts an Actor run and gets a `runId` immediately, then collects results later when the run completes. This lets agents do other work while Actors are running. + +```text +discover (search) -> discover (schema) -> start -> collect +``` + +### Batch multiple targets + +Most Actors accept arrays in their input (for example, `startUrls`, `queries`, `usernames`). As a best practice, batch multiple targets into a single run - one run with 5 URLs is cheaper and faster than 5 separate runs. + +## What you can do + +Once the plugin is set up, your OpenClaw agents can: + +- _Search for scrapers_ - Ask your agent to find an Actor for any platform (for example, "find me an Instagram scraper") and it discovers the right one from [Apify Store](https://apify.com/store). +- _Scrape any website_ - Your agent can extract data from Google Search, Instagram, TikTok, YouTube, Google Maps, e-commerce sites, and more. +- _Batch multiple targets_ - Scrape several URLs, profiles, or search queries in a single Actor run. One run with 5 targets is cheaper and faster than 5 separate runs. +- _Run multiple Actors in parallel_ - Start scrapers for different platforms at the same time and collect all results together. +- _Delegate to sub-agents_ - For complex research tasks, your agent can delegate scraping work to a sub-agent, keeping the parent agent's context focused on higher-level reasoning. + +:::note Actor runs may take some time + +Actor execution time varies depending on the task complexity. Check Actor run status in [Apify Console](https://console.apify.com/) if a run takes longer than expected. + +::: + +## Configuration options + +| Option | Type | Default | Description | +| ------ | ---- | ------- | ----------- | +| `apiKey` | string | `APIFY_API_KEY` env var | Your Apify API token | +| `baseUrl` | string | `https://api.apify.com` | Apify API base URL | +| `maxResults` | number | `20` | Maximum items to return per dataset (1-1000) | +| `enabledTools` | string[] | `[]` (all enabled) | Restrict which tool actions are available | + +## Troubleshooting + +### Authentication errors + +- _Check your API token_ - Verify your Apify API token is correct by running `openclaw apify status`. You can find your token in the **API & Integrations** section of [Apify Console](https://console.apify.com/settings/integrations). +- _Environment variable_ - If you prefer not to store the key in config, set the `APIFY_API_KEY` environment variable instead. + +### Tool not available to agents + +- _Check allowlisting_ - Ensure `"apify"` is in the `tools.alsoAllow` array in your OpenClaw config, or use `"group:plugins"` to allow all plugin tools. +- _Restart the gateway_ - Config changes don't take effect until you run `openclaw gateway restart`. + +### Actor run failures + +- _Check run logs_ - If an Actor run fails, check the logs in [Apify Console](https://console.apify.com/) for details. +- _Verify input schema_ - Use `action: "discover"` with the `actorId` to check what input parameters the Actor expects. + +### Report an issue + +If you encounter a bug or have a feature request, [open an issue](https://github.com/apify/apify-openclaw-plugin/issues) on the plugin's GitHub repository. + +## Resources + +- [OpenClaw documentation](https://docs.openclaw.ai/) - Official OpenClaw docs +- [Apify Actors documentation](https://docs.apify.com/platform/actors) - Learn about Apify Actors +- [Apify Store](https://apify.com/store) - Browse pre-built Actors +- [Apify API reference](https://docs.apify.com/api/v2) - Full API documentation +- [Apify OpenClaw plugin on GitHub](https://github.com/apify/apify-openclaw-plugin) - Source code and issue tracker