taodeng/ocp
1
0
Fork 0
mirror of https://github.com/dtzp555-max/ocp.git synced 2026-07-21 21:15:09 +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 $ ocp usage
Plan Usage Limits Plan Usage Limits
───────────────────────────────────── ─────────────────────────────────────
Current session 3% used Current session 21% used
Resets in 4h 32m (Tue, Mar 24, 10:00 PM) Resets in 3h 12m (Tue, Mar 28, 10:00 PM)
Weekly (all models) 3% used Weekly (all models) 45% used
Resets in 6d 6h (Tue, Mar 31, 12:00 AM) Resets in 4d 2h (Tue, Mar 31, 12:00 AM)
Extra usage off Extra usage off
Model Stats Model Stats
Model Req OK Er AvgT MaxT AvgP MaxP Model Req OK Er AvgT MaxT AvgP MaxP
────────────────────────────────────────────────────── ──────────────────────────────────────────────────────
haiku 1 1 0 6s 6s 0K 0K opus 5 5 0 32s 87s 42K 43K
opus 2 2 0 20s 26s 42K 43K sonnet 18 18 0 20s 45s 36K 56K
sonnet 2 2 0 24s 24s 41K 41K Total 23
Total 5
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 usage Plan usage limits & model stats
ocp status Quick overview ocp status Quick overview
ocp health Proxy diagnostics ocp health Proxy diagnostics
@@ -50,118 +95,73 @@ ocp sessions Active sessions
ocp clear Clear all sessions ocp clear Clear all sessions
ocp restart Restart proxy ocp restart Restart proxy
ocp restart gateway Restart gateway 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) ### 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 $ ocp settings maxPromptChars 200000
✓ maxPromptChars = 200000 ✓ maxPromptChars = 200000
$ ocp settings maxConcurrent 999 $ ocp settings maxConcurrent 4
✗ maxConcurrent: value 999 out of range [1, 32] ✓ 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 ## 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 | Model ID | Notes |
git clone https://github.com/dtzp555-max/ocp.git |----------|-------|
cd ocp | `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 ## API Endpoints
node setup.mjs
```
The setup script will: | Endpoint | Method | Description |
1. Verify Claude CLI is installed and authenticated |----------|--------|-------------|
2. Add `claude-local` provider to `openclaw.json` | `/v1/models` | GET | List available models |
3. Start the proxy and install auto-start (launchd on macOS, systemd on Linux) | `/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: ## OpenClaw Integration
```bash
openclaw config set agents.defaults.model.primary "claude-local/claude-sonnet-4-6"
openclaw gateway restart
```
### 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 ### Install the Gateway Plugin
# 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:
```bash ```bash
cp -r ocp-plugin/ ~/.openclaw/extensions/ocp/ 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`: Add to `~/.openclaw/openclaw.json`:
@@ -174,45 +174,7 @@ Add to `~/.openclaw/openclaw.json`:
} }
``` ```
Restart the gateway: `openclaw gateway restart` Restart: `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 |
## Environment Variables ## 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_SESSION_TTL` | `3600000` | Session expiry (ms, default: 1 hour) |
| `CLAUDE_ALLOWED_TOOLS` | `Bash,Read,...,Agent` | Comma-separated tools to pre-approve | | `CLAUDE_ALLOWED_TOOLS` | `Bash,Read,...,Agent` | Comma-separated tools to pre-approve |
| `CLAUDE_SKIP_PERMISSIONS` | `false` | Bypass all permission checks | | `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 | | `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 ## Security
- **Localhost only** — binds to `127.0.0.1`, not exposed to the network - **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` - **Bearer token auth (optional)** — set `PROXY_API_KEY` to require auth
- **No API keys** — authentication to Anthropic goes through Claude CLI's OAuth session - **No API keys needed** — authentication goes through Claude CLI's OAuth session
- **Auto-start** — launchd (macOS) / systemd (Linux) via `node setup.mjs` - **Auto-start** — launchd (macOS) / systemd (Linux)
- **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
## Known Issues ## 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)). 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:** Send `/new` to reset the session, then `/ocp restart` to restart the proxy:
**Workaround:**
``` ```
/new /new
/ocp restart /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 or place a `SKILL.md` in workspace skills — this creates a routing conflict.
**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.
## License ## License
package.json
+1 -1
View File
@@ -1,7 +1,7 @@
{ {
"name": "openclaw-claude-proxy", "name": "openclaw-claude-proxy",
"version": "3.0.0", "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", "type": "module",
"bin": { "bin": {
"openclaw-claude-proxy": "./server.mjs", "openclaw-claude-proxy": "./server.mjs",