From f783da238dcc9d47565e83c084b7364a10e3adbb Mon Sep 17 00:00:00 2001 From: Tao Deng Date: Fri, 17 Apr 2026 07:02:20 +1000 Subject: [PATCH] =?UTF-8?q?docs(readme):=20sync=20to=20v3.8.0=20=E2=80=94?= =?UTF-8?q?=20quota,=20cache,=20remove=20status=20badge?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - Remove "Status: Stable — Feature-complete, bug fixes only" tagline - Add Per-Key Quota section with curl examples and 429 response format - Add Response Cache section with enable/management instructions - Update API Endpoints table with new quota + cache endpoints - Add CLAUDE_CACHE_TTL to Environment Variables table - Update version references from v3.7.0 to v3.8.0 Co-Authored-By: Claude Opus 4.6 (1M context) --- README.md | 86 ++++++++++++++++++++++++++++++++++++++++++++++++++++--- 1 file changed, 82 insertions(+), 4 deletions(-) diff --git a/README.md b/README.md index c9cd6c3..cd71fa6 100644 --- a/README.md +++ b/README.md @@ -1,7 +1,5 @@ # OCP — Open Claude Proxy -> **Status: Stable (v3.7.0)** — Feature-complete. Bug fixes only. - > **Already paying for Claude Pro/Max? Use your subscription as an OpenAI-compatible API — $0 extra cost.** OCP turns your Claude Pro/Max subscription into a standard OpenAI-compatible API on localhost. Any tool that speaks the OpenAI protocol can use it — no separate API key, no extra billing. @@ -141,7 +139,7 @@ OCP Connect v1.3.0 Checking connectivity... ✓ Connected - Remote OCP v3.7.0 (auth: multi) + Remote OCP v3.8.0 (auth: multi) ⓘ Using server-advertised anonymous key: ocp_publ...n_v1 (set by admin via PROXY_ANONYMOUS_KEY; see issue #12 §14 Path A) @@ -197,7 +195,7 @@ OCP Connect v1.3.0 The script automatically: - Writes env vars to all relevant shell rc files (`.bashrc`, `.zshrc`) - Sets system-level env vars (`launchctl setenv` on macOS, `environment.d` on Linux) -- **Auto-discovers anonymous key** from `/health.anonymousKey` when no `--key` given (v1.3.0+, requires server v3.7.0+) +- **Auto-discovers anonymous key** from `/health.anonymousKey` when no `--key` given (v1.3.0+, requires server v3.8.0+) - Configures OpenClaw automatically (including per-agent `auth-profiles.json` for multi-agent setups) - Detects Cline, Continue.dev, Cursor, and opencode, and prints setup hints (manual configuration required for these IDEs) @@ -255,6 +253,46 @@ ocp start # or however you start the server **Not a secret**: because `/health` is an unauthenticated endpoint, the anonymous key is **publicly readable** by anyone who can reach the server. That is intentional — the key exists so clients can self-configure without out-of-band coordination. Treat it as a convenience handle, not as an access credential. +### Per-Key Quota (Budget Control) + +Prevent any single user from exhausting your subscription. Set daily, weekly, or monthly request limits per API key: + +```bash +# Set a daily limit of 50 requests for a key +curl -X PATCH http://127.0.0.1:3456/api/keys/wife-laptop/quota \ + -H "Authorization: Bearer $OCP_ADMIN_KEY" \ + -d '{"daily": 50}' + +# Set multiple limits at once +curl -X PATCH http://127.0.0.1:3456/api/keys/son-ipad/quota \ + -H "Authorization: Bearer $OCP_ADMIN_KEY" \ + -d '{"daily": 20, "weekly": 100}' + +# Check current quota + usage +curl http://127.0.0.1:3456/api/keys/wife-laptop/quota +# → { "daily": { "limit": 50, "used": 12 }, "weekly": { "limit": null, "used": 34 }, ... } + +# Remove a limit (set to null) +curl -X PATCH http://127.0.0.1:3456/api/keys/wife-laptop/quota \ + -d '{"daily": null}' +``` + +When a key exceeds its quota, OCP returns HTTP 429 with a structured error: +```json +{ + "error": { + "message": "Quota exceeded: 50/50 requests (daily). Resets 6h 12m.", + "type": "quota_exceeded", + "quota": { "period": "daily", "limit": 50, "used": 50, "resetsIn": "6h 12m" } + } +} +``` + +- `null` = unlimited (default for all keys) +- Only successful requests count toward quota +- Admin and anonymous users are never subject to quotas +- PATCH is a partial update — omitted fields are left unchanged + ### Important Notes - All users share your Claude Pro/Max **rate limits** (5h session + 7d weekly) @@ -346,6 +384,42 @@ $ ocp settings maxConcurrent 4 ✓ maxConcurrent = 4 ``` +## Response Cache + +OCP can cache responses to avoid redundant Claude CLI calls for identical prompts. This is useful during development when the same prompt is sent repeatedly. + +**Enable** by setting `CLAUDE_CACHE_TTL` (in milliseconds): + +```bash +# Cache responses for 5 minutes +export CLAUDE_CACHE_TTL=300000 + +# Or update at runtime (no restart) +ocp settings cacheTTL 300000 +``` + +**How it works:** +- Cache key = SHA-256 of `model` + `messages` + `temperature` + `max_tokens` + `top_p` +- Cache hits return instantly — no Claude CLI process spawned +- Works for both streaming and non-streaming requests +- Multi-turn conversations (with `session_id`) are never cached +- Expired entries are cleaned up automatically every 10 minutes + +**Management:** +```bash +# View cache stats +curl http://127.0.0.1:3456/cache/stats +# → { "entries": 42, "totalHits": 156, "sizeBytes": 284000 } + +# Clear all cached responses +curl -X DELETE http://127.0.0.1:3456/cache + +# Disable cache at runtime +ocp settings cacheTTL 0 +``` + +Cache is **disabled by default** (`CLAUDE_CACHE_TTL=0`). All data is stored locally in `~/.ocp/ocp.db`. + ## How It Works ``` @@ -377,7 +451,10 @@ OCP translates OpenAI-compatible `/v1/chat/completions` requests into `claude -p | `/dashboard` | GET | Web dashboard (always public) | | `/api/keys` | GET/POST | List or create API keys (admin only) | | `/api/keys/:id` | DELETE | Revoke an API key (admin only) | +| `/api/keys/:id/quota` | GET/PATCH | View or set per-key quota (admin only) | | `/api/usage` | GET | Per-key usage stats (`?since=&until=&hours=&limit=`) | +| `/cache/stats` | GET | Cache statistics (admin only) | +| `/cache` | DELETE | Clear response cache (admin only) | ## OpenClaw Integration @@ -456,6 +533,7 @@ ocp restart | `CLAUDE_MAX_CONCURRENT` | `8` | Max concurrent claude processes | | `CLAUDE_MAX_PROMPT_CHARS` | `150000` | Prompt truncation limit (chars) | | `CLAUDE_SESSION_TTL` | `3600000` | Session expiry (ms, default: 1 hour) | +| `CLAUDE_CACHE_TTL` | `0` | Response cache TTL (ms, 0 = disabled). Set to e.g. `300000` for 5-min cache | | `CLAUDE_ALLOWED_TOOLS` | `Bash,Read,...,Agent` | Comma-separated tools to pre-approve | | `CLAUDE_SKIP_PERMISSIONS` | `false` | Bypass all permission checks | | `CLAUDE_NO_CONTEXT` | `false` | Suppress CLAUDE.md and auto-memory injection (pure API mode) |