OCP — Open Claude Proxy

Already paying for Claude Pro/Max? Use your subscription as an OpenAI-compatible API — $0 extra cost.

Open source from day one, used daily by my family, maintained on nights and weekends. If OCP saves you money too, you can ☕ buy me a coffee — full story below.

If OCP saves you a setup, a ⭐ helps other folks discover it. Issue reports are even more useful — that's the highest-quality feedback this project gets.

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.

Cline          ──┐
OpenCode       ───┤
Aider          ───┼──→ OCP :3456 ──→ Claude CLI ──→ Your subscription
Continue.dev   ───┤
OpenClaw       ───┘

One proxy. Multiple IDEs. All models. $0 API cost.

Contents

• Why OCP? · Supported Tools
• Quickstart
• How It Works
• Reference: Available Models · API Endpoints · Environment Variables
• Modes & operations: LAN & multi-user → docs/lan-mode.md · Subscription-pool (TUI) mode → docs/tui-mode.md · Upgrading → docs/upgrading.md
• Built-in Usage Monitoring · Response Cache · Structured Outputs · Images / Multimodal · OpenClaw Integration
• Troubleshooting → docs/troubleshooting.md
• Repository Layout · Security · Governance · Support OCP · License

Why OCP?

There are several Claude proxy projects. OCP picks a specific lane: align tightly with what cli.js actually does, observe + multiplex what's already there, don't extend the protocol. What you get:

• LAN multi-user keys (v3.7.0) — reach one Claude Pro/Max subscription from your own devices across the LAN. Each device gets a per-key API token (no OAuth session leak), with independent usage tracking and one-line revocation. Pro/Max are per-user accounts — see Sharing with family / a team — honest limits before extending access to other people.
• ocp-connect one-shot client setup — one command on the client machine auto-configures OpenClaw, and detects Cursor, Cline, Continue.dev, and opencode to print ready-to-paste setup hints for each. No hunting for where each tool keeps its OPENAI_BASE_URL.
• Response cache with per-key isolation + singleflight (v3.13.0). Optional SHA-256 prompt cache, isolated per API key (cross-user pollution is impossible by hash construction, not by application logic), with stampede protection on concurrent identical prompts. Off by default. (PR #65, PR #66)
• Per-key request quotas (v3.8.0). Daily / weekly / monthly limits per key — set a kid's iPad to 20/day, a partner's laptop to 100/week. (PR #18)
• SSE heartbeat for long reasoning (v3.12.0, opt-in). If you've ever watched your IDE die at the 60s idle mark during a long Claude tool-use pause — that's nginx/Cloudflare default behavior. OCP emits an SSE comment frame to keep the connection alive without polluting the response. (PR #49)
• cli.js alignment + CI guardrail. LLM-assisted code drifts easily — it's tempting to invent plausible-looking endpoints that cli.js doesn't actually use. ALIGNMENT.md is binding: every endpoint OCP forwards from cli.js (Class A) must cite a cli.js line. OCP's own compatibility surface — the OpenAI-compatible and administrative endpoints, which have no cli.js analogue — is Class B: it cites OpenAI's published specification (the OpenAI-compatible endpoints) or its authorizing ADR (the administrative ones), under the same anti-invention discipline (ADR 0006). The alignment.yml CI workflow blocks PRs that introduce known-hallucinated tokens. The payoff is boring: your setup keeps working when cli.js ships its next minor.
• models.json single source of truth (v3.11.0). Adding a model is one file edit; both /v1/models and the OpenClaw bootstrap derive from it. (PR #30)
• Drives the official CLI as-is, no binary patching. OCP spawns the official claude CLI (or hosts it in an interactive tmux pane for TUI mode) — it does not extract OAuth tokens from memory, patch the binary, or invent protocol extensions. Traffic therefore looks like genuine Claude Code to Anthropic's classifiers (cc_entrypoint=cli). See ALIGNMENT.md for why this constraint is load-bearing.

Comparison

OCP and the alternatives serve adjacent but distinct needs. Pick the one that fits your use case:

Plain English: claude-code-router is the routing-and-switching power tool — pick it if you want to mix Anthropic, OpenAI, Gemini, and local models behind one endpoint. anthropic-proxy is the minimal forwarder. OCP focuses on disciplined cli.js-aligned forwarding plus subscription multiplexing — pick it if you want to reach one Claude Pro/Max subscription from your own IDEs and devices, with LAN auth, quotas, and a governance contract that prevents endpoint drift.

Related: OLP — Open LLM Proxy

OCP is Claude-only by design. If you want to spread across multiple LLM providers (not just Claude), see the sibling project OLP — Open LLM Proxy: the same spawn-the-provider-CLI approach, but across several provider CLIs behind one OpenAI-compatible endpoint, with intelligent fallback chains. It grew out of OCP in response to Anthropic's 2026-06-15 billing split — the idea being to spread subscription/quota risk across more than one provider. OCP remains the focused, Claude-only option; OLP is the multi-provider one.

OCP is single-maintainer + LLM-assisted, currently pre-1.0. It runs the maintainer's daily Claude Code workflow. If something breaks, open an issue.

Supported Tools

Any tool that accepts OPENAI_BASE_URL works with OCP:

[^openclaw]: OpenClaw is an IDE-agnostic AI coding agent (sibling project to OCP). When OCP runs on the same machine, OpenClaw can use it as a local provider — see scripts/sync-openclaw.mjs and ADR 0004.

Quickstart

The simplest path: ask your AI.

Paste this prompt to Claude Code / Cursor / Copilot:

Install OCP for me. Read README §Quickstart and follow it.
Tell me when I need to run `claude auth login`.

The AI will run git clone, npm install, node setup.mjs, and tell you when to OAuth.

Prerequisites: macOS or Linux (Windows is not supported), Node.js 22.5+ (Node 23+ recommended), git, and the Claude CLI, authenticated:

npm install -g @anthropic-ai/claude-code
claude auth login   # prints a URL + code — open on any browser, sign in, paste code back

Install (Server role — runs the proxy):

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

setup.mjs verifies the Claude CLI, starts the proxy on port 3456, and installs auto-start (launchd on macOS, systemd on Linux). The ocp CLI lands at ~/ocp/ocp — symlink it onto your PATH (sudo ln -sf ~/ocp/ocp /usr/local/bin/ocp, or ln -sf ~/ocp/ocp ~/.local/bin/ocp) or alias it (alias ocp=~/ocp/ocp); the rest of the docs assume ocp is on your PATH.

Verify — should list 7 models:

curl http://127.0.0.1:3456/v1/models
# claude-opus-5, claude-opus-4-8, claude-opus-4-7, claude-opus-4-6, claude-sonnet-5, claude-sonnet-4-6, claude-haiku-4-5-20251001

Connect one IDE — point any OpenAI-compatible tool at the proxy, then reload your shell and start a tool (Cline / Continue / Cursor / OpenCode):

export OPENAI_BASE_URL=http://127.0.0.1:3456/v1

See Supported Tools for per-tool config.

LAN / multi-user — reach OCP from your own devices, with per-key auth, quotas, and anonymous access:

node setup.mjs --bind 0.0.0.0 --auth-mode multi

The full LAN server + client handbook, headless (Pi / NAS / VPS) OAuth, key/quota/anonymous-access management, AI-assisted install prompts, and the deployment/security model live in docs/lan-mode.md. Claude Pro/Max are per-user accounts — read the honest limits of sharing before extending access to other people.

Uninstall

# From the cloned repo
node uninstall.mjs

Removes the launchd (macOS) or systemd (Linux) auto-start entry. Handles both legacy (ai.openclaw.proxy / openclaw-proxy) and current (dev.ocp.proxy / ocp-proxy) service names. Does not delete ~/.openclaw/, ~/.ocp/, or the cloned repo — remove those manually if desired.

How It Works

Your IDE → OCP (localhost:3456) → claude --output-format stream-json CLI → Anthropic (via subscription)

OCP translates OpenAI-compatible /v1/chat/completions requests into claude --output-format stream-json CLI calls. Anthropic sees normal Claude Code usage — no API billing, no separate key needed.

Billing-policy status (as of 2026-07). Anthropic announced (2026-05-14) that from 2026-06-15 the claude -p / Agent SDK path would move to a separate metered credit pool — then paused the change on its effective date: "For now, nothing has changed: Claude Agent SDK, claude -p, and third-party app usage still draw from your subscription's usage limits" (official help article). So the default path above currently bills your subscription. Anthropic has said it will give notice before any future change; if the split re-lands, OCP's opt-in subscription-pool (TUI) mode is the ready-made hedge — see the billing table there.

Client-tools boundary

OCP is a text-prompt bridge to the official claude CLI. It does not pass through OpenAI tools/functions payloads or Anthropic tool_use blocks to the client. Clients (Cline, Cursor, OpenClaw, etc.) pointed at OCP receive assistant TEXT only — they never get tool_calls to execute locally.

Offering tools is fine; forcing a tool call gets a 400. Because OCP never emits tool_calls, a request that requires one cannot be answered correctly, so it is refused rather than answered with prose that claims the turn ended normally:

Simply sending a tool list is never an error — that is the common case (every OpenClaw turn carries one) and it is unchanged. Only the instruction OCP cannot obey is refused, and it is refused loudly so a client can fall back to another provider or retry with "auto" instead of silently receiving a wrong answer. See ADR 0013 for why this is a refusal rather than an implementation.

Any tool use happens server-side, under the --allowedTools set configured on the OCP host. In default mode (no CLAUDE_NO_CONTEXT), the claude CLI's own built-in tools are available to the model; in TUI mode, the operator controls the tool surface via OCP_TUI_FULL_TOOLS. Either way, the tools run under the operator's credentials on the server, and the client sees only the final text output. Note that on the -p path OCP prepends a system-prompt wrapper telling the model it has no local access (right for a shared gateway) — a single-user loopback instance whose model should use its tools can flip this with OCP_LOCAL_TOOLS=1 (see Environment Variables).

Client-local tool execution is not supported by design. Supporting it would require bypassing the claude CLI to call the raw Anthropic API directly — that is a different product, and is out of scope per ALIGNMENT.md (every OCP endpoint must correspond to something cli.js actually does).

What this means for choosing OCP (workload fit). LAN/multi-device OCP is built for chat-class workloads — Q&A, translation, scripting against the API, chat frontends, home-automation backends — where text in/text out is the whole job. It is not the right tool for a coding agent running on a client machine that needs the AI to read and edit that machine's files: tools execute on the OCP host, so the model can never touch the client's filesystem. For that workload, run claude (or a local OCP) directly on the machine where the code lives.

Available Models

Context windows match the Claude Code CLI registry. Each model's prompt truncation ceiling is derived from its own window (contextWindow × 3 chars) — see ADR 0011 and CLAUDE_MAX_PROMPT_CHARS in Environment Variables.

The canonical list lives in models.json — the single source of truth as of v3.11.0, validated in CI against models.schema.json. Both server.mjs (the /v1/models endpoint) and setup.mjs (the OpenClaw registration) derive from it. Adding a new model is now a one-file edit:

# 1. Edit models.json — add an entry
# 2. Bump version, commit, tag, push
# 3. Users get it on next `ocp update`:
#    - OpenClaw: auto-synced via scripts/sync-openclaw.mjs
#    - Cline / Aider / Cursor / opencode: live /v1/models, picks up immediately
#    - Continue.dev: user edits their own config.json

API Endpoints

Environment Variables

What auth.ok means

/health's auth block answers "can this proxy authenticate", and it is deliberately conservative about saying yes. Two pairs of fields, deliberately separate: okSource / okAt say how and when auth.ok was established, while lastOutcome / lastCheck describe the last probe. A probe that cannot conclude updates only the second pair.

The table is keyed on okSource, because that is the field the verdict's meaning turns on. lastOutcome describes the probe, and the probe is not always what set auth.ok.

lastOutcome is not part of the request-verified verdict, and that is deliberate. A completed request sets okSource: "request" and leaves lastOutcome exactly as the probe last set it — overwriting it would make /health claim a probe ran when none did. So on a host that supplies the token through the environment, the steady state is okSource: "request" + lastOutcome: "token-present", and that pairing is normal rather than contradictory. It is also the state three of the four instances in the reference fleet spend most of their time in.

There is no lastOutcome: "verified-by-request". Earlier revisions of this table, of ADR 0014 and of the CHANGELOG all promised one; the server has never emitted it and by design never will (see the paragraph above). A monitor written against that value could not match any real response. Key on okSource: "request". Corrected in #342.

Inconclusive probes are not a row here, because they leave the verdict alone: a timeout or unavailable writes lastOutcome, lastCheck, message and consecutiveInconclusive, and leaves ok, okSource and okAt untouched. That is the point — a probe killed by host load measured load, not the credential.

Why token-present is not authenticated. claude auth status exits 0 whenever a token is present, without checking it: a fabricated token yields exit 0 and loggedIn: true. On a host that supplies CLAUDE_CODE_OAUTH_TOKEN through a systemd EnvironmentFile or an inlined unit — which is how OCP is normally deployed on Linux — the probe therefore cannot distinguish a working credential from an expired one. Reporting authenticated there is what issue #308 found: /health asserting the proxy was authenticated while every request failed on authentication. See ADR 0014.

A null is not a failure. It means no conclusive verdict, ocp doctor reports it as WARN rather than FAIL, and it does not block ocp update. On such a host the first successful request moves it to true.

auth.ok never moves status. proxyHealthStatus reads consecutiveFailures and never ok, so no verdict in the table above can flip a host to degraded.

The tally it reads is a different matter, and this is the part worth knowing. Conclusive probe rejections raise consecutiveFailures (ADR 0010), and any successful request clears it — a deliberate restoration of ADR 0010's self-heal, unqualified by which lane served the request (see ADR 0014 § Consequences). So a host reporting degraded can return to ok on the first request that succeeds, with no probe having run in between. If you are debugging status — ocp update's post-flight check and the dashboard's status card both read it, and the dashboard has no other auth signal — do not assume it is probe-driven only.

(This paragraph said "status is unaffected by any of this … never by auth.ok" until #361. The second clause was true and the bolded headline was not: it read as though nothing in this section could touch status, while a successful request has always cleared the tally that decides it.)

Running more than one instance on a host

DEFAULT_PORT (3456) is the primary and never changes — it is the single source of truth in lib/constants.mjs, and CI hard-fails any other port literal in source. A host that n