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

# LobeChat 설정 가이드

> LobeChat에서 Crazyrouter를 통해 OpenAI 호환 모델을 연동하고, 채팅, 자체 배포, 모델 관리, 트러블슈팅 설정을 완료하는 방법

> 업데이트: 2026-06-06

LobeChat은 팀 채팅 진입점, 개인 다중 모델 워크스페이스, 자체 배포 AI 대화 프론트엔드로 적합합니다. Crazyrouter와 연동할 때 가장 안정적인 방법은 LobeChat의 `OpenAI` 경로를 사용하고, 프록시 주소를 Crazyrouter의 OpenAI 호환 base URL로 지정하는 것입니다.

## 개요

LobeChat의 OpenAI 설정 항목을 통해 대화 요청을 Crazyrouter로 전달할 수 있습니다.

* 권장 프로토콜: `OpenAI-compatible API`
* 권장 연동 방식: LobeChat `OpenAI` provider
* Base URL: `https://api.crazyrouter.com/v1`
* 인증 방식: `sk-...` 토큰
* 최초 검증 권장 모델: `gpt-5.5`

자체 배포한 LobeChat이라면, 환경 변수를 통해 기본 OpenAI 경로를 Crazyrouter로 미리 설정해둘 수도 있습니다.

## 이런 분들께 적합합니다

* 안정적인 채팅 프론트엔드를 자체 배포하려는 분
* Crazyrouter를 개인 또는 팀 채팅 워크스페이스에서 사용하려는 분
* 여러 모델을 통합 관리하고 대화 기록을 보존하려는 분
* 내부 구성원에게 기본으로 고정된 모델과 기본 설정을 배포하려는 분

## 사용 프로토콜

권장 프로토콜: `OpenAI-compatible API`

LobeChat에서 Crazyrouter와 연동할 때는 OpenAI 호환 base URL을 사용해야 합니다.

```text theme={null}
https://api.crazyrouter.com/v1
```

다음과 같이 입력하지 마세요.

* `https://api.crazyrouter.com`
* `https://api.crazyrouter.com/v1/chat/completions`

<Note>
  LobeChat 문서에서 `OPENAI_PROXY_URL`은 "OpenAI API 요청 주소"로 설명되며, 일반적인 기본값과 예시도 `/v1` 형식입니다. 또한 로컬 `http://127.0.0.1:4000/api/status`에서 제공하는 공식 예시 링크도 `{address}/v1` 형태입니다. 따라서 Crazyrouter와 연동할 때는 `https://api.crazyrouter.com/v1`을 우선 입력하세요. 만약 자체 리버스 프록시에서 이미 `/v1`을 한 번 더 붙였다면, 별도로 조정하여 중복 접미사가 되지 않도록 하세요.
</Note>

## 사전 조건

| 항목             | 설명                                                                  |
| -------------- | ------------------------------------------------------------------- |
| Crazyrouter 계정 | 먼저 [crazyrouter.com](https://crazyrouter.com)에서 가입하세요               |
| Crazyrouter 토큰 | LobeChat 전용으로 `sk-...` 토큰을 별도로 생성하는 것을 권장합니다                        |
| LobeChat       | 온라인 버전과 자체 배포 버전 모두 가능하며, 현재 안정 버전 사용을 권장합니다                        |
| 사용 가능한 모델      | 당일 테스트를 통해 성공이 확인된 OpenAI 호환 채팅 모델을 최소 하나 이상 허용해야 합니다. 예: `gpt-5.5` |

권장 초기 화이트리스트:

* `gpt-5.5`
* `claude-opus-4-8`
* `gemini-3.1-pro`

<Tip>
  Cursor, Codex, Claude Code에도 Crazyrouter를 연동할 예정이라면, LobeChat은 별도의 토큰을 사용하는 것이 좋습니다. 이렇게 하면 채팅 측 소비를 더 쉽게 집계할 수 있습니다.
</Tip>

## 5분 빠른 시작

<Steps>
  <Step title="LobeChat 전용 토큰 생성">
    Crazyrouter 백엔드에서 `lobechat`이라는 이름의 토큰을 생성하고, 처음에는 `gpt-5.5`, `claude-opus-4-8` 같이 당일 테스트에서 성공이 확인된 모델만 허용하세요.
  </Step>

  <Step title="언어 모델 설정 열기">
    LobeChat에 접속하여 왼쪽 하단 아바타나 설정 진입점을 클릭하고 `설정` → `언어 모델`을 엽니다.
  </Step>

  <Step title="OpenAI 경로 설정">
    `OpenAI` 관련 설정에 다음을 입력합니다.

    * `API Key`: 사용할 `sk-...`
    * `API 프록시 주소 / API Proxy URL`: `https://api.crazyrouter.com/v1`

    동시에 `커스텀 API 프록시 주소 사용` 또는 이와 동등한 옵션을 활성화하세요.
  </Step>

  <Step title="기준 모델 선택">
    저장 후 먼저 `gpt-5.5`를 기본 모델로 선택하세요. 처음부터 여러 모델을 한꺼번에 추가하지 마세요.
  </Step>

  <Step title="최초 검증 진행">
    새 대화를 만들고 `Reply only OK`를 전송하세요. 정상적으로 응답이 오고 Crazyrouter 백엔드에서 로그가 확인되면 연동이 성공한 것입니다.
  </Step>
</Steps>

## 자체 배포 빠른 설정

Docker로 LobeChat을 자체 배포하는 경우, 기본 OpenAI 설정을 환경 변수에 먼저 작성해둘 수 있습니다.

```yaml theme={null}
services:
  lobechat:
    image: lobehub/lobe-chat
    ports:
      - "3210:3210"
    environment:
      - OPENAI_API_KEY=sk-xxx
      - OPENAI_PROXY_URL=https://api.crazyrouter.com/v1
      - OPENAI_MODEL_LIST=gpt-5.5,claude-opus-4-8,gemini-3.1-pro
```

프론트엔드 사용자가 Key를 임의로 변경하지 못하게 하려면, 현재 버전에서 지원하는 숨김 또는 호스팅 설정 항목과 결합하여 기본 Key를 서버 측 환경 변수에 고정할 수 있습니다.

## 권장 모델 설정

| 사용 시나리오      | 권장 모델             | 이유                                    |
| ------------ | ----------------- | ------------------------------------- |
| 기본 주 채팅 모델   | `gpt-5.5`         | 당일 테스트에서 성공이 확인되어 LobeChat 주 기준선으로 적합 |
| 고품질 작문 / 코드  | `claude-opus-4-8` | 긴 텍스트, 작문, 코드 보조 경험이 더 우수             |
| Gemini 대체 옵션 | `gemini-3.1-pro`  | 두 번째 호환성 검증 경로 보완에 적합                 |

권장 순서: 먼저 `gpt-5.5`로 정상 동작을 확인한 후, `claude-opus-4-8`과 `gemini-3.1-pro`로 확장하세요.

## 토큰 설정 모범 사례

| 설정        | 권장 사항                       | 설명                                         |
| --------- | --------------------------- | ------------------------------------------ |
| 전용 토큰     | 필수                          | LobeChat은 IDE / CLI 도구와 토큰을 공유하지 않아야 합니다   |
| 모델 화이트리스트 | 강력 권장                       | 채팅 측에서 실제로 사용할 모델만 허용하세요                   |
| IP 제한     | 자체 배포에서 고정 출구가 있는 경우 활성화 권장 | 공용 네트워크 접속이나 가정용 네트워크가 자주 바뀌는 경우 신중히 사용하세요 |
| 할당량 상한    | 강력 권장                       | 팀 채팅 프론트엔드는 여러 사람이 동일한 토큰을 공유하기 쉽습니다       |
| 환경 분리     | 권장                          | 테스트 환경과 프로덕션 환경에 다른 토큰을 사용하세요              |
| 기본 모델 제어  | 권장                          | 먼저 고가 모델을 기본 목록에서 제외하고, 필요할 때 열어주세요        |

## 검증 체크리스트

* [ ] `API Key`가 올바르게 저장되었습니다
* [ ] `API 프록시 주소 / API Proxy URL`을 `https://api.crazyrouter.com/v1`로 설정했습니다
* [ ] 커스텀 프록시 주소 스위치가 활성화되었습니다
* [ ] 첫 번째 모델이 성공적으로 선택되었습니다
* [ ] 첫 번째 대화 요청이 성공적으로 응답을 받았습니다
* [ ] 스트리밍 출력이 정상 동작합니다
* [ ] Crazyrouter 백엔드 로그에서 해당 요청을 확인할 수 있습니다
* [ ] 토큰의 할당량과 모델 화이트리스트가 예상과 일치합니다

## 자주 발생하는 오류와 해결 방법

| 증상                               | 일반적인 원인                                            | 해결 방법                                                             |
| -------------------------------- | -------------------------------------------------- | ----------------------------------------------------------------- |
| 저장할 수 없거나 검증에 실패함                | API Key 오류 또는 프록시 주소 오입력                           | `sk-...`와 `https://api.crazyrouter.com/v1`을 다시 확인하세요              |
| 401 unauthorized                 | 토큰이 만료, 실효, 또는 실수로 삭제됨                             | 토큰을 재생성하고 교체하세요                                                   |
| 403 / model not allowed          | 현재 모델이 토큰 화이트리스트에 추가되지 않음                          | Crazyrouter 백엔드에서 해당 모델을 허용하세요                                    |
| 404                              | 프록시 주소를 루트 도메인이나 구체적인 엔드포인트 경로로 입력함                | `https://api.crazyrouter.com/v1`로 변경하세요                           |
| 설정이 올바른 것 같은데 여전히 404 발생         | 자체 게이트웨이, 리버스 프록시, 배포 계층에서 이미 자동으로 `/v1`을 한 번 더 붙임 | 중복 접미사가 발생했는지 확인하세요. 업스트림 체인이 이미 자동으로 `/v1`을 붙였다면 다시 중복해서 붙이지 마세요 |
| 모델을 선택할 수 있는 것처럼 보이지만 실제로는 오류 발생 | LobeChat 프론트엔드가 이전 모델을 캐시했거나 기본 모델이 존재하지 않음        | `gpt-5.5`로 다시 전환하고 페이지를 새로고침한 후 다시 선택하세요                          |
| 대화는 전송되지만 스트리밍이 비정상              | 클라이언트 버전 또는 모델 호환성 문제                              | 먼저 `gpt-5.5`로 기준선을 검증하고 LobeChat을 업그레이드하세요                        |
| 팀에서 여러 명이 동시에 사용할 때 소비가 매우 빠름    | 여러 사용자가 동일한 토큰을 공유하며 할당량 상한이 없음                    | 팀 프론트엔드에 별도의 할당량을 설정하고, 필요하면 토큰을 여러 개로 분리하세요                      |
| 자체 배포 후에도 사용자가 다른 업스트림으로 변경 가능   | 기본값만 설정하고 프론트엔드의 커스텀 진입점을 제한하지 않음                  | 배포 계층에서 호스팅 설정을 추가하거나 사용자 커스텀 기능을 비활성화하세요                         |

## 성능 및 비용 권장 사항

* 첫 단계에서는 `gpt-5.5`만 유지하세요
* 팀 채팅 기본 모델은 저비용 옵션을 우선 선택하고, 고가 모델은 고급 사용자나 특정 시나리오에 남겨두세요
* 지식 베이스, 플러그인, 긴 컨텍스트 대화를 사용하는 경우 LobeChat 할당량을 별도로 설정하는 것이 더욱 중요합니다
* 자체 배포 환경에서는 프로덕션 토큰과 테스트 토큰을 분리하여 내부 실험이 정식 할당량에 영향을 주지 않도록 하세요
* 비정상적으로 높은 소비가 발생하면, 먼저 Crazyrouter 로그를 확인하여 여러 사용자의 긴 세션이 원인인지 파악하세요

## FAQ

### LobeChat은 어떤 Base URL을 입력해야 하나요?

`https://api.crazyrouter.com/v1`을 입력하세요.

### 여기서 루트 도메인만 입력할 수 없는 이유는 무엇인가요?

LobeChat의 OpenAI 프록시 설정은 루트 도메인이 아니라 OpenAI 호환 base URL을 직접 입력하는 것에 더 적합하기 때문입니다.

### 자체 리버스 프록시가 이미 자동으로 `/v1`을 붙였다면 어떻게 해야 하나요?

그렇다면 LobeChat에 최종적으로 노출하는 주소에 `/v1`을 다시 붙이지 마세요. 먼저 프록시 체인을 확인하여 접미사가 중복되지 않도록 하세요.

### 첫 번째 권장 모델은 무엇인가요?

먼저 `gpt-5.5`를 사용하세요.

### LobeChat은 여러 모델을 동시에 연동할 수 있나요?

가능합니다. 다만 먼저 모델 하나로 검증한 후 점진적으로 확장하는 것을 권장합니다.

### 자체 배포 시 토큰을 환경 변수에 고정해야 하나요?

업스트림과 비용을 통합 관리하고 싶다면 이렇게 하는 것을 권장합니다. 반대로 사용자마다 자신의 Key를 사용하게 하려면 프론트엔드 커스텀 진입점을 열어주세요.

<Note>
  안정적인 채팅 프론트엔드와 팀 공유 워크스페이스가 목표라면 LobeChat은 매우 적합한 선택입니다. 코드 에이전트와 자동 실행이 목표라면 우선순위는 여전히 Cursor, Claude Code, Codex, Cline 같은 도구에 두어야 합니다.
</Note>