From 256b2bfb7723012de1947a14cf02a5bf63c492a2 Mon Sep 17 00:00:00 2001 From: dtzp555 Date: Sat, 21 Mar 2026 14:02:33 +1000 Subject: [PATCH] docs: ship v2.3.0 positioning and coexistence guide --- openclaw-claude-proxy/README.md | 182 +++++++++++++++++++++++++++++ openclaw-claude-proxy/package.json | 4 +- openclaw-claude-proxy/server.mjs | 2 +- 3 files changed, 185 insertions(+), 3 deletions(-) create mode 100644 openclaw-claude-proxy/README.md diff --git a/openclaw-claude-proxy/README.md b/openclaw-claude-proxy/README.md new file mode 100644 index 0000000..e1906d5 --- /dev/null +++ b/openclaw-claude-proxy/README.md @@ -0,0 +1,182 @@ +# openclaw-claude-proxy v2.3.0 + +Use your **Claude Pro / Max** subscription as an **OpenAI-compatible local endpoint**. + +`openclaw-claude-proxy` accepts OpenAI-style chat completion requests, then runs them through the local `claude` CLI. That means tools which only know how to talk to an OpenAI API can still use Claude models through a local base URL. + +## Why v2 matters + +v2 is not just a bugfix release. It changes the runtime model: + +- **On-demand spawning** instead of fragile warm pools +- **Session resume** support for multi-turn conversations +- **Faster fallback** with first-byte timeout + lower default request timeout +- **Full tool access** via configurable allowed tools +- **MCP config + system prompt pass-through** +- **Health / sessions / diagnostics endpoints** +- **Safe coexistence with Claude Code channel / interactive mode** + +## The short pitch + +If Claude's new channel workflow feels useful, OCP v2 now covers the same practical ground for many local agent/tooling setups: + +- multi-turn continuity +- tool-enabled Claude runs +- local orchestration +- stable process isolation +- coexistence with your normal Claude Code workflow + +And it adds a few advantages that channel users usually still want: + +- **OpenAI-compatible HTTP API** for existing tools +- **Works with OpenClaw, Cursor, Continue, Open WebUI, LangChain, and anything with custom base URL support** +- **Explicit health checks and diagnostics** +- **Model/provider failover can happen outside Claude itself** +- **No lock-in to a single client UX** + +## Coexistence with Claude Code channel + +This is the important part: **OCP v2 does not replace Claude Code channel, and it does not need to. They can coexist on the same machine.** + +### Claude Code channel / interactive mode +- persistent interactive workflow +- MCP protocol / in-process experience +- great when you are directly driving Claude Code + +### OCP v2 +- local HTTP server on `localhost` +- OpenAI-compatible API surface +- per-request `claude -p` execution with session resume when you want continuity +- ideal for external tools, routers, orchestrators, OpenClaw providers, and local automation + +### Practical takeaway +Use both: +- use **Claude Code channel** when you want Claude's native interactive workflow +- use **OCP v2** when another app expects an OpenAI-style API but you still want to use Claude + +They solve adjacent problems, not identical ones. + +## Unique advantages of OCP v2 + +1. **API compatibility** + - Drop into tools that already support OpenAI-compatible endpoints. + - No need to wait for each tool to add native Claude channel support. + +2. **Routing freedom** + - Put OCP behind OpenClaw or another router. + - Mix Claude with fallback providers outside the Claude client itself. + +3. **Operational visibility** + - `/health`, `/sessions`, recent errors, auth state, resolved binary path, timeout config. + - Much easier to debug than a black-box local integration. + +4. **Safer runtime model** + - v2 removes the old pre-spawn pool crash loop. + - No stale workers, no degraded warm pool states, fewer hidden failure modes. + +5. **Configurable tools and behavior** + - allowed tools + - skip permissions mode + - system prompt append + - MCP config passthrough + - session TTL + - concurrency limits + +## Install + +```bash +git clone https://github.com/dtzp555-max/openclaw-claude-proxy +cd openclaw-claude-proxy +npm install +node server.mjs +``` + +Default base URL: + +```text +http://127.0.0.1:3456/v1 +``` + +## Quick OpenAI-compatible config + +```json +{ + "baseURL": "http://127.0.0.1:3456/v1", + "apiKey": "anything" +} +``` + +If `PROXY_API_KEY` is unset, auth is disabled. If you set it, pass it as a Bearer token. + +## Environment variables + +| Variable | Default | Purpose | +|---|---:|---| +| `CLAUDE_PROXY_PORT` | `3456` | Listen port | +| `CLAUDE_BIN` | auto-detect | Claude CLI binary path | +| `CLAUDE_TIMEOUT` | `120000` | Overall per-request timeout | +| `CLAUDE_FIRST_BYTE_TIMEOUT` | `30000` | Abort if Claude produces no stdout quickly | +| `CLAUDE_ALLOWED_TOOLS` | expanded set | Comma-separated allowed tools | +| `CLAUDE_SKIP_PERMISSIONS` | `false` | Bypass permission checks | +| `CLAUDE_SYSTEM_PROMPT` | unset | Append a system prompt to every request | +| `CLAUDE_MCP_CONFIG` | unset | Path to MCP config JSON | +| `CLAUDE_SESSION_TTL` | `3600000` | Session TTL | +| `CLAUDE_MAX_CONCURRENT` | `5` | Max concurrent Claude processes | +| `PROXY_API_KEY` | unset | Optional Bearer token auth | + +## Endpoints + +- `GET /health` +- `GET /v1/models` +- `POST /v1/chat/completions` +- `GET /sessions` +- `DELETE /sessions` + +## Example health response highlights + +`/health` reports useful operational state such as: + +- resolved Claude binary path +- whether the binary is executable +- auth status +- timeouts +- current sessions +- recent errors +- basic request stats + +## Version highlights + +### v2.3.0 +- clarified v2 positioning and coexistence story in docs +- officially documents faster fallback defaults +- recommends OCP v2 as the API bridge layer for Claude-powered tools + +### v2.2.0 +- first-byte timeout +- reduced default timeout for faster fallback + +### v2.0.0 +- on-demand architecture +- session management +- full tool access +- MCP + system prompt passthrough +- concurrency control +- coexistence with Claude Code interactive mode + +## When to use OCP v2 vs Claude channel + +Choose **OCP v2** when: +- your app only supports OpenAI-compatible endpoints +- you want routing / failover outside Claude +- you want explicit health checks and local diagnostics +- you want Claude available to multiple local tools through one endpoint + +Choose **Claude channel** when: +- you are primarily living inside Claude Code itself +- you want Claude's native interactive workflow directly + +Use **both together** when you want the best of both worlds. + +--- + +If you already pay for Claude Pro or Max, OCP v2 turns that subscription into a practical local API bridge for the rest of your tooling stack. diff --git a/openclaw-claude-proxy/package.json b/openclaw-claude-proxy/package.json index 30551fc..46b84f3 100644 --- a/openclaw-claude-proxy/package.json +++ b/openclaw-claude-proxy/package.json @@ -1,7 +1,7 @@ { "name": "openclaw-claude-proxy", - "version": "2.2.0", - "description": "OpenAI-compatible proxy that routes requests through Claude CLI \u2014 use your Claude Pro/Max subscription as an OpenClaw model provider", + "version": "2.3.0", + "description": "OpenAI-compatible proxy for Claude CLI v2 — on-demand sessions, faster fallback, and safe coexistence with Claude Code channels", "type": "module", "bin": { "openclaw-claude-proxy": "./server.mjs" diff --git a/openclaw-claude-proxy/server.mjs b/openclaw-claude-proxy/server.mjs index 55d6810..e3c0fdb 100644 --- a/openclaw-claude-proxy/server.mjs +++ b/openclaw-claude-proxy/server.mjs @@ -1,6 +1,6 @@ #!/usr/bin/env node /** - * openclaw-claude-proxy v2.2.0 — OpenAI-compatible proxy for Claude CLI + * openclaw-claude-proxy v2.3.0 — OpenAI-compatible proxy for Claude CLI * * Translates OpenAI chat/completions requests into `claude -p` CLI calls, * letting you use your Claude Pro/Max subscription as an OpenClaw model provider.