Claude SDK Compatibility

Claude SDK Compatibility

Understanding the differences between Claude Code SDK and standard AI APIs.

!!! important "Key Limitation" This proxy uses the Claude Code SDK internally, which has fundamentally different capabilities and limitations compared to the official Anthropic or OpenAI APIs. Many standard API parameters are ignored because they cannot be passed to the Claude SDK.

Overview

The Claude Code Proxy acts as a bridge between standard API formats (Anthropic/OpenAI) and the Claude Code SDK. However, the Claude SDK was designed for interactive development workflows, not general API usage, which creates significant compatibility limitations.

Parameter Support Matrix

Fully Supported Parameters

These parameters work exactly as expected:

Ignored Parameters

These parameters are accepted but completely ignored:

Legend: ✅ Supported, ⚠️ Ignored, ❌ Not applicable

Tool Parameters (Limited Support)

Tool-related parameters have very limited compatibility:

Why These Limitations Exist

Claude Code SDK Design Philosophy

The Claude Code SDK was designed for:

1. Interactive Development: Real-time coding assistance with built-in tools
2. Local Context: Working with local files, directories, and projects
3. Permission-Based Access: Controlled tool usage with user approval
4. Session Management: Maintaining context across development sessions

Standard API Design Philosophy

Traditional AI APIs (OpenAI/Anthropic) focus on:

1. Text Generation Control: Fine-grained sampling parameters
2. Custom Functions: User-defined tool/function calling
3. Batch Processing: Multiple responses and deterministic generation
4. Structured Output: JSON, formatted responses

These different design goals create fundamental incompatibilities.

Practical Implications

For Basic Chat Applications

✅ Works Well:

{
  "model": "claude-3-5-sonnet-20241022",
  "messages": [{"role": "user", "content": "Hello!"}],
  "max_tokens": 1000,
  "stream": true
}

❌ Parameters Ignored:

{
  "model": "claude-3-5-sonnet-20241022",
  "messages": [{"role": "user", "content": "Hello!"}],
  "max_tokens": 1000,
  "temperature": 0.7,          // Ignored
  "top_p": 0.9,               // Ignored
  "presence_penalty": 0.1     // Ignored
}

For Coding Applications

✅ Use ClaudeAgentOptions Instead:

{
  "model": "claude-3-5-sonnet-20241022",
  "messages": [{"role": "user", "content": "Help me debug this code"}],
  "max_tokens": 2000,

  // Claude SDK specific options
  "max_thinking_tokens": 10000,
  "allowed_tools": ["Read", "Write", "Bash", "Edit"],
  "permission_mode": "acceptEdits",
  "cwd": "/path/to/project"
}

For Production Applications

Consider whether Claude SDK limitations are acceptable:

Unsuitable for:

• Applications requiring precise temperature control
• Custom function/tool definitions
• Deterministic generation (seed-based)
• Multiple response variants
• Structured JSON output

Suitable for:

• Development assistance
• Code analysis and generation
• File manipulation tasks
• Interactive coding sessions

Migration Strategies

From OpenAI API

1. Remove unsupported parameters:

   # Before
   response = client.chat.completions.create(
       model="gpt-4",
       messages=messages,
       temperature=0.7,      # Remove
       top_p=0.9,           # Remove
       presence_penalty=0.1  # Remove
   )
   
   # After
   response = client.chat.completions.create(
       model="claude-3-5-sonnet-20241022",
       messages=messages
   )
   

2. Replace function calling with Claude tools:

   # Before: Custom function definitions
   tools = [{"type": "function", "function": {...}}]
   
   # After: Use built-in Claude tools
   extra_params = {
       "allowed_tools": ["Read", "Write", "Bash"],
       "permission_mode": "acceptEdits"
   }
   

From Anthropic API

1. Remove sampling parameters:

   # Before
   response = client.messages.create(
       model="claude-3-5-sonnet-20241022",
       messages=messages,
       temperature=0.7,  # Remove
       top_p=0.9,       # Remove
       top_k=40         # Remove
   )
   
   # After
   response = client.messages.create(
       model="claude-3-5-sonnet-20241022",
       messages=messages
   )
   

2. Add ClaudeAgentOptions for advanced features:

   # After: Enhanced with Claude-specific options
   response = client.messages.create(
       model="claude-3-5-sonnet-20241022",
       messages=messages,
       max_thinking_tokens=15000,
       allowed_tools=["Read", "Write"],
       cwd="/project/path"
   )
   

Testing Compatibility

Use the provided test script to verify parameter behavior:

./test-claude-options.sh

This will show which parameters are working and which are being ignored.

Best Practices

1. Don't rely on ignored parameters: Remove them from your code to avoid confusion
2. Use ClaudeAgentOptions: Leverage Claude-specific features for better results
3. Test thoroughly: Behavior may differ significantly from other APIs
4. Monitor logs: Enable debug logging to see what's actually being passed to the SDK
5. Understand the trade-offs: Accept limitations in exchange for powerful coding features

Conclusion

The Claude Code Proxy provides powerful development capabilities through the Claude SDK, but with significant API compatibility limitations. Understanding these limitations is crucial for successful integration and avoiding unexpected behavior.

For basic chat applications, the proxy works reasonably well with standard API formats. For advanced development workflows, ClaudeAgentOptions provide capabilities that exceed traditional APIs, but require learning Claude-specific parameters.