> ## Documentation Index
> Fetch the complete documentation index at: https://docs.cloosphere.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# 코드 게이트웨이

> AI 코딩 도구(Claude Code, Codex CLI, Gemini CLI, Cursor)용 LLM API 프록시 게이트웨이 설정 및 관리

<Info>관리자 › 설정 › 코드 게이트웨이</Info>

코드 게이트웨이는 AI 코딩 CLI 도구(Claude Code, Codex CLI, Gemini CLI, Cursor)의 LLM API 요청을 Cloosphere를 경유하도록 하는 엔터프라이즈 프록시 게이트웨이(요청을 중간에서 중계하며 검사·기록하는 관문)입니다.

* GitHub Copilot CLI 등 OpenAI 호환 클라이언트도 OpenAI 엔드포인트로 연결할 수 있습니다.

가드레일, 사용량 추적, 감사 로그, 요청 제한을 통해 AI 코딩 도구의 사용을 중앙에서 관리합니다.

<Frame caption="코드 게이트웨이 설정 메인 화면">
  <img src="https://mintcdn.com/cloocus/Or1RjU_AzOVJRxuS/images/admin/code-gateway-main.png?fit=max&auto=format&n=Or1RjU_AzOVJRxuS&q=85&s=9c9a7d7352f1b3d42439d91a7280c593" alt="코드 게이트웨이 설정 메인 화면" width="2880" height="1800" data-path="images/admin/code-gateway-main.png" />
</Frame>

***

## 개념

```mermaid theme={null}
flowchart LR
    subgraph 개발자
        A[Claude Code]
        B[Cursor]
        C[Codex CLI]
        D[Gemini CLI]
        D2[GitHub Copilot]
    end

    subgraph Cloosphere
        E[코드 게이트웨이]
        E --> F[인증]
        E --> G[가드레일]
        E --> H[요청 제한]
        E --> I[사용량 추적]
        E --> J[감사 로그]
    end

    subgraph LLM_Provider
        K[OpenAI]
        L[Anthropic]
        M[Azure OpenAI]
        N[Google Gemini]
        O[Vertex AI]
        P[Azure AI Foundry]
    end

    A --> E
    B --> E
    C --> E
    D --> E
    D2 --> E
    E --> K
    E --> L
    E --> M
    E --> N
    E --> O
    E --> P
```

| 구성 요소            | 설명                                                    |
| ---------------- | ----------------------------------------------------- |
| **개발자**          | AI 코딩 도구에서 Cloosphere 코드 게이트웨이를 BASE\_URL로 설정         |
| **코드 게이트웨이**     | 인증, 가드레일, 요청 제한, 사용량 추적을 수행한 후 upstream provider로 프록시 |
| **LLM Provider** | 실제 LLM API를 제공하는 서비스 (OpenAI, Anthropic, Azure 등)     |

<Note>
  코드 게이트웨이는 백엔드 API 전용이며, Cloosphere 웹 UI에서의 채팅과는 별도로 동작합니다. 관리자 설정에서만 구성하며, 사용자는 자신의 코딩 도구에 Cloosphere API 키를 설정하여 사용합니다.
</Note>

***

## 활성화 및 설정

### 코드 게이트웨이 활성화

<Steps>
  <Step title="관리자 설정 진입">
    관리자 패널에서 **코드 게이트웨이** 설정 페이지로 이동합니다.
  </Step>

  <Step title="게이트웨이 활성화">
    **"코드 게이트웨이 활성화"** 토글을 켭니다.
  </Step>

  <Step title="Provider 추가">
    **"+ Provider 추가"** 버튼을 클릭하여 LLM Provider를 등록합니다.
  </Step>

  <Step title="보안 설정">
    허용 모델, 요청 제한, 가드레일, 파일 패턴 차단을 구성합니다.
  </Step>
</Steps>

<Frame caption="코드 게이트웨이 활성화 및 전체 설정">
  <img src="https://mintcdn.com/cloocus/kN0YvsveHAOdEazS/images/admin/code-gateway-top.png?fit=max&auto=format&n=kN0YvsveHAOdEazS&q=85&s=0c09aadb5f14a42b35e29e3e604eb369" alt="코드 게이트웨이 활성화 및 전체 설정" width="2880" height="1800" data-path="images/admin/code-gateway-top.png" />
</Frame>

### 전역 설정

<Accordion title="전역 설정 항목 (10개)" icon="sliders">
  | 설정                 | 설명                                           |  기본값  |
  | ------------------ | -------------------------------------------- | :---: |
  | **활성화**            | 코드 게이트웨이 ON/OFF                              |  OFF  |
  | **허용 모델**          | 사용 가능한 모델 목록 (비어있으면 전체 허용)                   |   전체  |
  | **요청 제한**          | 사용자당 분당 최대 요청 수 (0 = 무제한)                    |   0   |
  | **보안**             | 보안 검사(가드레일·파일 패턴·리포지토리 차단)를 일괄로 켜고 끄는 마스터 토글 |   ON  |
  | **전역 가드레일 설정 따름**  | 전역 가드레일 설정을 코드 게이트웨이에 그대로 적용                 |   ON  |
  | **가드레일**           | 적용할 가드레일 ID 목록                               |   없음  |
  | **차단할 파일 패턴**      | 차단할 파일 경로 패턴 (glob 형식)                       |   없음  |
  | **파일 차단 동작**       | 차단 시 동작 (block / warn)                       | block |
  | **차단된 리포지토리**      | AI 코딩 도구 사용을 차단할 리포지토리 패턴                    |   없음  |
  | **리포지토리 메타데이터 필수** | 헬퍼 스크립트 미설정 시 요청 차단                          |  OFF  |
</Accordion>

***

## 프로바이더

프로바이더는 코드 게이트웨이가 요청을 전달할 upstream LLM 서비스입니다.

* 여러 프로바이더를 동시에 등록할 수 있으며, 각 프로바이더는 고유한 `provider_id`로 식별됩니다.

### 지원 프로바이더

| 타입                     | 서비스                             | 인증 방식               |
| ---------------------- | ------------------------------- | ------------------- |
| **openai**             | OpenAI, OpenAI-compatible 엔드포인트 | Bearer token        |
| **anthropic**          | Anthropic API                   | x-api-key 헤더        |
| **gemini**             | Google Gemini API               | x-goog-api-key 헤더   |
| **azure\_openai**      | Azure OpenAI Service            | api-key 헤더          |
| **azure\_ai\_foundry** | Azure AI Foundry                | api-key 헤더          |
| **vertex\_ai**         | Google Vertex AI (네이티브)         | GCP Service Account |

### 프로바이더 프리셋

프로바이더 추가 시 프리셋을 선택하면 타입과 기본 URL이 자동으로 설정됩니다.

<Note>
  **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 엔드포인트라도 사용하는 모델에 따라 적합한 프리셋을 선택하세요.
</Note>

### 프로바이더 추가

<Frame caption="코드 게이트웨이 프로바이더 추가">
  <img src="https://mintcdn.com/cloocus/kN0YvsveHAOdEazS/images/admin/code-gateway-scroll.png?fit=max&auto=format&n=kN0YvsveHAOdEazS&q=85&s=b9a6efcc6f801de1586ab6ebd262146a" alt="코드 게이트웨이 프로바이더 추가" width="1436" height="983" data-path="images/admin/code-gateway-scroll.png" />
</Frame>

<Tabs>
  <Tab title="OpenAI / Anthropic / Gemini">
    | 설정              | 설명                                |
    | --------------- | --------------------------------- |
    | **Provider ID** | 고유 식별자 (URL 경로에 사용)               |
    | **타입**          | openai / anthropic / gemini       |
    | **API URL**     | Provider API 엔드포인트                |
    | **API Key**     | 인증 키                              |
    | **모델 ID**       | 이 Provider에서 허용할 모델 목록 (비어있으면 전체) |
    | **활성화**         | Provider ON/OFF                   |
  </Tab>

  <Tab title="Azure OpenAI">
    | 설정                 | 설명                                              |
    | ------------------ | ----------------------------------------------- |
    | **Provider ID**    | 고유 식별자                                          |
    | **타입**             | azure\_openai                                   |
    | **API URL**        | Azure 엔드포인트 (`https://{name}.openai.azure.com`) |
    | **API Key**        | Azure API 키                                     |
    | **API Version**    | API 버전 (예: `2024-12-01-preview`)                |
    | **Deployment Map** | 모델명 → 배포명 매핑 (선택)                               |
  </Tab>

  <Tab title="Vertex AI">
    | 설정                      | 설명                           |
    | ----------------------- | ---------------------------- |
    | **Provider ID**         | 고유 식별자                       |
    | **타입**                  | vertex\_ai                   |
    | **Project ID**          | GCP 프로젝트 ID                  |
    | **Location**            | GCP 리전 (기본: us-central1)     |
    | **Service Account Key** | GCP 서비스 계정 JSON 키            |
    | **글로벌 GCP 키 사용**        | 서버의 글로벌 GCP 키를 fallback으로 사용 |
  </Tab>
</Tabs>

***

## 개발자 사용법

개발자는 AI 코딩 도구의 BASE\_URL을 Cloosphere 코드 게이트웨이로 설정하고, Cloosphere API 키를 사용합니다.

<Frame caption="개발자 설정 가이드 — 도구별 BASE_URL·API 키 안내">
  <img src="https://mintcdn.com/cloocus/kN0YvsveHAOdEazS/images/admin/code-gateway-bottom.png?fit=max&auto=format&n=kN0YvsveHAOdEazS&q=85&s=1d4200b4afed7bb1d9506fc32f064a2f" alt="개발자 설정 가이드 — 도구별 BASE_URL" width="2880" height="1800" data-path="images/admin/code-gateway-bottom.png" />
</Frame>

### 엔드포인트 구조

```
{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`

### 인증

코드 게이트웨이는 다음 네 가지 방식으로 API 키를 전달받습니다 (우선순위 순).

| 방식                  | 헤더/파라미터                           | 사용 도구                             |
| ------------------- | --------------------------------- | --------------------------------- |
| **Bearer Token**    | `Authorization: Bearer {api_key}` | Cursor, Codex CLI, GitHub Copilot |
| **x-api-key**       | `x-api-key: {api_key}`            | Claude Code (Anthropic SDK)       |
| **x-goog-api-key**  | `x-goog-api-key: {api_key}`       | Gemini CLI                        |
| **Query Parameter** | `?key={api_key}`                  | Fallback                          |

<Tip>
  API 키는 Cloosphere **설정 › 계정 › API Keys › 새로운 비밀 키 생성**에서 발급합니다. Provider의 원본 API 키가 아닌 Cloosphere API 키를 사용하세요.
</Tip>

### 도구별 설정 예시

<Tabs>
  <Tab title="Claude Code">
    ```bash theme={null}
    # .bashrc 또는 .zshrc
    export ANTHROPIC_BASE_URL="https://cloosphere.company.com/api/v1/code-gateway/anthropic"
    export ANTHROPIC_API_KEY="sk-cloosphere-..."
    ```
  </Tab>

  <Tab title="Cursor">
    Cursor 설정에서 **Override OpenAI Base URL**을 다음으로 설정:

    ```
    https://cloosphere.company.com/api/v1/code-gateway/openai/v1
    ```

    API Key를 Cloosphere API 키로 설정합니다.
  </Tab>

  <Tab title="Codex CLI">
    ```bash theme={null}
    export OPENAI_BASE_URL="https://cloosphere.company.com/api/v1/code-gateway/openai/v1"
    export OPENAI_API_KEY="sk-cloosphere-..."
    ```
  </Tab>

  <Tab title="Gemini CLI">
    ```bash theme={null}
    export GOOGLE_GEMINI_BASE_URL="https://cloosphere.company.com/api/v1/code-gateway/gemini"
    export GEMINI_API_KEY="sk-cloosphere-..."
    ```
  </Tab>

  <Tab title="GitHub Copilot">
    GitHub Copilot CLI는 OpenAI 호환 엔드포인트를 통해 연결합니다:

    ```bash theme={null}
    export OPENAI_BASE_URL="https://cloosphere.company.com/api/v1/code-gateway/openai/v1"
    export OPENAI_API_KEY="sk-cloosphere-..."

    # Start GitHub Copilot CLI
    gh copilot
    ```
  </Tab>
</Tabs>

### Claude Code 셋업 스크립트

Claude Code 사용자를 위한 자동 셋업 스크립트를 제공합니다.

* 스크립트는 헬퍼 스크립트 설치와 `~/.claude/settings.json` 설정을 자동으로 수행합니다.

<Tabs>
  <Tab title="Linux / macOS">
    ```bash theme={null}
    # 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
    ```
  </Tab>

  <Tab title="Windows (PowerShell)">
    ```powershell theme={null}
    # 1. 환경 변수 설정
    $env:ANTHROPIC_AUTH_TOKEN = "sk-cloosphere-..."
    $env:ANTHROPIC_BASE_URL = "https://cloosphere.company.com/api/v1/code-gateway/anthropic"

    # 2. 셋업 스크립트 실행
    irm "https://cloosphere.company.com/api/v1/code-gateway/setup-script?os=powershell" | iex
    ```
  </Tab>
</Tabs>

셋업 스크립트가 수행하는 작업:

1. **헬퍼 스크립트 설치** (`~/cloosphere-helper.sh` 또는 `~/cloosphere-helper.ps1`): 리포지토리 메타데이터(Git remote URL, 작업 디렉토리)를 API 키에 자동 첨부
2. **`~/.claude/settings.json` 구성**: `ANTHROPIC_AUTH_TOKEN`, `ANTHROPIC_BASE_URL`, `apiKeyHelper` 자동 설정

<Tip>
  헬퍼 스크립트는 리포지토리 메타데이터 기반 차단 정책(`blocked_repos`, `require_repo_metadata`)이 활성화된 환경에서 필수입니다.
</Tip>

***

## 보안

**보안** 마스터 토글로 아래 보안 검사(가드레일·허용 모델·파일 패턴·리포지토리 차단)를 일괄로 켜고 끕니다.

* **전역 가드레일 설정 따름**을 켜면 별도 지정 없이 전역 가드레일 설정을 코드 게이트웨이에 그대로 적용합니다.

### 가드레일

코드 게이트웨이에 가드레일을 적용하여 코딩 도구의 입력에서 PII 감지, 콘텐츠 필터링 등을 수행합니다.

* [가드레일 관리](/ko/workspace/guardrails)에서 생성한 가드레일 ID를 지정합니다.

가드레일 위반, 파일 패턴 차단, 리포지토리 차단 등의 이벤트는 모두 **모니터링 > 가드레일 로그** 탭에서 확인할 수 있습니다.

### 허용 모델

특정 모델만 사용하도록 제한합니다.

* 전역 레벨과 Provider 레벨에서 각각 설정할 수 있습니다.

| 레벨                 | 설정 필드            | 설명                                  |
| ------------------ | ---------------- | ----------------------------------- |
| **전역 허용 모델**       | `allowed_models` | 코드 게이트웨이 전체에서 사용 가능한 모델 (전역 설정)     |
| **Provider 모델 ID** | `model_ids`      | 특정 Provider에서 허용할 모델 (Provider별 설정) |

<Note>
  `allowed_models`(전역)과 `model_ids`(Provider별) 모두에서 모델 제한이 설정된 경우, 양쪽 모두에서 허용된 모델만 사용 가능합니다. `allowed_models`는 코드 게이트웨이 전체 정책이고, `model_ids`는 개별 Provider 내에서의 추가 제한입니다.
</Note>

### 요청 제한

사용자당 분당 최대 요청 수를 제한합니다.

* 60초 슬라이딩 윈도우 기반으로 동작합니다.

<Warning>
  요청 제한은 인메모리 방식이므로 서버 재시작 시 리셋됩니다.
</Warning>

### 차단할 파일 패턴

코딩 도구가 전송하는 파일 내용에서 특정 패턴의 파일을 차단합니다.

* 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`)도 자동으로 정규화하여 매칭합니다.

<Note>
  차단된 리포지토리 접근은 **가드레일 로그**에 자동 기록됩니다.
</Note>

### 리포지토리 메타데이터 필수

`require_repo_metadata`를 활성화하면, 헬퍼 스크립트를 통한 리포지토리 메타데이터가 없는 요청을 차단합니다.

* 이를 통해 모든 코드 게이트웨이 사용자가 헬퍼 스크립트를 설정하도록 강제할 수 있습니다.

<Warning>
  이 옵션을 활성화하면 헬퍼 스크립트가 설정되지 않은 사용자의 요청이 모두 차단됩니다. 활성화 전 사용자에게 헬퍼 스크립트 설정을 안내하세요.
</Warning>

***

## 사용량 추적

코드 게이트웨이를 통한 모든 요청은 자동으로 사용량이 기록됩니다.

* 관리자는 사용 로그를 조회하여 팀별, 사용자별, 모델별 사용 현황을 확인할 수 있습니다.

| 항목           | 설명           |
| ------------ | ------------ |
| **사용자**      | 요청한 사용자      |
| **모델**       | 사용된 LLM 모델   |
| **Provider** | 사용된 Provider |
| **입력/출력 토큰** | 요청/응답 토큰 수   |
| **시간**       | 요청 시간        |

### 사용량 통계

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

### 필터

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

***

## 프록시 처리 흐름

코드 게이트웨이가 요청을 처리하는 전체 흐름입니다.

```mermaid theme={null}
flowchart TD
    A[요청 수신] --> B[인증 확인]
    B --> C{Gateway 활성화?}
    C -->|No| X[403 Forbidden]
    C -->|Yes| D{기능 권한 확인}
    D -->|No| X
    D -->|Yes| E[Provider 설정 확인]
    E --> F[요청 제한 확인]
    F --> F2[차단된 리포지토리 확인]
    F2 --> G[모델 허용 확인]
    G --> H[파일 패턴 차단 확인]
    H --> I[가드레일 적용]
    I --> J{스트리밍?}
    J -->|Yes| K[스트리밍 프록시]
    J -->|No| L[일반 프록시]
    K --> M[사용량 기록]
    L --> M
    M --> N[응답 반환]
```

***

## 트러블슈팅

<Accordion title="403 Forbidden: Code Gateway is disabled">
  관리자 설정에서 코드 게이트웨이가 비활성화 상태입니다. 관리자에게 활성화를 요청하세요.
</Accordion>

<Accordion title="403 Forbidden: Code Gateway access not permitted">
  사용자의 기능 권한에 코드 게이트웨이 접근이 허용되지 않았습니다. 관리자가 그룹 권한 설정에서 `features.code_gateway`를 활성화해야 합니다.
</Accordion>

<Accordion title="404 Not Found: Provider not found">
  요청 URL의 `provider_id`가 등록된 Provider와 일치하지 않습니다. Provider ID를 확인하세요.
</Accordion>

<Accordion title="403 Forbidden: Model not allowed">
  요청한 모델이 전역 허용 모델 또는 Provider 허용 모델 목록에 포함되지 않았습니다. 관리자에게 모델 추가를 요청하세요.
</Accordion>

<Accordion title="429 Too Many Requests: Rate limit exceeded">
  분당 요청 한도를 초과했습니다. 잠시 대기 후 재시도하세요.
</Accordion>

<Accordion title="403 Forbidden: Repository metadata is required">
  `require_repo_metadata`가 활성화되었으나 헬퍼 스크립트가 설정되지 않았습니다. Claude Code 셋업 스크립트를 실행하여 헬퍼 스크립트를 설치하세요.
</Accordion>

<Accordion title="403 Forbidden: AI coding tool usage is blocked for repository">
  요청의 리포지토리 URL 또는 작업 디렉토리가 `blocked_repos` 패턴과 일치합니다. 관리자에게 차단 해제를 요청하세요.
</Accordion>