claude-code-openai-wrapper: exposing Claude Code as an OpenAI chat completions API

An OpenAI-shaped endpoint in front of Claude Code

The project describes itself as an OpenAI API-compatible wrapper for Claude Code, allowing you to use Claude Code with any OpenAI client library, and states that it is now powered by the official Claude Code Python SDK with enhanced authentication and features. That is the entire proposition. A FastAPI application exposes the OpenAI chat completions path, and any library that can talk to an OpenAI endpoint can talk to this. The audience is specific: teams with existing integrations, tooling or internal services already written against the OpenAI SDK that they want to point at Claude Code instead of rewriting. The README describes the project as production ready with core features working and tested, and the top level entries back that up with a small set of flat Python modules, main.py, auth.py, claude_cli.py, message_adapter.py, models.py, parameter_validator.py and session_manager.py, alongside several test modules covering basic behaviour, endpoints, non-streaming responses, parameter mapping and session continuity.

Four ways to authenticate, detected automatically

The authentication section is the part that decides whether the wrapper works in your environment, and it supports four paths with automatic detection. Claude CLI auth works with an existing claude auth setup, which the README recommends for development. A direct API key comes from the ANTHROPIC_API_KEY environment variable. AWS Bedrock provides enterprise authentication with AWS credentials, and Google Vertex AI provides GCP authentication support. The advantage of the CLI route is that a developer who already uses Claude Code interactively does not have to manage a second credential, and the SDK path also brings session management with proper session IDs and continuity, plus real time cost tracking from the SDK metadata and accurate input and output token counts. The error handling is described as enhanced, with detailed authentication diagnostics, which matters because a misconfigured credential in a wrapper otherwise shows up as an opaque failure.

Tools are off by default, which is a deliberate speed choice

The most consequential design decision is stated plainly in the feature list: fast by default, with tools disabled for OpenAI compatibility, which the README quantifies as five to ten times faster. Optional tool usage, covering Read, Write and Bash among others, can be enabled when explicitly asked for. The reasoning behind the default is compatibility rather than performance alone. A plain OpenAI chat completion does not involve the tool loop, so leaving tools on means the wrapper spends effort on a protocol the client never asked for, and on the lower value path of a model calling a tool and having the result fed back. The cost is that a client expecting Claude Code to read and edit files will not get that unless it turns the option on, and it will get noticeably slower once it does. The wrapper also supports system prompts through SDK options, model selection with validation, and both streaming and non-streaming responses.

Getting it running with Poetry and uvicorn

The quick start is a short sequence. You install the Claude Code CLI, authenticate, clone the repository, install dependencies with Poetry, and start the server under uvicorn.

# 1. Install Claude Code CLI (if not already installed)
npm install -g @anthropic-ai/claude-code

# 2. Authenticate (choose one method)
claude auth login  # Recommended for development
# OR set: export ANTHROPIC_API_KEY=your-api-key

# 3. Clone and setup the wrapper
git clone https://github.com/RichardAtCT/claude-code-openai-wrapper
cd claude-code-openai-wrapper
poetry install

# 4. Start the server
poetry run uvicorn main:app --reload --port 8000

# 5. Test it works
poetry run python test_endpoints.py

The prerequisites are Python 3.10 or newer and Poetry for dependency management, and the server then listens on http://localhost:8000. In production mode the port handling is described in more detail: the default is 8000 or whatever PORT is set to, if the port is in use the server automatically finds the next available one, and a custom port can be passed as an argument or set through the environment variable. The project metadata confirms the stack, with FastAPI 0.115, uvicorn with the standard extra, pydantic 2.10, httpx, sse-starlette for server sent events, python-multipart, and claude-code-sdk pinned at 0.0.14.

The .env file is the whole configuration surface

Configuration is a single environment file, and the example file shipped in the repository shows every key that exists.

# Claude CLI path (usually just "claude")
CLAUDE_CLI_PATH=claude

# Optional API key for client authentication
# If not set, server will prompt for interactive API key protection on startup
# API_KEY=your-optional-api-key
PORT=8000

# Timeout Configuration (milliseconds)
MAX_TIMEOUT=600000

# CORS Configuration
CORS_ORIGINS=["*"]

The interesting key is the commented out API_KEY. If it is absent, the server prompts at startup, asking whether to protect the API endpoint with an API key, and choosing no is the default, which means the server runs without authentication at all. Choosing yes makes it generate and display a key, with a message to save it because you need it for API calls. The README positions this as fitting three situations, local development with no authentication, remote access with generated tokens, and use over a VPN or Tailscale where the extra layer is welcome. The CORS default of a wildcard origin is worth thinking about before exposing the server beyond localhost.

Sessions, health endpoints and the examples directory

Beyond the chat endpoint, the feature list includes session continuity with conversation history carried across requests, and separate session management endpoints for full session control. There are also health, auth status and models endpoints, and a development mode with auto-reload using uvicorn --reload. The examples directory shows how a client is expected to use all of this, with a curl_example.sh, an openai_sdk.py showing the OpenAI client in use, a session_continuity.py and a session_curl_example.sh for the session flow, and a streaming.py. The test modules at the root mirror that coverage, with test_basic.py, test_endpoints.py, test_non_streaming.py, test_parameter_mapping.py, test_session_complete.py, test_session_continuity.py, test_session_simple.py and test_textblock_fix.py, which is a good sign about what the author considered fragile. The console script is registered as claude-wrapper pointing at main:run_server, so the server can be started as a command rather than only through uvicorn.

Where the wrapper is the wrong tool

There are limits that follow from the shape of the project. It is a single-purpose adapter rather than a gateway, so it gives you one backend, one protocol and no routing, no fallback between providers, and no quota management, none of which you need if you only want one thing to talk to one thing. It also inherits Claude Code's licence and terms through the SDK path, and the repository's own licensing is in an odd state: the project metadata declares MIT, while the repository page shows no recognised licence, so treat the terms as unverified until you read the files yourself. The tool mode trade-off is the other sharp edge. Tool use is off by default for speed, and a client that needs Claude Code to read or write files has to turn it on and accept the slowdown, which means the wrapper is not a transparent drop-in for every Claude Code use. The alternative worth naming is talking to the Anthropic API directly, or using a general gateway that speaks several provider protocols, and the difference in approach is exactly the trade here: one narrow adapter that is easy to reason about, against a more capable layer that does more but has more of its own surface to maintain.

Editorial conclusion

Adopt claude-code-openai-wrapper if you have existing code that speaks the OpenAI chat completions protocol and you want it to talk to Claude Code without rewriting the client. Do not adopt it as a general model gateway, because it is scoped to one backend and one purpose, and note the licence situation, since the repository page lists no recognised licence while the project metadata claims MIT. Verify first which authentication method your environment can use, and whether the tool-using mode you need is acceptable at the reduced speed the default mode buys.

Frequently asked questions

Official sources

1. Issues
2. README
3. Releases
4. RichardAtCT/claude-code-openai-wrapper on GitHub