Конфигурация

Обнаружение конфигурационных файлов

Claudex использует figment для многоуровневой конфигурации. Источники объединяются в следующем порядке (более поздние источники переопределяют более ранние):

1. Программные значения по умолчанию (встроенные запасные значения)
2. Глобальная конфигурация (~/.config/claudex/config.toml или config.yaml)
3. Конфигурация проекта (claudex.toml или claudex.yaml в текущем каталоге или родительских каталогах до 10 уровней, либо $CLAUDEX_CONFIG)
4. Переменные окружения (префикс CLAUDEX_, разделитель __)

Поддерживаются оба формата: TOML и YAML. Формат файла определяется по расширению (.toml или .yaml/.yml).

Заметка

XDG-путь (~/.config/claudex/config.toml) является расположением по умолчанию. Если конфигурационный файл не найден нигде, этот путь используется при создании новой конфигурации.

# Показать путь к загруженной конфигурации и все места поиска
claudex config show

# Показать только путь к конфигурационному файлу
claudex config path

# Создать новую конфигурацию в текущем каталоге
claudex config init

# Пересоздать конфигурацию из config.example.toml
claudex config recreate

# Открыть конфигурацию в вашем $EDITOR
claudex config edit

# Проверить синтаксис конфигурации и ссылки профилей
claudex config validate

# Получить конкретное значение конфигурации
claudex config get proxy_port

# Установить конкретное значение конфигурации
claudex config set proxy_port 8080

# Экспортировать текущую конфигурацию в stdout
claudex config export

Совет

Конфигурация на уровне проекта (./claudex.toml) имеет приоритет над глобальной, что позволяет настраивать провайдеров для каждого проекта отдельно.

Глобальные настройки

# Путь к бинарному файлу claude (по умолчанию: "claude" из PATH)
# claude_binary = "/usr/local/bin/claude"

# Настройки прокси
proxy_port = 13456
proxy_host = "127.0.0.1"

# Уровень логирования: trace, debug, info, warn, error
log_level = "info"

# Терминальные гиперссылки (OSC 8): "auto" | true | false
# "auto" автоматически определяет поддержку терминала; true/false принудительно включают/выключают
hyperlinks = "auto"

# Алиасы моделей (сокращение → полное имя модели)
[model_aliases]
grok3 = "grok-3-beta"
gpt4o = "gpt-4o"
ds3 = "deepseek-chat"

Профили

Каждый профиль представляет подключение к AI-провайдеру. Существует три типа провайдеров:

DirectAnthropic

Для провайдеров, нативно поддерживающих Anthropic Messages API. Запросы пересылаются с минимальными изменениями.

[[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

Совместимые провайдеры: Anthropic, MiniMax, Google Vertex AI

OpenAICompatible

Для провайдеров, использующих OpenAI Chat Completions API. Claudex автоматически переводит между протоколами Anthropic и 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

Совместимые провайдеры: 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

Для провайдеров, использующих OpenAI Responses API (например, подписки ChatGPT/Codex). Claudex переводит между Anthropic Messages API и 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"

Совместимые провайдеры: подписки ChatGPT/Codex (через Codex CLI)

Совет

Этот тип провайдера в основном используется с OAuth-подписками. См. Руководство по настройке провайдеров для подробных инструкций по настройке Codex CLI.

Поля профиля

Поле	По умолчанию	Описание
name	обязательно	Уникальный идентификатор профиля
provider_type	DirectAnthropic	DirectAnthropic, OpenAICompatible или OpenAIResponses
base_url	обязательно	Endpoint API провайдера
api_key	""	API-ключ (открытый текст)
api_key_keyring	—	Читать API-ключ из связки ключей ОС
default_model	обязательно	Модель по умолчанию
auth_type	"api-key"	"api-key" или "oauth"
oauth_provider	—	OAuth-провайдер (claude, openai, google, qwen, kimi, github, gitlab). Обязательно при auth_type = "oauth"
backup_providers	[]	Имена профилей для failover
custom_headers	{}	Дополнительные HTTP-заголовки
extra_env	{}	Дополнительные переменные окружения для Claude
priority	100	Приоритет для умной маршрутизации
enabled	true	Активен ли этот профиль
max_tokens	—	Ограничить максимальное количество выходных токенов, отправляемых провайдеру (опционально)
strip_params	"auto"	"auto", "none" или ["temperature", "top_p"]. Автоопределение неподдерживаемых параметров (например, ChatGPT Codex endpoint)
[profiles.query_params]	{}	URL query-параметры (например, Azure api-version)
[profiles.models]	—	Таблица маппинга слотов моделей (поля haiku, sonnet, opus)

Интерактивная настройка

Самый простой способ добавить профиль:

claudex profile add

Интерактивный мастер проведёт вас через выбор провайдера, ввод API-ключа (с опциональным хранением в связке ключей), выбор модели и тестирование подключения.

Интеграция со связкой ключей

Храните API-ключи безопасно в связке ключей ОС вместо открытого текста в конфигурации:

[[profiles]]
name = "grok"
api_key_keyring = "grok-api-key"   # читает из связки ключей ОС

Поддерживаемые бэкенды:

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

OAuth-аутентификация по подписке

Вместо API-ключей вы можете аутентифицироваться с помощью существующей подписки провайдера через OAuth. Это полезно при наличии подписки Claude Pro/Team, ChatGPT Plus или другого тарифного плана.

Настройка

1. Установите auth_type профиля в "oauth" и укажите 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. Войдите с помощью команды auth:

claudex auth login openai

3. Проверьте статус аутентификации:

claudex auth status

Поддерживаемые провайдеры

Провайдер	oauth_provider	Источник токена
Claude	claude	Читает из ~/.claude/.credentials.json (нативная конфигурация Claude Code)
ChatGPT	openai	Browser PKCE или Device Code, запасной вариант ~/.codex/auth.json (Codex CLI)
Google	google	Читает из учётных данных Gemini CLI
Qwen	qwen	Device Code flow
Kimi	kimi	Читает из учётных данных Kimi CLI
GitHub	github	Device Code flow, запасной вариант ~/.config/github-copilot/
GitLab	gitlab	Переменная окружения GITLAB_TOKEN

Подробности по OAuth-потоку каждого провайдера см. в OAuth-подписки.

Режим Gateway Auth

При использовании OAuth-профилей Claudex устанавливает ANTHROPIC_AUTH_TOKEN (а не ANTHROPIC_API_KEY) при запуске Claude Code. Это предотвращает конфликты с собственным механизмом входа Claude Code по подписке, который внутренне использует ANTHROPIC_API_KEY.

Прокси автоматически обновляет OAuth-токены до их истечения. Вы также можете обновить вручную:

claudex auth refresh openai

Query-параметры

Некоторые провайдеры требуют URL query-параметры (например, api-version у Azure OpenAI). Используйте таблицу [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 добавляет эти параметры к каждому URL запроса для профиля. Azure OpenAI автоматически определяется по base_url, содержащему openai.azure.com, и использует заголовок api-key для аутентификации вместо Authorization: Bearer.

Фильтрация параметров

Некоторые провайдеры не поддерживают определённые параметры (например, ChatGPT Codex endpoint отклоняет temperature, top_p). Поле strip_params определяет, какие параметры удаляются перед отправкой:

strip_params = "auto"       # автоопределение и удаление неподдерживаемых параметров (по умолчанию)
strip_params = "none"       # отправлять все параметры как есть
strip_params = ["temperature", "top_p", "top_k"]  # удалить конкретные параметры

При значении "auto" Claudex распознаёт известные endpoint-ы (например, chatgpt.com) и удаляет параметры, которые вызвали бы ошибки.

Маппинг слотов моделей

Claude Code имеет встроенный переключатель /model с тремя слотами: haiku, sonnet и opus. См. Маппинг слотов моделей для подробностей.

Совместимость имён инструментов

Некоторые провайдеры (в частности OpenAI) устанавливают лимит в 64 символа для имён инструментов (функций). Claude Code может генерировать имена инструментов, превышающие этот лимит.

Claudex автоматически усекает имена инструментов длиннее 64 символов при отправке запросов OpenAI-совместимым провайдерам и прозрачно восстанавливает оригинальные имена при обработке ответов. Этот цикл полностью прозрачен.

Неинтерактивный режим

Claudex поддерживает одиночное (неинтерактивное) выполнение для использования в CI/CD-конвейерах, скриптах и автоматизации:

# Вывести ответ и завершить
claudex run grok "Explain this codebase" --print

# Пропустить все запросы разрешений (для полностью автоматизированных конвейеров)
claudex run grok "Fix lint errors" --print --dangerously-skip-permissions

Осторожно

--dangerously-skip-permissions отключает все запросы безопасности. Используйте только в доверенных автоматизированных средах.

В неинтерактивном режиме логи записываются в файлы логов для каждого инстанса по пути ~/Library/Caches/claudex/proxy-{timestamp}-{pid}.log вместо stderr, сохраняя чистый stdout для пайпинга и автоматизации.

Терминальные гиперссылки

Claudex поддерживает кликабельные OSC 8 гиперссылки в терминальном выводе. См. Терминальные гиперссылки для подробностей.

# "auto" определяет поддержку терминала; true/false принудительно включают/выключают
hyperlinks = "auto"

Конфигурационные наборы

Установка повторно используемых пакетов правил, навыков и MCP-серверов. См. Конфигурационные наборы для подробностей.

claudex sets add ./my-set
claudex sets list

Полный пример

См. config.example.toml для полного конфигурационного файла со всеми провайдерами и опциями.

Для пошаговых инструкций по настройке каждого провайдера (включая ссылки на API-ключи и OAuth-потоки) см. Руководство по настройке провайдеров.