ClewdR

https://github.com/xerxes-2/clewdr
Admin
ClewdR is a high-performance, production-grade proxy server built with Rust for Claude and Google...
Tokens:19,737
Snippets:80
Trust Score:8.5
License:AGPL-3.0
Update:1 year ago
Show doc for...
Tokens:
Raw
### ClewdR Configuration File Example (TOML)

Source: https://context7.com/xerxes-2/clewdr/llms.txt

An example of the `clewdr.toml` configuration file, which stores network settings and authentication credentials. Passwords are auto-generated on the first run. This file is used for initial setup and can be populated via export operations.

```toml
# Network configuration
ip = "127.0.0.1"
port = 8484

# Authentication
admin_password = "auto-generated-64-char-password"
api_password = "auto-generated-64-char-password"

```

--------------------------------

### Full ClewdR Configuration Example

Source: https://github.com/xerxes-2/clewdr/blob/master/wiki/hf-space.md

A comprehensive example of ClewdR's default configuration settings, demonstrating various parameters like cookie management, API settings, update behavior, and chat preservation. Some parameters like IP and port are restricted from being added as variables.

```env
clewdr_cookie_array = [[]]
clewdr_wasted_cookie = [] #这个可以不用管
clewdr_ip = "127.0.0.1" #此项禁止加入变量
clewdr_port = 8484  #此项禁止加入变量
clewdr_check_update = true
clewdr_auto_update = false
clewdr_password = "password"
clewdr_admin_password = "password"
clewdr_max_retries = 5
clewdr_preserve_chats = false
clewdr_skip_first_warning = false
clewdr_skip_second_warning = false
clewdr_skip_restricted = false
clewdr_skip_non_pro = false
clewdr_use_real_roles = true
clewdr_custom_prompt = ""

```

--------------------------------

### Docker Deployment of ClewdR

Source: https://context7.com/xerxes-2/clewdr/llms.txt

Instructions for deploying ClewdR using Docker, including basic setup, port mapping, volume mounting for data persistence, and environment variable configuration for database integration.

```bash
# Pull and run official image
docker run -d \
  -p 8484:8484 \
  -v ./clewdr-data:/etc/clewdr \
  -e CLEWDR_IP=0.0.0.0 \
  -e CLEWDR_ADMIN_PASSWORD=secure-password \
  --name clewdr \
  ghcr.io/xerxes-2/clewdr:latest

# View admin password from logs
docker logs clewdr | grep "Web Admin Password"

# With database persistence
docker run -d \
  -p 8484:8484 \
  -e CLEWDR_PERSISTENCE__MODE=postgres \
  -e CLEWDR_PERSISTENCE__DATABASE_URL=postgres://user:pass@postgres:5432/clewdr \
  --name clewdr \
  ghcr.io/xerxes-2/clewdr:latest

```

--------------------------------

### Example ClewdR API Endpoint

Source: https://github.com/xerxes-2/clewdr/blob/master/wiki/hf-space.md

An example of the API endpoint URL for ClewdR deployed on Hugging Face Spaces. This URL is used to interact with the Claude AI model via the reverse proxy. The API key is required for authentication.

```plaintext
https://3v4pyve7-clewdr.hf.space/v1
```

--------------------------------

### Start ClewdR with Environment Variables using Docker Run

Source: https://github.com/xerxes-2/clewdr/wiki/部署到-Docker

This command provides a single-line alternative to Docker Compose for starting ClewdR with environment variable configuration. It's useful for quick deployments or when Docker Compose is not available. All necessary parameters are passed directly as environment flags.

```bash
docker run -d \
  --name clewdr \
  --hostname clewdr \
  --network host \
  --restart unless-stopped \
  -e CLEWDR_ADMIN_PASSWORD="前端访问密码" \
  -e CLEWDR_PASSWORD="Clewdr APIKEY" \
  -e CLEWDR_COOKIE_ARRAY=[[COOKIE 1],[COOKIE 2]] \
  -e CLEWDR_GEMINI_KEYS=[[GEMINI KEY 1],[GEMINI KEY 2]] \
  -e CLEWDR_MAX_RETRIES=10 \
  -e CLEWDR_CACHE_RESPONSE=0 \
  ghcr.io/xerxes-2/clewdr:latest

```

--------------------------------

### Environment Variable Configuration for Persistence

Source: https://github.com/xerxes-2/clewdr/blob/master/wiki/database.md

Example environment variables for configuring ClewdR's persistence. This demonstrates how to switch to SQLite mode and specify the path, or configure a database URL for PostgreSQL/MySQL using environment variables.

```bash
export CLEWDR_PERSISTENCE__MODE=sqlite
export CLEWDR_PERSISTENCE__SQLITE_PATH=/var/lib/clewdr/clewdr.db
# 或者使用服务器数据库
export CLEWDR_PERSISTENCE__DATABASE_URL="postgres://user:pass@db/clewdr"
```

--------------------------------

### SillyTavern Configuration for ClewdR

Source: https://github.com/xerxes-2/clewdr/blob/master/README.md

Example JSON configuration for connecting SillyTavern to ClewdR using an OpenAI-compatible endpoint. Requires the API URL, your console-provided password, and the desired model.

```json
{
  "api_url": "http://127.0.0.1:8484/v1/chat/completions",
  "api_key": "your-api-password-from-console",
  "model": "claude-3-sonnet-20240229"
}
```

--------------------------------

### Run ClewdR Binary - Bash

Source: https://github.com/xerxes-2/clewdr/blob/master/README.md

This snippet demonstrates how to download, extract, and run the ClewdR binary on Linux/macOS. It assumes the user has `wget` and `tar` installed. The process involves downloading the release, making the binary executable, and then running it. Note that `[platform]` should be replaced with the specific operating system and architecture (e.g., `linux-x64`).

```bash
# Download the latest release for your platform
wget https://github.com/Xerxes-2/clewdr/releases/latest/download/clewdr-[platform]

# Extract the binary (if necessary)
tar -xzf clewdr-[platform].tar.gz

# Navigate to the directory
cd clewdr-[platform]

# Make executable (Linux/macOS)
chmod +x clewdr

# Run ClewdR
./clewdr
```

--------------------------------

### Configure ClewdR Database Persistence (TOML)

Source: https://github.com/xerxes-2/clewdr/blob/master/README.md

Example TOML configuration for ClewdR's database persistence. Specifies the database mode (e.g., 'postgres') and the connection URL. SQLite also has an optional `sqlite_path`.

```toml
[persistence]
mode = "postgres"            # sqlite | postgres | mysql
database_url = "postgres://user:pass@db:5432/clewdr"
```

--------------------------------

### Configure ClewdR Database Persistence (Environment Variables)

Source: https://github.com/xerxes-2/clewdr/blob/master/README.md

Example environment variables for configuring ClewdR's database persistence using Figment's double-underscore syntax. Supports SQLite and server-based databases like PostgreSQL and MySQL.

```bash
export CLEWDR_PERSISTENCE__MODE=sqlite
export CLEWDR_PERSISTENCE__SQLITE_PATH=/var/lib/clewdr/clewdr.db
# or database_url for server backends
export CLEWDR_PERSISTENCE__DATABASE_URL="postgres://user:pass@db/clewdr"
```

--------------------------------

### TOML Configuration for Persistence

Source: https://github.com/xerxes-2/clewdr/blob/master/wiki/database.md

Example TOML configuration for ClewdR's persistence settings. This snippet shows how to set the persistence mode to PostgreSQL and provide the necessary database connection URL. SQLite and MySQL configurations are also commented.

```toml
[persistence]
mode = "postgres"               # sqlite | postgres | mysql
database_url = "postgres://user:pass@db:5432/clewdr"

# SQLite 可选：使用绝对路径自动展开为 sqlite://...?... 并创建目录
# sqlite_path = "/var/lib/clewdr/clewdr.db"

```

--------------------------------

### Get ClewdR Version (Bash)

Source: https://context7.com/xerxes-2/clewdr/llms.txt

Retrieves the current version information of the ClewdR application via a simple GET request.

```bash
curl -X GET http://127.0.0.1:8484/api/version
```

--------------------------------

### ClewdR Environment Variables Configuration

Source: https://github.com/xerxes-2/clewdr/blob/master/wiki/hf-space.md

This snippet shows the basic environment variables for configuring ClewdR, including API keys, passwords, and cookie arrays. Sensitive information like passwords and cookies should be stored in secrets.

```env
CLEWDR_COOKIE_ARRAY=[[cookie1],[cookie2]]
CLEWDR_PASSWORD=your_secure_password
CLEWDR_ADMIN_PASSWORD=your_admin_password
```

--------------------------------

### Check Database Status (Bash)

Source: https://context7.com/xerxes-2/clewdr/llms.txt

Gets the current status, health, and performance metrics of the database connection via a GET request. The response varies based on whether the database is enabled and its mode (e.g., postgres, file). Includes details on connection, write errors, and write statistics.

```bash
curl -X GET http://127.0.0.1:8484/api/storage/status
```

--------------------------------

### POST /v1/vertex/v1beta/{*path} - Vertex AI with OAuth2

Source: https://context7.com/xerxes-2/clewdr/llms.txt

Access Google Vertex AI with service account authentication for enterprise deployments. Requires initial credential setup.

```APIDOC
## POST /v1/vertex/v1beta/{*path} - Vertex AI with OAuth2

### Description
Access Google Vertex AI with service account authentication for enterprise deployments. This involves first setting up credentials via the admin API and then using the Vertex AI endpoint.

### Method
POST

### Endpoint
`/v1/vertex/v1beta/projects/{project_id}/locations/{location}/publishers/{publisher}/models/{model_id}:generateContent`

### Parameters
#### Path Parameters
- `*path` (string) - Required - The rest of the path for the Vertex AI API, including project, location, publisher, and model.

#### Query Parameters
- `key` (string) - Required - Your API password for authentication.

#### Request Body
- **contents** (array) - Required - The content to send to the model.
  - **parts** (array) - Required - An array of parts for the content.
    - **text** (string) - Required - The text content for a part.

### Request Example (Credential Setup)
```bash
curl -X POST http://127.0.0.1:8484/api/vertex/credential \
  -H "Authorization: Bearer your-admin-password" \
  -H "Content-Type: application/json" \
  -d '{
    "credential": {
      "type": "service_account",
      "project_id": "my-gcp-project",
      "private_key_id": "key-id-123",
      "private_key": "-----BEGIN PRIVATE KEY-----\n...\n-----END PRIVATE KEY-----\n",
      "client_email": "service-account@my-project.iam.gserviceaccount.com",
      "client_id": "123456789",
      "auth_uri": "https://accounts.google.com/o/oauth2/auth",
      "token_uri": "https://oauth2.googleapis.com/token"
    }
  }'
```

### Request Example (Vertex AI Endpoint)
```bash
curl -X POST "http://127.0.0.1:8484/v1/vertex/v1beta/projects/my-gcp-project/locations/us-central1/publishers/google/models/gemini-2.0-flash-exp:generateContent?key=your-api-password" \
  -H "Content-Type: application/json" \
  -d '{
    "contents": [
      {"parts": [{"text": "Analyze this business model"}]}
    ]
  }'
```

### Response
#### Success Response (200)
Responses follow the Gemini native format.
```

--------------------------------

### Integrate ESLint for React-Specific Rules

Source: https://github.com/xerxes-2/clewdr/blob/master/frontend/README.md

This snippet shows how to integrate the 'eslint-plugin-react-x' and 'eslint-plugin-react-dom' plugins into an ESLint configuration for a React project. It adds the plugins to the configuration and enables their recommended TypeScript and DOM-specific rules, respectively. This enhances linting for React components and their usage.

```javascript
// eslint.config.js
import reactX from "eslint-plugin-react-x";
import reactDom from "eslint-plugin-react-dom";

export default tseslint.config({
  plugins: {
    // Add the react-x and react-dom plugins
    "react-x": reactX,
    "react-dom": reactDom,
  },
  rules: {
    // other rules...
    // Enable its recommended typescript rules
    ...reactX.configs["recommended-typescript"].rules,
    ...reactDom.configs.recommended.rules,
  },
});
```

--------------------------------

### List Vertex AI Credentials (Bash)

Source: https://context7.com/xerxes-2/clewdr/llms.txt

Retrieves a list of all configured Vertex AI service account credentials using a GET request. Excludes sensitive private key information, returning only client email, project ID, and private key ID. Requires administrator authentication.

```bash
curl -X GET http://127.0.0.1:8484/api/vertex/credentials \
  -H "Authorization: Bearer your-admin-password"
```

--------------------------------

### GET /api/config - Retrieve Current Configuration

Source: https://context7.com/xerxes-2/clewdr/llms.txt

Fetch the current ClewdR configuration with sensitive fields removed. This endpoint provides insights into the proxy's operational settings.

```APIDOC
## GET /api/config - Retrieve Current Configuration

### Description
Fetch the current ClewdR configuration with sensitive fields removed. This endpoint provides insights into the proxy's operational settings.

### Method
GET

### Endpoint
`/api/config`

### Parameters
#### Query Parameters
None.

#### Request Body
None.

### Request Example
```bash
curl -X GET http://127.0.0.1:8484/api/config \
  -H "Authorization: Bearer your-admin-password"
```

### Response
#### Success Response (200)
- **ip** (string) - The IP address the proxy is listening on.
- **port** (integer) - The port the proxy is listening on.
- **admin_password** (string) - The admin password for the proxy (masked).
- **api_password** (string) - The API password for the proxy (masked).
- **max_retries** (integer) - Maximum number of retries for upstream requests.
- **check_update** (boolean) - Whether to check for updates automatically.
- **log_to_file** (boolean) - Whether to log output to a file.
- **no_fs** (boolean) - Whether to disable filesystem access.
- **skip_cool_down** (boolean) - Whether to skip cooldown periods between requests.
- **use_real_roles** (boolean) - Whether to use real roles for authentication.
- **upstream_proxy** (string or null) - The URL of an upstream proxy, if configured.
- **custom_endpoint** (string or null) - A custom endpoint configuration, if set.
- **persistence** (object) - Persistence settings.
  - **mode** (string) - The persistence mode ('file', 'database', etc.).
  - **database_url** (string or null) - The database URL, if applicable.
  - **sqlite_path** (string or null) - The path to the SQLite database file, if applicable.

#### Response Example
```json
{
  "ip": "127.0.0.1",
  "port": 8484,
  "admin_password": "your-admin-password",
  "api_password": "your-api-password",
  "max_retries": 5,
  "check_update": true,
  "log_to_file": false,
  "no_fs": false,
  "skip_cool_down": false,
  "use_real_roles": false,
  "upstream_proxy": null,
  "custom_endpoint": null,
  "persistence": {
    "mode": "file",
    "database_url": null,
    "sqlite_path": null
  }
}
```
```

--------------------------------

### GET Retrieve Current Configuration

Source: https://context7.com/xerxes-2/clewdr/llms.txt

Fetch the current configuration of the ClewdR proxy. This endpoint requires an admin password for authentication and returns a JSON object with all configuration settings, excluding sensitive details like passwords where applicable.

```bash
curl -X GET http://127.0.0.1:8484/api/config \
  -H "Authorization: Bearer your-admin-password"
```

--------------------------------

### POST Vertex AI - Generate Content

Source: https://context7.com/xerxes-2/clewdr/llms.txt

Access Google Vertex AI for content generation using the Gemini model. This endpoint requires prior credential setup via the admin API and uses OAuth2 authentication. The request payload is similar to the Gemini native format.

```bash
curl -X POST "http://127.0.0.1:8484/v1/vertex/v1beta/projects/my-gcp-project/locations/us-central1/publishers/google/models/gemini-2.0-flash-exp:generateContent?key=your-api-password" \
  -H "Content-Type: application/json" \
  -d '{
    "contents": [
      {"parts": [{"text": "Analyze this business model"}]}
    ]
  }'
```

--------------------------------

### Extend ESLint for Type-Checked React Linting

Source: https://github.com/xerxes-2/clewdr/blob/master/frontend/README.md

This snippet demonstrates how to extend the ESLint configuration in a React + TypeScript + Vite project to include type-aware lint rules. It requires the '@typescript-eslint/eslint-plugin' and provides options for recommended, stricter, and stylistic type-checked rules. The configuration specifies project files for type checking.

```javascript
export default tseslint.config({
  extends: [
    // Remove ...tseslint.configs.recommended and replace with this
    ...tseslint.configs.recommendedTypeChecked,
    // Alternatively, use this for stricter rules
    ...tseslint.configs.strictTypeChecked,
    // Optionally, add this for stylistic rules
    ...tseslint.configs.stylisticTypeChecked,
  ],
  languageOptions: {
    // other options...
    parserOptions: {
      project: ["./tsconfig.node.json", "./tsconfig.app.json"],
      tsconfigRootDir: import.meta.dirname,
    },
  },
});
```

--------------------------------

### 检查系统架构 - Bash

Source: https://github.com/xerxes-2/clewdr/blob/master/wiki/bt-clewdr.md

此命令用于检查服务器的系统架构，输出结果如 x86_64 或 arm64。这是选择正确 clewdr 二进制文件的重要依据。无需特殊依赖，直接在终端执行。

```bash
uname -m
```

--------------------------------

### Import Data to Database (Bash)

Source: https://context7.com/xerxes-2/clewdr/llms.txt

Imports configuration, cookies, and keys from the `clewdr.toml` file into the database using a POST request. This operation is only available if the application was compiled with database support (e.g., `db-sqlite`, `db-postgres`, `db-mysql`) and the `persistence.mode` is configured accordingly. Requires administrator authentication.

```bash
curl -X POST http://127.0.0.1:8484/api/storage/import \
  -H "Authorization: Bearer your-admin-password"
```

--------------------------------

### Build with Database Features (Rust/Cargo)

Source: https://github.com/xerxes-2/clewdr/blob/master/wiki/database.md

Build ClewdR from source with specific database features enabled using Cargo. This allows the pre-compiled binary to support database persistence. Ensure to include `db-*` features like `db-postgres` for the desired database driver.

```bash
cargo build --release --no-default-features --features "embed-resource,xdg,db-postgres"
```

--------------------------------

### Run ClewdR Executable

Source: https://github.com/xerxes-2/clewdr/blob/master/README.md

This command executes the ClewdR binary. Ensure it is in your system's PATH or run it from the directory where it's located. No arguments are typically needed for basic execution.

```bash
./clewdr
```

--------------------------------

### GET /v1/models - List Available Models

Source: https://context7.com/xerxes-2/clewdr/llms.txt

Retrieve the list of available Claude models through the proxy. This endpoint provides information about the models accessible via the ClewdR proxy.

```APIDOC
## GET /v1/models - List Available Models

### Description
Retrieve the list of available Claude models through the proxy. This endpoint provides information about the models accessible via the ClewdR proxy.

### Method
GET

### Endpoint
`/v1/models`

### Parameters
#### Query Parameters
None.

#### Request Body
None.

### Request Example
```bash
curl -X GET http://127.0.0.1:8484/v1/models \
  -H "Authorization: Bearer your-api-password"
```

### Response
#### Success Response (200)
- **object** (string) - The type of object returned ('list').
- **data** (array) - An array of model objects.
  - **id** (string) - The unique identifier of the model.
  - **object** (string) - The type of object ('model').
  - **created** (integer) - Timestamp of model creation (usually 0 for proxy-provided models).
  - **owned_by** (string) - Indicates the owner of the model ('clewdr' in this case).

#### Response Example
```json
{
  "object": "list",
  "data": [
    {
      "id": "claude-3-7-sonnet-20250219",
      "object": "model",
      "created": 0,
      "owned_by": "clewdr"
    },
    {
      "id": "claude-sonnet-4-20250514",
      "object": "model",
      "created": 0,
      "owned_by": "clewdr"
    },
    {
      "id": "claude-sonnet-4-20250514-thinking",
      "object": "model",
      "created": 0,
      "owned_by": "clewdr"
    },
    {
      "id": "claude-opus-4-20250514",
      "object": "model",
      "created": 0,
      "owned_by": "clewdr"
    }
  ]
}
```
```

--------------------------------

### Configure Cursor IDE with Local API

Source: https://github.com/xerxes-2/clewdr/blob/master/README_zh.md

This JSON configuration is for the Cursor IDE to connect to a local OpenAI-compatible API. It requires setting the `openaiApiBase` and `openaiApiKey` to point to your local service. Replace "控制台显示的API密码" with your actual API key.

```json
{
  "openaiApiBase": "http://127.0.0.1:8484/v1/",
  "openaiApiKey": "控制台显示的API密码"
}
```

--------------------------------

### 下载和运行 ClewdR (Bash)

Source: https://github.com/xerxes-2/clewdr/blob/master/README_zh.md

此代码段展示了如何在 Linux 或 macOS 系统上下载、解压、赋予执行权限并运行 ClewdR 可执行文件。它包含了使用 `wget` 下载预编译二进制文件，使用 `tar` 解压，以及使用 `chmod` 命令来设置文件权限。

```bash
# 下载对应平台的最新版本
wget https://github.com/Xerxes-2/clewdr/releases/latest/download/clewdr-[平台]

# 如果需要，解压二进制文件
tar -xzf clewdr-[平台].tar.gz

# 进入目录
cd clewdr-[平台]

# 赋予执行权限 (Linux/macOS)
chmod +x clewdr

# 运行 ClewdR
./clewdr
```

--------------------------------

### GET List Available Models - Claude

Source: https://context7.com/xerxes-2/clewdr/llms.txt

Retrieve a list of available Claude models accessible through the ClewdR proxy. This endpoint requires API password authentication and returns a JSON object containing model details.

```bash
curl -X GET http://127.0.0.1:8484/v1/models \
  -H "Authorization: Bearer your-api-password"
```

--------------------------------

### POST /v1/v1beta/{*path} - Gemini AI Studio Native Format

Source: https://context7.com/xerxes-2/clewdr/llms.txt

Access Google Gemini AI Studio API through ClewdR proxy with automatic key rotation. Supports standard and streaming content generation.

```APIDOC
## POST /v1/v1beta/{*path} - Gemini AI Studio Native Format

### Description
Access Google Gemini AI Studio API through ClewdR proxy with automatic key rotation. This endpoint allows for content generation using Gemini models.

### Method
POST

### Endpoint
`/v1/v1beta/{*path}`

### Parameters
#### Path Parameters
- `*path` (string) - Required - The rest of the path for the Gemini API.

#### Query Parameters
- `key` (string) - Required - Your API password for authentication.

#### Request Body
- **contents** (array) - Required - The content to send to the model.
  - **parts** (array) - Required - An array of parts for the content.
    - **text** (string) - Required - The text content for a part.
- **generationConfig** (object) - Optional - Configuration for content generation.
  - **temperature** (number) - Optional - Controls randomness. Higher values mean more random.
  - **maxOutputTokens** (integer) - Optional - The maximum number of tokens to generate.

### Request Example
```json
{
  "contents": [
    {
      "parts": [
        {"text": "Write a haiku about programming"}
      ]
    }
  ],
  "generationConfig": {
    "temperature": 0.9,
    "maxOutputTokens": 256
  }
}
```

### Response
#### Success Response (200)
- **candidates** (array) - The generated content candidates.
  - **content** (object) - The generated content.
    - **parts** (array) - The parts of the generated content.
      - **text** (string) - The text of the generated part.
      - **role** (string) - The role of the content ('model' or 'user').
    - **role** (string) - The role of the candidate ('model').
  - **finishReason** (string) - The reason the generation finished.
  - **safetyRatings** (array) - Safety ratings for the generated content.
- **usageMetadata** (object) - Information about token usage.
  - **promptTokenCount** (integer) - The number of tokens in the prompt.
  - **candidatesTokenCount** (integer) - The number of tokens in the candidates.
  - **totalTokenCount** (integer) - The total number of tokens used.

#### Response Example
```json
{
  "candidates": [
    {
      "content": {
        "parts": [
          {"text": "Code flows like streams\nBugs hide in silent shadows\nDebug finds the light"}
        ],
        "role": "model"
      },
      "finishReason": "STOP",
      "safetyRatings": []
    }
  ],
  "usageMetadata": {
    "promptTokenCount": 8,
    "candidatesTokenCount": 15,
    "totalTokenCount": 23
  }
}
```

### Streaming Request Example
```bash
curl -X POST "http://127.0.0.1:8484/v1/v1beta/models/gemini-2.0-flash-exp:streamGenerateContent?key=your-api-password" \
  -H "Content-Type: application/json" \
  -d '{
    "contents": [{"parts": [{"text": "Count from 1 to 3"}]}] 
  }'
```
```

--------------------------------

### Environment Variables for ClewdR Configuration

Source: https://context7.com/xerxes-2/clewdr/llms.txt

Demonstrates how to override ClewdR's configuration settings using environment variables. This includes network settings, authentication, and persistence modes.

```bash
# Override config via environment (uses Figment double-underscore syntax)
export CLEWDR_IP=0.0.0.0
export CLEWDR_PORT=8080
export CLEWDR_ADMIN_PASSWORD=custom-admin-pass
export CLEWDR_API_PASSWORD=custom-api-pass
export CLEWDR_MAX_RETRIES=3
export CLEWDR_LOG_TO_FILE=true
export CLEWDR_UPSTREAM_PROXY=http://proxy.example.com:8080
export CLEWDR_PERSISTENCE__MODE=postgres
export CLEWDR_PERSISTENCE__DATABASE_URL=postgres://user:pass@db:5432/clewdr

# Run ClewdR
./clewdr

```

--------------------------------

### Verify Authentication (Bash)

Source: https://context7.com/xerxes-2/clewdr/llms.txt

Tests the validity of an administrator token by making a GET request to the authentication endpoint. A 200 OK response indicates a valid token, while a 401 Unauthorized response signifies an invalid or expired token.

```bash
curl -X GET http://127.0.0.1:8484/api/auth \
  -H "Authorization: Bearer your-admin-password"
```

--------------------------------

### Continue VSCode Extension Configuration for ClewdR

Source: https://context7.com/xerxes-2/clewdr/llms.txt

JSON configuration for the Continue VSCode extension to use ClewdR as a model provider. It details the model title, provider, model name, API base URL, and API key.

```json
{
  "models": [
    {
      "title": "Claude via ClewdR",
      "provider": "openai",
      "model": "claude-sonnet-4-20250514",
      "apiBase": "http://127.0.0.1:8484/v1/",
      "apiKey": "your-api-password"
    }
  ]
}

```

--------------------------------

### JavaScript for Batch Cookie Processing

Source: https://github.com/xerxes-2/clewdr/blob/master/wiki/hf-space.md

A JavaScript snippet to process raw cookie input (multiple lines or comma-separated) into a JSON array format suitable for the CLEWDR_COOKIE_ARRAY environment variable. This utility runs in the browser's developer console.

```javascript
(async function() {
  const raw = `
sk-ant-sid01-CV27
sk-ant-sid01-XYZ9
`.trim(); // ← 替换为你的 cookie 原始输入

  const cookies = raw
    .split('\n')
    .flatMap(line => line.split(','))
    .map(c => c.trim())
    .filter(Boolean)
    .map(c => [c]);

  const json = JSON.stringify(cookies);
  await navigator.clipboard.writeText(json);
  console.log("已处理并复制到剪贴板：", json);
})();

```

--------------------------------

### Build ClewdR with SQLite Database Feature

Source: https://github.com/xerxes-2/clewdr/blob/master/README.md

Command to build ClewdR from source with the SQLite database persistence feature enabled. This is an alternative to file-based persistence and requires specifying the feature flag during compilation.

```bash
cargo build --release --no-default-features --features "embed-resource,xdg,db-sqlite"
```

--------------------------------

### ClewdR API 端点 (Bash)

Source: https://github.com/xerxes-2/clewdr/blob/master/README_zh.md

此代码段列出了 ClewdR 提供的各种 API 端点，包括 Claude 和 Gemini 的原生格式以及 OpenAI 兼容格式。这些端点可用于将应用程序连接到 ClewdR 代理服务器。

```bash
# Claude 端点
Claude Web:    http://127.0.0.1:8484/v1/messages          # 原生格式
Claude OpenAI: http://127.0.0.1:8484/v1/chat/completions  # OpenAI兼容
Claude Code:   http://127.0.0.1:8484/code/v1/messages     # Claude Code

# Gemini 端点
Gemini Native: http://127.0.0.1:8484/v1/v1beta/generateContent    # 原生格式
Gemini OpenAI: http://127.0.0.1:8484/gemini/chat/completions      # OpenAI兼容
Vertex AI:     http://127.0.0.1:8484/v1/vertex/v1beta/            # Vertex AI
```

--------------------------------

### Configuration Settings for ClewdR

Source: https://context7.com/xerxes-2/clewdr/llms.txt

Defines core behavior settings, proxy configurations, database persistence options, and credentials for ClewdR. These settings control aspects like retry mechanisms, logging, database mode, and API endpoints.

```toml
# Behavior settings
max_retries = 5
check_update = true
log_to_file = false
no_fs = false
skip_cool_down = false
use_real_roles = false

# Optional proxy for upstream requests
upstream_proxy = "http://proxy.example.com:8080"

# Optional custom Claude endpoint
custom_endpoint = "https://custom-claude-api.com"

# Database persistence (requires db-* feature)
[persistence]
mode = "postgres"  # file | sqlite | postgres | mysql
database_url = "postgres://user:pass@localhost:5432/clewdr"
# OR for SQLite:
# mode = "sqlite"
# sqlite_path = "/var/lib/clewdr/clewdr.db"

# Vertex AI credentials (managed via API)
[vertex]
credentials = []  # populated via /api/vertex/credential endpoint

# Runtime state (managed by actors)
cookie_array = []  # managed by CookieActor
wasted_cookie = []  # exhausted cookies with reset times
gemini_keys = []  # managed by KeyActor

```

--------------------------------

### Cursor IDE Configuration for ClewdR

Source: https://context7.com/xerxes-2/clewdr/llms.txt

JSON configuration for Cursor IDE to integrate with ClewdR. It sets the OpenAI API base URL, API key, and the specific model to be used.

```json
{
  "openaiApiBase": "http://127.0.0.1:8484/v1/",
  "openaiApiKey": "your-api-password",
  "openaiModel": "claude-sonnet-4-20250514"
}

```

--------------------------------

### POST /api/config

Source: https://context7.com/xerxes-2/clewdr/llms.txt

Updates the ClewdR configuration with hot reload support.

```APIDOC
## POST /api/config - Update Configuration

### Description
Update ClewdR configuration with hot reload (no restart required).

### Method
POST

### Endpoint
/api/config

### Parameters
#### Query Parameters
None

#### Request Body
- **ip** (string) - The IP address to bind to.
- **port** (integer) - The port to listen on.
- **admin_password** (string) - The new admin password.
- **api_password** (string) - The new API password.
- **max_retries** (integer) - Maximum number of retries for requests.
- **check_update** (boolean) - Whether to check for updates.
- **log_to_file** (boolean) - Whether to log to a file.
- **upstream_proxy** (string, optional) - URL of the upstream proxy.
- **custom_endpoint** (string, optional) - Custom endpoint for Claude.

### Request Example
```json
{
  "ip": "0.0.0.0",
  "port": 8484,
  "admin_password": "new-admin-pass",
  "api_password": "new-api-pass",
  "max_retries": 3,
  "check_update": true,
  "log_to_file": true,
  "upstream_proxy": "http://proxy.example.com:8080",
  "custom_endpoint": "https://custom-claude-endpoint.com"
}
```

### Response
#### Success Response (200)
- **message** (string) - Confirmation message.
- **config** (object) - The updated configuration object.

#### Response Example
```json
{
  "message": "Config updated successfully",
  "config": {
    "ip": "0.0.0.0",
    "port": 8484,
    "admin_password": "********",
    "api_password": "********",
    "max_retries": 3,
    "check_update": true,
    "log_to_file": true,
    "upstream_proxy": "http://proxy.example.com:8080",
    "custom_endpoint": "https://custom-claude-endpoint.com"
  }
}
```
```

--------------------------------

### 检查 glibc 版本 - Bash

Source: https://github.com/xerxes-2/clewdr/blob/master/wiki/bt-clewdr.md

此命令用于检查系统当前安装的 glibc 版本。该版本信息对于判断是否需要下载 musl 版本的 clewdr 至关重要，以避免运行时出现 GLIBC_X.XX not found 错误。无需特殊依赖。

```bash
ldd --version
```

--------------------------------

### Cursor IDE Configuration for ClewdR

Source: https://github.com/xerxes-2/clewdr/blob/master/README.md

Configuration for the Cursor IDE to connect to ClewdR's OpenAI-compatible endpoint. Requires the OpenAI API base URL and the API key obtained from the console.

```json
{
  "openaiApiBase": "http://127.0.0.1:8484/v1/",
  "openaiApiKey": "your-api-password-from-console"
}
```

--------------------------------

### Authentication and Utilities API

Source: https://context7.com/xerxes-2/clewdr/llms.txt

Endpoints for verifying authentication and retrieving the ClewdR version.

```APIDOC
## GET /api/auth - Verify Authentication

### Description
Test if the provided admin token is valid.

### Method
GET

### Endpoint
`/api/auth`

### Parameters
#### Headers
- **Authorization**: `Bearer your-admin-password` - Required

### Response
#### Success Response (200 OK)
Indicates a valid admin token.

#### Error Response (401 Unauthorized)
Indicates an invalid admin token.
```

```APIDOC
## GET /api/version - Get ClewdR Version

### Description
Retrieve the current version information of ClewdR.

### Method
GET

### Endpoint
`/api/version`

### Response
#### Success Response (200 OK)
A string representing the ClewdR version.

#### Response Example
```
"ClewdR v0.11.18"
```
```

--------------------------------

### Export Data from Database (Bash)

Source: https://context7.com/xerxes-2/clewdr/llms.txt

Exports the current database state to the `clewdr.toml` file using a POST request. This is useful for creating backups, migrating back to file mode, or generating portable configuration snapshots. Requires administrator authentication.

```bash
curl -X POST http://127.0.0.1:8484/api/storage/export \
  -H "Authorization: Bearer your-admin-password"
```

--------------------------------

### Database Persistence Operations API

Source: https://context7.com/xerxes-2/clewdr/llms.txt

Endpoints for checking database status, importing data, and exporting data to a file.

```APIDOC
## GET /api/storage/status - Check Database Status

### Description
Get the current database connection status, health, and performance metrics.

### Method
GET

### Endpoint
`/api/storage/status`

### Response
#### Success Response (200 OK)
- **enabled** (boolean) - Indicates if the database persistence is enabled.
- **mode** (string) - The current persistence mode (e.g., "postgres", "file").
- **healthy** (boolean) - Indicates if the database is healthy.
- **details** (object) - Database-specific details.
  - **driver** (string) - The database driver name.
  - **url** (string) - The database connection URL (if enabled).
- **write_error_count** (integer) - The number of write errors.
- **total_writes** (integer) - The total number of write operations.
- **avg_write_ms** (float) - The average time in milliseconds for write operations.
- **failure_ratio** (float) - The ratio of failed write operations.
- **last_write_ts** (integer) - The timestamp of the last write operation.

#### Response Example (Database Enabled)
```json
{
  "enabled": true,
  "mode": "postgres",
  "healthy": true,
  "details": {
    "driver": "postgres",
    "url": "postgres://user@host:5432/clewdr"
  },
  "write_error_count": 0,
  "total_writes": 1523,
  "avg_write_ms": 12.5,
  "failure_ratio": 0.0,
  "last_write_ts": 1729267890
}
```
#### Response Example (File Mode)
```json
{
  "enabled": false,
  "mode": "file",
  "healthy": true,
  "details": {
    "driver": "file"
  },
  "write_error_count": 0,
  "total_writes": 0,
  "avg_write_ms": 0.0,
  "failure_ratio": 0.0,
  "last_write_ts": 0
}
```

## POST /api/storage/import - Import from File to Database

### Description
Import configuration, cookies, and keys from a `clewdr.toml` file into the database. This operation is only available when the application is compiled with database features (e.g., `db-sqlite`, `db-postgres`, `db-mysql`) and the persistence mode is set to the corresponding database type.

### Method
POST

### Endpoint
`/api/storage/import`

### Parameters
#### Headers
- **Authorization**: `Bearer your-admin-password` - Required

### Response
#### Success Response (200 OK)
- **status** (string) - The status of the import operation (e.g., "success").
- **imported** (object) - A summary of imported items.
  - **cookies** (integer) - Number of cookies imported.
  - **keys** (integer) - Number of keys imported.
  - **vertex_credentials** (integer) - Number of Vertex AI credentials imported.
  - **config_keys** (integer) - Number of configuration keys imported.
- **message** (string) - A confirmation message.

#### Response Example
```json
{
  "status": "success",
  "imported": {
    "cookies": 5,
    "keys": 3,
    "vertex_credentials": 1,
    "config_keys": 12
  },
  "message": "Configuration imported from file to database successfully"
}
```

## POST /api/storage/export - Export from Database to File

### Description
Export the current database state to a `clewdr.toml` file. This is useful for backing up the database, migrating back to file mode, or creating portable configuration snapshots.

### Method
POST

### Endpoint
`/api/storage/export`

### Parameters
#### Headers
- **Authorization**: `Bearer your-admin-password` - Required

### Response
#### Success Response (200 OK)
- **status** (string) - The status of the export operation (e.g., "success").
- **exported** (object) - A summary of exported items.
  - **cookies** (integer) - Number of cookies exported.
  - **keys** (integer) - Number of keys exported.
  - **vertex_credentials** (integer) - Number of Vertex AI credentials exported.
  - **config_keys** (integer) - Number of configuration keys exported.
- **file_path** (string) - The path to the exported `clewdr.toml` file.
- **message** (string) - A confirmation message.

#### Response Example
```json
{
  "status": "success",
  "exported": {
    "cookies": 5,
    "keys": 3,
    "vertex_credentials": 1,
    "config_keys": 12
  },
  "file_path": "/etc/clewdr/clewdr.toml",
  "message": "Configuration exported from database to file successfully"
}
```
```

--------------------------------

### POST Gemini AI Studio Native Format - Generate Content

Source: https://context7.com/xerxes-2/clewdr/llms.txt

Access Google Gemini AI Studio API for content generation using its native format. This endpoint supports automatic key rotation and requires a JSON payload with content and generation configuration. The response includes generated content and usage metadata.

```bash
curl -X POST "http://127.0.0.1:8484/v1/v1beta/models/gemini-2.0-flash-exp:generateContent?key=your-api-password" \
  -H "Content-Type: application/json" \
  -d '{
    "contents": [
      {
        "parts": [
          {"text": "Write a haiku about programming"}
        ]
      }
    ],
    "generationConfig": {
      "temperature": 0.9,
      "maxOutputTokens": 256
    }
  }'
```

--------------------------------

### POST /v1/chat/completions - OpenAI Compatible Format (Claude)

Source: https://context7.com/xerxes-2/clewdr/llms.txt

Use Claude through OpenAI-compatible API endpoints for drop-in replacement in existing applications. Supports 'Extended Thinking' mode.

```APIDOC
## POST /v1/chat/completions - OpenAI Compatible Format (Claude)

### Description
Use Claude through OpenAI-compatible API endpoints for drop-in replacement in existing applications. Supports 'Extended Thinking' mode by appending '-thinking' to the model name.

### Method
POST

### Endpoint
`/v1/chat/completions`

### Parameters
#### Query Parameters
None

#### Request Body
- **model** (string) - Required - The model to use (e.g., `claude-sonnet-4-20250514` or `claude-sonnet-4-20250514-thinking`).
- **messages** (array) - Required - An array of message objects, each with a `role` (`system`, `user`, or `assistant`) and `content` (string).
- **max_tokens** (integer) - Required - The maximum number of tokens to generate.
- **temperature** (number) - Optional - Controls randomness; higher values mean more random output.
- **stream** (boolean) - Optional - Whether to stream the response.
- **reasoning_effort** (string) - Optional - Used with '-thinking' models to control the depth of reasoning (e.g., `low`, `medium`, `high`).

### Request Example
```json
{
  "model": "claude-sonnet-4-20250514",
  "messages": [
    {"role": "system", "content": "You are a helpful assistant."},
    {"role": "user", "content": "What is 2+2?"}
  ],
  "max_tokens": 1024,
  "temperature": 0.5,
  "stream": false
}
```

### Response
#### Success Response (200)
- **id** (string) - Unique completion identifier.
- **object** (string) - Type of object (`chat.completion`).
- **created** (integer) - Timestamp of creation.
- **model** (string) - The model used.
- **choices** (array) - An array of completion choices.
  - **index** (integer) - Index of the choice.
  - **message** (object) - The generated message (`role`, `content`).
  - **finish_reason** (string) - Reason for finishing generation (e.g., `stop`, `max_tokens`).
- **usage** (object) - Token usage information (`prompt_tokens`, `completion_tokens`, `total_tokens`).

#### Response Example
```json
{
  "id": "chatcmpl-abc123",
  "object": "chat.completion",
  "created": 1234567890,
  "model": "claude-sonnet-4-20250514",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "2+2 equals 4."
      },
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 20,
    "completion_tokens": 6,
    "total_tokens": 26
  }
}
```

#### Extended Thinking Mode Example
```json
{
  "model": "claude-sonnet-4-20250514-thinking",
  "messages": [{"role": "user", "content": "Solve x^2 + 5x + 6 = 0"}],
  "reasoning_effort": "medium",
  "max_tokens": 4096
}
```
```
Tokens:
Raw