diff --git a/README.md b/README.md index 736c327..1560273 100644 --- a/README.md +++ b/README.md @@ -1,44 +1,89 @@ -# OCP — OpenClaw Control Plane +# OCP — Open Claude Proxy -> **Status: Stable (v3.0.0)** — Feature-complete. Bug fixes only, no new development planned. +> **Status: Stable (v3.0.0)** — Feature-complete. Bug fixes only. -> **Already paying for Claude Pro/Max? Use it as your OpenClaw model provider — $0 extra API cost.** +> **Already paying for Claude Pro/Max? Use your subscription as an OpenAI-compatible API — $0 extra cost.** -A lightweight, zero-dependency proxy that lets [OpenClaw](https://github.com/openclaw/openclaw) agents talk to Claude through your existing subscription. One command to set up, one file to run. Built-in plan usage monitoring, runtime settings, and a CLI. +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. -## What's New in v3.0.0 +``` +Cline ──┐ +OpenCode ───┤ +Aider ───┼──→ OCP :3456 ──→ Claude CLI ──→ Your subscription +Continue.dev ───┤ +OpenClaw ───┘ +``` -### `/ocp` — Your Proxy Command Center +One proxy. Multiple IDEs. All models. **$0 API cost.** -Full management interface available from Telegram, Discord, or any terminal. +## Supported Tools + +Any tool that accepts `OPENAI_BASE_URL` works with OCP: + +| Tool | Configuration | +|------|--------------| +| **Cline** | Settings → `OPENAI_BASE_URL=http://127.0.0.1:3456/v1` | +| **OpenCode** | `OPENAI_BASE_URL=http://127.0.0.1:3456/v1` | +| **Aider** | `aider --openai-api-base http://127.0.0.1:3456/v1` | +| **Continue.dev** | config.json → `apiBase: "http://127.0.0.1:3456/v1"` | +| **OpenClaw** | `setup.mjs` auto-configures | +| **Any OpenAI client** | Set base URL to `http://127.0.0.1:3456/v1` | + +## Quick Start + +```bash +git clone https://github.com/dtzp555-max/ocp.git +cd ocp +node setup.mjs +``` + +The setup script will: +1. Verify Claude CLI is installed and authenticated +2. Start the proxy on port 3456 +3. Install auto-start (launchd on macOS, systemd on Linux) + +Then point your IDE to the proxy: + +```bash +export OPENAI_BASE_URL=http://127.0.0.1:3456/v1 +``` + +### Verify + +```bash +curl http://127.0.0.1:3456/v1/models +# Returns: claude-opus-4-6, claude-sonnet-4-6, claude-haiku-4 +``` + +## Built-in Usage Monitoring + +Check your subscription usage from the terminal: ``` $ ocp usage Plan Usage Limits ───────────────────────────────────── - Current session 3% used - Resets in 4h 32m (Tue, Mar 24, 10:00 PM) + Current session 21% used + Resets in 3h 12m (Tue, Mar 28, 10:00 PM) - Weekly (all models) 3% used - Resets in 6d 6h (Tue, Mar 31, 12:00 AM) + Weekly (all models) 45% used + Resets in 4d 2h (Tue, Mar 31, 12:00 AM) Extra usage off Model Stats Model Req OK Er AvgT MaxT AvgP MaxP ────────────────────────────────────────────────────── -haiku 1 1 0 6s 6s 0K 0K -opus 2 2 0 20s 26s 42K 43K -sonnet 2 2 0 24s 24s 41K 41K -Total 5 +opus 5 5 0 32s 87s 42K 43K +sonnet 18 18 0 20s 45s 36K 56K +Total 23 -Proxy: up 0h 37m | 5 reqs | 0 err | 0 timeout +Proxy: up 6h 32m | 23 reqs | 0 err | 0 timeout ``` -**All commands:** +### All Commands ``` -$ ocp --help ocp usage Plan usage limits & model stats ocp status Quick overview ocp health Proxy diagnostics @@ -50,118 +95,73 @@ ocp sessions Active sessions ocp clear Clear all sessions ocp restart Restart proxy ocp restart gateway Restart gateway +ocp version Show version +ocp --help Command reference ``` -In **Telegram/Discord**, use `/ocp usage`, `/ocp settings`, etc. — registered as a native slash command via the OCP gateway plugin. +### Install the CLI + +```bash +# Symlink to PATH (recommended) +sudo ln -sf $(pwd)/ocp /usr/local/bin/ocp + +# Verify +ocp --help +``` + +> **Cloud/Linux servers:** If `ocp: command not found`, the binary isn't in PATH. Full path: `~/.openclaw/projects/ocp/ocp` ### Runtime Settings (No Restart Needed) -``` -$ ocp settings -OCP Settings -───────────────────────────────────── - timeout 300000 ms Overall request timeout - firstByteTimeout 90000 ms Base first-byte timeout - maxConcurrent 8 Max concurrent claude processes - sessionTTL 3600000 ms Session idle expiry - maxPromptChars 150000 chars Prompt truncation limit - -Timeout Tiers (first-byte): - opus base=150000ms perChar=0.0005 - sonnet base=120000ms perChar=0.0005 - haiku base= 45000ms perChar=0.0001 -``` - -Change any setting live: - ``` $ ocp settings maxPromptChars 200000 ✓ maxPromptChars = 200000 -$ ocp settings maxConcurrent 999 -✗ maxConcurrent: value 999 out of range [1, 32] +$ ocp settings maxConcurrent 4 +✓ maxConcurrent = 4 ``` -### Circuit Breaker Removed - -The v2.5.0 circuit breaker has been **removed entirely**. It was designed for direct API connections but caused cascading failures in the CLI-proxy architecture — once API got briefly slow, the breaker blocked ALL agents for 120s+, making the problem worse. With CLI spawning, timeouts are transient and don't benefit from back-off. - -### Prompt Truncation Guard - -New safety valve prevents runaway context from conversation history accumulation (a recurring issue where prompts balloon from 40K to 400K+ chars). - -- Default limit: **150K characters** (configurable via `maxPromptChars`) -- When exceeded: keeps system messages + as many recent messages as fit -- Logs `prompt_truncated` events for monitoring - -### Increased Timeouts - -| Model | Old Base | New Base | Per 100K chars | -|-------|----------|----------|----------------| -| Opus | 90s | **150s** | +50s | -| Sonnet | 60s | **120s** | +50s | -| Haiku | 30s | **45s** | +10s | - ---- - ## How It Works ``` -OpenClaw Gateway → proxy (localhost:3456) → claude -p CLI → Anthropic (via OAuth) +Your IDE → OCP (localhost:3456) → claude -p CLI → Anthropic (via subscription) ``` -The proxy translates OpenAI-compatible `/v1/chat/completions` requests into `claude -p` CLI calls. Anthropic sees normal Claude Code usage under your subscription — no API billing, no separate key. +OCP translates OpenAI-compatible `/v1/chat/completions` requests into `claude -p` CLI calls. Anthropic sees normal Claude Code usage — no API billing, no separate key needed. -## Quick Start +## Available Models -```bash -git clone https://github.com/dtzp555-max/ocp.git -cd ocp +| Model ID | Notes | +|----------|-------| +| `claude-opus-4-6` | Most capable, slower | +| `claude-sonnet-4-6` | Good balance of speed/quality | +| `claude-haiku-4` | Fastest, lightweight | -# Auto-configure OpenClaw + start proxy + install auto-start -node setup.mjs -``` +## API Endpoints -The setup script will: -1. Verify Claude CLI is installed and authenticated -2. Add `claude-local` provider to `openclaw.json` -3. Start the proxy and install auto-start (launchd on macOS, systemd on Linux) +| Endpoint | Method | Description | +|----------|--------|-------------| +| `/v1/models` | GET | List available models | +| `/v1/chat/completions` | POST | Chat completion (streaming + non-streaming) | +| `/health` | GET | Comprehensive health check | +| `/usage` | GET | Plan usage limits + per-model stats | +| `/status` | GET | Combined overview (usage + health) | +| `/settings` | GET/PATCH | View or update settings at runtime | +| `/logs` | GET | Recent log entries (`?n=20&level=error`) | +| `/sessions` | GET/DELETE | List or clear active sessions | -Then set your preferred model: -```bash -openclaw config set agents.defaults.model.primary "claude-local/claude-sonnet-4-6" -openclaw gateway restart -``` +## OpenClaw Integration -### Install the CLI +OCP was originally built for [OpenClaw](https://github.com/openclaw/openclaw) and includes deep integration: -The `ocp` command is included in the repo but **not automatically added to PATH**. You need to do one of: +- **`setup.mjs`** auto-configures the `claude-local` provider in `openclaw.json` +- **Gateway plugin** registers `/ocp` as a native slash command in Telegram/Discord +- **Multi-agent** — 8 concurrent requests sharing one subscription -```bash -# Option 1: symlink to PATH (recommended) -sudo ln -sf ~/.openclaw/projects/ocp/ocp /usr/local/bin/ocp - -# Option 2: from the repo directory -cd ~/.openclaw/projects/ocp # or wherever you cloned it -ln -sf $(pwd)/ocp /usr/local/bin/ocp - -# Option 3: add to PATH in your shell profile -echo 'export PATH="$HOME/.openclaw/projects/ocp:$PATH"' >> ~/.bashrc -source ~/.bashrc -``` - -Verify: `ocp --help` - -> **Common issue on cloud/Linux servers:** If you get `ocp: command not found`, the repo was cloned but the binary isn't in PATH. Use one of the options above. The full path is typically `~/.openclaw/projects/ocp/ocp`. - -### Install the Gateway Plugin (for Telegram/Discord) - -Copy the plugin to the OpenClaw extensions directory: +### Install the Gateway Plugin ```bash cp -r ocp-plugin/ ~/.openclaw/extensions/ocp/ -# Or into the bundled extensions: -cp -r ocp-plugin/ /opt/homebrew/lib/node_modules/openclaw/dist/extensions/ocp/ ``` Add to `~/.openclaw/openclaw.json`: @@ -174,45 +174,7 @@ Add to `~/.openclaw/openclaw.json`: } ``` -Restart the gateway: `openclaw gateway restart` - -### Upgrading from v2.x (skill-based /ocp) - -If you previously used the skill-based `/ocp` command (via `skills/ocp/SKILL.md`), remove it to avoid conflicts: - -```bash -# Remove the old skill -rm -rf ~/.openclaw/workspace/main/skills/ocp - -# Restart gateway -launchctl kickstart -k gui/501/ai.openclaw.gateway # macOS -# or: systemctl --user restart openclaw-gateway # Linux -``` - -**Why?** The old skill routed `/ocp` to the agent as a prompt (slow, costs tokens). The new plugin handles commands directly in the gateway (instant, free). If both exist, the skill takes priority and you get "Unknown skill" errors. - -## API Endpoints - -| Endpoint | Method | Description | -|----------|--------|-------------| -| `/v1/models` | GET | List available models | -| `/v1/chat/completions` | POST | Chat completion (streaming + non-streaming) | -| `/health` | GET | Comprehensive health check | -| `/usage` | GET | Plan usage limits + per-model stats | -| `/status` | GET | Combined overview (usage + health) | -| `/settings` | GET | View tunable settings | -| `/settings` | PATCH | Update settings at runtime | -| `/logs` | GET | Recent log entries (`?n=20&level=error`) | -| `/sessions` | GET | List active sessions | -| `/sessions` | DELETE | Clear all sessions | - -## Available Models - -| Model ID | Claude CLI Model | Notes | -|----------|-----------------|-------| -| `claude-opus-4-6` | claude-opus-4-6 | Most capable, slower | -| `claude-sonnet-4-6` | claude-sonnet-4-6 | Good balance of speed/quality | -| `claude-haiku-4` | claude-haiku-4-5-20251001 | Fastest, lightweight | +Restart: `openclaw gateway restart` ## Environment Variables @@ -227,116 +189,28 @@ launchctl kickstart -k gui/501/ai.openclaw.gateway # macOS | `CLAUDE_SESSION_TTL` | `3600000` | Session expiry (ms, default: 1 hour) | | `CLAUDE_ALLOWED_TOOLS` | `Bash,Read,...,Agent` | Comma-separated tools to pre-approve | | `CLAUDE_SKIP_PERMISSIONS` | `false` | Bypass all permission checks | -| `CLAUDE_SYSTEM_PROMPT` | *(empty)* | System prompt appended to all requests | -| `CLAUDE_MCP_CONFIG` | *(empty)* | Path to MCP server config JSON | | `PROXY_API_KEY` | *(unset)* | Bearer token for API authentication | -## Session Management - -Multi-turn conversations use `--resume` to avoid resending full history on every request. - -Include a `session_id` field in the request body or `X-Session-Id` header: - -```json -{ - "model": "claude-sonnet-4-6", - "session_id": "conv-abc-123", - "messages": [ - {"role": "user", "content": "Hello"}, - {"role": "assistant", "content": "Hi!"}, - {"role": "user", "content": "What did I just say?"} - ] -} -``` - -Sessions expire after 1 hour of inactivity (configurable via `CLAUDE_SESSION_TTL`). - ## Security - **Localhost only** — binds to `127.0.0.1`, not exposed to the network -- **Bearer token auth (optional)** — set `PROXY_API_KEY` to require auth on all requests except `/health` -- **No API keys** — authentication to Anthropic goes through Claude CLI's OAuth session -- **Auto-start** — launchd (macOS) / systemd (Linux) via `node setup.mjs` -- **Remove auto-start**: `node uninstall.mjs` - -## Architecture - -| | v1.x (pool) | v2.0+ (on-demand) | -|---|---|---| -| Process lifecycle | Pre-spawn idle workers | Spawn per request | -| Crash handling | Backoff spiral | No crash loops | -| Session support | None | `--resume` with tracking | -| Tool access | 6 hardcoded | Configurable, expanded | -| Prompt guard | None | Truncation at 150K chars | -| Monitoring | Basic `/health` | `/usage`, `/status`, `/settings`, `/logs` | -| CLI | None | `ocp` command | -| Gateway plugin | None | `/ocp` slash command | - -## Coexistence with Claude Code - -OCP and Claude Code interactive mode are completely independent: - -| | OCP (this proxy) | Claude Code | -|---|---|---| -| Protocol | HTTP (localhost:3456) | MCP (in-process) | -| Process model | Per-request spawn | Persistent session | -| Lifecycle | Daemon (auto-start) | Requires terminal | -| Use case | Automated agent work | Human-in-the-loop | - -Both run on the same machine simultaneously. No shared state, no port conflicts. - -## Recovery After OpenClaw Upgrade - -```bash -cd ~/.openclaw/projects/claude-proxy -git pull -node setup.mjs -openclaw gateway restart -``` - -## Changelog - -### v3.0.0 (2026-03-24) -- **`/ocp` CLI** — full management from terminal (`ocp usage`, `ocp settings`, etc.) -- **`/ocp` gateway plugin** — native slash command in Telegram/Discord -- **Plan usage monitoring** — real-time session/weekly limits via Anthropic API rate-limit headers -- **Per-model stats** — request count, avg/max elapsed time, avg/max prompt size -- **Runtime settings** — `PATCH /settings` to tune timeouts, concurrency, prompt limits without restart -- **Prompt truncation** — auto-truncate prompts exceeding 150K chars to prevent timeout cascades -- **Circuit breaker removed** — caused more harm than good in CLI-proxy architecture -- **Timeout increases** — Opus 150s, Sonnet 120s, Haiku 45s (base first-byte) -- **New endpoints** — `/usage`, `/status`, `/settings`, `/logs` - -### v2.5.0 (2026-03-22) -- Sliding-window circuit breaker (replaced consecutive-count) -- Graduated backoff, multi-probe half-open -- Increased default timeouts for large agent prompts - -### v2.0.0 -- On-demand spawning (replaced pool architecture) -- Session management with `--resume` -- Full tool access, system prompt, MCP config support +- **Bearer token auth (optional)** — set `PROXY_API_KEY` to require auth +- **No API keys needed** — authentication goes through Claude CLI's OAuth session +- **Auto-start** — launchd (macOS) / systemd (Linux) ## Known Issues -### `/ocp` command returns "Unknown skill: ocp" +### `/ocp` command returns "Unknown skill: ocp" (OpenClaw only) -The `/ocp` plugin command may intermittently stop working and return "Unknown skill: ocp". This is caused by an OpenClaw gateway bug where internal session routing interferes with plugin command dispatch ([openclaw/openclaw#26895](https://github.com/openclaw/openclaw/issues/26895)). - -**Workaround:** Send `/new` to reset the session, then `/ocp restart` to restart the proxy: +The `/ocp` plugin command may intermittently stop working in Telegram/Discord. This is caused by an OpenClaw gateway bug ([openclaw/openclaw#26895](https://github.com/openclaw/openclaw/issues/26895)). +**Workaround:** ``` /new /ocp restart ``` -This reliably restores the plugin. The issue may recur after some time — repeat the workaround as needed. - -**Important:** -- Do **not** add `ocp` to agent `skills` lists in `openclaw.json` — this creates a routing conflict and makes the problem worse. OCP should only be registered as a **plugin**. -- Do **not** place a `SKILL.md` file in the workspace skills directory for ocp — same conflict. - -We are tracking the upstream fix. This section will be updated when it is resolved. +**Important:** Do not add `ocp` to agent `skills` lists or place a `SKILL.md` in workspace skills — this creates a routing conflict. ## License diff --git a/package.json b/package.json index fe99a7d..f8cb1b6 100644 --- a/package.json +++ b/package.json @@ -1,7 +1,7 @@ { "name": "openclaw-claude-proxy", "version": "3.0.0", - "description": "OCP (OpenClaw Control Plane) — stable proxy for Claude CLI subscriptions. Plan usage monitoring, runtime settings, prompt truncation, OCP CLI.", + "description": "OCP (Open Claude Proxy) — use your Claude Pro/Max subscription as an OpenAI-compatible API for any IDE. Works with Cline, OpenCode, Aider, Continue.dev, OpenClaw, and more.", "type": "module", "bin": { "openclaw-claude-proxy": "./server.mjs",