| name | flaresolverr |
| description | Bypass Cloudflare protection — use when curl/summarize gets 403 or Cloudflare blocks |
| metadata | {"openclaw":{"emoji":"🛡️","requires":{"bins":["curl","jq"],"env":["FLARESOLVERR_URL"]},"primaryEnv":"FLARESOLVERR_URL"}} |
FlareSolverr — Cloudflare Bypass
Use FlareSolverr to bypass Cloudflare protection when direct curl requests fail with 403 or Cloudflare challenge pages.
Setup
- Run FlareSolverr (Docker recommended):
docker run -d --name flaresolverr -p 8191:8191 ghcr.io/flaresolverr/flaresolverr:latest
- Set the environment variable:
export FLARESOLVERR_URL="http://localhost:8191"
- Verify:
curl -s "$FLARESOLVERR_URL/health" | jq '.'
When to Use
- Direct curl fails with 403 Forbidden
- Cloudflare challenge page appears (JS challenge, captcha, "Checking your browser")
- Bot detection blocks automated requests
- Rate limiting or anti-scraping measures
Workflow
- Try direct curl first (it's faster and simpler)
- If blocked: Use FlareSolverr to get cookies/user-agent
- Reuse session for subsequent requests (optional, for performance)
Basic Usage
Simple GET Request
curl -X POST "$FLARESOLVERR_URL/v1" \
-H "Content-Type: application/json" \
-d '{
"cmd": "request.get",
"url": "https://example.com/protected-page",
"maxTimeout": 60000
}' | jq '.'
Response Structure
{
"status": "ok",
"message": "Challenge solved!",
"solution": {
"url": "https://example.com/protected-page",
"status": 200,
"headers": {},
"response": "<html>...</html>",
"cookies": [
{
"name": "cf_clearance",
"value": "...",
"domain": ".example.com"
}
],
"userAgent": "Mozilla/5.0 ..."
},
"startTimestamp": 1234567890,
"endTimestamp": 1234567895,
"version": "3.3.2"
}
Extract Page Content
curl -s -X POST "$FLARESOLVERR_URL/v1" \
-H "Content-Type: application/json" \
-d '{
"cmd": "request.get",
"url": "https://example.com/protected-page"
}' | jq -r '.solution.response'
Extract Cookies
curl -s -X POST "$FLARESOLVERR_URL/v1" \
-H "Content-Type: application/json" \
-d '{
"cmd": "request.get",
"url": "https://example.com"
}' | jq -r '.solution.cookies[] | "\(.name)=\(.value)"'
Session Management
Sessions allow reusing browser context (cookies, user-agent) for multiple requests, improving performance.
Create Session
curl -s -X POST "$FLARESOLVERR_URL/v1" \
-H "Content-Type: application/json" \
-d '{"cmd": "sessions.create"}' | jq -r '.session'
Use Session for Request
curl -s -X POST "$FLARESOLVERR_URL/v1" \
-H "Content-Type: application/json" \
-d '{
"cmd": "request.get",
"url": "https://example.com/page1",
"session": "SESSION_ID"
}' | jq -r '.solution.response'
List Active Sessions
curl -s -X POST "$FLARESOLVERR_URL/v1" \
-H "Content-Type: application/json" \
-d '{"cmd": "sessions.list"}' | jq '.sessions'
Destroy Session
curl -s -X POST "$FLARESOLVERR_URL/v1" \
-H "Content-Type: application/json" \
-d '{
"cmd": "sessions.destroy",
"session": "SESSION_ID"
}'
POST Requests
curl -s -X POST "$FLARESOLVERR_URL/v1" \
-H "Content-Type: application/json" \
-d '{
"cmd": "request.post",
"url": "https://example.com/api/endpoint",
"postData": "key1=value1&key2=value2",
"maxTimeout": 60000
}' | jq '.'
For JSON POST data:
curl -s -X POST "$FLARESOLVERR_URL/v1" \
-H "Content-Type: application/json" \
-d '{
"cmd": "request.post",
"url": "https://example.com/api/endpoint",
"postData": "{\"key\":\"value\"}",
"headers": {
"Content-Type": "application/json"
}
}' | jq '.'
Advanced Options
Custom User-Agent
curl -s -X POST "$FLARESOLVERR_URL/v1" \
-H "Content-Type: application/json" \
-d '{
"cmd": "request.get",
"url": "https://example.com",
"userAgent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36"
}' | jq '.'
Custom Headers
curl -s -X POST "$FLARESOLVERR_URL/v1" \
-H "Content-Type: application/json" \
-d '{
"cmd": "request.get",
"url": "https://example.com",
"headers": {
"Accept-Language": "en-US,en;q=0.9",
"Referer": "https://google.com"
}
}' | jq '.'
Proxy Support
curl -s -X POST "$FLARESOLVERR_URL/v1" \
-H "Content-Type: application/json" \
-d '{
"cmd": "request.get",
"url": "https://example.com",
"proxy": {
"url": "http://proxy.example.com:8080"
}
}' | jq '.'
Download Binary Content
curl -s -X POST "$FLARESOLVERR_URL/v1" \
-H "Content-Type: application/json" \
-d '{
"cmd": "request.get",
"url": "https://example.com/file.pdf",
"download": true
}' | jq -r '.solution.response' | base64 -d > file.pdf
Error Handling
Common Errors
"status": "error": Request failed (check message field)"status": "timeout": maxTimeout exceeded (increase timeout)"status": "captcha": Manual captcha required (rare, usually auto-solved)
Check Status
curl -s -X POST "$FLARESOLVERR_URL/v1" \
-H "Content-Type: application/json" \
-d '{"cmd": "request.get", "url": "https://example.com"}' | \
jq -r '.status'
Example Workflow
Bypass Cloudflare and Extract Data
RESPONSE=$(curl -s -X POST "$FLARESOLVERR_URL/v1" \
-H "Content-Type: application/json" \
-d '{
"cmd": "request.get",
"url": "https://example.com/protected-page"
}')
STATUS=$(echo "$RESPONSE" | jq -r '.status')
if [ "$STATUS" != "ok" ]; then
echo "Failed: $(echo "$RESPONSE" | jq -r '.message')"
exit 1
fi
echo "$RESPONSE" | jq -r '.solution.response'
Multi-Page Session
SESSION=$(curl -s -X POST "$FLARESOLVERR_URL/v1" \
-H "Content-Type: application/json" \
-d '{"cmd": "sessions.create"}' | jq -r '.session')
curl -s -X POST "$FLARESOLVERR_URL/v1" \
-H "Content-Type: application/json" \
-d "{\"cmd\": \"request.get\", \"url\": \"https://example.com/page1\", \"session\": \"$SESSION\"}" | \
jq -r '.solution.response'
curl -s -X POST "$FLARESOLVERR_URL/v1" \
-H "Content-Type: application/json" \
-d "{\"cmd\": \"request.get\", \"url\": \"https://example.com/page2\", \"session\": \"$SESSION\"}" | \
jq -r '.solution.response'
curl -s -X POST "$FLARESOLVERR_URL/v1" \
-H "Content-Type: application/json" \
-d "{\"cmd\": \"sessions.destroy\", \"session\": \"$SESSION\"}"
Health Check
curl -s "$FLARESOLVERR_URL/health" | jq '.'
Performance Tips
- Use sessions for multiple requests to same domain (reuses cookies/context)
- Increase maxTimeout for slow sites (default: 60000ms)
- Fallback to direct curl when possible (FlareSolverr is slower due to browser overhead)
- Destroy sessions when done to free resources
Limitations
- Slower than direct curl (launches headless browser)
- Resource intensive (limit concurrent requests)
- May not solve all captchas (most Cloudflare challenges work)
- HTML only in response (no client-side JS execution after fetch)
Best Practices
- Always try direct curl first
- Use sessions for multi-page workflows
- Set appropriate maxTimeout (default 60s, increase for slow sites)
- Clean up sessions when done
- Handle errors gracefully (check
status field)
- Rate limit your requests (don't overwhelm FlareSolverr or target site)
