PL ▾

Strona głównaPrzewodnik

Konfiguracja proxy Claude Code z interfejsem API kompatybilnym z OpenAI

Ta konfiguracja proxy Claude Code składa się z pięciu kroków: uzyskanie klucza, napisanie konfiguracji LiteLLM, uruchomienie proxy, ustawienie dwóch zmiennych środowiskowych i przeprowadzenie testu. Zajmuje to około dziesięć minut.

Pięć świetlistych kamieni milowych prowadzących od terminala do serwera, pokazujących konfigurację proxy krok po kroku

Kluczowe punkty

  1. Uruchom lokalne proxy LiteLLM, które przekieruje ruch do https://api.claudecodeproxyapi.com/v1
  2. Wskaż Claude Code na proxy za pomocą ANTHROPIC_BASE_URL i ANTHROPIC_AUTH_TOKEN
  3. Powiąż nazwę modelu wysyłaną przez Claude Code z modelem upstreamowym uncensored
  4. Przetestuj proxy za pomocą curl przed uruchomieniem CLI

Czego potrzebujesz

  • Klucz API ze strony kluczy. Zarejestruj się za pomocą Google lub e-maila i hasła, a następnie odbierz kredyt próbny $0,50 jednym kliknięciem.
  • Python 3.9 lub nowszy, aby zainstalować proxy.
  • Claude Code zainstalowany i działający na Twojej maszynie.

Po co w ogóle proxy? Claude Code używa formatu Anthropic Messages, a nasz interfejs API obsługuje format OpenAI Chat Completions z identyfikatorem modelu uncensored. Proxy tłumaczy między nimi. Jeśli wolisz najpierw poznać tło, przeczytaj przewodnik rozwiązywania problemów z proxy. Model to model o otwartych wagach, a nie Claude, więc spodziewaj się innego zachowania przy trudnych zadaniach wieloetapowych.

Krok 1: zainstaluj proxy

Użyj wirtualnego środowiska, aby zależności proxy były odseparowane od Twoich projektów:

python3 -m venv ~/litellm-env
source ~/litellm-env/bin/activate
pip install 'litellm[proxy]'

LiteLLM to zewnętrzne oprogramowanie open-source. Poniższe polecenia i klucze konfiguracji odpowiadają jego publicznym dokumentom w momencie pisania, ale sprawdź jego aktualną dokumentację, jeśli jakaś flaga się zmieniła.

Krok 2: napisz konfigurację

Utwórz config.yaml. Nazwa model_name to nazwa wysyłana przez klienta. Blok litellm_params określa, gdzie przekierować żądanie. Prefiks openai/ mówi LiteLLM, aby rozmawiał z serwerem kompatybilnym z OpenAI.

cat > config.yaml <<'EOF'
model_list:
  - model_name: claude-sonnet
    litellm_params:
      model: openai/uncensored
      api_base: https://api.claudecodeproxyapi.com/v1
      api_key: os.environ/UPSTREAM_KEY
EOF

Alias claude-sonnet to tylko przykład, nie wymóg. Claude Code może wysyłać różne nazwy modeli, np. główny model i mniejszy do zadań w tle. Dodaj jeden wpis model_list dla każdej nazwy widocznej w logach proxy, wszystkie wskazujące na ten sam upstream. Wskazanie każdego aliasu na uncensored jest OK, bo jest tylko jeden model.

Klucz jest odczytywany ze zmiennej środowiskowej, więc nigdy nie trafi do pliku, który możesz dodać do repozytorium.

Krok 3: uruchom proxy

export UPSTREAM_KEY="YOUR_KEY"
litellm --config config.yaml --port 4000

Zostaw ten terminal otwarty. Powinieneś zobaczyć serwer nasłuchujący na porcie 4000. Teraz sprawdź ścieżkę upstreamową ze strony proxy za pomocą testowego zapytania w formacie Anthropic, które wyśle Claude Code:

curl http://localhost:4000/v1/messages \
  -H "content-type: application/json" \
  -H "x-api-key: sk-local-anything" \
  -H "anthropic-version: 2023-06-01" \
  -d '{
    "model": "claude-sonnet",
    "max_tokens": 200,
    "messages": [{"role": "user", "content": "Reply with the word ready."}]
  }'

Odpowiedź JSON, której treść zawiera słowo „ready”, oznacza, że tłumaczenie działa w całości: format Anthropic na wejściu, format OpenAI do https://api.claudecodeproxyapi.com/v1 i z powrotem. Jeśli ustawisz klucz główny w konfiguracji LiteLLM, użyj go zamiast sk-local-anything.

Krok 4: wskaż Claude Code na proxy

Claude Code odczytuje adres API i token ze zmiennych środowiskowych. Ustaw je w powłoce, w której uruchamiasz CLI:

export ANTHROPIC_BASE_URL="http://localhost:4000"
export ANTHROPIC_AUTH_TOKEN="sk-local-anything"
export ANTHROPIC_MODEL="claude-sonnet"
claude

Użyj adresu proxy bez sufiksu /v1, ponieważ CLI dodaje swoją własną ścieżkę. Token musi spełniać tylko proxy, ponieważ prawdziwym kluczem upstreamowym jest ten, który wyeksportowałeś jako UPSTREAM_KEY. Jeśli użyjesz pliku ustawień CLI do wartości środowiskowych zamiast powłoki, wpisz tam te same trzy nazwy. Nazwy zmiennych środowiskowych dla Claude Code mogą się zmieniać między wydaniami, więc zweryfikuj je z aktualną dokumentacją Claude Code, jeśli coś jest ignorowane.

Krok 5: uruchom pierwsze zadanie i obserwuj logi

Zacznij od małych rzeczy. Poproś CLI o wyjaśnienie jednego pliku lub dodanie komentarza do funkcji. W terminalu proxy powinieneś zobaczyć zapytanie na krok. Zapisz każdą pojawiającą się nazwę modelu; jeśli którejś nie ma w model_list, proxy odpowiada błędem, więc dodaj ją i zrestartuj.

Wywoływanie funkcji ma tutaj znaczenie, ponieważ CLI odczytuje pliki i edytuje kod za pomocą narzędzi. Interfejs API obsługuje tools, tool_choice i strumieniowane tool_calls, a proxy je konwertuje. Słabsze przestrzeganie schematu narzędzia objawia się nieudaną edycją lub powtórzeniem kroku. W takim przypadku skróć zadanie i spróbuj ponownie, zanim uznasz konfigurację za wadliwą.

Okno kontekstu ma 100 000 tokenów, łącznie z promptem i uzupełnieniem. Długie sesje przekraczające ten limit zawiodą, więc zacznij nową sesję dla nowego zadania. Koszty są niskie: $0,15 za 1M tokenów wejściowych i $0,50 za 1M tokenów wyjściowych. Zapytanie z 20 000 tokenami wejściowymi i 800 wyjściowymi kosztuje $0,003 + $0,0004 = $0,0034. Zobacz stronę z cenami, aby doładować środki, które na tej stronie są płatne kryptowalutami (USDT w sieci TRC20, USDC na Base).

Rozwiązywanie problemów

Co widziszPrzyczynaNaprawa
Połączenie odrzuconeProxy nie działa lub port jest innyUruchom go i dopasuj port w ANTHROPIC_BASE_URL
Proxy 404 lub „model nie znaleziony”Nazwa modelu wysłana przez CLI nie występuje w konfiguracjiDodaj tę nazwę do model_list
Upstream 401Zły lub pusty UPSTREAM_KEYWyeksportuj ponownie klucz w powłoce proxy i zrestartuj
429 z concurrencyPonad 8 równoległych zapytań (2 w wersji próbnej)Zmniejsz liczbę równoległych agentów
429 z rate_limitedPonad 300 zapytań na minutę (60 w wersji próbnej)Zwolnij i powtórz zapytanie
429 z Retry-After: 5Tymczasowe przeciążeniePonów próbę po pięciu sekundach
Zawieszony strumieńStrumieniowane zapytanie blokuje slot, dopóki się nie zakończyAnuluj je w CLI, aby zwolnić slot

Dla dowolnych spraw, których nie omówiono tutaj, dołącz nagłówek odpowiedzi X-Request-Id, gdy piszesz do supportu. Dokumentacja wymienia każdy obsługiwany parametr.

Utrwal konfigurację

Wpisywanie exportów za każdym razem męczy. Umieść uruchomienie proxy w małym skrypcie, a zmienne klienta w aliasie, aby jedno polecenie uruchomiło wszystko:

cat > ~/start-proxy.sh <<'EOF'
. ~/litellm-env/bin/activate
export UPSTREAM_KEY="YOUR_KEY"
exec litellm --config ~/config.yaml --port 4000
EOF
chmod +x ~/start-proxy.sh

alias claude-uncensored='ANTHROPIC_BASE_URL=http://localhost:4000 ANTHROPIC_AUTH_TOKEN=sk-local-anything ANTHROPIC_MODEL=claude-sonnet claude'

Ponieważ zmienne są ustawione tylko dla tego jednego polecenia, Twoje zwykłe polecenie claude działa nadal z domyślnymi ustawieniami. Dodaj alias do profilu powłoki. Chroń skrypt uprawnieniami pliku, np. chmod 700, ponieważ zawiera Twój klucz.

Powrót do poprzedniego stanu

Jeśli wyeksportowałeś zmienne w bieżącej powłoce, uruchom unset ANTHROPIC_BASE_URL ANTHROPIC_AUTH_TOKEN ANTHROPIC_MODEL i uruchom CLI ponownie. Nic nie zostało zmienione po stronie API, więc nie ma nic do cofnięcia.

Śledź saldo i wydatki

Każda odpowiedź z API zawiera X-Balance-USD, czyli pozostały kredyt na Twoim kluczu. LiteLLM może przekazywać nagłówki upstream w niektórych konfiguracjach, ale najpewniejszym sposobem sprawdzenia salda jest bezpośrednie wywołanie upstream raz na jakiś czas:

curl -i https://api.claudecodeproxyapi.com/v1/models \
  -H "Authorization: Bearer YOUR_KEY" | grep -i x-balance-usd

Sesje agenta rosną niezauważalnie. Każdy krok ponownie wysyła aktualny kontekst, więc długa sesja kosztuje więcej na zapytanie niż krótka. Rozpoczynanie nowej sesji dla każdego zadania utrzymuje mały rozmiar danych wejściowych i niski koszt. Przy opublikowanych cenach ($0,15 za 1M tokenów wejściowych i $0,50 za 1M tokenów wyjściowych) zapytanie z 50 000 tokenami wejściowymi i 1000 wyjściowymi kosztuje 50 000 x $0,15 / 1M = $0,0075 plus $0,0005, co daje $0,008. Dwadzieścia takich zapytań daje łącznie $0,16.

Doładowania wynoszą od $20 do $500 w pełnych kwotach i są płatne kryptowalutami (USDT na TRC20 lub USDC na Base) na tej stronie. Kredyt nigdy nie wygasa, więc większe doładowanie z bonusem +5%, +10% lub +15% nie ogranicza czasowo Twojego salda.

Pytania i odpowiedzi

Jakie zmienne środowiskowe potrzebuje Claude Code dla proxy?

ANTHROPIC_BASE_URL dla adresu proxy i ANTHROPIC_AUTH_TOKEN dla tokenu akceptowanego przez proxy. ANTHROPIC_MODEL może wskazywać alias, który zdefiniowałeś. Sprawdź aktualną dokumentację Claude Code w celu uzyskania informacji o zmianach.

Czy powinienem dodać /v1 do ANTHROPIC_BASE_URL?

Nie. Użyj adresu proxy, takiego jak http://localhost:4000, ponieważ aplikacja CLI dodaje swoją własną ścieżkę. /v1 należy tylko do upstream api_base w konfiguracji proxy.

Czy mogę użyć innego proxy niż LiteLLM?

Tak. Każde proxy, które konwertuje zapytania Anthropic Messages na OpenAI Chat Completions, działa, np. claude-code-router. Wskaż jego upstream na https://api.claudecodeproxyapi.com/v1 z modelem uncensored.

Czy mój klucz upstreamowy jest bezpieczny w konfiguracji?

Przechowuj go w zmiennej środowiskowej zamiast w pliku, jak pokazano w powyższej konfiguracji. Nie dodawaj klucza do repozytorium.

Twój klucz jest o jeden formularz stąd

Utwórz konto, skopiuj klucz, zmień bazowy URL. To cała konfiguracja.