torbjorn/antigravity-claude-proxy
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

feat(webui): update README with comprehensive documentation for WebUI features and usage

Browse Source
This commit is contained in:
Wha1eChai
2026-01-09 23:22:28 +08:00
parent 48ad476b5f
commit 98685241e8
8 changed files with 123 additions and 72 deletions
Download Patch File Download Diff File Expand all files Collapse all files

184
README.md
View File

@@ -59,62 +59,7 @@ npm start
## Quick Start
### 1. Add Account(s)
You have two options:
**Option A: Use Antigravity (Single Account)**
If you have Antigravity installed and logged in, the proxy will automatically extract your token. No additional setup needed.
**Option B: Add Google Accounts via OAuth (Recommended for Multi-Account)**
Add one or more Google accounts for load balancing.
#### Desktop/Laptop (with browser)
```bash
# If installed via npm
antigravity-claude-proxy accounts add
# If using npx
npx antigravity-claude-proxy@latest accounts add
# If cloned locally
npm run accounts:add
```
This opens your browser for Google OAuth. Sign in and authorize access. Repeat for multiple accounts.
#### Headless Server (Docker, SSH, no desktop)
```bash
# If installed via npm
antigravity-claude-proxy accounts add --no-browser
# If using npx
npx antigravity-claude-proxy@latest accounts add -- --no-browser
# If cloned locally
npm run accounts:add -- --no-browser
```
This displays an OAuth URL you can open on another device (phone/laptop). After signing in, copy the redirect URL or authorization code and paste it back into the terminal.
#### Manage accounts
```bash
# List all accounts
antigravity-claude-proxy accounts list
# Verify accounts are working
antigravity-claude-proxy accounts verify
# Interactive account management
antigravity-claude-proxy accounts
```
### 2. Start the Proxy Server
### 1. Start the Proxy Server
```bash
# If installed via npm
@@ -129,6 +74,34 @@ npm start
The server runs on `http://localhost:8080` by default.
### 2. Link Account(s)
Choose one of the following methods to authorize the proxy:
#### **Method A: Web Dashboard (Recommended)**
1. With the proxy running, open `http://localhost:8080` in your browser.
2. Navigate to the **Accounts** tab and click **Add Account**.
3. Complete the Google OAuth authorization in the popup window.
#### **Method B: CLI (Desktop or Headless)**
If you prefer the terminal or are on a remote server:
```bash
# Desktop (opens browser)
antigravity-claude-proxy accounts add
# Headless (Docker/SSH)
antigravity-claude-proxy accounts add --no-browser
```
> For full CLI account management options, run `antigravity-claude-proxy accounts --help`.
#### **Method C: Automatic (Antigravity Users)**
If you have the **Antigravity** app installed and logged in, the proxy will automatically detect your local session. No additional setup is required.
### 3. Verify It's Working
```bash
@@ -145,6 +118,18 @@ curl "http://localhost:8080/account-limits?format=table"
### Configure Claude Code
You can configure these settings in two ways:
#### **Via Web Console (Recommended)**
1. Open the WebUI at `http://localhost:8080`.
2. Go to **Settings** → **Claude CLI**.
3. Select your preferred models and click **Apply to Claude CLI**.
> [!TIP] > **Configuration Precedence**: System environment variables (set in shell profile like `.zshrc`) take precedence over the `settings.json` file. If you use the Web Console to manage settings, ensure you haven't manually exported conflicting variables in your terminal.
#### **Manual Configuration**
Create or edit the Claude Code settings file:
**macOS:** `~/.claude/settings.json`
@@ -236,18 +221,18 @@ claude
### Claude Models
| Model ID | Description |
|----------|-------------|
| Model ID | Description |
| ---------------------------- | ---------------------------------------- |
| `claude-sonnet-4-5-thinking` | Claude Sonnet 4.5 with extended thinking |
| `claude-opus-4-5-thinking` | Claude Opus 4.5 with extended thinking |
| `claude-sonnet-4-5` | Claude Sonnet 4.5 without thinking |
| `claude-opus-4-5-thinking` | Claude Opus 4.5 with extended thinking |
| `claude-sonnet-4-5` | Claude Sonnet 4.5 without thinking |
### Gemini Models
| Model ID | Description |
|----------|-------------|
| `gemini-3-flash` | Gemini 3 Flash with thinking |
| `gemini-3-pro-low` | Gemini 3 Pro Low with thinking |
| Model ID | Description |
| ------------------- | ------------------------------- |
| `gemini-3-flash` | Gemini 3 Flash with thinking |
| `gemini-3-pro-low` | Gemini 3 Pro Low with thinking |
| `gemini-3-pro-high` | Gemini 3 Pro High with thinking |
Gemini models include full thinking support with `thoughtSignature` handling for multi-turn conversations.
@@ -267,20 +252,71 @@ When you add multiple accounts, the proxy automatically:
Check account status anytime:
```bash
# Web UI: http://localhost:8080/ (Accounts tab)
# CLI Table:
curl "http://localhost:8080/account-limits?format=table"
```
#### CLI Management Reference
If you prefer using the terminal for management:
```bash
# List all accounts
antigravity-claude-proxy accounts list
# Verify account health
antigravity-claude-proxy accounts verify
# Interactive CLI menu
antigravity-claude-proxy accounts
```
---
## Web Management Console
The proxy includes a built-in, modern web interface for real-time monitoring and configuration. Access the console at: `http://localhost:8080` (default port).
![Antigravity Console](images/webui-dashboard.png)
### Key Features
- **Real-time Dashboard**: Monitor request volume, active accounts, and model health.
- **Visual Model Quota**: Track per-model usage and next reset times.
- **Account Management**: Add/remove Google accounts via OAuth without using the CLI.
- **Claude CLI Configuration**: Edit your `~/.claude/settings.json` directly from the browser.
- **Live Logs**: Stream server logs with level-based filtering and search.
- **Advanced Tuning**: Configure retries, timeouts, and debug mode on the fly.
- **Bilingual Interface**: Full support for English and Chinese (switch via Settings).
---
## Advanced Configuration
While most users can use the default settings, you can tune the proxy behavior via the **Settings → Server** tab in the WebUI or by creating a `config.json` file.
### Configurable Options
- **WebUI Password**: Secure your dashboard with `WEBUI_PASSWORD` env var or in config.
- **Custom Port**: Change the default `8080` port.
- **Retry Logic**: Configure `maxRetries`, `retryBaseMs`, and `retryMaxMs`.
- **Load Balancing**: Adjust `defaultCooldownMs` and `maxWaitBeforeErrorMs`.
- **Persistence**: Enable `persistTokenCache` to save OAuth sessions across restarts.
Refer to `config.example.json` for a complete list of fields and documentation.
---
## API Endpoints
| Endpoint | Method | Description |
|----------|--------|-------------|
| `/health` | GET | Health check |
| `/account-limits` | GET | Account status and quota limits (add `?format=table` for ASCII table) |
| `/v1/messages` | POST | Anthropic Messages API |
| `/v1/models` | GET | List available models |
| `/refresh-token` | POST | Force token refresh |
| Endpoint | Method | Description |
| ----------------- | ------ | --------------------------------------------------------------------- |
| `/health` | GET | Health check |
| `/account-limits` | GET | Account status and quota limits (add `?format=table` for ASCII table) |
| `/v1/messages` | POST | Anthropic Messages API |
| `/v1/models` | GET | List available models |
| `/refresh-token` | POST | Force token refresh |
---
@@ -314,6 +350,7 @@ npm run test:caching # Prompt caching
### "Could not extract token from Antigravity"
If using single-account mode with Antigravity:
1. Make sure Antigravity app is installed and running
2. Ensure you're logged in to Antigravity
@@ -322,11 +359,13 @@ Or add accounts via OAuth instead: `antigravity-claude-proxy accounts add`
### 401 Authentication Errors
The token might have expired. Try:
```bash
curl -X POST http://localhost:8080/refresh-token
```
Or re-authenticate the account:
```bash
antigravity-claude-proxy accounts
```
@@ -338,6 +377,7 @@ With multiple accounts, the proxy automatically switches to the next available a
### Account Shows as "Invalid"
Re-authenticate the account:
```bash
antigravity-claude-proxy accounts
# Choose "Re-authenticate" for the invalid account
@@ -404,4 +444,4 @@ MIT
## Star History
[![Star History Chart](https://api.star-history.com/svg?repos=badrisnarayanan/antigravity-claude-proxy&type=date&legend=top-left&cache-control=no-cache)](https://www.star-history.com/#badrisnarayanan/antigravity-claude-proxy&type=date&legend=top-left)
[![Star History Chart](https://api.star-history.com/svg?repos=badrisnarayanan/antigravity-claude-proxy&type=date&legend=top-left&cache-control=no-cache)](https://www.star-history.com/#badrisnarayanan/antigravity-claude-proxy&type=date&legend=top-left)