claude-code-openai-wrapper

By default, the wrapper is stateless (standard OpenAI behavior). However, you can enable Session Mode by providing a session_id in the request body. This allows Claude to maintain conversation history across multiple requests.

Using Sessions with OpenAI SDK

Pass the session_id via extra_body.

import openai

client = openai.OpenAI(
    base_url="http://localhost:8000/v1",
    api_key="not-needed"
)

# Request 1: Start session
client.chat.completions.create(
    model="claude-sonnet-4-6",
    messages=[{"role": "user", "content": "My name is Alice."}],
    extra_body={"session_id": "my-learning-session"}
)

# Request 2: Claude remembers context
response = client.chat.completions.create(
    model="claude-sonnet-4-6",
    messages=[{"role": "user", "content": "What is my name?"}],
    extra_body={"session_id": "my-learning-session"}
)
# Output: "Your name is Alice."

Session Management API

You can manage active sessions using the following endpoints:

• GET /v1/sessions - List all active sessions
• GET /v1/sessions/{session_id} - Get session details
• DELETE /v1/sessions/{session_id} - Delete a session
• GET /v1/sessions/stats - Get session statistics

Note: Sessions expire after 1 hour of inactivity.

client.chat.completions.create(
    model="claude-sonnet-4-6",
    messages=[{"role": "user", "content": "Hello!"}],
    extra_body={"session_id": "my-session"}
)

The wrapper provides an OpenAI-compatible interface to Claude services. You must use your own valid Claude subscription or API access. The recommended method depends on your scale and use case:

Authentication Details

• ANTHROPIC_API_KEY: Explicitly allowed for programmatic access under Commercial Terms.
• AWS Bedrock / Google Vertex AI: Explicitly allowed for programmatic access under Commercial Terms.
• CLI Auth (claude auth login): Uses the official Claude Agent SDK with your personal Claude Pro/Max subscription. This is functionally equivalent to using Claude Code directly.

You can containerize the Claude Code OpenAI API Wrapper using Docker. This includes options for production, custom workspaces, and development with hot reloading.

Build the image

docker build -t claude-wrapper:latest .

Run modes

Production: Runs in detached mode, mapping port 8000 and mounting the .claude directory for authentication persistence.

docker run -d -p 8000:8000 \
  -v ~/.claude:/root/.claude \
  --name claude-wrapper \
  claude-wrapper:latest

With custom workspace: Use this to allow the agent to access specific project files. Set CLAUDE_CWD to the mounted path.

docker run -d -p 8000:8000 \
  -v ~/.claude:/root/.claude \
  -v /path/to/project:/workspace \
  -e CLAUDE_CWD=/workspace \
  claude-wrapper:latest

Development (hot reload): Mounts the current directory to /app and uses poetry to run uvicorn with the --reload flag.

docker run -d -p 8000:8000 \
  -v ~/.claude:/root/.claude \
  -v $(pwd):/app \
  claude-wrapper:latest \
  poetry run uvicorn src.main:app --host 0.0.0.0 --port 8000 --reload

After starting the server, you can verify the installation and functionality using the provided test scripts.

Quick Test

Run the quick test suite to verify all endpoints are responding:

poetry run python test_endpoints.py

Basic Test

Run the comprehensive test suite. If you have enabled API key protection, you must provide the TEST_API_KEY environment variable:

# Standard run
poetry run python test_basic.py

# With API key protection
TEST_API_KEY=your-generated-key poetry run python test_basic.py

Verify Authentication Status

You can check the current authentication status via a curl command:

curl http://localhost:8000/v1/auth/status | python -m json.tool

Expected Results

Successful tests should indicate:

• 4/4 endpoint tests passing
• 4/4 basic tests passing
• Detected authentication method (e.g., claude_cli, anthropic, bedrock, or vertex)
• Real cost tracking and accurate token counts

# Quick Test
poetry run python test_endpoints.py

# Basic Test with API key
TEST_API_KEY=your-generated-key poetry run python test_basic.py

# Check auth status
curl http://localhost:8000/v1/auth/status | python -m json.tool

When upgrading to version 2.0.0+, the project migrates from the legacy claude-code-sdk to the new claude-agent-sdk. This involves updating imports, dependency management, and the configuration object structure.

Dependency Update

Replace the old SDK with the new version using Poetry:

poetry remove claude-code-sdk
poetry add claude-agent-sdk@^0.1.6
poetry lock
poetry install

Code Changes

1. Update Imports: Change the import source from claude_code_sdk to claude_agent_sdk.
2. Update Options Class: Replace ClaudeCodeOptions with ClaudeAgentOptions.
3. System Prompt Configuration: The system prompt now uses a structured format. To restore the default Claude Code behavior, use the preset key.

Example Migration

# Before
from claude_code_sdk import query, ClaudeCodeOptions, Message
options = ClaudeCodeOptions(max_turns=1, cwd="/path")

# After
from claude_agent_sdk import query, ClaudeAgentOptions, Message
options = ClaudeAgentOptions(
    max_turns=1,
    cwd="/path",
    system_prompt={"type": "preset", "preset": "claude_code"}
)