設定 – CC-Relay - Multi-Provider LLM Proxy

設定

CC-Relay は YAML ファイルで設定されます。このガイドでは、すべての設定オプションについて説明します。

設定ファイルの場所

デフォルトの場所（この順序でチェックされます）：

./config.yaml（カレントディレクトリ）
~/.config/cc-relay/config.yaml
--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       # 1分あたりのリクエスト数
        tpm_limit: 100000   # 1分あたりのトークン数

    # オプション: 利用可能なモデルを指定
    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 は現在2つのプロバイダータイプをサポートしています：

タイプ	説明	デフォルト Base URL
`anthropic`	Anthropic ダイレクト API	`https://api.anthropic.com`
`zai`	Z.AI / Zhipu GLM	`https://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 は、さまざまなデプロイメントシナリオに対応する複数のバックエンドオプションを備えた統合キャッシュレイヤーを提供します。

キャッシュモード

モード	バックエンド	用途
`single`	Ristretto	シングルインスタンスデプロイメント、高性能
`ha`	Olric	マルチインスタンスデプロイメント、共有状態
`disabled`	Noop	キャッシングなし、パススルー

シングルモード (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_counters`	int64	1,000,000	4ビットアクセスカウンターの数。推奨: 予想最大アイテム数の10倍。
`max_cost`	int64	104,857,600 (100 MB)	キャッシュが保持できる最大メモリ（バイト）。
`buffer_items`	int64	64	Get バッファあたりのキー数。アドミッションバッファサイズを制御。

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

フィールド	タイプ	デフォルト	説明
`embedded`	bool	false	埋め込み Olric ノードを実行 (true) vs. 外部クラスターに接続 (false)。
`bind_addr`	string	必須	Olric クライアント接続用アドレス（例: “0.0.0.0:3320”）。
`dmap_name`	string	“cc-relay”	分散マップの名前。すべてのノードで同じ名前を使用する必要があります。
`environment`	string	“local”	Memberlist プリセット: “local”、“lan”、または “wan”。
`peers`	[]string	-	ピア検出用の Memberlist アドレス。bind_addr + 2 のポートを使用。
`replica_count`	int	1	キーあたりのコピー数。1 = レプリケーションなし。
`read_quorum`	int	1	応答に必要な最小読み取り成功数。
`write_quorum`	int	1	応答に必要な最小書き込み成功数。
`member_count_quorum`	int32	1	動作に必要な最小クラスターメンバー数。
`leave_timeout`	duration	5s	シャットダウン前の離脱メッセージブロードキャスト時間。

重要: Olric は2つのポートを使用します - クライアント接続用の 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"

フィールド	タイプ	説明
`embedded`	bool	クライアントモードでは `false` に設定。
`addresses`	[]string	外部 Olric クラスターアドレス。
`dmap_name`	string	分散マップ名（クラスター設定と一致する必要があります）。

無効モード

デバッグ用または他の場所でキャッシングが処理される場合、キャッシングを完全に無効にします：

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

ホットリロード

設定変更にはサーバーの再起動が必要です。ホットリロードは将来のリリースで予定されています。

次のステップ

はじめにアーキテクチャ