How to Configure FlareSolverr for Cloudflare Clearance in Grok Web/Console

Set clearanceMode to flaresolverr and provide a valid flareSolverrURL to enable automatic acquisition of Cloudflare clearance cookies (cf_clearance and __cf_bm) for Grok Web and Console egress nodes.

The chenyme/grok2api repository implements an automated clearance mechanism that proxies Cloudflare challenges to a FlareSolverr instance. This configuration eliminates manual cookie management and ensures persistent connectivity to upstream Grok services without interruption.

Architecture Overview

The clearance system consists of coordinated components that handle configuration, validation, and execution:

Component	Responsibility	Source Location
Configuration	Defines provider.web.clearanceMode and provider.web.flareSolverrURL parameters	backend/internal/infra/config/config.go
Settings API	Exposes /settings endpoint for runtime configuration updates	backend/internal/transport/http/settings/handler.go
Egress Manager	Orchestrates ClearanceConfig and instantiates the FlareSolverr client	backend/internal/infra/egress/manager.go
FlareSolverr Client	Executes HTTP requests to solve Cloudflare challenges and extract cookies	backend/internal/infra/egress/flaresolverr.go
Frontend UI	Provides the Clearance tab for mode selection and URL input	frontend/src/features/settings/settings-page.tsx

When clearanceMode is set to flaresolverr, the egress manager initializes a dedicated client that communicates with the external FlareSolverr service. This client obtains fresh cf_clearance and __cf_bm cookies along with a compatible User-Agent string, caching them according to the clearanceRefresh interval (default 1 hour).

Configuration Methods

Static YAML Configuration

Define the FlareSolverr integration in your config.yaml file. The parser validates the URL via validateFlareSolverrURL in config.go (line 864), accepting only http or https schemes without query parameters or fragments.

provider:
  web:
    clearanceMode: flaresolverr
    flareSolverrURL: http://flaresolverr:8191
    clearanceTimeout: 30s
    clearanceRefresh: 1h

Runtime API Updates

Update the configuration dynamically via the REST API. The request body follows the settingsConfigDTO structure defined in handler.go (lines 23-78).

curl -X PUT http://localhost:8000/v1/settings \
  -H "Content-Type: application/json" \
  -d '{
        "revision": 42,
        "config": {
          "providerWeb": {
            "clearanceMode": "flaresolverr",
            "flareSolverrURL": "http://flaresolverr:8191",
            "clearanceTimeout": "30s",
            "clearanceRefresh": "1h"
          }
        }
      }'

Web UI Configuration

The React frontend (settings-page.tsx) provides a dedicated interface for FlareSolverr setup. Users select the FlareSolverr clearance mode and enter the service endpoint (default: http://flaresolverr:8191).

The UI components bind to the Zod schema in settings-model.ts (lines 86-112), ensuring type safety for the flareSolverrURL field.

Docker Compose Deployment

Deploy FlareSolverr alongside Grok API using the optional profile defined in docker-compose.yml (lines 40-48):

docker compose --profile flaresolverr up -d

Alternatively, run FlareSolverr independently and reference its host and port in the Grok API configuration.

Technical Implementation Details

Clearance Manager Logic

The egress manager (backend/internal/infra/egress/manager.go) maintains a ClearanceConfig struct that tracks the current mode, target URL, timeout, and refresh interval. When initialized with clearanceMode: flaresolverr, the manager creates a flarerSolverrClient instance.

For each clearance request, the manager invokes:

solution, err := flaresolverrClient.Solve(ctx, ClearanceRequest{
    TargetURL: "https://grok.com",
    Timeout:   cfg.Provider.Web.ClearanceTimeout,
})
if err != nil {
    // Handle error or fallback to manual mode
}
node.CloudflareCookies = solution.Cookies
node.UserAgent = solution.UserAgent

FlareSolverr Client Workflow

The client implementation (backend/internal/infra/egress/flaresolverr.go) handles the low-level communication:

1. Constructs a JSON payload targeting the FlareSolverr HTTP API
2. Posts to cfg.FlareSolverrURL+"/v1" (or the configured base path)
3. Parses the ClearanceResponse to extract Set-Cookie headers
4. Sanitizes error messages via sanitizeFlareSolverrMessage to prevent credential leakage

The retrieved cookies are cached per-account (or per-node when using Resin) and automatically injected into outbound requests to https://grok.com.

Summary

• Configure FlareSolverr mode by setting provider.web.clearanceMode to flaresolverr in YAML or via the /settings API
• Provide a valid FlareSolverr URL (e.g., http://flaresolverr:8191) that the system validates in config.go
• The egress manager automatically creates a client that solves Cloudflare challenges and caches cf_clearance cookies
• Cookies refresh automatically based on the clearanceRefresh interval (default 1 hour)
• Use the Docker Compose profile flaresolverr for quick deployment or connect to an existing instance

Frequently Asked Questions

What is the default FlareSolverr URL if not specified?

The system defaults to http://flaresolverr:8191 as defined in backend/internal/infra/config/config.go. This assumes FlareSolverr runs as a container named flaresolverr on the default port 8191 within the same Docker network.

How does the system handle FlareSolverr timeouts?

The clearanceTimeout parameter (default 30 seconds) controls how long the egress manager waits for a solution. If the FlareSolverr service fails to respond within this window, the client returns an error and the system may fall back to manual clearance mode or retry according to the error handling logic in manager.go.

Can I use FlareSolverr for Grok Console clearance as well?

Yes. The clearanceMode and flareSolverrURL settings apply to both Grok Web and Grok Console egress nodes. The clearance manager handles both service types through the same ClearanceConfig structure, ensuring consistent Cloudflare bypass across all upstream Grok endpoints.

Where are the clearance cookies stored?

The solved cookies (cf_clearance and __cf_bm) are stored in-memory within the egress node structure, cached per-account or per-node when using Resin clustering. They are not persisted to disk; instead, the system refreshes them automatically via the FlareSolverr client according to the configured clearanceRefresh interval.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}