Claude Proxy with Easegress

August 19, 2025 · View on GitHub

Overview

The Claude Proxy feature in Easegress enables seamless integration between Anthropic's Claude AI models and systems designed for OpenAI's API. This powerful capability allows you to:

  • Route AI requests through a consistent interface
  • Access Claude's unique capabilities through familiar OpenAI endpoints

This guide walks you through setting up and using the Claude Proxy with Easegress.

Prerequisites

Before proceeding, ensure you have:

Setting Up the Claude Proxy

The Claude Proxy requires configuring three components in Easegress:

  1. AIGatewayController: Manages provider connections and API keys
  2. HTTPServer: Exposes the proxy endpoints
  3. Pipeline: Processes and routes the requests

Follow the detailed steps in the AI Gateway Configuration guide to set up these components. Once configured, any request with the path prefix /v1/messages will be automatically handled in Claude proxy mode.

Here's a complete example configuration:

# HTTPServer configuration - handles incoming requests
- kind: HTTPServer
  name: ai-gateway-server
  port: 8080  # Change this if port 8080 is already in use
  rules:
    - paths:
        - backend: ai-gateway-pipeline
          pathPrefix: /  # Routes all requests to the AI gateway pipeline

---
# Pipeline configuration - processes the requests
- kind: Pipeline
  name: ai-gateway-pipeline
  filters:
    - kind: AIGatewayProxy
      name: ai-gateway-proxy
      providerName: openai-provider  # Must match the provider name in AIGatewayController

---
# AIGatewayController configuration - manages providers
kind: AIGatewayController
name: AIGatewayController
providers:
    - apiKey: sk-proj-openai-api-key  # Replace with your actual OpenAI API key
      baseURL: https://api.openai.com
      name: openai-provider
      providerType: openai

After applying this configuration, your Claude Proxy will be ready to accept requests at http://localhost:8080.

Set up the Claude Environment

To use the Claude CLI with your proxy, you need to set environment variables that redirect Claude to use your Easegress proxy instead of the default Anthropic endpoints:

# Configure Claude to use your local Easegress proxy
export ANTHROPIC_BASE_URL=http://localhost:8080

# Map Claude models to OpenAI model names
# Note: Choose appropriate OpenAI models that match your use case
export ANTHROPIC_SMALL_FAST_MODEL="gpt-3.5-turbo"  # For faster, smaller tasks
export ANTHROPIC_MODEL="gpt-4"  # For more complex reasoning

# Start the Claude CLI
claude

Important: Claude may use significantly more tokens than OpenAI for certain tasks, especially when processing large contexts. Consider this when setting up rate limits or budgets.

Using Claude with OpenAI-Compatible API

After setting up the environment and launching Claude, you can verify the proxy connection is working:

  1. Check the welcome message confirms the correct API Base URL:
Overrides (via env):
    • API Base URL: http://localhost:8080
  1. Test with a simple query:
> who are you
⏺ Claude Code

You can now use Claude through the OpenAI-compatible API interface for various tasks:

  • Code generation and analysis
  • Text completion and summarization
  • Question answering
  • Document analysis
  • Creative writing

Troubleshooting

If you encounter issues with your Claude Proxy setup:

  • Connection errors: Verify Easegress is running and the port (8080 by default) is available
  • Authentication failures: Check that your OpenAI API key is correctly configured in the AIGatewayController
  • Model errors: Ensure you're specifying model names that exist in OpenAI's API
  • Unexpected responses: Check Easegress logs for detailed error information