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

> Learn how to configure FlareSolverr for Cloudflare clearance in Grok Web/Console. Get automatic cf_clearance and __cf_bm cookies for seamless access.

- Repository: [Chenyme/grok2api](https://github.com/chenyme/grok2api)
- Tags: how-to-guide
- Published: 2026-08-09

---

**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`](https://github.com/chenyme/grok2api/blob/main/backend/internal/infra/config/config.go) |
| **Settings API** | Exposes `/settings` endpoint for runtime configuration updates | [`backend/internal/transport/http/settings/handler.go`](https://github.com/chenyme/grok2api/blob/main/backend/internal/transport/http/settings/handler.go) |
| **Egress Manager** | Orchestrates `ClearanceConfig` and instantiates the FlareSolverr client | [`backend/internal/infra/egress/manager.go`](https://github.com/chenyme/grok2api/blob/main/backend/internal/infra/egress/manager.go) |
| **FlareSolverr Client** | Executes HTTP requests to solve Cloudflare challenges and extract cookies | [`backend/internal/infra/egress/flaresolverr.go`](https://github.com/chenyme/grok2api/blob/main/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`](https://github.com/chenyme/grok2api/blob/main/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`](https://github.com/chenyme/grok2api/blob/main/config.yaml) file. The parser validates the URL via `validateFlareSolverrURL` in [`config.go`](https://github.com/chenyme/grok2api/blob/main/config.go) (line 864), accepting only `http` or `https` schemes without query parameters or fragments.

```yaml
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`](https://github.com/chenyme/grok2api/blob/main/handler.go) (lines 23-78).

```bash
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`](https://github.com/chenyme/grok2api/blob/main/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`](https://github.com/chenyme/grok2api/blob/main/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`](https://github.com/chenyme/grok2api/blob/main/docker-compose.yml) (lines 40-48):

```bash
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`](https://github.com/chenyme/grok2api/blob/main/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:

```go
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`](https://github.com/chenyme/grok2api/blob/main/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`](https://github.com/chenyme/grok2api/blob/main/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`](https://github.com/chenyme/grok2api/blob/main/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`](https://github.com/chenyme/grok2api/blob/main/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.