문서
설정

설정

CC-Relay는 YAML 파일로 설정됩니다. 이 가이드는 모든 설정 옵션을 다룹니다.

설정 파일 위치

기본 위치 (순서대로 확인):

  1. ./config.yaml (현재 디렉토리)
  2. ~/.config/cc-relay/config.yaml
  3. --config 플래그로 지정된 경로

다음 명령으로 기본 설정을 생성하세요:

cc-relay config init

환경 변수 확장

CC-Relay는 ${VAR_NAME} 구문을 사용한 환경 변수 확장을 지원합니다:

providers:
  - name: "anthropic"
    type: "anthropic"
    keys:
      - key: "${ANTHROPIC_API_KEY}"  # 로드 시 확장됨

전체 설정 레퍼런스 

# ==========================================================================
# 서버 설정
# ==========================================================================
server:
  # 수신 대기 주소
  listen: "127.0.0.1:8787"

  # 요청 타임아웃 (밀리초, 기본값: 600000 = 10분)
  timeout_ms: 600000

  # 최대 동시 요청 수 (0 = 무제한)
  max_concurrent: 0

  # 성능 향상을 위해 HTTP/2 활성화
  enable_http2: true

  # 인증 설정
  auth:
    # 프록시 접근에 특정 API 키 요구
    api_key: "${PROXY_API_KEY}"

    # Claude Code 구독 Bearer 토큰 허용
    allow_subscription: true

    # 검증할 특정 Bearer 토큰 (선택 사항)
    bearer_secret: "${BEARER_SECRET}"

# ==========================================================================
# 프로바이더 설정
# ==========================================================================
providers:
  # Anthropic 직접 API
  - name: "anthropic"
    type: "anthropic"
    enabled: true
    base_url: "https://api.anthropic.com"  # 선택 사항, 기본값 사용

    keys:
      - key: "${ANTHROPIC_API_KEY}"
        rpm_limit: 60       # 분당 요청 수
        tpm_limit: 100000   # 분당 토큰 수

    # 선택 사항: 사용 가능한 모델 지정
    models:
      - "claude-sonnet-4-5-20250514"
      - "claude-opus-4-5-20250514"
      - "claude-haiku-3-5-20241022"

  # Z.AI / Zhipu GLM
  - name: "zai"
    type: "zai"
    enabled: true
    base_url: "https://api.z.ai/api/anthropic"

    keys:
      - key: "${ZAI_API_KEY}"

    # Claude 모델명을 Z.AI 모델로 매핑
    model_mapping:
      "claude-sonnet-4-5-20250514": "GLM-4.7"
      "claude-haiku-3-5-20241022": "GLM-4.5-Air"

    # 선택 사항: 사용 가능한 모델 지정
    models:
      - "GLM-4.7"
      - "GLM-4.5-Air"
      - "GLM-4-Plus"

# ==========================================================================
# 로깅 설정
# ==========================================================================
logging:
  # 로그 레벨: debug, info, warn, error
  level: "info"

  # 로그 형식: json, text
  format: "text"

  # 컬러 출력 활성화 (text 형식용)
  pretty: true

  # 상세 디버그 옵션
  debug_options:
    log_request_body: false
    log_response_headers: false
    log_tls_metrics: false
    max_body_log_size: 1000

# ==========================================================================
# 캐시 설정
# ==========================================================================
cache:
  # 캐시 모드: single, ha, disabled
  mode: single

  # 싱글 모드 (Ristretto) 설정
  ristretto:
    num_counters: 1000000  # 10x expected max items
    max_cost: 104857600    # 100 MB
    buffer_items: 64       # Admission buffer size

  # HA 모드 (Olric) 설정
  olric:
    embedded: true                 # Run embedded Olric node
    bind_addr: "0.0.0.0:3320"      # Olric client port
    dmap_name: "cc-relay"          # Distributed map name
    environment: lan               # local, lan, or wan
    peers:                         # Memberlist addresses (bind_addr + 2)
      - "other-node:3322"
    replica_count: 2               # Copies per key
    read_quorum: 1                 # Min reads for success
    write_quorum: 1                # Min writes for success
    member_count_quorum: 2         # Min cluster members
    leave_timeout: 5s              # Leave broadcast duration

서버 설정

수신 대기 주소

listen 필드는 프록시가 요청을 수신하는 위치를 지정합니다:

server:
  listen: "127.0.0.1:8787"  # 로컬 전용 (권장)
  # listen: "0.0.0.0:8787"  # 모든 인터페이스 (주의해서 사용)

인증

CC-Relay는 여러 인증 방식을 지원합니다:

API 키 인증

클라이언트에게 특정 API 키를 요구합니다:

server:
  auth:
    api_key: "${PROXY_API_KEY}"

클라이언트는 헤더를 포함해야 합니다: x-api-key: <your-proxy-key>

Claude Code 구독 패스스루

Claude Code 구독 사용자 연결을 허용합니다:

server:
  auth:
    allow_subscription: true

Claude Code의 Authorization: Bearer 토큰을 수락합니다.

복합 인증

API 키와 구독 인증 모두 허용:

server:
  auth:
    api_key: "${PROXY_API_KEY}"
    allow_subscription: true

인증 없음

인증을 비활성화하려면 (프로덕션에서는 권장하지 않음):

server:
  auth: {}
  # 또는 단순히 auth 섹션 생략

HTTP/2 지원

동시 요청 성능 향상을 위해 HTTP/2를 활성화합니다:

server:
  enable_http2: true

프로바이더 설정

프로바이더 유형

CC-Relay는 현재 두 가지 프로바이더 유형을 지원합니다:

유형설명기본 Base URL
anthropicAnthropic 직접 APIhttps://api.anthropic.com
zaiZ.AI / Zhipu GLMhttps://api.z.ai/api/anthropic

Anthropic 프로바이더 

providers:
  - name: "anthropic"
    type: "anthropic"
    enabled: true
    base_url: "https://api.anthropic.com"  # 선택 사항

    keys:
      - key: "${ANTHROPIC_API_KEY}"
        rpm_limit: 60
        tpm_limit: 100000

    models:
      - "claude-sonnet-4-5-20250514"
      - "claude-opus-4-5-20250514"
      - "claude-haiku-3-5-20241022"

Z.AI 프로바이더

Z.AI는 저렴한 비용으로 GLM 모델과 함께 Anthropic 호환 API를 제공합니다:

providers:
  - name: "zai"
    type: "zai"
    enabled: true
    base_url: "https://api.z.ai/api/anthropic"

    keys:
      - key: "${ZAI_API_KEY}"

    model_mapping:
      "claude-sonnet-4-5-20250514": "GLM-4.7"
      "claude-haiku-3-5-20241022": "GLM-4.5-Air"

    models:
      - "GLM-4.7"
      - "GLM-4.5-Air"
      - "GLM-4-Plus"

다중 API 키

처리량 향상을 위해 여러 API 키를 풀링합니다:

providers:
  - name: "anthropic"
    type: "anthropic"
    enabled: true

    keys:
      - key: "${ANTHROPIC_API_KEY_1}"
        rpm_limit: 60
        tpm_limit: 100000
      - key: "${ANTHROPIC_API_KEY_2}"
        rpm_limit: 60
        tpm_limit: 100000
      - key: "${ANTHROPIC_API_KEY_3}"
        rpm_limit: 60
        tpm_limit: 100000

커스텀 Base URL

기본 API 엔드포인트를 재정의합니다:

providers:
  - name: "anthropic-custom"
    type: "anthropic"
    base_url: "https://custom-endpoint.example.com"

로깅 설정

로그 레벨

레벨설명
debug개발용 상세 출력
info정상 작동 메시지
warn경고 메시지
error오류 메시지만

로그 형식 

logging:
  format: "text"   # 사람이 읽기 쉬운 형식 (기본값)
  # format: "json" # 기계가 읽기 쉬운 형식, 로그 집계용

디버그 옵션

디버그 로깅에 대한 세밀한 제어:

logging:
  level: "debug"
  debug_options:
    log_request_body: true      # 요청 본문 로깅 (마스킹됨)
    log_response_headers: true  # 응답 헤더 로깅
    log_tls_metrics: true       # TLS 연결 정보 로깅
    max_body_log_size: 1000     # 본문에서 로깅할 최대 바이트

캐시 설정

CC-Relay는 다양한 배포 시나리오에 맞는 여러 백엔드 옵션을 지원하는 통합 캐시 레이어를 제공합니다.

캐시 모드

모드백엔드사용 사례
singleRistretto단일 인스턴스 배포, 고성능
haOlric다중 인스턴스 배포, 공유 상태
disabledNoop캐싱 없음, 패스스루

싱글 모드 (Ristretto)

Ristretto는 고성능 동시성 지원 인메모리 캐시입니다. 단일 인스턴스 배포의 기본 모드입니다.

cache:
  mode: single
  ristretto:
    num_counters: 1000000  # 10x expected max items
    max_cost: 104857600    # 100 MB
    buffer_items: 64       # Admission buffer size
필드타입기본값설명
num_countersint641,000,0004비트 접근 카운터 수. 권장: 예상 최대 항목의 10배.
max_costint64104,857,600 (100 MB)캐시가 보유할 수 있는 최대 메모리(바이트).
buffer_itemsint6464Get 버퍼당 키 수. 어드미션 버퍼 크기 제어.

HA 모드 (Olric) - 임베디드

공유 캐시 상태가 필요한 다중 인스턴스 배포의 경우, 각 cc-relay 인스턴스가 Olric 노드를 실행하는 임베디드 Olric 모드를 사용합니다.

cache:
  mode: ha
  olric:
    embedded: true
    bind_addr: "0.0.0.0:3320"
    dmap_name: "cc-relay"
    environment: lan
    peers:
      - "other-node:3322"  # Memberlist port = bind_addr + 2
    replica_count: 2
    read_quorum: 1
    write_quorum: 1
    member_count_quorum: 2
    leave_timeout: 5s
필드타입기본값설명
embeddedboolfalse임베디드 Olric 노드 실행 (true) vs. 외부 클러스터 연결 (false).
bind_addrstring필수Olric 클라이언트 연결 주소 (예: “0.0.0.0:3320”).
dmap_namestring“cc-relay”분산 맵 이름. 모든 노드가 동일한 이름을 사용해야 함.
environmentstring“local”Memberlist 프리셋: “local”, “lan”, 또는 “wan”.
peers[]string-피어 검색을 위한 Memberlist 주소. bind_addr + 2 포트 사용.
replica_countint1키당 복제본 수. 1 = 복제 없음.
read_quorumint1응답에 필요한 최소 성공 읽기 수.
write_quorumint1응답에 필요한 최소 성공 쓰기 수.
member_count_quorumint321운영에 필요한 최소 클러스터 멤버 수.
leave_timeoutduration5s종료 전 이탈 메시지 브로드캐스트 시간.

중요: Olric은 두 개의 포트를 사용합니다 - 클라이언트 연결용 bind_addr 포트와 memberlist 가십용 bind_addr + 2. 방화벽에서 두 포트 모두 열어야 합니다.

HA 모드 (Olric) - 클라이언트 모드

임베디드 노드를 실행하는 대신 외부 Olric 클러스터에 연결합니다:

cache:
  mode: ha
  olric:
    embedded: false
    addresses:
      - "olric-node-1:3320"
      - "olric-node-2:3320"
    dmap_name: "cc-relay"
필드타입설명
embeddedbool클라이언트 모드에서는 false로 설정.
addresses[]string외부 Olric 클러스터 주소.
dmap_namestring분산 맵 이름 (클러스터 설정과 일치해야 함).

비활성화 모드

디버깅용이거나 다른 곳에서 캐싱을 처리할 때 캐싱을 완전히 비활성화합니다:

cache:
  mode: disabled

HA 클러스터링 가이드 및 문제 해결을 포함한 전체 캐시 문서는 캐싱을 참조하세요.

설정 예제

최소 단일 프로바이더 

server:
  listen: "127.0.0.1:8787"

providers:
  - name: "anthropic"
    type: "anthropic"
    enabled: true
    keys:
      - key: "${ANTHROPIC_API_KEY}"

멀티 프로바이더 설정 

server:
  listen: "127.0.0.1:8787"
  auth:
    allow_subscription: true

providers:
  - name: "anthropic"
    type: "anthropic"
    enabled: true
    keys:
      - key: "${ANTHROPIC_API_KEY}"

  - name: "zai"
    type: "zai"
    enabled: true
    keys:
      - key: "${ZAI_API_KEY}"
    model_mapping:
      "claude-sonnet-4-5-20250514": "GLM-4.7"

logging:
  level: "info"
  format: "text"

디버그 로깅을 포함한 개발 설정 

server:
  listen: "127.0.0.1:8787"

providers:
  - name: "anthropic"
    type: "anthropic"
    enabled: true
    keys:
      - key: "${ANTHROPIC_API_KEY}"

logging:
  level: "debug"
  format: "text"
  pretty: true
  debug_options:
    log_request_body: true
    log_response_headers: true
    log_tls_metrics: true

설정 검증

설정 파일을 검증합니다:

cc-relay config validate

핫 리로딩

설정 변경 시 서버를 재시작해야 합니다. 핫 리로딩은 향후 릴리스에 계획되어 있습니다.

다음 단계

시작하기아키텍처