Guide

Hermes Agent + Firecrawl: Search, Extract, and Browse the Web

Q: Does Hermes Agent support Firecrawl natively?

Yes. Hermes ships a web-firecrawl plugin for web_search and web_extract, and a separate browser-firecrawl plugin for cloud browsing. Both read FIRECRAWL_API_KEY but use different endpoints.

Q: How do I add Firecrawl to a Hermes bot hosted on OpenClaw Launch?

Connect Firecrawl on the openclawlaunch.com/integrations page. Managed Hermes instances carry the Composio bridge, so the Firecrawl tools reach the bot without editing files in the container.

Q: Which env vars does Hermes read for Firecrawl?

FIRECRAWL_API_KEY for the key, FIRECRAWL_API_URL for a self-hosted endpoint, and FIRECRAWL_BROWSER_TTL for the browser session timeout (default 300 seconds). They go in ~/.hermes/.env.

Q: Do Nous Portal subscribers need a Firecrawl key?

No. A paid Nous Portal subscription provides web search and extract through the tool gateway with managed Firecrawl. Run hermes setup --portal on new installs, or hermes tools on existing ones.

Q: Will Firecrawl handle localhost and LAN pages?

Hermes uses hybrid routing. A local Chromium sidecar handles loopback, private, and link-local addresses, while public URLs continue to use the cloud provider.

Firecrawl is the default web provider in Hermes Agent, and it can also serve as a cloud browser backend. Which setup you use depends on whether your bot is managed here or running on your own machine.

Two Firecrawl integrations, not one

This trips people up, so it is worth stating first. Hermes ships two separate Firecrawl plugins:

web-firecrawl — the web provider behind web_search and web_extract. Firecrawl is the default choice here, and it is one of the few providers that does both search and extraction rather than search alone.
browser-firecrawl — a cloud browser backend, alongside Browserbase and Browser Use. This is the one that drives pages rather than just reading them.

They read the same FIRECRAWL_API_KEY but call different endpoints, so turning on one does not turn on the other. Pick based on what you actually want the agent to do: read pages, or operate them.

Path 1: A Hermes bot hosted here

If your Hermes Agent runs on OpenClaw Launch, connect Firecrawl on the Integrations page:

Sign in, open Integrations, search for Firecrawl, click Connect.
Leave the pre-filled Base URL (https://api.firecrawl.dev/v1) alone unless you run your own instance, and paste your fc- key.
Submit. There is no OAuth round trip — the connection activates immediately.

Managed Hermes instances already carry the Composio bridge, so the Firecrawl actions become available to the agent without editing anything inside the container. The same connection also serves any OpenClaw bots on the account. Ask the agent to list its connected apps if it claims it has no scraping tool — that forces a fresh lookup instead of a guess.

One honest limitation: the hosted dashboard does not currently expose Firecrawl in the Hermes search-provider dropdown, so this route gives you Firecrawl as a set of callable tools rather than as the bot's native web_search backend. For that, use path 2 or 3.

Path 2: Your own Hermes install

On a self-managed Hermes, Firecrawl is configured with environment variables in ~/.hermes/.env:

# ~/.hermes/.env
FIRECRAWL_API_KEY=fc-your-key-here

That alone makes Firecrawl the provider for web_search and web_extract. Get the key at firecrawl.dev; the free tier covers casual agent use and the quota is billed by Firecrawl.

Split search and extraction

You do not have to use one provider for both capabilities. A common frugal setup runs a free search backend and keeps Firecrawl for the extraction step, where clean output matters most:

# ~/.hermes/config.yaml
web:
  search_backend: "searxng"
  extract_backend: "firecrawl"

Use Firecrawl as the browser backend

The browser plugin is selected through the setup CLI rather than by env var alone:

hermes setup tools
# → Browser Automation → Firecrawl

Optional knobs:

# ~/.hermes/.env
FIRECRAWL_API_URL=https://firecrawl.example.com   # your own endpoint
FIRECRAWL_BROWSER_TTL=600                         # session TTL in seconds (default 300)

Use an address the Hermes host can actually reach. Upstream examples show http://localhost:3002, which is only correct when Hermes and Firecrawl share a network namespace — under Docker, localhost resolves to the Hermes container itself, not to a Firecrawl container beside it.

Local pages stay local

Turning on a cloud browser does not push your internal dashboards through it. Hermes routes loopback, RFC1918, and link-local targets to a local Chromium sidecar while public URLs keep using the cloud provider in the same conversation. The self-hosted Firecrawl guide covers the exact address ranges and how to test the split.

Path 3: Nous Portal subscription

A paid Nous Portal subscription routes web search and extract through the Hermes tool gateway using managed Firecrawl, with no key of your own:

hermes setup --portal   # new installs: log in and enable gateway tools
hermes tools            # existing installs: switch web over

Browser automation can run through the gateway the same way, selecting the Nous Subscription provider instead of a keyed cloud backend.

Running Firecrawl yourself

Firecrawl is open source, so the endpoint can be yours. Set FIRECRAWL_API_URL to your deployment and the key becomes optional, depending on how you configured server auth. That is its own topic — retention, TLS, network placement, browser-worker memory, and the layered test sequence live in the self-hosted Firecrawl guide.

Which path fits

	Integrations page	Own install + key	Nous Portal gateway
Works on managed hosting	Yes	Not exposed today	Needs a Portal subscription
Setup	Paste a key in the browser	Edit `~/.hermes/.env`	`hermes setup --portal`
Becomes the native web provider	No — exposed as tools	Yes	Yes
Browser backend too	No	Yes, via `hermes setup tools`	Yes, via the gateway
Who holds the key	Composio	You	Nous

Troubleshooting

The agent says it has no web tools

On a self-managed install, a newly added skill or plugin lands in the agent prompt only after a gateway restart or a skills reload — check that first before assuming the key is wrong. On a hosted bot, ask it to list connected apps so it re-reads the bridge.

Search works but extraction does not

Several providers are search-only. If your search backend is Brave, DDGS, or xAI, you need a second provider with extraction — Firecrawl, Tavily, Exa, or Parallel — wired to extract_backend.

Pages on your LAN fail

That is the sidecar's job, not Firecrawl's. Confirm the local Chromium sidecar can start; a cloud provider will never reach a private address on its own.

Out of credits

The quota sits on your Firecrawl key, not on your hosting plan. Check the Firecrawl dashboard, and consider a free search backend paired with Firecrawl extraction to stretch it.

Frequently asked questions

Does Hermes Agent support Firecrawl natively?

Yes, in two separate places. Hermes ships a web-firecrawl plugin that provides web_search and web_extract, and a browser-firecrawl plugin that provides a cloud browser backend. They share one FIRECRAWL_API_KEY but hit different endpoints, so enabling one does not enable the other.

How do I add Firecrawl to a Hermes bot hosted on OpenClaw Launch?

Connect Firecrawl on the Integrations page. That routes the Firecrawl tools to your bot through the Composio bridge that managed Hermes instances already carry, so there is no file to edit inside the container. The native FIRECRAWL_API_KEY search-provider slot is not exposed in the hosted dashboard today.

Which env vars does Hermes read for Firecrawl?

FIRECRAWL_API_KEY for the key, FIRECRAWL_API_URL to point at a self-hosted instance instead of the cloud API, and FIRECRAWL_BROWSER_TTL to change the browser session timeout (default 300 seconds). They live in ~/.hermes/.env.

Do Nous Portal subscribers need a Firecrawl key?

No. A paid Nous Portal subscription routes web search and extract through the Hermes tool gateway using managed Firecrawl. New installs can run hermes setup --portal to log in and enable the gateway tools; existing installs can switch web over with hermes tools.

Will Firecrawl handle localhost and LAN pages?

Not directly, and it does not need to. When a cloud browser provider is configured, Hermes auto-spawns a local Chromium sidecar for URLs that resolve to loopback, private, or link-local addresses, and keeps public URLs on the cloud provider in the same conversation.