taodeng/ocp
1
0
Fork 0
mirror of https://github.com/dtzp555-max/ocp.git synced 2026-07-19 09:44:07 +00:00
Code Issues Packages Projects Releases Wiki Activity

rebrand: Open Claude Proxy — multi-IDE positioning

Browse Source 
Renamed from OpenClaw Control Plane to Open Claude Proxy. README
rewritten to position OCP as a universal proxy for any IDE that
speaks the OpenAI protocol, not just OpenClaw.

Added: supported tools table (Cline, OpenCode, Aider, Continue.dev),
simplified Quick Start, architecture diagram showing multi-IDE flow.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
This commit is contained in:
taodeng
2026-03-31 12:06:41 +10:00
co-authored by Claude Opus 4.6
parent d9b7c0d905
commit 2b05558b8b
2 changed files with 112 additions and 238 deletions
Download Patch File Download Diff File Expand all files Collapse all files
README.md
+111 -237
View File
@@ -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
package.json
+1 -1
View File
@@ -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",