claude-max-api-proxy

Use Claude Code, Gemini CLI, and OpenAI-compatible providers from the clients you already use.

One local endpoint. Claude by default. Other providers only when you request
their configured model IDs.

Quick start · Compare · Client setup · API reference

_{Continue · Aider · OpenAI SDKs · Open WebUI · curl · custom agents}

Claw Proxy turns authenticated AI CLIs and configured model providers into a
local OpenAI-compatible service. Point an existing editor, SDK, agent, or chat
frontend at a new baseURL; keep the rest of your workflow.

Why Claw Proxy

Most editors, agents, and SDKs already speak the OpenAI API. Claude Code and
Gemini CLI already know who you are. Claw Proxy connects those two sides
without making you rebuild your toolchain.

Quick Start

The default Claude route needs Node.js 22+, npm, and an authenticated
Claude Code CLI session.

# Authenticate Claude Code once
npm install -g @anthropic-ai/claude-code
claude auth login

# Install and run Claw Proxy
git clone https://github.com/mattschwen/claude-max-api-proxy.git
cd claude-max-api-proxy
npm ci
npm run build
npm start

Startup probes the models available to the local account before the server is
ready. Verify the runtime:

curl http://127.0.0.1:3456/health
curl http://127.0.0.1:3456/v1/models

Send the first request:

curl -N http://127.0.0.1:3456/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{
    "model": "sonnet",
    "stream": true,
    "messages": [
      { "role": "user", "content": "Reply with: bridge online" }
    ]
  }'

Point a client at the proxy

from openai import OpenAI

client = OpenAI(
    base_url="http://127.0.0.1:3456/v1",
    api_key="local",
)

response = client.chat.completions.create(
    model="sonnet",
    messages=[{"role": "user", "content": "Reply with: bridge online"}],
)

print(response.choices[0].message.content)

import OpenAI from "openai";

const client = new OpenAI({
  baseURL: "http://127.0.0.1:3456/v1",
  apiKey: "local",
});

const response = await client.chat.completions.create({
  model: "sonnet",
  messages: [{ role: "user", content: "Reply with: bridge online" }],
});

console.log(response.choices[0].message.content);

How Routing Works

flowchart TB
    Client["OpenAI-compatible client<br/>editor · SDK · agent · chat UI"]
    Proxy["Claw Proxy<br/>127.0.0.1:3456/v1"]
    Claude["Claude Code CLI<br/>authenticated local session"]
    Gemini["Gemini CLI<br/>authenticated local session"]
    External["OpenAI-compatible HTTP<br/>OpenAI · Z.AI · OpenRouter · local"]
    Runtime["sessions · queues · cancellation<br/>health · metrics · operator UI"]

    Client --> Proxy
    Proxy -->|"default or Claude selector"| Claude
    Proxy -->|"configured Gemini model"| Gemini
    Proxy -->|"configured external model"| External
    Proxy -.-> Runtime

The routing rule is intentionally simple: Claude is implicit; every other
provider is explicit.

External models never silently replace Claude. If the Claude path is
unavailable, a Claude-default request returns a Claude error instead of
quietly sending the prompt elsewhere.

What You Get

• Keep your toolchain. Continue, Aider, Open WebUI, OpenAI SDKs, curl,
  and custom agents only need a new base URL.
• Reuse authenticated CLIs. Route through local Claude Code or Gemini CLI
  sessions without adding a provider API key for those paths.
• Use OpenAI-shaped interfaces. Stream Chat Completions or use the
  non-streaming Responses compatibility surface.
• Runtime model discovery. /v1/models reports the Claude IDs the installed
  CLI can actually use alongside configured external models.
• Durable conversations. Stable conversation IDs, committed checkpoints,
  idempotent non-streaming retries, and branchable Responses continuations
  survive process restarts.
• Safe concurrency. Independent conversations run in parallel; each
  conversation can use interrupt-style latest-wins or FIFO queueing.
• Operational control. Cancel queued or active work, inspect health and
  capabilities, scrape Prometheus metrics, and use the built-in operator UI.
• Agent-ready discovery. Capability metadata describes available models,
  reasoning inputs, provider state, and the built-in expert-coder profile.

Compare the Options

This comparison is for connecting OpenAI-compatible developer tools to the
providers and authenticated CLIs you already use.

API Surface

See the full API reference for request shapes,
response headers, reasoning controls, conversation identity, idempotency, and
error codes.

[!IMPORTANT]
An empty /v1/models response is a real availability signal. It means no
Claude model passed its runtime probe and no external model is configured.
Check claude auth status, /health.models.unavailable, and the
troubleshooting guide.

Connect a Provider

Claude Code CLI — default

Claw Proxy does not require an Anthropic API key for this route. It launches
the locally authenticated claude CLI and preserves committed CLI sessions
across turns.

claude auth login
npm start

Gemini CLI — explicit

Use a local authenticated Gemini CLI session without a hosted API key:

export GEMINI_CLI_ENABLED=true
# `auto` lets the installed Gemini CLI select a currently available model.
export GEMINI_CLI_MODEL=auto
npm start

Request auto to use that route. To expose specific models instead, set
GEMINI_CLI_MODEL and GEMINI_CLI_EXTRA_MODELS to IDs supported by your
installed CLI. Google recommends the CLI's
auto model selection
because model availability changes over time.

OpenAI-compatible HTTP — explicit

OpenAI itself and any service with a compatible Chat Completions endpoint can
be registered as an explicit provider:

export OPENAI_COMPAT_FALLBACK_PROVIDER=openai
export OPENAI_COMPAT_FALLBACK_BASE_URL=https://api.openai.com/v1
export OPENAI_COMPAT_FALLBACK_API_KEY=your-api-key
export OPENAI_COMPAT_FALLBACK_MODEL=your-current-model-id
npm start

Shortcuts are included for Google AI Studio (GEMINI_API_KEY) and Z.AI
(ZAI_API_KEY). For multiple providers, per-model upstream IDs, custom
headers, timeouts, and capability metadata, use
OPENAI_COMPAT_PROVIDERS_JSON.

Provider configuration →

Client Integrations

Use the same connection details everywhere; choose a model from
GET /v1/models instead of copying an ID from an old example.

name: Claw Proxy
version: 1.0.0
schema: v1

models:
  - name: Claw Proxy
    provider: openai
    model: sonnet
    apiBase: http://127.0.0.1:3456/v1
    apiKey: local

{
  "models": {
    "providers": {
      "claw-proxy": {
        "baseUrl": "http://127.0.0.1:3456/v1",
        "apiKey": "local",
        "api": "openai-completions",
        "models": [
          {
            "id": "sonnet",
            "name": "Claw Proxy · Sonnet"
          }
        ]
      }
    }
  }
}

Built-in expert agent

expert-coder is a discoverable, repository-aware coding profile exposed by
GET /v1/agents. Request it through /v1/agents/expert-coder/chat/completions,
or make it the default for every request:

export CLAUDE_PROXY_DEFAULT_AGENT=expert-coder
npm start

Conversations, Queues, and Cancellation

Set conversation_id when a client needs a durable thread:

{
  "model": "sonnet",
  "conversation_id": "project-42",
  "messages": [
    { "role": "user", "content": "Continue the implementation." }
  ]
}

Every accepted request returns X-Request-Id and X-Conversation-Id.
Use the request ID to cancel work:

curl -X DELETE http://127.0.0.1:3456/v1/requests/REQUEST_ID

The default same-conversation policy is latest-wins. Set
CLAUDE_PROXY_SAME_CONVERSATION_POLICY=queue for FIFO, or choose
interrupt / queue per request. Independent conversation IDs run
concurrently up to CLAUDE_PROXY_MAX_CONCURRENT_REQUESTS.

Operator Surfaces

Run the proxy on the host, then open:

The command deck exposes queue pressure, throughput, latency, sessions,
subprocesses, model state, recent conversations, and structured logs. Chat Lab
supports independent thread tabs, transcript branching, and per-thread
interrupt or FIFO behavior.

Open WebUI is optional:

# The host proxy must be reachable from Docker.
HOST=0.0.0.0 CLAUDE_PROXY_LOG_FILE=logs/proxy.jsonl npm start

# In another shell:
docker compose up -d open-webui

Open WebUI will be available at http://127.0.0.1:8080/.

Configuration Essentials

All configuration is environment-variable driven. See the
complete configuration reference.

Deployment

For long-running deployments, persist DB_PATH, SESSION_FILE, and
RUNTIME_STATE_FILE; set CLAUDE_PROXY_LOG_FILE; probe /health; scrape
/metrics; and keep the service behind trusted network controls.

Documentation

Compatibility and Requirements

• Node.js 22 or newer
• npm
• For the default route: authenticated Claude Code CLI access to at least one
  Claude model
• For the Gemini CLI route: an authenticated local Gemini CLI
• For HTTP providers: a compatible base URL, model ID, and any required
  credentials

Claw Proxy implements the OpenAI surfaces documented above; it is not a
complete reimplementation of every OpenAI API. In particular, Responses
streaming is not currently supported. Query /v1/capabilities instead of
assuming optional features.

Development

npm ci
npm run ci
npm start

Source lives in src/. TypeScript builds to dist/; tests live beside source
files as *.test.ts and run from their compiled dist/**/*.test.js output.

Security

The proxy binds to 127.0.0.1 by default and does not authenticate normal
inference, diagnostic, or cancellation requests. Anything that can reach the
service can spend configured provider quota, inspect operational diagnostics,
or cancel a request if it obtains that request's opaque ID.

Keep it on localhost unless you place authentication and network controls in
front of it. Leave the optional admin API disabled unless needed, and use
CLAUDE_PROXY_ADMIN_TOKEN when enabling it beyond loopback. Provider plans,
usage limits, and terms still apply.

See the security policy for responsible
disclosure.

Community

Issues and pull requests are welcome. Read the
contribution guide and
code of conduct before participating.

If Claw Proxy removes an integration layer from your stack,
star the repository so
other indie developers can find it.

License

MIT