Diffbot tools and skills for OpenClaw: Knowledge Graph search (organizations, people, news, places, deals, DQL), web search, URL extraction, entity resolution, and site crawling.
Install
openclaw plugins install clawhub:@diffbot/openclaw-pluginDiffbot for OpenClaw
Structured web knowledge for OpenClaw agents. This plugin gives an agent Diffbot's Knowledge Graph and web-structuring APIs as native tools, plus ten bundled skills that teach it how to use them well.
It is the OpenClaw counterpart of diffbot-skills (agent skills for Claude Code, Copilot, Cortex, Factory) and diffbot-mcp (the MCP server): the same capabilities, the same tool contracts, running in-process in the OpenClaw Gateway with nothing to install on the client. All Diffbot API calls go through @diffbot/typescript, the official client library.
Install
From ClawHub (once published):
openclaw plugins install clawhub:@diffbot/openclaw-plugin
From a local checkout:
git clone https://github.com/diffbot/diffbot-openclaw.git
cd diffbot-openclaw
npm install
npm run plugin:build
openclaw plugins install . --accept-capabilities
Recent OpenClaw releases ask for explicit capability consent on install; the flag records it. Then restart the Gateway. Confirm the plugin and its tools loaded with:
openclaw plugins inspect diffbot --runtime
Setup
A Diffbot token is required. Get a free one at app.diffbot.com/get-started. The plugin resolves the token in this order:
plugins.entries.diffbot.config.apiTokeninopenclaw.json- The
DIFFBOT_API_TOKENorDIFFBOT_TOKENenvironment variable - A
DIFFBOT_API_TOKEN=<token>line in~/.diffbot/credentials, the same file thedbCLI, diffbot-skills, diffbot-mcp, and@diffbot/typescriptread, so one credential serves all of them
Config example:
{
plugins: {
entries: {
diffbot: {
enabled: true,
config: {
apiToken: "YOUR_TOKEN",
timeoutSeconds: 120, // optional, per-request timeout
},
},
},
},
}
Tools
All twelve tools are required tools: they are available as soon as the plugin is enabled. Every tool name is prefixed diffbot_ so nothing collides with OpenClaw's core web_search and web_fetch.
Web
| Tool | What it does |
|---|---|
diffbot_search_web | Web search that ranks accuracy over popularity, built on Diffbot's first-party index. Returns scored, dated results with the matching content chunks. Query url:<URL> <what you need> reads Diffbot's already-parsed copy of a known page in about 300ms, even for pages that block fetchers. |
diffbot_extract | Live fetch of a URL into LLM-friendly markdown or structured JSON, with automatic page classification (article, product, discussion, ...). The replacement for a raw web fetch. |
diffbot_crawl | Crawl a site and extract every page as a background job: start, status, urls, results, list, delete. |
diffbot_resolve_entities | Named entity recognition and resolution to Knowledge Graph ids, with confidence, salience, and sentiment. Returns a ready-made dql_filter. |
Knowledge Graph
| Tool | What it does |
|---|---|
diffbot_search_news | Articles by mentioned entity, topic, publisher, language, date range, or sentiment. Newest first. Use it for all news, including breaking stories. |
diffbot_search_organizations | Companies by industry, headquarters, headcount, revenue, funding, ownership, or leadership, plus similar_to lookalike lists. |
diffbot_search_people | People by title, employer, employer industry, skills, education, location, or nationality. Employment conditions are co-constrained on one job; C-suite titles are expanded to both spellings. |
diffbot_search_places | Cities, counties, states, countries, and points of interest by name, population, prominence, containing place, or proximity. |
diffbot_search_deals | Funding rounds, investments, and acquisitions by date, size, series, investor, acquirer, or industry. |
diffbot_dql | Raw DQL over any entity type: products, patents, brands, job posts, facet aggregations, cross-entity queries. Compact CSV rows by default, full JSON on request. |
diffbot_dql_probe | Parallel hit counts for several candidate queries, to check selectivity before pulling rows. |
diffbot_dql_ontology | Entity types, fields, taxonomies, and enums, so field paths and taxonomy values are confirmed instead of guessed. |
Each typed Knowledge Graph tool resolves free-text industry and topic values against the live ontology, returns the DQL it ran, and reports candidates when a value is ambiguous.
Skills
Ten skills ship in skills/ and load automatically with the plugin. They carry the long-form workflow guidance from diffbot-skills: the operator reference, the measured traps, and the display rules. Reference them in a prompt with $diffbot-news, $diffbot-dql, and so on, or invoke them as slash commands.
| Skill | Covers |
|---|---|
diffbot-news | The sort rule, narrowing levers, entity-specific sentiment, coverage facets |
diffbot-organizations | Industry taxonomy, HQ vs offices, strict name matching, near, similarTo |
diffbot-people | The {} co-constraint rule, employer-industry filtering, title traps, coverage boundary |
diffbot-places | The place-type hierarchy, containment, the continent gap, diacritics |
diffbot-deals | Investment vs Organization vs Transaction routing, the investee industry gap, amounts |
diffbot-dql | Full DQL operator reference, ontology lookup, probing, csv vs json fetches |
diffbot-web-search | The index-before-fetch rule and when a cached copy cannot be trusted |
diffbot-extract | When a live fetch is actually needed, page types, response fields |
diffbot-entities | Confidence vs salience, bridging text to DQL with entity ids |
diffbot-crawl | Start, poll, inspect, read |
Development
Requires Node 24.16+ (or 26.1+) and npm.
npm install
npm run typecheck # tsc --noEmit
npm test # vitest: builder, executor, and tool unit tests (no network)
npm run plugin:build # compile to dist/ and regenerate openclaw.plugin.json
npm run plugin:validate # check the manifest, entry, and package metadata
npm run check # all of the above
Layout:
src/
index.ts plugin entry (defineToolPlugin) registering the twelve tools
config.ts TypeBox config schema (apiToken, timeoutSeconds)
api.ts DiffbotClient factory (from @diffbot/typescript), token resolution, error mapping
dql.ts DQL executor, csv export, OntologyStore cache and lookups
dql-builder.ts pure DQL string helpers
tools/ one module per tool
skills/ ten SKILL.md files loaded via the manifest's "skills" field
assets/icon.png catalog icon (rendered from diffbot.com's favicon.svg)
openclaw.plugin.json
openclaw plugins build regenerates the id, description, configSchema, activation, and contracts.tools fields of the manifest from the entry; the hand-maintained skills field is preserved. Run it after adding or renaming a tool, or validation fails with a stale-manifest error.
Packaged smoke test:
npm pack
openclaw plugins install npm-pack:./diffbot-openclaw-plugin-0.1.0.tgz --force --accept-capabilities
openclaw plugins inspect diffbot --runtime --json
Publishing to ClawHub
npm i -g clawhub
clawhub login
clawhub package validate .
clawhub package publish . --dry-run --source-repo diffbot/diffbot-openclaw --source-commit <sha> --topics "Web Search,Web Extraction,Knowledge Graph,Crawling,Entity Resolution" --categories web
clawhub package publish . --source-repo diffbot/diffbot-openclaw --source-commit <sha> --topics "Web Search,Web Extraction,Knowledge Graph,Crawling,Entity Resolution" --categories web
--topics and --categories are publish-time-only metadata: ClawHub does not derive them from npm keywords or the plugin manifest, and there is no way to set them after publishing. They drive openclaw plugins search ranking (a Web Search topic lifts the score above the top-20 display cutoff for queries like openclaw plugins search "web search").
The package name is scoped to the ClawHub owner (@diffbot/openclaw-plugin), as ClawHub requires. New releases stay hidden from install surfaces until ClawHub's automated security checks and review finish. After the first manual publish, clawhub package trusted-publisher set @diffbot/openclaw-plugin --repository diffbot/diffbot-openclaw --workflow-filename clawhub-publish.yml lets the .github/workflows/clawhub-publish.yml workflow publish from GitHub Actions without a stored token.
License
MIT. See LICENSE.