> ## 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.

# ChatBox 설정 가이드

> ChatBox 데스크톱 애플리케이션에서 OpenAI 호환 방식으로 Crazyrouter에 연동하고, 모델, 지식 베이스, 문제 해결 및 첫 검증에 대한 권장 사항을 제공합니다

> 업데이트: 2026-06-06

ChatBox는 Windows, macOS, Linux를 지원하고 Web 버전도 있는 일반적인 크로스 플랫폼 AI 클라이언트입니다. Crazyrouter를 연동할 때는 특정 제조사 사전 설정을 찾기보다 ChatBox의 `OpenAI API Compatible` 또는 `OpenAI API` 방식으로 설정하는 것을 권장합니다.

이 방식의 장점은 다음과 같습니다.

* 설정이 간단하여 일반 사용자가 빠르게 연동하기 적합
* Crazyrouter에서 이미 허용된 모델로 바로 전환 가능
* 데스크톱 대화, 지식 베이스 질의응답, 파일 보조 독해 등의 사용 시나리오에 적합

## 먼저 결론부터

다음 설정 조합을 우선 사용하는 것을 권장합니다.

* Provider / API Mode: `OpenAI API Compatible` 또는 `OpenAI API`
* API Host: `https://api.crazyrouter.com`
* API Path: 기본값 유지 또는 비워둠
* API Key: `sk-xxx`
* 첫 검증 모델: `gpt-5.5`

<Note>
  ChatBox 공식 문서에 따르면, `API Path`는 일반적으로 수동으로 입력할 필요가 없으며 기본값이 바로 OpenAI 호환 채팅 경로입니다. 따라서 Crazyrouter 문서에서는 `API Host`를 루트 도메인인 `https://api.crazyrouter.com`으로 작성하고, 먼저 `/v1/chat/completions`를 수동으로 추가하지 않는 것을 권장합니다.
</Note>

## 이런 분께 추천합니다

* 데스크톱 환경에서 Crazyrouter를 빠르게 사용하고 싶은 사용자
* 다중 모델로 일상 대화, 번역, 요약, 작문 보조를 하고 싶은 분
* 로컬 지식 베이스나 파일 질의응답 기능을 Crazyrouter와 결합하고 싶은 분
* 코드를 작성하지 않고 GUI에서만 설정을 완료하고 싶은 분

## 사전 준비 사항

| 항목             | 설명                                                 |
| -------------- | -------------------------------------------------- |
| Crazyrouter 계정 | 먼저 [crazyrouter.com](https://crazyrouter.com)에서 가입 |
| Crazyrouter 토큰 | ChatBox 전용 토큰을 별도로 생성하는 것을 권장                      |
| ChatBox 클라이언트  | 데스크톱 버전 설치를 권장, 지식 베이스 등의 기능이 더 완전함                |
| 사용 가능한 모델      | 최소 1개의 채팅 모델을 먼저 허용                                |

첫 라운드에는 다음만 허용하는 것을 권장합니다.

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

## ChatBox 설치

### Windows

1. [ChatBox 공식 사이트](https://chatboxai.app/) 열기
2. Windows 설치 패키지 다운로드
3. 더블클릭하여 설치
4. 완료 후 ChatBox 실행

### macOS

1. [ChatBox 공식 사이트](https://chatboxai.app/) 열기
2. macOS 설치 패키지 다운로드
3. `Applications`로 드래그
4. 처음 열 때 시스템 보안 경고가 나타나면 시스템 안내에 따라 허용을 완료

### Linux

1. [ChatBox 공식 사이트](https://chatboxai.app/) 열기
2. 사용 중인 배포판에 맞는 설치 패키지 또는 데스크톱 버전 다운로드
3. 설치 후 ChatBox 실행

<Tip>
  Crazyrouter가 ChatBox에서 정상 작동하는지만 먼저 검증하려는 경우, 데스크톱 클라이언트를 우선 사용하고 처음부터 다중 기기 동기화, 지식 베이스, 복잡한 모델 목록을 동시에 다루지 마세요.
</Tip>

## 권장 설정 방식

ChatBox 버전마다 인터페이스 명칭이 약간 다를 수 있으며, 흔히 볼 수 있는 진입점은 다음과 같습니다.

* `Settings`
* `Model Provider`
* `AI Provider`
* `Add`

현재 버전에 이미 `OpenAI API` 제공자가 내장되어 있다면 바로 선택하면 되고, 없다면 `OpenAI API Compatible` 제공자를 새로 추가하세요.

## 설정 단계

<Steps>
  <Step title="1단계: Crazyrouter에서 ChatBox 전용 토큰 생성">
    처음에는 1\~2개의 모델만 허용하는 것을 권장합니다. 예:

    * `gpt-5.5`
    * `claude-opus-4-8`

    이렇게 하면 문제를 더 쉽게 파악할 수 있고, 모델이 너무 많아 문제 해결 범위가 과도하게 넓어지는 것을 방지할 수 있습니다.
  </Step>

  <Step title="2단계: ChatBox 설정 열기">
    ChatBox를 실행한 후, 왼쪽 하단의 설정 진입점을 클릭하고 다음으로 이동합니다.

    * `Model Provider`
    * 또는 `AI Provider`
  </Step>

  <Step title="3단계: OpenAI 호환 제공자 선택 또는 추가">
    두 가지 경우를 권장합니다.

    * 이미 `OpenAI API`가 있다면 바로 선택
    * 없다면 `Add`를 클릭하여 `OpenAI API Compatible` 제공자를 새로 추가
  </Step>

  <Step title="4단계: Crazyrouter 연결 정보 입력">
    다음과 같이 입력하는 것을 권장합니다.

    * `API Host`: `https://api.crazyrouter.com`
    * `API Path`: 기본값 유지 또는 비워둠
    * `API Key`: `sk-xxx`

    화면에서 제공자 이름을 요구하는 경우 `Crazyrouter`로 작성할 수 있습니다.
  </Step>

  <Step title="5단계: 첫 모델 추가">
    처음에는 모델 하나만 추가하는 것을 권장합니다.

    * `gpt-5.5`

    최소 링크 검증이 통과된 후, 점차 다음을 추가하세요.

    * `claude-opus-4-8`
    * `gemini-3.1-pro`
  </Step>

  <Step title="6단계: Check 또는 Save로 먼저 연결 테스트">
    사용 중인 ChatBox 버전에 `Check` 버튼이 있다면 먼저 `Check`를 클릭하세요.

    `Save`만 있다면 먼저 저장한 후, 메인 화면으로 돌아가 새 대화를 만들어 테스트하세요.
  </Step>

  <Step title="7단계: 메인 화면에서 첫 최소 검증 수행">
    새 채팅을 만들고, 현재 모델이 `gpt-5.5`인지 확인한 후 다음을 입력하세요.

    ```text theme={null}
    Reply only OK
    ```

    안정적으로 `OK` 또는 그와 유사한 결과가 반환되면, ChatBox에서 Crazyrouter로 이어지는 주 경로가 이미 연결된 것입니다.
  </Step>
</Steps>

## 권장 검증 순서

다음 순서로 진행하는 것을 권장하며, 처음부터 많은 모델과 기능을 한 번에 켜지 마세요.

1. 먼저 토큰 1개만 설정
2. 먼저 모델 1개 `gpt-5.5`만 설정
3. 먼저 순수 텍스트 채팅만 검증
4. 그다음 두 번째 모델 추가
5. 마지막으로 지식 베이스, 파일 질의응답, 복잡한 대화 파라미터를 활성화

## 권장 모델

| 시나리오         | 권장 모델             | 이유                                            |
| ------------ | ----------------- | --------------------------------------------- |
| 첫 연결 검증      | `gpt-5.5`         | 당일 실측으로 성공이 확인되어 OpenAI 호환 기준선 검증에 가장 적합      |
| 고품질 작문 및 설명  | `claude-opus-4-8` | 복잡한 설명, 윤문, 요약에 더 적합                          |
| Gemini 대체 등급 | `gemini-3.1-pro`  | 동일 클라이언트에서 비 OpenAI 계열 모델을 하나 추가해 교차 검증하기에 적합 |

## ChatBox의 일반적인 기능을 Crazyrouter와 어떻게 조합할까

### 일반 채팅

가장 간단하며 설정이 올바른지 검증하는 데 우선 사용합니다.

### 지식 베이스 / 파일 질의응답

일반 채팅이 이미 정상 작동한 후에 활성화하는 것을 권장합니다. 첫 테스트 시:

* 파일은 최대한 작게
* 내용은 최대한 명확하게
* 먼저 단일 파일 질의응답을 검증

API 설정이 올바른지 확인하지 않은 상태에서 대량의 파일로 복잡한 지식 베이스 테스트를 바로 진행하지 마세요.

### 다중 모델 전환

ChatBox에서 서로 다른 작업 분업을 하기에 적합합니다. 예:

* 기본 기준 채팅: `gpt-5.5`
* 중요 요약 및 작문: `claude-opus-4-8`
* 첫 라운드 표준 검증: `gpt-5.5`

## 파라미터 권장 사항

ChatBox 버전이 일반적인 샘플링 파라미터를 지원한다면, 처음에는 보수적으로 유지하는 것을 권장합니다.

| 파라미터             | 권장값              | 설명                             |
| ---------------- | ---------------- | ------------------------------ |
| Temperature      | `0.2`에서 `0.7`    | 첫 검증 시 너무 높게 설정하지 마세요          |
| Max Tokens       | 기본값 또는 적당한 수준 유지 | 출력이 너무 길어져 문제 해결에 영향을 주지 않도록 함 |
| Context Messages | 기본값 유지           | 먼저 기본 채팅만 검증하면 충분              |

## 토큰 모범 사례

| 설정        | 권장    | 설명                                      |
| --------- | ----- | --------------------------------------- |
| 전용 토큰     | 필수    | IDE, 자동화 프로세스와 공유하지 마세요                 |
| 모델 화이트리스트 | 강력 권장 | 먼저 1\~2개 모델만 개방                         |
| 크레딧 상한    | 강력 권장 | 지식 베이스 일괄 질의응답으로 인한 소비 증폭 방지            |
| 환경별 토큰 분리 | 권장    | 데스크톱 개인 사용과 팀 공유를 분리                    |
| 유출 대응     | 즉시 교체 | 스크린샷, 화면 녹화, 화면 공유로 노출되면 즉시 key를 교체해야 함 |

## 검증 체크리스트

* [ ] ChatBox를 설치하고 정상적으로 실행할 수 있음
* [ ] ChatBox 전용 Crazyrouter 토큰을 생성함
* [ ] `OpenAI API` 또는 `OpenAI API Compatible`을 선택함
* [ ] `API Host`를 `https://api.crazyrouter.com`으로 입력함
* [ ] `API Path`를 기본값으로 유지하거나 비워둠
* [ ] `sk-xxx`를 성공적으로 입력함
* [ ] 먼저 `gpt-5.5`만 추가함
* [ ] `Check` 또는 최소 대화로 검증을 완료함
* [ ] Crazyrouter 백엔드 로그에서 해당 요청을 확인할 수 있음

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

| 현상                      | 흔한 원인                              | 해결 방법                                                    |
| ----------------------- | ---------------------------------- | -------------------------------------------------------- |
| 401 unauthorized        | 토큰 오류, 불완전한 복사, 또는 만료됨             | 토큰을 다시 생성하고 다시 붙여넣으세요                                    |
| 404                     | Host 또는 Path 입력 오류                 | Host를 `https://api.crazyrouter.com`으로 되돌리고, Path는 기본값 유지 |
| 403 / model not allowed | 토큰이 현재 모델을 허용하지 않음                 | Crazyrouter 토큰 설정에서 해당 모델을 허용하세요                         |
| `model not found`       | 모델 이름 철자 오류                        | 먼저 `gpt-5.5`로 되돌려 최소 검증 수행                               |
| 저장은 성공했지만 채팅이 실패함       | Provider 선택 오류, 또는 모델이 실제로 추가되지 않음 | provider 유형과 모델 목록을 다시 확인하세요                             |
| 지식 베이스 질의응답이 느리거나 실패함   | 파일이 너무 크거나 한 번에 너무 복잡한 작업          | 먼저 작은 파일과 순수 텍스트 질의응답으로 되돌리세요                            |
| `/v1`을 입력해야 할지 확실하지 않음  | 현재 버전은 보통 전체 경로를 수동으로 입력할 필요가 없음   | 먼저 루트 도메인 Host를 사용하고, Path는 비워두거나 기본값 유지                 |

## FAQ

### ChatBox에서 어떤 Provider를 선택해야 하나요?

`OpenAI API` 또는 `OpenAI API Compatible`을 우선 선택하세요.

### API Host에는 무엇을 입력해야 하나요?

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

### `/v1/chat/completions`를 수동으로 입력해야 하나요?

일반적으로 필요하지 않습니다. ChatBox 공식 문서에 따르면 `API Path`는 보통 기본값이 있으므로 먼저 기본값을 유지하거나 비워두면 됩니다.

### 첫 모델은 무엇을 입력하는 것이 좋나요?

먼저 `gpt-5.5`를 입력하세요.

### 언제 더 많은 모델과 지식 베이스를 추가해야 하나요?

최소 채팅 링크 검증이 통과된 후, 점차 늘려나가세요.

<Note>
  "먼저 ChatBox를 정상 작동시키는 것"이 목표라면, 가장 좋은 방법은 한 번에 많은 모델과 기능을 설정하는 것이 아니라 먼저 `gpt-5.5`로 최소 채팅 링크 검증을 성공시키는 것입니다.
</Note>