설정

설정 파일 탐색

Claudex는 figment를 사용한 계층형 설정을 제공합니다. 소스는 다음 순서로 병합됩니다(나중 소스가 이전 소스를 덮어씁니다):

1. 프로그래밍 기본값 (내장 폴백)
2. 전역 설정 (~/.config/claudex/config.toml 또는 config.yaml)
3. 프로젝트 설정 (현재 디렉토리 또는 상위 디렉토리(최대 10단계)에서 claudex.toml 또는 claudex.yaml, 또는 $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 바이너리 경로 (기본값: PATH에서 "claude")
# 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	필수	프로바이더 API 엔드포인트
api_key	""	API 키 (평문)
api_key_keyring	—	OS 키체인에서 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	[]	장애 조치 프로파일 이름 목록
custom_headers	{}	추가 HTTP 헤더
extra_env	{}	Claude용 추가 환경 변수
priority	100	스마트 라우팅 우선순위
enabled	true	이 프로파일의 활성화 여부
max_tokens	—	프로바이더에 전송하는 최대 출력 토큰 수 제한 (선택)
strip_params	"auto"	"auto", "none", 또는 ["temperature", "top_p"]. 지원되지 않는 파라미터를 자동 감지 (예: ChatGPT Codex 엔드포인트)
[profiles.query_params]	{}	URL 쿼리 파라미터 (예: Azure api-version)
[profiles.models]	—	모델 슬롯 매핑 테이블 (haiku, sonnet, opus 필드)

대화형 설정

프로파일을 추가하는 가장 쉬운 방법은 대화형 마법사입니다:

claudex profile add

프로바이더 선택, API 키 입력(선택적 키링 저장), 모델 선택, 연결 테스트를 안내합니다.

키링 통합

평문 설정 대신 OS 키체인에 API 키를 안전하게 저장할 수 있습니다:

[[profiles]]
name = "grok"
api_key_keyring = "grok-api-key"   # OS 키체인에서 읽기

지원 백엔드:

• 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	브라우저 PKCE 또는 Device Code, ~/.codex/auth.json(Codex CLI)으로 폴백
Google	google	Gemini CLI 자격 증명에서 읽기
Qwen	qwen	Device Code 플로우
Kimi	kimi	Kimi CLI 자격 증명에서 읽기
GitHub	github	Device Code 플로우, ~/.config/github-copilot/으로 폴백
GitLab	gitlab	GITLAB_TOKEN 환경 변수

각 프로바이더의 OAuth 플로우에 대한 자세한 내용은 OAuth 구독 인증을 참조하세요.

게이트웨이 인증 모드

OAuth 프로파일 사용 시, Claudex는 Claude Code 실행 시 ANTHROPIC_API_KEY가 아닌 ANTHROPIC_AUTH_TOKEN을 설정합니다. 이는 내부적으로 ANTHROPIC_API_KEY를 사용하는 Claude Code 자체 구독 로그인 메커니즘과의 충돌을 방지합니다.

프록시는 OAuth 토큰이 만료되기 전에 자동으로 갱신합니다. 수동 갱신도 가능합니다:

claudex auth refresh openai

쿼리 파라미터

일부 프로바이더는 URL 쿼리 파라미터가 필요합니다(예: Azure OpenAI의 api-version). [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이 포함되어 있으면 자동 감지되며, Authorization: Bearer 대신 api-key 헤더로 인증합니다.

파라미터 스트리핑

일부 프로바이더는 특정 파라미터를 지원하지 않습니다(예: ChatGPT Codex 엔드포인트는 temperature, top_p를 거부). strip_params 필드로 전송 전 제거할 파라미터를 제어합니다:

strip_params = "auto"       # 지원되지 않는 파라미터를 자동 감지하여 제거 (기본값)
strip_params = "none"       # 모든 파라미터를 그대로 전송
strip_params = ["temperature", "top_p", "top_k"]  # 특정 파라미터만 제거

"auto"로 설정하면, Claudex가 알려진 엔드포인트(예: chatgpt.com)를 감지하고 오류를 유발할 수 있는 파라미터를 자동으로 제거합니다.

모델 슬롯 매핑

Claude Code에는 haiku, sonnet, opus 세 가지 슬롯을 가진 내장 /model 전환기가 있습니다. 자세한 내용은 모델 슬롯 매핑을 참조하세요.

도구 이름 호환성

일부 프로바이더(특히 OpenAI)는 도구(함수) 이름에 64자 제한을 적용합니다. Claude Code는 이 제한을 초과하는 도구 이름을 생성할 수 있습니다.

Claudex는 OpenAI 호환 프로바이더에 요청을 보낼 때 64자를 초과하는 도구 이름을 자동으로 단축하고, 응답 처리 시 원래 이름을 투명하게 복원합니다. 이 왕복 처리는 완전히 투명합니다.

비대화형 모드

Claudex는 CI/CD 파이프라인, 스크립트, 자동화를 위한 원샷(비대화형) 실행을 지원합니다:

# 응답을 출력하고 종료
claudex run grok "Explain this codebase" --print

# 모든 권한 프롬프트 건너뛰기 (완전 자동화 파이프라인용)
claudex run grok "Fix lint errors" --print --dangerously-skip-permissions

주의

--dangerously-skip-permissions는 모든 안전 프롬프트를 비활성화합니다. 신뢰할 수 있는 자동화 환경에서만 사용하세요.

비대화형 모드에서는 stderr 대신 ~/Library/Caches/claudex/proxy-{timestamp}-{pid}.log 인스턴스별 로그 파일에 로그가 기록되어, 파이핑 및 자동화를 위해 stdout 출력이 깔끔하게 유지됩니다.

터미널 하이퍼링크

Claudex는 터미널 출력에서 OSC 8 클릭 가능한 하이퍼링크를 지원합니다. 자세한 내용은 터미널 하이퍼링크를 참조하세요.

# "auto"는 터미널 지원을 자동 감지; true/false는 강제 활성화/비활성화
hyperlinks = "auto"

설정 세트

재사용 가능한 규칙, 스킬, MCP 서버 번들을 설치합니다. 자세한 내용은 설정 세트를 참조하세요.

claudex sets add ./my-set
claudex sets list

전체 예시

모든 프로바이더 및 옵션이 포함된 완전한 설정 파일은 config.example.toml을 참조하세요.

각 프로바이더의 단계별 설정 안내(API 키 링크 및 OAuth 플로우 포함)는 프로바이더 설정 가이드를 참조하세요.