This integration is done by treating Firecrawl Search as an external API: register and configure a skill in ClawHub, choose whether to use an API key or OAuth for authentication, store credentials as secrets, implement skill handlers that make authenticated REST calls to Firecrawl, validate any incoming webhooks using HMAC/signature verification, and move durable state or background jobs outside the agent runtime. Below are concrete design steps, security considerations, and working code snippets (replace placeholder endpoints/headers with Firecrawl’s actual values).

Overview

• Goal: Let an OpenClaw skill invoke Firecrawl Search (and receive Firecrawl webhooks) reliably and securely.
• Key constraints: OpenClaw does not “magically” connect — you must explicitly configure credentials in ClawHub, write code in the skill to call Firecrawl’s REST APIs, and host any long-lived state or scheduled jobs outside the ephemeral agent runtime.

Prerequisites

• Access to ClawHub where you can create and configure a skill, and store environment variables/secrets.
• Firecrawl API credentials: either an API key or OAuth client credentials and (if using OAuth) a redirect URL you control.
• A reachable HTTPS endpoint if Firecrawl will call webhooks back to you (or a relay/proxy).
• Developer tools: Node.js or your preferred runtime for the skill code and testing tools like curl or Postman.

Design and architecture (what runs where)

• Skill runtime (inside agent): Short-lived request handlers that call Firecrawl for immediate queries, produce responses, and return results. Suitable for simple request/response search operations.
• External services (outside agent): Persisted token stores, refresh token exchange endpoints, background workers for heavy indexing or bulk operations, queues for retries, and web servers for OAuth callbacks or incoming webhooks. Use these when you need persistence, retries, or guaranteed uptime.
• Secrets/Config: Keep API keys, client secrets, webhook secrets as encrypted secrets in ClawHub (or a secrets manager). Do not embed them in code.

Authentication options

• API key (simplest): Store the Firecrawl API key as a secret and use it in the Authorization header for REST calls: Authorization: Bearer <API\_KEY>. Works when Firecrawl supports token-based API keys.
• OAuth2 (recommended for user-scoped access): Implement Authorization Code flow: redirect users to Firecrawl’s consent page, receive a code at your redirect URI, exchange code for access/refresh tokens at Firecrawl’s token endpoint, and store tokens in a secure store. Refresh tokens must be persisted outside a short-lived agent runtime.
• Service accounts or JWT (if Firecrawl supports): Use server-to-server credentials stored securely; run token minting in an external service if needed.

Implementing the skill: example REST calls

• Replace placeholder URLs, header names, and JSON fields with Firecrawl’s actual API docs.
• Keep calls synchronous and short in the skill. For long-running requests, return an immediate acknowledgement and orchestrate long work from an external worker.

<b>//</b> Node.js example: call Firecrawl Search using an API key
const fetch = require('node-fetch');

async function searchFirecrawl(query) {
  const apiKey = process.env.FIRECRAWL_API_KEY; <b>//</b> store as a secret in ClawHub
  const resp = await fetch('https://api.firecrawl.example/v1/search', {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'Authorization': `Bearer ${apiKey}`
    },
    body: JSON.stringify({ query })
  });

  if (!resp.ok) {
    const body = await resp.text();
    throw new Error(`Firecrawl ${resp.status}: ${body}`);
  }
  return resp.json();
}

<b>//</b> OAuth token exchange (server-side): exchange code for tokens
const fetch = require('node-fetch');

async function exchangeCodeForTokens(code) {
  const tokenUrl = 'https://auth.firecrawl.example/oauth/token'; <b>//</b> replace with Firecrawl token endpoint
  const res = await fetch(tokenUrl, {
    method: 'POST',
    headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
    body: new URLSearchParams({
      grant_type: 'authorization_code',
      code,
      client_id: process.env.FIRECRAWL_CLIENT_ID,
      client_secret: process.env.FIRECRAWL_CLIENT_SECRET,
      redirect_uri: process.env.FIRECRAWL_REDIRECT_URI
    })
  });

  if (!res.ok) throw new Error(await res.text());
  return res.json(); <b>//</b> contains access_token, refresh_token, expires_in
}

Webhook handling and verification

• Firecrawl webhooks must be validated. Most providers sign payloads (HMAC) or include a signature header. Validate with timing-safe comparison.
• The skill runtime might not be suitable to host public webhook endpoints — if ClawHub skill cannot accept inbound webhooks reliably, place a web endpoint externally and notify the skill via a secure internal call or message queue.

<b>//</b> Express example: verify HMAC-SHA256 webhook signature
const express = require('express');
const crypto = require('crypto');
const app = express();
app.use(express.json());

app.post('/webhook/firecrawl', (req, res) => {
  const secret = process.env.FIRECRAWL_WEBHOOK_SECRET; <b>//</b> store securely
  const signatureHeader = req.get('x-firecrawl-signature'); <b>//</b> replace with actual header name Firecrawl uses
  const payload = JSON.stringify(req.body);

  const expected = crypto.createHmac('sha256', secret).update(payload).digest('hex');
  try {
    const sigBuf = Buffer.from(signatureHeader, 'utf8');
    const expBuf = Buffer.from(expected, 'utf8');
    if (sigBuf.length !== expBuf.length || !crypto.timingSafeEqual(sigBuf, expBuf)) {
      return res.status(401).send('invalid signature');
    }
  } catch (e) {
    return res.status(401).send('invalid signature');
  }

  <b>//</b> Process webhook payload (enqueue work, notify skill, etc.)
  res.status(200).send('ok');
});

Persistence and background work

• Refresh tokens and long-lived state: Store refresh tokens and any indexing state in an external data store (database or secret store). Agent runtime should not be relied on as durable storage.
• Background workers: For reindexing, bulk search, or scheduled syncs, run external workers or scheduled functions that call Firecrawl and update your DB. Use queues for retries and backoffs.

Configuration in ClawHub

• Skill manifest/registration: Create the skill in ClawHub and upload your handler code or container as required by ClawHub’s process.
• Environment variables and secrets: Put FIRECRAWL_API_KEY, FIRECRAWL_CLIENT_ID, FIRECRAWL_CLIENT_SECRET, FIRECRAWL_WEBHOOK_SECRET, and any redirect URIs into the secret/config store provided by ClawHub (or your external vault). Ensure only the skill has access to these secrets.
• Redirect URIs and webhook URLs: If using OAuth, add the redirect URI configured in ClawHub (or your external service) to Firecrawl’s application settings. For webhooks, register the public endpoint URL with Firecrawl.

Testing and debugging

• Step-by-step tests: Start with direct REST calls to Firecrawl (curl/Postman) using the stored credentials to verify they work, then call the skill locally or in ClawHub with the same credentials.
• Verify headers and scopes: Check that Authorization headers, content-type, and required Firecrawl scopes are present. If OAuth, ensure access tokens include required scopes.
• Inspect responses: Log full request/response bodies (sanitized) and HTTP status codes. Look for 401/403 for auth issues, 429 for rate-limits, and 5xx for service errors.
• Webhook debugging: If you cannot receive webhooks directly, use a tool like a webhook relay (ngrok or a proper webhook relay service) to validate signatures and payloads in a dev environment.
• ClawHub logs: Use ClawHub’s skill invocation logs to confirm the skill is invoked and to see any runtime errors or timeouts.

Security and operational considerations

• Least privilege: Request only the Firecrawl API scopes you need.
• Secrets handling: Never check secrets into source control; use ClawHub secrets or a secrets manager.
• Signature validation: Use timing-safe comparisons for webhook verification.
• Rate limiting and retries: Implement exponential backoff for 429 responses. Respect Firecrawl’s rate limits and monitor quota usage.
• Monitoring: Emit metrics for request counts, latencies, error rates, and token refresh activity. Track webhook delivery failures and queue them for retry.
• Data residency and privacy: Ensure any indexed content and search results comply with your policies and Firecrawl’s terms.

Checklist to deploy

• Decide auth method (API key vs OAuth) and obtain credentials from Firecrawl.
• Implement and test REST calls to Firecrawl locally.
• Securely store credentials in ClawHub or a vault and reference them via environment variables.
• Implement webhook verification and host webhook endpoint (or use external host + relay to skill).
• Push skill to ClawHub, set environment variables/secrets, and test end-to-end using sandbox/test Firecrawl account if available.
• Move any durable state, refresh token storage, and background workers outside the agent runtime before production.

This describes an explicit, verifiable integration path: configure credentials in ClawHub, make authenticated REST calls from the skill, validate webhooks, persist tokens and long-running state externally, and observe the usual debugging steps (logs, inspect API responses, verify scopes/headers, check signatures).