Dokumentacja konfiguracji

Lokalizacja pliku konfiguracyjnego

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

1. Domyslne programowe
2. Konfiguracja globalna (~/.config/claudex/config.toml lub .yaml)
3. Konfiguracja projektu (claudex.toml/.claudex/config.toml w CWD lub katalogach nadrzednych, lub $CLAUDEX_CONFIG)
4. Zmienne srodowiskowe (prefiks CLAUDEX_, separator __)

Obslugiwane sa oba formaty TOML i YAML.

Szczegoly w sekcji Konfiguracja.

Ustawienia globalne

# Sciezka do pliku binarnego claude (domyslnie: "claude" z PATH)
claude_binary = "claude"

# Port nasluchiwania serwera proxy
proxy_port = 13456

# Adres nasluchiwania serwera proxy
proxy_host = "127.0.0.1"

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

# Hiperlinki terminala (OSC 8): "auto" | true | false
hyperlinks = "auto"

Pole	Typ	Domyslnie	Opis
claude_binary	string	"claude"	Sciezka do pliku binarnego Claude Code CLI
proxy_port	integer	13456	Port, na ktorym nasluchuje proxy tlumaczace
proxy_host	string	"127.0.0.1"	Adres, do ktorego binduje sie proxy
log_level	string	"info"	Minimalny poziom logowania
hyperlinks	string/bool	"auto"	Hiperlinki terminala: "auto" (wykrywanie), true (wymus wlaczenie), false (wymus wylaczenie)

Aliasy modeli

Definiuj skrocone nazwy dla identyfikatorow modeli:

[model_aliases]
grok3 = "grok-3-beta"
gpt4o = "gpt-4o"
ds3 = "deepseek-chat"
claude = "claude-sonnet-4-20250514"

Uzyj aliasow z -m:

claudex run grok -m grok3

Konfiguracja profilu

[[profiles]]
name = "grok"
provider_type = "OpenAICompatible"
base_url = "https://api.x.ai/v1"
api_key = "xai-..."
# api_key_keyring = "grok-api-key"
default_model = "grok-3-beta"
auth_type = "api-key"              # "api-key" (domyslnie) lub "oauth"
# oauth_provider = "openai"        # wymagane gdy auth_type = "oauth"
backup_providers = ["deepseek"]
custom_headers = {}
extra_env = {}
priority = 100
enabled = true
max_tokens = 16384                  # opcjonalnie: limit tokenow wyjsciowych
strip_params = "auto"               # "auto" | "none" | ["temperature", "top_p"]

# Parametry zapytania URL (np. Azure api-version)
[profiles.query_params]
# api-version = "2024-12-01-preview"

# Mapowanie slotow modeli (opcjonalne)
[profiles.models]
haiku = "grok-3-mini-beta"
sonnet = "grok-3-beta"
opus = "grok-3-beta"

Pole	Typ	Domyslnie	Opis
name	string	wymagane	Unikalny identyfikator profilu
provider_type	string	"DirectAnthropic"	"DirectAnthropic", "OpenAICompatible" lub "OpenAIResponses"
base_url	string	wymagane	URL endpointu API dostawcy
api_key	string	""	Klucz API w postaci zwyklego tekstu
api_key_keyring	string	—	Nazwa wpisu w lancuchu kluczy systemu operacyjnego (nadpisuje api_key)
default_model	string	wymagane	Identyfikator modelu uzywany domyslnie
auth_type	string	"api-key"	Metoda uwierzytelniania: "api-key" lub "oauth"
oauth_provider	string	—	Nazwa dostawcy OAuth. Jedna z: claude, openai, google, qwen, kimi, github, gitlab
backup_providers	string[]	[]	Nazwy profili do przelaczania awaryjnego, probowane kolejno
custom_headers	map	{}	Dodatkowe naglowki HTTP wysylane z kazdym zadaniem
extra_env	map	{}	Zmienne srodowiskowe ustawiane podczas uruchamiania Claude
priority	integer	100	Waga priorytetu dla inteligentnego trasowania (wyzszy = preferowany)
enabled	boolean	true	Czy profil jest aktywny
max_tokens	integer	—	Limit maksymalnych tokenow wyjsciowych wysylanych do dostawcy. Gdy ustawiony, nadpisuje max_tokens w zadaniach
strip_params	string/array	"auto"	Parametry do usuniecia z zadan. "auto" wykrywa znane endpointy; "none" wysyla wszystko; tablica usuwa konkretne parametry

Parametry zapytania

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

Pole	Typ	Opis
query_params	map	Pary klucz-wartosc dolaczane jako parametry zapytania URL do kazdego zadania

Uzywane glownie dla Azure OpenAI (api-version), ale dziala z dowolnym dostawca.

Mapowanie slotow modeli

Opcjonalna tabela [profiles.models] mapuje sloty przelacznika /model Claude Code na nazwy modeli specyficzne dla dostawcy. Gdy przelaczasz modele wewnatrz Claude Code (np. /model opus), Claudex tlumaczy zadanie na zmapowany model.

[profiles.models]
haiku = "grok-3-mini-beta"    # mapuje /model haiku
sonnet = "grok-3-beta"        # mapuje /model sonnet
opus = "grok-3-beta"          # mapuje /model opus

Pole	Typ	Opis
haiku	string	Model uzywany gdy Claude Code wybiera haiku
sonnet	string	Model uzywany gdy Claude Code wybiera sonnet
opus	string	Model uzywany gdy Claude Code wybiera opus

Wskazówka

Jesli slot nie jest zdefiniowany, jako zapasowy uzywany jest default_model profilu. Sloty sa rowniez eksponowane jako zmienne srodowiskowe: ANTHROPIC_DEFAULT_HAIKU_MODEL, ANTHROPIC_DEFAULT_SONNET_MODEL, ANTHROPIC_DEFAULT_OPUS_MODEL.

Przyklady dostawcow

# Anthropic (DirectAnthropic — bez tlumaczenia)
[[profiles]]
name = "anthropic"
provider_type = "DirectAnthropic"
base_url = "https://api.anthropic.com"
api_key = "sk-ant-..."
default_model = "claude-sonnet-4-20250514"

# MiniMax (DirectAnthropic — bez tlumaczenia)
[[profiles]]
name = "minimax"
provider_type = "DirectAnthropic"
base_url = "https://api.minimax.io/anthropic"
api_key = "..."
default_model = "claude-sonnet-4-20250514"
backup_providers = ["anthropic"]

# OpenRouter (OpenAICompatible — wymaga tlumaczenia)
[[profiles]]
name = "openrouter"
provider_type = "OpenAICompatible"
base_url = "https://openrouter.ai/api/v1"
api_key = "..."
default_model = "anthropic/claude-sonnet-4"

# Grok (OpenAICompatible — wymaga tlumaczenia)
[[profiles]]
name = "grok"
provider_type = "OpenAICompatible"
base_url = "https://api.x.ai/v1"
api_key = "xai-..."
default_model = "grok-3-beta"
backup_providers = ["deepseek"]

# OpenAI (OpenAICompatible — wymaga tlumaczenia)
[[profiles]]
name = "chatgpt"
provider_type = "OpenAICompatible"
base_url = "https://api.openai.com/v1"
api_key = "sk-..."
default_model = "gpt-4o"

# DeepSeek (OpenAICompatible — wymaga tlumaczenia)
[[profiles]]
name = "deepseek"
provider_type = "OpenAICompatible"
base_url = "https://api.deepseek.com"
api_key = "..."
default_model = "deepseek-chat"
backup_providers = ["grok"]

# Kimi / Moonshot (OpenAICompatible — wymaga tlumaczenia)
[[profiles]]
name = "kimi"
provider_type = "OpenAICompatible"
base_url = "https://api.moonshot.ai/v1"
api_key = "..."
default_model = "kimi-k2-0905-preview"

# GLM / Zhipu (OpenAICompatible — wymaga tlumaczenia)
[[profiles]]
name = "glm"
provider_type = "OpenAICompatible"
base_url = "https://api.z.ai/api/paas/v4"
api_key = "..."
default_model = "glm-4.6"

# Groq (OpenAICompatible — szybka inferencja)
[[profiles]]
name = "groq"
provider_type = "OpenAICompatible"
base_url = "https://api.groq.com/openai/v1"
api_key = "gsk_..."
default_model = "llama-3.3-70b-versatile"

# Mistral AI (OpenAICompatible — wymaga tlumaczenia)
[[profiles]]
name = "mistral"
provider_type = "OpenAICompatible"
base_url = "https://api.mistral.ai/v1"
api_key = "..."
default_model = "mistral-large-latest"

# Together AI (OpenAICompatible — wymaga tlumaczenia)
[[profiles]]
name = "together"
provider_type = "OpenAICompatible"
base_url = "https://api.together.xyz/v1"
api_key = "..."
default_model = "meta-llama/Llama-3.3-70B-Instruct-Turbo"

# Perplexity (OpenAICompatible — wyszukiwanie online + LLM)
[[profiles]]
name = "perplexity"
provider_type = "OpenAICompatible"
base_url = "https://api.perplexity.ai"
api_key = "pplx-..."
default_model = "sonar-pro"

# Cerebras (OpenAICompatible — szybka inferencja)
[[profiles]]
name = "cerebras"
provider_type = "OpenAICompatible"
base_url = "https://api.cerebras.ai/v1"
api_key = "..."
default_model = "llama-3.3-70b"

# Azure OpenAI (OpenAICompatible — naglowek api-key + 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"

# Google Vertex AI (DirectAnthropic)
[[profiles]]
name = "vertex-ai"
provider_type = "DirectAnthropic"
base_url = "https://us-east5-aiplatform.googleapis.com/v1/projects/YOUR_PROJECT/locations/us-east5/publishers/anthropic/models"
api_key = "YOUR_GCLOUD_TOKEN"
default_model = "claude-sonnet-4@20250514"

# Ollama (lokalny, bez klucza API)
[[profiles]]
name = "local-qwen"
provider_type = "OpenAICompatible"
base_url = "http://localhost:11434/v1"
api_key = ""
default_model = "qwen2.5:72b"
enabled = false

# vLLM / LM Studio (lokalny)
[[profiles]]
name = "local-llama"
provider_type = "OpenAICompatible"
base_url = "http://localhost:8000/v1"
api_key = ""
default_model = "llama-3.3-70b"
enabled = false

Przyklady profili OAuth

# Claude Max (pomija proxy, uzywa natywnego OAuth Claude z ~/.claude)
[[profiles]]
name = "claude-max"
provider_type = "DirectAnthropic"
base_url = "https://api.claude.ai"
default_model = "claude-sonnet-4-20250514"
auth_type = "oauth"
oauth_provider = "claude"

[profiles.models]
haiku = "claude-haiku-4-20250514"
sonnet = "claude-sonnet-4-20250514"
opus = "claude-opus-4-20250514"

# Subskrypcja ChatGPT/Codex (OpenAIResponses)
[[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"

[profiles.models]
haiku = "codex-mini-latest"
sonnet = "gpt-5.3-codex"
opus = "gpt-5.3-codex"

# Google Gemini przez OAuth
[[profiles]]
name = "gemini-sub"
provider_type = "OpenAICompatible"
base_url = "https://generativelanguage.googleapis.com/v1beta/openai"
default_model = "gemini-2.5-pro"
auth_type = "oauth"
oauth_provider = "google"

# Kimi przez OAuth
[[profiles]]
name = "kimi-oauth"
provider_type = "OpenAICompatible"
base_url = "https://api.moonshot.cn/v1"
default_model = "moonshot-v1-128k"
auth_type = "oauth"
oauth_provider = "kimi"

# Qwen przez OAuth
[[profiles]]
name = "qwen-oauth"
provider_type = "OpenAICompatible"
base_url = "https://chat.qwen.ai/api"
default_model = "qwen3-235b-a22b"
auth_type = "oauth"
oauth_provider = "qwen"

# GitHub Copilot przez OAuth
[[profiles]]
name = "copilot"
provider_type = "OpenAICompatible"
base_url = "https://api.githubcopilot.com"
default_model = "gpt-4o"
auth_type = "oauth"
oauth_provider = "github"

# GitLab Duo przez GITLAB_TOKEN
[[profiles]]
name = "gitlab-duo"
provider_type = "OpenAICompatible"
base_url = "https://gitlab.com/api/v4/ai/llm/proxy"
default_model = "claude-sonnet-4-20250514"
auth_type = "oauth"
oauth_provider = "gitlab"

Uwaga

Dla dostawcy OAuth claude Claudex pomija proxy i pozwala Claude Code uzywac wlasnego OAuth bezposrednio. Dla wszystkich innych dostawcow OAuth proxy obsluguje zarzadzanie tokenami i odswiezanie.

Inteligentny router

[router]
enabled = false
profile = "local-qwen"    # ponowne uzycie base_url + api_key profilu
model = "qwen2.5:3b"      # nadpisanie modelu (opcjonalne)

Pole	Typ	Domyslnie	Opis
enabled	boolean	false	Wlacz inteligentne trasowanie
profile	string	""	Nazwa profilu do ponownego uzycia do klasyfikacji (uzywa jego base_url + api_key)
model	string	""	Nadpisanie modelu do klasyfikacji (domyslnie default_model profilu)

Reguly trasowania

[router.rules]
code = "deepseek"
analysis = "grok"
creative = "chatgpt"
search = "kimi"
math = "deepseek"
default = "grok"

Klucz	Opis
code	Profil dla zadan programistycznych
analysis	Profil dla analizy i rozumowania
creative	Profil dla pisania kreatywnego
search	Profil dla wyszukiwania i badan
math	Profil dla matematyki i logiki
default	Zapasowy gdy intencja nie jest sklasyfikowana

Silnik kontekstu

Kompresja

[context.compression]
enabled = false
threshold_tokens = 50000
keep_recent = 10
profile = "local-qwen"    # ponowne uzycie base_url + api_key profilu
model = "qwen2.5:3b"      # nadpisanie modelu (opcjonalne)

Pole	Typ	Domyslnie	Opis
enabled	boolean	false	Wlacz kompresje konwersacji
threshold_tokens	integer	50000	Kompresuj gdy liczba tokenow przekroczy te wartosc
keep_recent	integer	10	Zawsze zachowuj ostatnie N wiadomosci bez kompresji
profile	string	""	Nazwa profilu do ponownego uzycia do podsumowywania
model	string	""	Nadpisanie modelu do podsumowywania

Udostepnianie kontekstu miedzy profilami

[context.sharing]
enabled = false
max_context_size = 2000

Pole	Typ	Domyslnie	Opis
enabled	boolean	false	Wlacz udostepnianie kontekstu miedzy profilami
max_context_size	integer	2000	Maksymalna liczba tokenow do wstrzykniecia z innych profili

Lokalny RAG

[context.rag]
enabled = false
index_paths = ["./src", "./docs"]
profile = "local-qwen"              # ponowne uzycie base_url + api_key profilu
model = "nomic-embed-text"           # model osadzen
chunk_size = 512
top_k = 5

Pole	Typ	Domyslnie	Opis
enabled	boolean	false	Wlacz lokalny RAG
index_paths	string[]	[]	Katalogi do indeksowania
profile	string	""	Nazwa profilu do ponownego uzycia dla osadzen
model	string	""	Nazwa modelu osadzen
chunk_size	integer	512	Rozmiar fragmentu tekstu w tokenach
top_k	integer	5	Liczba wynikow do wstrzykniecia