메인 콘텐츠로 건너뛰기
Code Gateway는 AI 코딩 CLI 도구(Claude Code, Cursor, Codex CLI, Gemini CLI, GitHub Copilot 등)의 LLM API 요청을 Cloosphere를 경유하도록 하는 엔터프라이즈 프록시 게이트웨이입니다. 가드레일, 사용량 추적, 감사 로그, 레이트 리밋을 통해 AI 코딩 도구의 사용을 중앙에서 관리합니다.
Code Gateway 설정 메인 화면

​
개념

구성 요소설명
개발자AI 코딩 도구에서 Cloosphere Code Gateway를 BASE_URL로 설정
Code Gateway인증, 가드레일, 레이트 리밋, 사용량 추적을 수행한 후 upstream provider로 프록시
LLM Provider실제 LLM API를 제공하는 서비스 (OpenAI, Anthropic, Azure 등)
Code Gateway는 백엔드 API 전용이며, Cloosphere 웹 UI에서의 채팅과는 별도로 동작합니다. 관리자 설정에서만 구성하며, 사용자는 자신의 코딩 도구에 Cloosphere API 키를 설정하여 사용합니다.

​
활성화 및 설정

​
Code Gateway 활성화

1

관리자 설정 진입

관리자 패널에서 Code Gateway 설정 페이지로 이동합니다.
2

게이트웨이 활성화

“Code Gateway 활성화” 토글을 켭니다.
3

Provider 추가

**”+ Provider 추가”**를 클릭하여 LLM Provider를 등록합니다.
4

보안 설정

허용 모델, 레이트 리밋, 가드레일, 파일 패턴 차단을 구성합니다.
Code Gateway 활성화 및 전체 설정

​
전역 설정

설정설명기본값
활성화Code Gateway ON/OFFOFF
허용 모델사용 가능한 모델 목록 (비어있으면 전체 허용)전체
레이트 리밋사용자당 분당 최대 요청 수 (0 = 무제한)0
가드레일적용할 가드레일 ID 목록없음
파일 패턴 차단차단할 파일 패턴 (glob 형식)없음
파일 차단 동작차단 시 동작 (block / warn)block
차단된 레포지토리AI 코딩 도구 사용을 차단할 레포지토리 패턴없음
레포지토리 메타데이터 필수헬퍼 스크립트 미설정 시 요청 차단OFF

​
Provider 설정

Provider는 Code Gateway가 요청을 전달할 upstream LLM 서비스입니다. 여러 Provider를 동시에 등록할 수 있으며, 각 Provider는 고유한 provider_id로 식별됩니다.

​
지원 Provider

타입서비스인증 방식
openaiOpenAI, OpenAI-compatible 엔드포인트Bearer token
anthropicAnthropic APIx-api-key 헤더
geminiGoogle Gemini APIx-goog-api-key 헤더
azure_openaiAzure OpenAI Serviceapi-key 헤더
azure_ai_foundryAzure AI Foundryapi-key 헤더
vertex_aiGoogle Vertex AI (네이티브)GCP Service Account

​
Provider 프리셋

Provider 추가 시 프리셋을 선택하면 타입과 기본 URL이 자동으로 설정됩니다.
Azure AI Foundry는 두 가지 서브 프리셋으로 나뉩니다:
  • Azure AI Foundry - OpenAI: OpenAI 호환 모델용 (openai 타입). Cursor, Codex CLI, GitHub Copilot에서 사용.
  • Azure AI Foundry - Claude: Claude 모델용 (azure_ai_foundry 타입). Claude Code, Cursor에서 사용.
동일한 AI Foundry 엔드포인트라도 사용하는 모델에 따라 적합한 프리셋을 선택하세요.

​
Provider 추가

Code Gateway Provider 추가
설정설명
Provider ID고유 식별자 (URL 경로에 사용)
타입openai / anthropic / gemini
API URLProvider API 엔드포인트
API Key인증 키
모델 ID이 Provider에서 허용할 모델 목록 (비어있으면 전체)
활성화Provider ON/OFF

​
개발자 사용법

개발자는 AI 코딩 도구의 BASE_URL을 Cloosphere Code Gateway로 설정하고, Cloosphere API 키를 사용합니다.

​
엔드포인트 구조

{CLOOSPHERE_URL}/api/v1/code-gateway/{provider_id}/{path}
예시:
  • OpenAI Provider: https://cloosphere.company.com/api/v1/code-gateway/openai/v1/chat/completions
  • Anthropic Provider: https://cloosphere.company.com/api/v1/code-gateway/anthropic/v1/messages

​
인증

Code Gateway는 다음 네 가지 방식으로 API 키를 전달받습니다 (우선순위 순).
방식헤더/파라미터사용 도구
Bearer TokenAuthorization: Bearer {api_key}Cursor, Codex CLI, GitHub Copilot
x-api-keyx-api-key: {api_key}Claude Code (Anthropic SDK)
x-goog-api-keyx-goog-api-key: {api_key}Gemini CLI
Query Parameter?key={api_key}Fallback
API 키는 Cloosphere 사용자 설정의 “API 키” 섹션에서 생성합니다. Provider의 원본 API 키가 아닌 Cloosphere API 키를 사용하세요.

​
도구별 설정 예시

# .bashrc 또는 .zshrc
export ANTHROPIC_BASE_URL="https://cloosphere.company.com/api/v1/code-gateway/anthropic"
export ANTHROPIC_API_KEY="sk-cloosphere-..."

​
Claude Code 셋업 스크립트

Claude Code 사용자를 위한 자동 셋업 스크립트를 제공합니다. 스크립트는 헬퍼 스크립트 설치와 ~/.claude/settings.json 설정을 자동으로 수행합니다. 
# 1. 환경 변수 설정
export ANTHROPIC_AUTH_TOKEN="sk-cloosphere-..."
export ANTHROPIC_BASE_URL="https://cloosphere.company.com/api/v1/code-gateway/anthropic"

# 2. 셋업 스크립트 실행
curl -s https://cloosphere.company.com/api/v1/code-gateway/setup-script | bash
셋업 스크립트가 수행하는 작업:
  1. 헬퍼 스크립트 설치 (~/cloosphere-helper.sh 또는 ~/cloosphere-helper.ps1): 레포지토리 메타데이터(Git remote URL, 작업 디렉토리)를 API 키에 자동 첨부
  2. ~/.claude/settings.json 구성: ANTHROPIC_AUTH_TOKEN, ANTHROPIC_BASE_URL, apiKeyHelper 자동 설정
헬퍼 스크립트는 레포지토리 메타데이터 기반 차단 정책(blocked_repos, require_repo_metadata)이 활성화된 환경에서 필수입니다.

​
보안 기능

​
가드레일

Code Gateway에 가드레일을 적용하여 코딩 도구의 입력에서 PII 감지, 콘텐츠 필터링 등을 수행합니다. 가드레일 관리에서 생성한 가드레일 ID를 지정합니다. 가드레일 위반, 파일 패턴 차단, 레포지토리 차단 등의 이벤트는 모두 모니터링 > 가드레일 로그 탭에서 확인할 수 있습니다.
Code Gateway 보안 설정

​
허용 모델

특정 모델만 사용하도록 제한합니다. 전역 레벨과 Provider 레벨에서 각각 설정할 수 있습니다.
레벨설정 필드설명
전역 허용 모델allowed_modelsCode Gateway 전체에서 사용 가능한 모델 (전역 설정)
Provider 모델 IDmodel_ids특정 Provider에서 허용할 모델 (Provider별 설정)
allowed_models(전역)과 model_ids(Provider별) 모두에서 모델 제한이 설정된 경우, 양쪽 모두에서 허용된 모델만 사용 가능합니다. allowed_models는 Code Gateway 전체 정책이고, model_ids는 개별 Provider 내에서의 추가 제한입니다.

​
레이트 리밋

사용자당 분당 최대 요청 수를 제한합니다. 60초 슬라이딩 윈도우 기반으로 동작합니다.
레이트 리밋은 인메모리 방식이므로 서버 재시작 시 리셋됩니다.

​
파일 패턴 차단

코딩 도구가 전송하는 파일 내용에서 특정 패턴의 파일을 차단합니다. glob 형식으로 패턴을 지정합니다.
설정설명예시
패턴차단할 파일 경로 패턴*.env, *credentials*, *.pem
동작block (요청 차단) 또는 warn (로그만 기록)block

​
차단된 레포지토리

특정 Git 레포지토리에서의 AI 코딩 도구 사용을 차단합니다. 헬퍼 스크립트를 통해 전달되는 레포지토리 메타데이터(repo URL, 작업 디렉토리)를 기반으로 매칭합니다.
설정설명예시
차단 패턴차단할 레포지토리 URL 또는 경로 패턴 (부분 문자열 매칭)secret-project, github.com/org/private-repo
패턴은 대소문자 구분 없이 레포지토리 URL과 작업 디렉토리 경로에 대해 부분 문자열 매칭됩니다. Git SSH URL(git@github.com:org/repo.git)도 자동으로 정규화하여 매칭합니다.
차단된 레포지토리 접근은 가드레일 로그에 자동 기록됩니다.

​
레포지토리 메타데이터 필수

require_repo_metadata를 활성화하면, 헬퍼 스크립트를 통한 레포지토리 메타데이터가 없는 요청을 차단합니다. 이를 통해 모든 Code Gateway 사용자가 헬퍼 스크립트를 설정하도록 강제할 수 있습니다.
이 옵션을 활성화하면 헬퍼 스크립트가 설정되지 않은 사용자의 요청이 모두 차단됩니다. 활성화 전 사용자에게 헬퍼 스크립트 설정을 안내하세요.

​
사용량 추적

Code Gateway를 통한 모든 요청은 자동으로 사용량이 기록됩니다. 관리자는 사용 로그를 조회하여 팀별, 사용자별, 모델별 사용 현황을 확인할 수 있습니다.
항목설명
사용자요청한 사용자
모델사용된 LLM 모델
Provider사용된 Provider
입력/출력 토큰요청/응답 토큰 수
시간요청 시간

​
사용량 통계

기간별 사용량 통계를 조회하여 비용과 사용 추이를 분석합니다.

​
필터

필터설명
사용자특정 사용자로 필터링
모델특정 모델로 필터링
기간시작일 ~ 종료일

​
프록시 처리 흐름

Code Gateway가 요청을 처리하는 전체 흐름입니다.

​
트러블슈팅

관리자 설정에서 Code Gateway가 비활성화 상태입니다. 관리자에게 활성화를 요청하세요.
사용자의 기능 권한에 Code Gateway 접근이 허용되지 않았습니다. 관리자가 그룹 권한 설정에서 features.code_gateway를 활성화해야 합니다.
요청 URL의 provider_id가 등록된 Provider와 일치하지 않습니다. Provider ID를 확인하세요.
요청한 모델이 전역 허용 모델 또는 Provider 허용 모델 목록에 포함되지 않았습니다. 관리자에게 모델 추가를 요청하세요.
분당 요청 한도를 초과했습니다. 잠시 대기 후 재시도하세요.
require_repo_metadata가 활성화되었으나 헬퍼 스크립트가 설정되지 않았습니다. Claude Code 셋업 스크립트를 실행하여 헬퍼 스크립트를 설치하세요.
요청의 레포지토리 URL 또는 작업 디렉토리가 blocked_repos 패턴과 일치합니다. 관리자에게 차단 해제를 요청하세요.