Konfiguracja API Endpointu Claude Code dla Gatewaya Trzeciorzędowego z Modelami Otwartymi Chińskimi

Claude Code może być skonfigurowany, aby komunikował się z endpointem kompatybilnym z Anthropicami, zamiast bezpośrednio korzystać z endpointu dostawcy. Pozwala to przetestować pracę workflowu zarządzanego przez gateway, z modelami o identyfikatorach dostarczanymi przez gateway, w tym dostępnymi w obecnym katalogu modeli ECAIX chińskich otwartych źródeł.

Ta instrukcja dotyczy pracowni kompatybilności dostawcy z trzeciorzędową zgodnością. Dokumentacja oficjalnego gatewaya Claude Code Anthropic wyjaśnia, że Anthropic nie wspiera routingu Claude Code do modeli nieklauzowych przez gateway. ECAIX nie stwierdza, że ta praca jest oficjalnie wspierana przez Anthropic, a model nieklauzowy może nie zapewniać wszystkich funkcji Claude Code.

Szybki start

Jeśli już rozumiesz granice kompatybilności, zacznij od krótkiego ścieżki:

1. Otwórz aktualny katalog modeli ECAIX i wybierz aktywny identyfikator modelu.
2. Utwórz klucz API ECAIX i trzymaj go poza kontrolą źródłową.
3. Ustaw ANTHROPIC_BASE_URL na https://ecaix.com/api/ai/v1/anthropic.
4. Wyślij poniższy diagnostyczny zapytanie i zapisz kod HTTP.
5. Uruchom Claude Code w testowym projekcie tylko do odczytu z użyciem claude -p.
6. Testuj narzędzia, strumieniowanie, granice kontekstu i uprawnień oddzielnie.

Status walidacji przy publikacji

Ta tabela jest zamierzona: przykład konfiguracji nie jest taki sam jak wynik pomiaru kompatybilności.

Co zmienia ta konfiguracja

Konfiguracja składa się z czterech oddzielnych części:

1. Claude Code to klient, który tworzy zadania kodowe i wysyła zapytania.
2. Gateway kompatybilny z Anthropic przyjmuje zapytania na endpointzie w stylu Anthropic.
3. ID modelu wybiera model źródłowy dostarczany przez gateway.
4. Klucz API autoryzuje zapytanie i określa konto, ceny i uprawnienia.

Zmiana endpointu nie przekształca modelu nieklauzowego w Claude. Wyłącznie zmienia, jakie kompatybilne powierzchnię API przyjmuje zapytanie. Użycie narzędzi, obsługa kontekstu, nazwy modeli, zachowanie strumieniowania oraz przepływ uprawnień może różnić się w zależności od wersji klienta i implementacji gatewayu.

Przed rozpoczęciem

Potrzebujesz:

• Instalacji Claude Code, która wspiera konfigurację endpointu na podstawie środowiska lub ustawień.
• Klucza API ECAIX.
• ID modelu obecnego w aktualnym katalogu modeli ECAIX.
• Terminala, w którym możesz uruchomić małe testowe zapytanie bez umieszczania klucza API w kontrolach źródłowych.

Katalog modeli zmienia się z czasem. Przed kopiowaniem ID modelu do pliku konfiguracyjnego otwórz katalog modeli ECAIX i potwierdź, że model jest aktywny i dostępny dla stylu API, który zamierzasz użyć.

Konfiguracja endpointu gatewayu

Claude Code przechowuje ustawienia w pliku ~/.claude/settings.json na wielu instalacjach. Schemat ustawień może się zmieniać, więc traktuj poniższy wzór jako punkt wyjścia i porównaj go z dokumentacją dla Twojej instalowanej wersji.

{
  "env": {
    "ANTHROPIC_BASE_URL": "https://ecaix.com/api/ai/v1/anthropic",
    "ANTHROPIC_API_KEY": "YOUR_ECAIX_API_KEY",
    "CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC": "1",
    "CLAUDE_CODE_DISABLE_UNKNOWN_MODEL_WINDOW_ENFORCEMENT": "1"
  },
  "model": "deepseek-v4.1-flash"
}

Nie zapuszczaj tego pliku do publicznego repozytorium, jeśli zawiera prawdziwy klucz API. Preferuj lokalną zmienną środowiskową, menedżer sekretów lub mechanizm kredencji zalecany przez Twoją instalację Claude Code.

Możesz również skonfigurować endpoint w trakcie testów w sesji terminala:

export ANTHROPIC_BASE_URL="https://ecaix.com/api/ai/v1/anthropic"
export ANTHROPIC_API_KEY="YOUR_ECAIX_API_KEY"
export ANTHROPIC_MODEL="deepseek-v4.1-flash"

Nazwy zmiennych i ustawienia wspierane przez konkretną wersję Claude Code mogą się zmieniać. Jeśli klient ignoruje ANTHROPIC_MODEL, użyj pola modelu lub mechanizmu aliasów modelu opisanych w dokumentacji Twojej wersji. Gateway nadal musi rozpoznać ostatecznie identyfikator modelu.

Zweryfikuj endpoint kompatybilny z Anthropicem

Przed rozpoczęciem interaktywnego sesji kodowania wyslij jedno małe zapytanie. To oddzieli problemy z endpointem, autoryzacją i identyfikatorem modelu od zachowań specyficznych dla Claude Code.

Poniższa komenda zapisuje nagłówek odpowiedzi i ciało odpowiedzi oddzielnie, a następnie wyświetla kod HTTP. Używaj tylko autoryzowanego klucza w lokalnym terminalu; nigdy nie wklejaj go do artykułu, issue lub wspólnego logu.

curl -sS -D /tmp/ecaix-anthropic-headers.txt \
  -o /tmp/ecaix-anthropic-response.json \
  -w '\nHTTP %{http_code}\n' \
  "${ANTHROPIC_BASE_URL}/messages" \
  -H "x-api-key: ${ANTHROPIC_API_KEY}" \
  -H "anthropic-version: 2023-06-01" \
  -H "content-type: application/json" \
  -d '{
    "model": "deepseek-v4.1-flash",
    "max_tokens": 128,
    "messages": [
      {"role": "user", "content": "Reply with one short sentence."}
    ]
  }'

Oczekiwana interpretacja:

• 200: sprawdź kształt odpowiedzi i potwierdź pola modelu lub zużycia w powracających danych.
• 401 lub 403: sprawdź klucz, nagłówki, konto i zakres uprawnień przed zmianą zapytania.
• 404: sprawdź base URL, sufix /messages oraz deployement endpointu.
• 400: zmniejsz zapytanie do najmniejszej ważnej ciała i sprawdź pola specyficzne dla modelu.
• 5xx lub timeout: zapisz czas trwania zapytania i ciało odpowiedzi, a następnie oddziel zachowanie gatewayu, modelu źródłowego i timeoutu klienta.

Udało się odpowiedź potwierdza, że klucz, endpoint, format zapytania i identyfikator modelu działały razem dla tego zapytania. Nie oznacza to jednak, że każda funkcja Claude Code będzie działać poprawnie.

Testowanie kodu Claude po udanej prośbie do API

Gdy bezpośredni wywołanie udane się, zacznij od prostej lub bezpiecznej komendy:

claude -p "Explain what this repository does without editing files."

Później przetestuj zadanie ograniczonym zakresie. Przykład:

claude -p "List the likely entry points for the web application. Do not modify files."

Użyj coraz bardziej wymagających testów:

1. Odpowiedź w formacie tekstowym.
2. Krótkie wyjaśnienie kodu.
3. Nawigacja w repozytorium.
4. Kontrolowane edycje w tymczasowej gałęzi.
5. Użycie narzędzi lub zadania wieloetapowego.
6. Streamowanie i zachowanie kontekstu długiego.

Nie zakładaj, że udana odpowiedź tekstowa dowodzi, że zachowanie prośb o uprawnienia, wywołania narzędzi, streamowanie, granice kontekstu lub edycja plików zachowuje się identycznie jak w sesji z Claude.

Wybór odpowiedniej ścieżki API

Claude Code to tylko jeden z workflowów klienta. Wybór odpowiedniej ścieżki API zależy od potrzeb klienta i zestawu funkcjonalności:

Dla ECAIX użyj dokumentacji o wiadomościach Anthropic dla ścieżki w stylu Anthropic i dokumentacji o Chat Completions dla klientów kompatybilnych z OpenAI. Sprawdź katalog modeli, aby potwierdzić aktualny model i stronę cen dla aktualnie wyświetlanych cen.

Matryca kompatybilności

Poniższa matryca stanowi granice publikacji, a nie gwarancję, że każda funkcja jest wspierana:

Ta różnica zapobiega przedstawieniu udanej minimalnej prośby jako pełnej certyfikacji kompatybilności z Claude Code.

Strony szczegółów modeli i aktualne identyfikatory

Użyj stron szczegółów modeli zamiast kopiowania starego nazwy modelu z bloga:

• DeepSeek v4.1 Flash
• Qwen 3.8 Flash
• GLM 5.3
• Kimi K3

Te linki są wejściami do sprawdzenia aktualnego identyfikatora modelu, informacji o kontekście i szczegółów na poziomie strony. Dostępność może się zmienić po publikacji.

Po błędzie użyj tej kolejności zamiast zmiany kilku zmiennych jednocześnie:

1. Zapisz kod HTTP i ciało odpowiedzi.
2. Potwierdź podstawową URL i sufix ścieżki.
3. Potwierdź, że klucz API jest obecny lokalnie i ma oczekiwany zakres.
4. Potwierdź dokładny identyfikator modelu w aktualnym katalogu modeli.
5. Powtórz z najmniejszym ważnym żądaniem.
6. Porównaj wynik z żądaniem wysłanym przez Claude Code.
7. Dopiero wtedy badz różnice w routingu, czasie oczekiwania lub schemacie narzędzi.

Dla Model nie znaleziony, to oddziela błąd pisowni od problemu z uprawnieniami, problemu z mapowaniem gatewayu i nieudanej operacji dostawcy. Dla 401 i 403, zmiana modelu zwykle nie jest pierwszym krokiem. W przypadku sukcesu tekstu/niepowodzenia narzędzia, następny test powinien być schematem narzędzia, a nie kolejnym żądaniem tekstowym.

Typowe błędy

Bezpieczeństwo i obsługa danych

Trzymaj gateway jako oddzielną granicę usługi. Przed wysłaniem kodu źródłowego lub danych klienta sprawdź:

• Która usługa otrzymuje prośby i treści plików.
• Czy żądania i odpowiedzi są logowane.
• Jak są przechowywane i obrotowane klucze API.
• Czy ścieżka modelu jest rzeczywistą połączeniem z dostawcą lub inną usługą jako fallback.
• Jakie narzędzia może wywoływać klient.
• Jak odwołać klucz po testowaniu.

Nigdy nie wklejaj klucza API produkcji w publicznym issue, artykule, ekranie lub historii shell, który jest udostępniany innym.

Różnice w stosunku do oficjalnej wsparcia Claude Code

Oficjalna dokumentacja Anthropic jest autorytetem dla wsparcia Claude Code. Gateway trzeciej strony może wystawiać zgodny format żądań, ale kompatybilność nie jest taka sama jak oficjalna wsparcie. Bezpieczny sposób opisania tego workflowu to:

• Wspierane przez tę konfigurację gatewaya: endpoint, nagłówki autoryzacji, identyfikatory modeli i funkcje, które ECAIX przetestował.
• Nie automatycznie wspierane: wszystkie funkcje Claude Code, zachowanie modeli poza Claude, specyficzne semantyki narzędzi dostawcy i nowsze wersje klienta.
• Potrzebuje ponownego testowania po zmianach: dostępność modeli, pola żądań, granice kontekstu, streamowanie, wywołania narzędzi i ceny.

FAQ

Czy potrzebuję abonamentu Claude dla tego workflowu?

Zależy od Twojej instalacji Claude Code, warunków konta i konfiguracji gatewaya. Ten artykuł nie zmienia wymagań abonamentowych lub produktowych Anthropic. Sprawdź aktualną oficjalną dokumentację Claude Code i warunki gatewayu, którego zamierzasz użyć.

Czy mogę użyć dowolnego identyfikatora modelu z katalogu?

Nie. Użyj identyfikatora modelu, który jest obecnie widoczny, aktywny i kompatybilny z endpointem i kontem. Model może być obecny w katalogu, ale może być niedostępny dla konkretnego stylu API lub klucza.

Czy endpoint kompatybilny z Anthropic gwarantuje wywołania narzędzi?

Nie. Kompatybilność protokołu i zachowanie narzędzi są odrębnymi sprawami. Uruchom test wywołania pojedynczej funkcji i sprawdź aktualną dokumentację modelu przed użyciem narzędzi w automatycznym workflowie.

Gdzie powinno się sprawdzać aktualne modele i ceny?

Użyj katalogu modeli ECAIX i strony cen. Te strony są źródłem prawdy dla aktualnej dostępności i wyświetlanych cen; nie kopiuj starych identyfikatorów modeli lub cen z tego artykułu.

Podsumowanie

Bezpieczna sekwencja integracji to:

1. Przeczytaj oficjalną dokumentację Claude Code i gatewaya.
2. Utwórz klucz API ECAIX bez jego publicznego udostępniania.
3. Wybierz dostępny aktualnie identyfikator modelu z /models.
4. Konfiguruj lokalnie ANTHROPIC_BASE_URL i klucz.
5. Testuj /api/ai/v1/anthropic/messages z minimalnym żądaniem.
6. Testuj Claude Code z zadaniem tylko do odczytu.
7. Testuj narzędzia, streamowanie, kontekst i uprawnienia oddzielnie.
8. Sprawdzaj kompatybilność po każdej zmianie w kluczu, gatewayu, modelu lub endpointzie.

Następnym krokiem jest przeczytanie dokumentacji API o wiadomościach Anthropic, przeglądanie aktualnego katalogu modeli oraz utworzenie klucza z API Keys.

Przewodnik praktyczny do sprawdzenia zgodności

Zanim traktujesz integrację jako przydatną dla zespołu, zapisz wynik każdego testu:

Ten przewodnik jest bardziej przydatny niż pojedyncze udane powitanie. Brama może przyjąć żądanie tekstu, podczas gdy nadal wymaga innych ustawień dla narzędzi, streamingu, okien kontekstu lub aliasów modeli.

Kiedy nie używać konfiguracji

Nie używaj tej konfiguracji dla wrażliwych na dane repozytoriów produkcyjnych, dopóki nie zrozumiesz logowania, retencji, routingu i kontroli dostępu. Nie zakładaj, że endpoint zgodny z providerem zapewnia taką samą bezpieczeństwo zachowania, systemowe podprompty, uprawnienia narzędzi czy rachunek kontekstu, jak u źródłowego dostawcy. Dla regulowanych lub poufnych prac wykonaj wewnętrzną recenzję bezpieczeństwa i użyj ścieżki deploymencji, którą Twoja organizacja zatwierdziła.

Utrzymywanie aktualności konfiguracji

Sprawdź konfigurację, gdy następują następujące zmiany:

• Claude Code jest aktualizowany.
• Brama zmienia swoją zgodną implementację z Anthropic.
• ID modelu jest zmienione, usunięte lub przypisane do innego dostawcy.
• Limity streamingu, narzędzi, kontekstu lub zachowanie błędów się zmieniają.
• ECAIX zmienia modele lub limity API wyświetlane w żywym katalogu.

Utrzymuj konfigurację w małym, dobrze dokumentowanym projekcie testowym. To ułatwia porównanie zachowania po aktualizacji klienta lub modelu bez ekspozycji repozytorium produkcyjnego.

Źródła

• Anthropic Claude Code: Inne bramy LLM
• DeepSeek API dokumentacja
• Qwen Quickstart
• Zhipu OpenAI API zgodność