Konfiguracja

Wyszukiwanie pliku konfiguracyjnego

Claudex uzywa figment do warstwowej konfiguracji. Zrodla sa laczane w nastepujacej kolejnosci (pozniejsze zrodla nadpisuja wczesniejsze):

1. Domyslne programowe (wbudowane wartosci zapasowe)
2. Konfiguracja globalna (~/.config/claudex/config.toml lub config.yaml)
3. Konfiguracja projektu (claudex.toml lub claudex.yaml w biezacym katalogu lub katalogach nadrzednych do 10 poziomow, lub $CLAUDEX_CONFIG)
4. Zmienne srodowiskowe (prefiks CLAUDEX_, separator __)

Obslugiwane sa oba formaty TOML i YAML. Format pliku jest wykrywany po rozszerzeniu (.toml lub .yaml/.yml).

Notatka

Sciezka XDG (~/.config/claudex/config.toml) jest domyslna lokalizacja. Jesli plik konfiguracyjny nie istnieje nigdzie, ta sciezka jest uzywana podczas tworzenia nowej konfiguracji.

# Pokaz zaladowana sciezke konfiguracji i wszystkie lokalizacje wyszukiwania
claudex config show

# Pokaz tylko sciezke pliku konfiguracyjnego
claudex config path

# Utworz nowa konfiguracje w biezacym katalogu
claudex config init

# Odtworz konfiguracje z config.example.toml
claudex config recreate

# Otworz konfiguracje w edytorze $EDITOR
claudex config edit

# Zwaliduj skladnie konfiguracji i referencje profili
claudex config validate

# Pobierz konkretna wartosc konfiguracji
claudex config get proxy_port

# Ustaw konkretna wartosc konfiguracji
claudex config set proxy_port 8080

# Eksportuj biezaca konfiguracje na stdout
claudex config export

Wskazówka

Konfiguracja na poziomie projektu (./claudex.toml) ma pierwszenstwo przed konfiguracja globalna, wiec mozesz dostosowywac dostawcow per projekt.

Ustawienia globalne

# Sciezka do pliku binarnego claude (domyslnie: "claude" z PATH)
# claude_binary = "/usr/local/bin/claude"

# Ustawienia proxy
proxy_port = 13456
proxy_host = "127.0.0.1"

# Poziom logowania: trace, debug, info, warn, error
log_level = "info"

# Hiperlinki terminala (OSC 8): "auto" | true | false
# "auto" wykrywa obsluge terminala; true/false wymusza wlaczenie/wylaczenie
hyperlinks = "auto"

# Aliasy modeli (skrot → pelna nazwa modelu)
[model_aliases]
grok3 = "grok-3-beta"
gpt4o = "gpt-4o"
ds3 = "deepseek-chat"

Profile

Kazdy profil reprezentuje polaczenie z dostawca AI. Istnieja trzy typy dostawcow:

DirectAnthropic

Dla dostawcow natywnie obslugujacych Anthropic Messages API. Zadania sa przekazywane z minimalnymi modyfikacjami.

[[profiles]]
name = "anthropic"
provider_type = "DirectAnthropic"
base_url = "https://api.anthropic.com"
api_key = "sk-ant-..."
default_model = "claude-sonnet-4-20250514"
priority = 100
enabled = true

Kompatybilni dostawcy: Anthropic, MiniMax, Google Vertex AI

OpenAICompatible

Dla dostawcow uzywajacych OpenAI Chat Completions API. Claudex automatycznie tlumaczy miedzy protokolami Anthropic i OpenAI.

[[profiles]]
name = "grok"
provider_type = "OpenAICompatible"
base_url = "https://api.x.ai/v1"
api_key = "xai-..."
default_model = "grok-3-beta"
backup_providers = ["deepseek"]
priority = 100
enabled = true

Kompatybilni dostawcy: Grok (xAI), OpenAI, DeepSeek, Kimi/Moonshot, GLM (Zhipu), OpenRouter, Groq, Mistral, Together AI, Perplexity, Cerebras, Azure OpenAI, GitHub Copilot, GitLab Duo, Ollama, vLLM, LM Studio

OpenAIResponses

Dla dostawcow uzywajacych OpenAI Responses API (np. subskrypcje ChatGPT/Codex). Claudex tlumaczy miedzy Anthropic Messages API a OpenAI Responses API.

[[profiles]]
name = "codex-sub"
provider_type = "OpenAIResponses"
base_url = "https://chatgpt.com/backend-api/codex"
default_model = "gpt-5.3-codex"
auth_type = "oauth"
oauth_provider = "openai"

Kompatybilni dostawcy: subskrypcje ChatGPT/Codex (przez Codex CLI)

Wskazówka

Ten typ dostawcy jest uzywany glownie z subskrypcjami OAuth. Zapoznaj sie z Przewodnikiem konfiguracji dostawcy, aby uzyskac szczegolowe instrukcje dotyczace konfiguracji Codex CLI.

Pola profilu

Pole	Domyslnie	Opis
name	wymagane	Unikalny identyfikator profilu
provider_type	DirectAnthropic	DirectAnthropic, OpenAICompatible lub OpenAIResponses
base_url	wymagane	Endpoint API dostawcy
api_key	""	Klucz API (zwykly tekst)
api_key_keyring	—	Odczytaj klucz API z lancucha kluczy systemu operacyjnego
default_model	wymagane	Domyslny model do uzycia
auth_type	"api-key"	"api-key" lub "oauth"
oauth_provider	—	Dostawca OAuth (claude, openai, google, qwen, kimi, github, gitlab). Wymagane gdy auth_type = "oauth"
backup_providers	[]	Nazwy profili zapasowych
custom_headers	{}	Dodatkowe naglowki HTTP
extra_env	{}	Dodatkowe zmienne srodowiskowe dla Claude
priority	100	Priorytet dla inteligentnego trasowania
enabled	true	Czy profil jest aktywny
max_tokens	—	Limit maksymalnych tokenow wyjsciowych wysylanych do dostawcy (opcjonalny)
strip_params	"auto"	"auto", "none" lub ["temperature", "top_p"]. Automatyczne wykrywanie nieobslugiwanych parametrow (np. endpoint ChatGPT Codex)
[profiles.query_params]	{}	Parametry zapytania URL (np. Azure api-version)
[profiles.models]	—	Tabela mapowania slotow modeli (pola haiku, sonnet, opus)

Interaktywna konfiguracja

Najprostszym sposobem dodania profilu jest interaktywny kreator:

claudex profile add

Prowadzi przez wybor dostawcy, wprowadzenie klucza API (z opcjonalnym zapisem w lancuchu kluczy), wybor modelu i testowanie lacznosci.

Integracja z lancuchem kluczy

Przechowuj klucze API bezpiecznie w lancuchu kluczy systemu operacyjnego zamiast w konfiguracji w postaci zwyklego tekstu:

[[profiles]]
name = "grok"
api_key_keyring = "grok-api-key"   # odczytuje z lancucha kluczy systemu operacyjnego

Obslugiwane mechanizmy:

• macOS: Keychain
• Linux: Secret Service (GNOME Keyring / KDE Wallet)

Uwierzytelnianie OAuth przez subskrypcje

Zamiast kluczy API mozesz uwierzytelniac sie przy uzyciu istniejacej subskrypcji dostawcy przez OAuth. Jest to przydatne, jesli posiadasz plan Claude Pro/Team, ChatGPT Plus lub inny plan subskrypcji.

Konfiguracja

1. Ustaw auth_type profilu na "oauth" i okresl oauth_provider:

[[profiles]]
name = "codex-sub"
provider_type = "OpenAIResponses"
base_url = "https://chatgpt.com/backend-api/codex"
default_model = "gpt-5.3-codex"
auth_type = "oauth"
oauth_provider = "openai"

2. Zaloguj sie poleceniem auth:

claudex auth login openai

3. Sprawdz status uwierzytelnienia:

claudex auth status

Obslugiwani dostawcy

Dostawca	oauth_provider	Zrodlo tokenu
Claude	claude	Odczytuje z ~/.claude/.credentials.json (natywna konfiguracja Claude Code)
ChatGPT	openai	Browser PKCE lub Device Code, zapasowo ~/.codex/auth.json (Codex CLI)
Google	google	Odczytuje z poswiadczen Gemini CLI
Qwen	qwen	Przeplyw Device Code
Kimi	kimi	Odczytuje z poswiadczen Kimi CLI
GitHub	github	Przeplyw Device Code, zapasowo ~/.config/github-copilot/
GitLab	gitlab	Zmienna srodowiskowa GITLAB_TOKEN

Szczegoly dotyczace przeplywu OAuth kazdego dostawcy znajduja sie w Subskrypcje OAuth.

Tryb uwierzytelniania bramkowego

Podczas uzywania profili OAuth Claudex ustawia ANTHROPIC_AUTH_TOKEN (nie ANTHROPIC_API_KEY) podczas uruchamiania Claude Code. Zapobiega to konfliktom z wlasnym mechanizmem logowania subskrypcyjnego Claude Code, ktory wewnetrznie uzywa ANTHROPIC_API_KEY.

Proxy automatycznie odswierza tokeny OAuth przed ich wygasnieciem. Mozesz tez recznie odswiezyc:

claudex auth refresh openai

Parametry zapytania

Niektorzy dostawcy wymagaja parametrow zapytania URL (np. api-version w Azure OpenAI). Uzyj tabeli [profiles.query_params]:

[[profiles]]
name = "azure-openai"
provider_type = "OpenAICompatible"
base_url = "https://YOUR_RESOURCE.openai.azure.com/openai/deployments/YOUR_DEPLOYMENT"
api_key = "YOUR_AZURE_KEY"
default_model = "gpt-4o"

[profiles.query_params]
api-version = "2024-12-01-preview"

Claudex dolacza te parametry do kazdego URL zadania dla profilu. Azure OpenAI jest automatycznie wykrywany po base_url zawierajacym openai.azure.com i uzywa naglowka api-key do uwierzytelniania zamiast Authorization: Bearer.

Usuwanie parametrow

Niektorzy dostawcy nie obsluguja okreslonych parametrow (np. endpoint ChatGPT Codex odrzuca temperature, top_p). Pole strip_params kontroluje, ktore parametry sa usuwane przed wyslaniem:

strip_params = "auto"       # automatyczne wykrywanie i usuwanie nieobslugiwanych parametrow (domyslnie)
strip_params = "none"       # wyslij wszystkie parametry bez zmian
strip_params = ["temperature", "top_p", "top_k"]  # usun konkretne parametry

Gdy ustawione na "auto", Claudex wykrywa znane endpointy (np. chatgpt.com) i usuwa parametry, ktore spowodowalyby bledy.

Mapowanie slotow modeli

Claude Code ma wbudowany przelacznik /model z trzema slotami: haiku, sonnet i opus. Szczegoly w Mapowanie slotow modeli.

Kompatybilnosc nazw narzedzi

Niektorzy dostawcy (w szczegolnosci OpenAI) narzucaja limit 64 znakow na nazwy narzedzi (funkcji). Claude Code moze generowac nazwy narzedzi przekraczajace ten limit.

Claudex automatycznie skraca nazwy narzedzi dluzsze niz 64 znaki podczas wysylania zadan do dostawcow kompatybilnych z OpenAI i transparentnie przywraca oryginalne nazwy podczas przetwarzania odpowiedzi. Ten mechanizm dziala calkowicie transparentnie.

Tryb nieinteraktywny

Claudex obsluguje jednorazowe (nieinteraktywne) wykonanie do uzycia w potokach CI/CD, skryptach i automatyzacji:

# Wydrukuj odpowiedz i wyjdz
claudex run grok "Explain this codebase" --print

# Pomin wszystkie monity o uprawnienia (dla w pelni zautomatyzowanych potokow)
claudex run grok "Fix lint errors" --print --dangerously-skip-permissions

Uwaga

--dangerously-skip-permissions wylacza wszystkie monity bezpieczenstwa. Uzywaj tylko w zaufanych, zautomatyzowanych srodowiskach.

W trybie nieinteraktywnym logi sa zapisywane do plikow logow per instancja w ~/Library/Caches/claudex/proxy-{timestamp}-{pid}.log zamiast na stderr, utrzymujac czyste wyjscie stdout dla potokow i automatyzacji.

Hiperlinki terminala

Claudex obsluguje klikalne hiperlinki OSC 8 w wyjsciu terminala. Szczegoly w Hiperlinki terminala.

# "auto" wykrywa obsluge terminala; true/false wymusza wlaczenie/wylaczenie
hyperlinks = "auto"

Zestawy konfiguracji

Instaluj pakiety regul, umiejetnosci i serwerow MCP do wielokrotnego uzytku. Szczegoly w Zestawy konfiguracji.

claudex sets add ./my-set
claudex sets list

Pelny przyklad

Zobacz config.example.toml, aby uzyskac kompletny plik konfiguracyjny ze wszystkimi dostawcami i opcjami.

Aby uzyskac szczegolowe instrukcje konfiguracji dla kazdego dostawcy (w tym linki do kluczy API i przeplywy OAuth), zapoznaj sie z Przewodnikiem konfiguracji dostawcy.