# API 게이트웨이

## API 게이트웨이란?

AQBot에는 구성된 제공업체를 **OpenAI 호환**, **Claude 네이티브**, **Gemini 네이티브** 엔드포인트로 노출하는 내장 로컬 API 서버가 포함되어 있습니다. 이러한 프로토콜 중 하나를 사용하는 모든 도구나 클라이언트는 AQBot을 백엔드로 사용할 수 있습니다 — 별도의 API 키나 릴레이 서비스가 필요 없습니다.

사용 사례:

- **Claude Code CLI**, **OpenAI Codex CLI**, **Gemini CLI**, **OpenCode**를 AQBot을 통해 실행.
- IDE 확장 프로그램을 단일 로컬 관리 엔드포인트에 연결.
- 키당 속도 제한으로 하나의 제공업체 키 세트를 여러 도구에서 공유.

---

## 시작하기

1. **설정 → API 게이트웨이**를 엽니다(또는 <kbd>Cmd/Ctrl</kbd>+<kbd>Shift</kbd>+<kbd>G</kbd>를 누릅니다).
2. **시작**을 클릭하여 게이트웨이 서버를 시작합니다.
3. 기본적으로 서버는 `127.0.0.1:8080`(HTTP)에서 수신합니다. **설정** 탭에서 수신 주소와 포트를 변경할 수 있습니다.

> **팁**
>
> 게이트웨이 설정에서 **자동 시작**을 활성화하면 AQBot이 시작될 때 서버가 자동으로 시작됩니다.

---

## API 키 관리

게이트웨이는 제공업체 키와는 별도로 자체 API 키로 수신 요청을 인증합니다.

1. **API 키** 탭으로 이동합니다.
2. **새 키 생성**을 클릭합니다.
3. 각 키를 식별하기 위해 선택적으로 **설명**을 추가합니다(예: *Claude Code*, *VS Code*).
4. 키를 복사합니다 — 한 번만 표시됩니다.

각 키에는 **접두사**, **생성 날짜**, **마지막 사용** 타임스탬프가 표시됩니다. 키는 언제든지 **활성화/비활성화** 또는 **삭제**할 수 있습니다.

> **주의**
>
> 게이트웨이 키를 다른 API 키처럼 취급하세요. 키를 가진 사람은 게이트웨이가 실행 중일 때 로컬 게이트웨이에 요청을 보낼 수 있습니다.

---

## SSL/TLS

게이트웨이는 HTTP 외에 HTTPS를 제공할 수 있습니다.

### 자동 생성 인증서

1. **설정** 탭을 엽니다.
2. **SSL/TLS**를 활성화하고 **생성** 모드를 선택합니다.
3. AQBot이 다음에 자가 서명 인증서와 개인 키를 만듭니다:

   ```
   ~/.aqbot/ssl/cert.pem
   ~/.aqbot/ssl/key.pem
   ```

4. **HTTPS 포트**를 설정합니다(기본값 `8443`).
5. 선택적으로 **SSL 강제**를 활성화하여 모든 HTTP 요청을 HTTPS로 리디렉션합니다.

### 사용자 지정 인증서

**업로드** 모드를 선택하고 자체 인증서와 개인 키 파일의 경로를 제공합니다.

> **참고**
>
> 개인 키는 Unix 시스템에서 파일 모드 `0600`으로 저장되어 다른 사용자가 읽을 수 없도록 합니다.

---

## 사용량 분석

**메트릭** 탭에는 게이트웨이 활동을 모니터링하는 대시보드가 제공됩니다:

| 보기 | 설명 |
|------|------|
| **API 키별** | 각 게이트웨이 키별 요청 볼륨 및 토큰 사용량 |
| **제공업체별** | 각 업스트림 AI 제공업체로 라우팅된 요청 및 토큰 |
| **일별** | 시간 경과에 따른 일별 사용 트렌드 |

이러한 대시보드를 사용하여 비용을 추적하고 이상을 발견하고 제공업체 간에 부하를 분산합니다.

---

## 요청 로그

**개요** 탭에는 다음 세부 정보가 포함된 최근 요청 로그가 표시됩니다:

- **타임스탬프**, **HTTP 메서드**, **경로**
- **상태 코드** 및 **응답 시간**
- 사용된 **제공업체** 및 **모델**
- **토큰 수** (프롬프트 + 완성)

임의의 로그 항목을 클릭하여 전체 요청과 응답을 검사합니다. **로그 지우기** 버튼으로 로그 기록을 재설정합니다.

---

## 구성 템플릿

AQBot에는 인기 있는 CLI 도구를 위한 기성 구성 스니펫이 제공됩니다. **템플릿** 탭으로 이동하여 도구를 선택하고 **복사**를 클릭하여 필요한 구성을 가져옵니다.

### Claude Code CLI

```bash
claude config set --global apiUrl http://127.0.0.1:8080
claude config set --global apiKey aqbot-xxxx
```

### OpenAI Codex CLI

```bash
export OPENAI_BASE_URL=http://127.0.0.1:8080/v1
export OPENAI_API_KEY=aqbot-xxxx
codex
```

### OpenCode

OpenCode 구성에 추가합니다:

```json
{
  "provider": "openai",
  "baseURL": "http://127.0.0.1:8080/v1",
  "apiKey": "aqbot-xxxx"
}
```

### Gemini CLI

```bash
export GEMINI_API_BASE=http://127.0.0.1:8080
export GEMINI_API_KEY=aqbot-xxxx
gemini
```

### 사용자 지정 클라이언트

OpenAI 호환 Base URL을 허용하는 모든 도구는 게이트웨이에 연결할 수 있습니다:

```
Base URL:  http://127.0.0.1:8080/v1
API Key:   aqbot-xxxx
```

`aqbot-xxxx`를 **API 키** 탭에서 생성한 키로 교체합니다. SSL이 활성화된 경우 `https://`와 포트 `8443`(또는 구성된 HTTPS 포트)을 사용합니다.

---

## 외부 도구 연결

다음은 OpenAI 호환 클라이언트를 연결하기 위한 일반적인 패턴입니다:

1. AQBot에서 **게이트웨이 API 키를 생성**합니다.
2. 도구의 구성에서 **Base URL**을 `http://127.0.0.1:8080/v1`(또는 HTTPS 등가)로 설정합니다.
3. **API 키**를 생성한 게이트웨이 키로 설정합니다.
4. AQBot 제공업체 중 하나에 구성한 **모델을 선택**합니다.
5. 도구를 사용하기 시작합니다 — 모든 요청은 AQBot을 통해 업스트림 제공업체로 라우팅됩니다.

> **팁**
>
> 도구가 특정 API 형식(예: Claude 또는 Gemini 네이티브)을 필요로 하는 경우 AQBot은 요청 형식을 자동으로 감지하여 올바른 제공업체로 라우팅합니다. 형식별로 별도의 엔드포인트를 구성할 필요가 없습니다.

---

## 다음 단계

- [빠른 시작](./getting-started) — 빠른 시작 가이드로 돌아가기
- [제공업체 설정](./providers) — 게이트웨이가 라우팅하는 업스트림 제공업체 추가
- [MCP 서버](./mcp) — AI 도구 호출을 위한 외부 도구 연결