Skillget

ocp

agent
SUMMARY

OCP (OpenClaw Control Plane) — Stable v3.0.0. Use your Claude Pro/Max subscription as an OpenAI-compatible API. Zero cost, zero dependencies.

README.md

OCP — OpenClaw Control Plane

Status: Stable (v3.0.0) — Feature-complete. Bug fixes only, no new development planned.

Already paying for Claude Pro/Max? Use it as your OpenClaw model provider — $0 extra API cost.

A lightweight, zero-dependency proxy that lets 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.

What's New in v3.0.0

/ocp — Your Proxy Command Center

Full management interface available from Telegram, Discord, or any terminal.

$ ocp usage
Plan Usage Limits
─────────────────────────────────────
  Current session       3% used
                      Resets in 4h 32m  (Tue, Mar 24, 10:00 PM)

  Weekly (all models)   3% used
                      Resets in 6d 6h  (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

Proxy: up 0h 37m | 5 reqs | 0 err | 0 timeout

All commands:

$ ocp --help
ocp usage              Plan usage limits & model stats
ocp status             Quick overview
ocp health             Proxy diagnostics
ocp settings           View tunable settings
ocp settings <k> <v>   Update a setting at runtime
ocp logs [N] [level]   Recent logs (default: 20, error)
ocp models             Available models
ocp sessions           Active sessions
ocp clear              Clear all sessions
ocp restart            Restart proxy
ocp restart gateway    Restart gateway

In Telegram/Discord, use /ocp usage, /ocp settings, etc. — registered as a native slash command via the OCP gateway plugin.

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]

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)

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.

Quick Start

git clone https://github.com/dtzp555-max/ocp.git
cd ocp

# Auto-configure OpenClaw + start proxy + install auto-start
node setup.mjs

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)

Then set your preferred model:

openclaw config set agents.defaults.model.primary "claude-local/claude-sonnet-4-6"
openclaw gateway restart

Install the CLI

The ocp command is included in the repo but not automatically added to PATH. You need to do one of:

# 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:

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:

{
  "plugins": {
    "allow": ["ocp"],
    "entries": { "ocp": { "enabled": true } }
  }
}

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:

# 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

Variable Default Description
CLAUDE_PROXY_PORT 3456 Listen port
CLAUDE_BIN (auto-detect) Path to claude binary
CLAUDE_TIMEOUT 300000 Overall request timeout (ms)
CLAUDE_FIRST_BYTE_TIMEOUT 90000 Base first-byte timeout (ms)
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_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:

{
  "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

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

/ocp command returns "Unknown skill: ocp"

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).

Workaround: Send /new to reset the session, then /ocp restart to restart the proxy:

/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.

License

MIT

Yorumlar (0)

Sonuc bulunamadi