openclaw-claude-proxy (OCP)

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. Now with 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/openclaw-claude-proxy.git
cd openclaw-claude-proxy

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

# Option 1: symlink to PATH
ln -sf $(pwd)/ocp /usr/local/bin/ocp

# Option 2: npm link (if installed globally)
npm link

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

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

License

MIT