> ## 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.
# NextChat 설정 가이드
> NextChat에서 Crazyrouter를 통해 OpenAI 호환 모델에 연결하고, 온라인 설정, 자체 배포, 모델 목록, 문제 해결 설정을 완료하는 방법
> 업데이트: 2026-06-06
NextChat(구 ChatGPT Next Web)은 빠르게 구축할 수 있고 반응 속도가 빠르며 자체 배포가 쉬운 가벼운 채팅 프론트엔드에 적합합니다. Crazyrouter와 연동할 때는 기본 OpenAI 호환 경로를 그대로 사용하면서, 서비스 주소를 Crazyrouter 루트 도메인으로 지정하는 것을 권장합니다.
## 개요
NextChat의 OpenAI 설정 항목을 통해 요청을 Crazyrouter로 보낼 수 있습니다.
* 권장 프로토콜: `OpenAI-compatible API`
* 권장 연동 방식: NextChat 기본 OpenAI 경로
* Base URL: `https://api.crazyrouter.com`
* 인증 방식: `sk-...` token
* 권장 첫 검증 모델: `gpt-5.5`
NextChat 공식 README는 `BASE_URL`을 OpenAI API request base URL로 정의하며, 예시도 루트 도메인 형식입니다. 또한 로컬 `http://127.0.0.1:4000/api/status`에서 노출되는 `server_address`도 루트 주소입니다. 따라서 Crazyrouter와 연동할 때는 첫 검증에서 `https://api.crazyrouter.com`을 우선 입력하고, 사용 중인 커스텀 버전이 명확히 더 구체적인 경로를 요구한다면 해당 버전 설명에 맞춰 조정하세요.
## 이런 분들께 적합합니다
* 가벼운 채팅 프론트엔드를 빠르게 배포하고 싶은 분
* 개인 또는 소규모 팀의 웹 채팅에 Crazyrouter를 사용하고 싶은 분
* 환경 변수로 기본 모델과 기본 상류를 통일해서 배포하고 싶은 분
* 최소한의 설정으로 OpenAI 호환 경로를 먼저 검증하고 싶은 분
## 사용 프로토콜
권장 프로토콜: `OpenAI-compatible API`
NextChat이 Crazyrouter와 연동할 때는 다음을 우선 입력하세요.
```text theme={null}
https://api.crazyrouter.com
```
다음과 같이 입력하지 마세요.
* `https://api.crazyrouter.com/v1/chat/completions`
* `https://api.crazyrouter.com/v1/models`
사용 중인 NextChat의 특정 이전 버전이 더 구체적인 API host를 수동으로 입력하도록 요구한다면 해당 버전 설명에 맞춰 조정하세요. 처음 연동할 때는 루트 도메인으로 기준선 검증을 먼저 하세요.
NextChat의 배포 형태에 따라 설정 진입점 위치가 다를 수 있습니다. 온라인으로 사용할 때는 보통 설정 페이지에서 입력하고, 자체 배포 시에는 환경 변수로 직접 전달하는 경우가 더 흔합니다. UI가 어떻게 바뀌든 첫 검증에서는 항상 최소 설정을 유지하세요: `API Key` + 루트 도메인 `BASE_URL` + 단일 모델 `gpt-5.5`.
## 사전 준비
| 항목 | 설명 |
| ----------------- | ---------------------------------------------------- |
| Crazyrouter 계정 | 먼저 [crazyrouter.com](https://crazyrouter.com)에서 가입 |
| Crazyrouter token | NextChat 전용 `sk-...` token을 별도로 생성하는 것을 권장 |
| NextChat | 온라인 버전 또는 자체 배포 버전 모두 가능하며, 현재 안정 버전 사용을 권장 |
| 사용 가능한 모델 | 당일 실측 성공한 OpenAI 호환 채팅 모델을 최소 1개 이상 허용, 예: `gpt-5.5` |
권장 첫 화이트리스트:
* `gpt-5.5`
* `claude-opus-4-8`
* `gemini-3.1-pro`
## 5분 빠른 시작
Crazyrouter 백엔드에서 새 token을 생성하고, 이름은 `nextchat`으로 작성하는 것을 권장합니다. 처음에는 `gpt-5.5`와 `claude-opus-4-8` 같은 기준선 모델만 허용하세요.
NextChat에 접속해 좌측 하단의 `설정` 아이콘 또는 `Settings` 진입점을 클릭하세요.
OpenAI 관련 설정에 다음을 입력하세요.
* `API Key`: 사용자의 `sk-...`
* `인터페이스 주소 / Base URL`: `https://api.crazyrouter.com`
`모델 / Model`에서 먼저 `gpt-5.5`를 수동으로 입력하거나 선택하세요. 현재 버전이 사용자 지정 모델 목록을 지원한다면 필요한 다른 모델도 추가로 입력하세요.
새 대화를 만들고 `Reply only OK`를 전송하세요. 정상적으로 응답을 받은 후 단계적으로 더 많은 모델을 추가하세요.
## 자체 배포 빠른 설정
Docker 환경에서 흔히 사용하는 작성 방식은 다음과 같습니다.
```yaml theme={null}
services:
nextchat:
image: yidadaa/chatgpt-next-web
ports:
- "3000:3000"
environment:
- OPENAI_API_KEY=sk-xxx
- BASE_URL=https://api.crazyrouter.com
- CUSTOM_MODELS=+gpt-5.5,+claude-opus-4-8,+gemini-3.1-pro
- HIDE_USER_API_KEY=1
```
자주 사용하는 환경 변수 설명:
| 변수 | 권장 값 | 설명 |
| ------------------- | ------------------------------------------- | --------------------------------------------------- |
| `OPENAI_API_KEY` | `sk-xxx` | 기본 Crazyrouter token |
| `BASE_URL` | `https://api.crazyrouter.com` | 공식 `BASE_URL` 사용법에 따라 루트 도메인을 먼저 입력하여 첫 검증 기준선으로 사용 |
| `CUSTOM_MODELS` | `+gpt-5.5,+claude-opus-4-8,+gemini-3.1-pro` | 프론트엔드에 선택 가능한 모델 추가 |
| `HIDE_USER_API_KEY` | `1` | 최종 사용자가 임의로 다른 Key를 입력하지 못하게 함 |
## 권장 모델 설정
| 사용 시나리오 | 권장 모델 | 이유 |
| ------------ | ----------------- | -------------------------------- |
| 기본 주 채팅 모델 | `gpt-5.5` | 당일 실측 성공했으며, NextChat 주 기준선으로 적합 |
| 고품질 장문 및 설명 | `claude-opus-4-8` | 장문 텍스트와 복잡한 설명에 더 적합 |
| Gemini 예비 등급 | `gemini-3.1-pro` | 두 번째 호환성 검증 경로를 보완하는 데 적합 |
권장 순서: 먼저 `gpt-5.5`로 검증을 완료한 후 `CUSTOM_MODELS`로 모델 목록을 확장하세요.
## Token 설정 모범 사례
| 설정 | 권장 | 설명 |
| ---------- | --------------------- | ---------------------------------------------------- |
| 전용 token | 필수 | NextChat은 LobeChat, Cursor, Codex와 token을 공유하지 않아야 함 |
| 모델 화이트리스트 | 강력 권장 | 프론트엔드에서 실제로 표시할 모델만 허용 |
| IP 제한 | 자체 배포 시 고정 출구라면 고려 가능 | 네트워크를 자주 바꾸는 개인 환경에서는 신중히 사용 |
| 할당량 상한 | 강력 권장 | 웹 채팅을 여러 명이 사용할 때 소모량이 빠르게 늘어날 수 있음 |
| 환경 격리 | 권장 | 데모 사이트, 테스트 사이트, 운영 사이트에 서로 다른 token 사용 |
| 사용자 지정 Key | 기본 비활성화 권장 | 상류와 과금을 통일하고 싶다면 `HIDE_USER_API_KEY=1` 설정 |
## 검증 체크리스트
* [ ] `API Key`가 올바르게 저장됨
* [ ] `Base URL`이 `https://api.crazyrouter.com`으로 설정됨
* [ ] 첫 번째 모델이 `gpt-5.5`로 설정됨
* [ ] 첫 대화 요청이 성공적으로 반환됨
* [ ] 자체 배포인 경우 `CUSTOM_MODELS`가 적용됨
* [ ] 스트리밍 출력이 정상 작동함
* [ ] Crazyrouter 백엔드 로그에서 해당 요청을 확인할 수 있음
* [ ] token 할당량과 모델 화이트리스트가 예상과 일치함
## 자주 발생하는 오류와 해결
| 증상 | 흔한 원인 | 해결 방법 |
| ----------------------------------- | ------------------------------------------- | --------------------------------------------------------------------------------- |
| 401 unauthorized | token이 잘못되었거나 만료되었거나, 복사 시 공백이 포함됨 | token을 새로 생성하고 교체 |
| 403 / model not allowed | 모델이 화이트리스트에 없음 | Crazyrouter token 설정에서 해당 모델을 허용 |
| 404 | 주소를 완전한 인터페이스 경로로 작성했거나, 버전에 맞지 않는 변수명을 사용함 | `https://api.crazyrouter.com`으로 다시 수정하고, 사용 중인 버전이 `BASE_URL`을 쓰는지 다른 변수명을 쓰는지 확인 |
| 자체 배포 후 프론트엔드 화면에서 관련 설정 항목이 보이지 않음 | 현재 배포 방식이 설정을 프론트엔드 설정 페이지가 아니라 환경 변수에 고정함 | 배포 설정에서 `OPENAI_API_KEY`, `BASE_URL`, `CUSTOM_MODELS`를 직접 확인 |
| 페이지에서 모델이 보이지 않음 | `CUSTOM_MODELS`를 설정하지 않았거나, 이전 설정이 캐시됨 | 먼저 `gpt-5.5`를 수동 입력해 검증한 후 새로고침하고 환경 변수를 확인 |
| 요청은 전송되지만 모델 오류가 발생함 | 기본 모델을 잘못 작성했거나, 해당 모델이 현재 사용 불가함 | `gpt-5.5`로 되돌려 기준선 검증 수행 |
| 사용자가 여전히 자신의 Key로 변경할 수 있음 | `HIDE_USER_API_KEY=1`을 활성화하지 않음 | 배포 환경에 해당 변수를 추가 |
| 비용이 빠르게 증가함 | 여러 명이 하나의 고권한 token을 공유함 | token을 분리하고, 화이트리스트를 축소하고, 할당량을 설정 |
## 성능 및 비용 권장 사항
* 기본적으로 `gpt-5.5`만 개방하세요
* 고가 모델은 기본 목록에서 제외하고 필요할 때만 추가하세요
* 공개 또는 반공개 배포라면 사용자 지정 Key 입력 항목을 최대한 숨기세요
* 데모 사이트와 운영 사이트를 분리하여 과금해서, 테스트 트래픽이 운영 할당량에 영향을 주지 않도록 하세요
* 비정상적인 소모가 발생하면 먼저 Crazyrouter 로그를 확인하여 긴 세션이나 다중 사용자 공유로 인한 것인지 확인하세요
## FAQ
### NextChat에는 어떤 주소를 입력해야 하나요?
`https://api.crazyrouter.com`을 우선 입력하세요.
### 여기서 왜 `/v1`을 직접 입력하는 것을 권장하지 않나요?
NextChat 공식 문서에서 `BASE_URL`에 제시한 예시가 루트 도메인 형식이기 때문입니다. 또한 로컬 `4000` 환경에서 반환되는 `server_address`를 함께 고려하면, 루트 도메인으로 첫 검증을 하는 것이 더 안정적입니다.
### 첫 번째로 권장하는 모델은 무엇인가요?
먼저 `gpt-5.5`를 사용하세요.
### `CUSTOM_MODELS`를 반드시 설정해야 하나요?
필수는 아닙니다. 먼저 `gpt-5.5`를 수동으로 입력해 검증한 후, 사용 가능함을 확인하고 나서 모델 목록을 추가할 수 있습니다.
### 일부 배포에서는 왜 환경 변수만 바꿀 수 있고 페이지에서는 바꿀 수 없나요?
NextChat 배포 방식마다 노출되는 설정 진입점이 다르기 때문입니다. 일부 자체 배포 인스턴스는 상류, 모델, Key를 환경 변수에 고정하고, 프론트엔드는 사용만 담당하며 편집은 담당하지 않습니다.
### 자체 배포 시 사용자 지정 Key를 숨기는 것을 권장하나요?
상류와 비용을 통일해서 제어하고 싶다면 숨기는 것을 권장합니다.
최소한의 배포 비용으로 가벼운 채팅 프론트엔드를 만들고 싶다면 NextChat이 매우 적합합니다. 팀 협업과 복잡한 기능이 더 필요하다면 LobeChat이나 Dify가 확장하기에 더 적합한 경우가 많습니다.