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

# Coze 설정 가이드

> Coze(扣子)에서 HTTP/API 플러그인 또는 워크플로 노드를 통해 Crazyrouter를 호출하며, 공개적으로 사용 가능한 방식과 엔터프라이즈 버전 커스텀 모델 방식을 명확히 구분합니다

> 업데이트: 2026-06-06

Coze(扣子)는 ByteDance가 출시한 에이전트 및 워크플로 플랫폼으로, Bot, 워크플로 오케스트레이션, 플러그인 호출, 멀티채널 배포에 적합합니다. Crazyrouter를 연동할 때 가장 안정적이고 공개 문서에 적합한 경로는 "모든 버전이 커스텀 모델을 지원한다"고 가정하는 것이 아니라, HTTP / API 플러그인 또는 워크플로 HTTP 요청 노드를 우선적으로 사용하는 것입니다.

## 결론부터 말하면

대다수의 Crazyrouter 사용자에게 Coze는 현재 다음 두 가지 방법을 더 권장합니다.

* 방법 1: `API 기반 생성`을 통한 플러그인으로 Crazyrouter 호출
* 방법 2: 워크플로에서 HTTP 요청 노드를 통해 Crazyrouter 호출

"Coze 모델 관리에서 Crazyrouter 커스텀 모델을 직접 연동하는 방법"을 공개 문서의 메인 가이드로 작성하는 것은 권장하지 않습니다. 이유는 다음과 같습니다.

* 버전, 지역, 요금제에 따라 Coze의 기능 차이가 크기 때문
* Coze의 공식 요금제 문서에서 `커스텀 모델`을 엔터프라이즈 플래그십 버전 기능 중 하나로 명시하고 있기 때문
* 따라서 공개 문서에서는 HTTP / API 플러그인 경로를 메인 가이드로 삼는 것이 더 안정적임

<Warning>
  이 페이지에서 가장 중요한 정확성 원칙은, Coze의 공개 메인 가이드를 "HTTP / API 플러그인으로 Crazyrouter를 호출"하는 것으로 작성하고, 모든 사용자가 모델 관리에서 커스텀 업스트림을 바로 연결할 수 있다고 기본값으로 가정하지 않는 것입니다.
</Warning>

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

* Coze Bot 또는 워크플로에서 Crazyrouter를 연동하려는 사용자
* Crazyrouter를 외부 모델 호출 노드로 사용하려는 분
* 처음부터 엔터프라이즈 버전 커스텀 모델 기능으로 뛰어들지 않고, 최소 검증 가능한 체인부터 시작하려는 분
* Bot이 플러그인이나 워크플로를 통해 멀티모델 기능에 접근하도록 하려는 분

## 권장 연동 방법

### 공개 메인 가이드: HTTP / API 플러그인 경로

권장 파라미터:

* 요청 방법: `POST`
* URL: `https://api.crazyrouter.com/v1/chat/completions`
* Header:
  * `Authorization: Bearer sk-xxx`
  * `Content-Type: application/json`
* 첫 번째 검증 모델: `gpt-5.5`

### 이 경로를 먼저 권장하는 이유

다음과 같은 이유 때문입니다.

* Coze 요금제 차이에 가장 덜 의존적임
* "Coze 설정 문제"인지 "Crazyrouter 토큰 / 모델 문제"인지 가장 쉽게 파악 가능
* 공개 문서에서 안정적으로 설명하기에 가장 적합함

## 시스템 요구 사항과 사전 조건

| 항목             | 설명                                                 |
| -------------- | -------------------------------------------------- |
| Crazyrouter 계정 | 먼저 [crazyrouter.com](https://crazyrouter.com)에서 가입 |
| Crazyrouter 토큰 | Coze 전용 토큰을 별도로 생성하는 것을 권장                         |
| Coze 계정        | Bot / 워크플로 / 플러그인을 생성할 수 있어야 함                     |
| 배포 권한          | 최소한 Bot 또는 워크플로를 디버깅할 수 있어야 함                      |
| 사용 가능 모델       | 최소 채팅 모델 1개 허용                                     |

권장 초기 화이트리스트:

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

## 방법 1: API 플러그인을 통해 Crazyrouter 연동

<Steps>
  <Step title="1단계: Crazyrouter에서 Coze 전용 토큰 생성">
    처음에는 다음만 허용하는 것을 권장합니다.

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

    처음부터 너무 많은 모델을 개방하지 마세요. 문제 해결이 더 쉬워집니다.
  </Step>

  <Step title="2단계: Coze에서 API 플러그인 생성">
    Coze 워크스페이스에 진입한 후, 현재 버전의 인터페이스에 따라 다음으로 이동합니다.

    * `플러그인`
    * `플러그인 생성`
    * `API 기반 생성` 또는 유사한 명칭의 항목 선택

    <Note>
      Coze의 인터페이스 명칭은 버전, 지역, 제품 라인에 따라 다소 다를 수 있지만, 핵심 개념은 모두 동일합니다. 외부에 노출되는 HTTP API 플러그인을 생성하는 것입니다.
    </Note>
  </Step>

  <Step title="3단계: 요청 방법과 URL 설정">
    다음을 입력합니다.

    * `Method`: `POST`
    * `URL`: `https://api.crazyrouter.com/v1/chat/completions`
  </Step>

  <Step title="4단계: 요청 헤더 설정">
    다음을 입력합니다.

    ```text theme={null}
    Authorization: Bearer sk-xxx
    Content-Type: application/json
    ```
  </Step>

  <Step title="5단계: 최소 요청 본문 설정">
    처음에는 최소 요청 본문을 사용하는 것을 권장합니다.

    ```json theme={null}
    {
      "model": "gpt-5.5",
      "messages": [
        {
          "role": "user",
          "content": "{{input}}"
        }
      ]
    }
    ```

    플러그인 인터페이스가 파라미터 매핑을 지원한다면, 사용자 입력을 `{{input}}`과 같은 플레이스홀더 변수에 매핑할 수 있습니다.
  </Step>

  <Step title="6단계: 먼저 플러그인에서 연결 검증">
    현재 버전이 플러그인 디버깅을 지원한다면, 먼저 다음 문구를 전달해 보세요.

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

    인터페이스가 먼저 안정적으로 응답하는지 확인한 후, Bot이나 워크플로에 연결하세요.
  </Step>

  <Step title="7단계: Bot 또는 워크플로에서 플러그인 호출">
    플러그인 단독 테스트가 통과되면, 다음에 추가합니다.

    * Bot 플러그인 기능
    * 또는 워크플로 노드

    처음에는 플러그인이 요약, 재작성, 고정 질의응답 등 단순한 작업 하나만 담당하도록 하는 것을 권장합니다.
  </Step>
</Steps>

## 방법 2: 워크플로 HTTP 요청 노드를 통해 Crazyrouter 연동

플러그인을 별도로 관리하고 싶지 않다면, 워크플로에서 직접 HTTP 요청 노드를 호출할 수도 있습니다.

### 권장 설정

* 요청 방법: `POST`
* URL: `https://api.crazyrouter.com/v1/chat/completions`
* Headers:
  * `Authorization: Bearer sk-xxx`
  * `Content-Type: application/json`
* Body:

```json theme={null}
{
  "model": "gpt-5.5",
  "messages": [
    {
      "role": "user",
      "content": "{{input}}"
    }
  ]
}
```

### 권장 검증 순서

1. 먼저 노드에 고정 문자열 `Reply only OK`를 전달
2. 다음으로 변수 입력으로 변경
3. 마지막으로 출력을 다음 노드에 매핑

## "커스텀 모델 연동"을 어떻게 이해해야 하는가

Coze의 일부 버전이나 요금제는 실제로 커스텀 모델 연동을 지원할 수 있지만, 이를 Crazyrouter 공개 문서의 기본 메인 가이드로 삼아서는 안 됩니다.

이유:

* Coze 공식 요금제 FAQ는 현재 `커스텀 모델`을 엔터프라이즈 플래그십 버전 기능 중 하나로 분류하고 있음
* 대다수 일반 사용자에게는 공개적으로 재현 가능하고 가장 쉽게 검증할 수 있는 것이 여전히 HTTP / API 플러그인 경로임
* 따라서 이 페이지에서는 커스텀 모델 기능을 보조 배경 정보로만 다루며, 기본 공개 가이드로 작성하지 않음

## 권장 모델 구성

| 사용 시나리오      | 권장 모델             | 이유                                                                       |
| ------------ | ----------------- | ------------------------------------------------------------------------ |
| 첫 번째 연결 검증   | `gpt-5.5`         | 2026년 3월 23일 프로덕션 환경에서 실측 성공, Coze에서 Crazyrouter로의 호출 체인을 먼저 확인하기에 가장 적합 |
| 고품질 출력       | `claude-opus-4-8` | 더 강력한 설명과 콘텐츠 생성에 적합                                                     |
| Gemini 대체 옵션 | `gemini-3.1-pro`  | 두 번째 호환성 검증 경로로 적합                                                       |

## 토큰 설정 모범 사례

| 설정        | 권장    | 설명                                       |
| --------- | ----- | ---------------------------------------- |
| 전용 토큰     | 필수    | Coze는 데스크톱 클라이언트, IDE 도구와 토큰을 공유하지 않아야 함 |
| 모델 화이트리스트 | 강력 권장 | 먼저 1\~2개 모델만 허용                          |
| 할당량 상한    | 강력 권장 | 워크플로 루프, 플러그인 재시도는 소비를 증폭시킴              |
| 환경 격리     | 권장    | dev / test / production 토큰을 분리           |
| 유출 대응     | 즉시 교체 | 플러그인 스크린샷, 공유 워크스페이스 노출 후 즉시 key를 교체해야 함 |

## 검증 체크리스트

* [ ] Coze 전용 Crazyrouter 토큰이 생성됨
* [ ] HTTP / API 플러그인 또는 워크플로 HTTP 요청 노드 경로를 우선 선택함
* [ ] 요청 URL이 `https://api.crazyrouter.com/v1/chat/completions`로 설정됨
* [ ] `Authorization` 헤더가 `Bearer sk-xxx`로 올바르게 입력됨
* [ ] `Content-Type`이 `application/json`으로 설정됨
* [ ] 최소 요청 본문이 `gpt-5.5`로 검증 성공함
* [ ] 플러그인 또는 노드가 단독 디버깅에 성공함
* [ ] Bot / 워크플로에 연결한 후에도 정상 동작함
* [ ] Crazyrouter 백엔드 로그에서 해당 요청이 확인됨

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

| 증상                                    | 일반적인 원인                                 | 해결 방법                                                   |
| ------------------------------------- | --------------------------------------- | ------------------------------------------------------- |
| 401 unauthorized                      | 토큰이 잘못되었거나 만료되었거나 복사가 불완전함              | 토큰을 재생성하고 `Authorization` 헤더를 다시 입력                     |
| 404                                   | URL이 잘못되었거나 `/v1/chat/completions`가 누락됨 | 전체 URL로 수정                                              |
| 403 / model not allowed               | 토큰에 현재 모델이 허용되지 않음                      | Crazyrouter 토큰 설정에서 모델 허용                               |
| `model not found`                     | 모델명 오타                                  | 먼저 `gpt-5.5`로 되돌려 재검증                                   |
| 플러그인은 생성되지만 Bot에서 호출 실패               | 플러그인 입력 / 출력 매핑 불일치                     | 먼저 고정 문자열 디버깅으로 되돌림                                     |
| 워크플로 노드가 간헐적으로 실패                     | 노드 입력이 너무 길거나, 재시도가 과도하거나, 동시성이 높음      | 먼저 입력을 축소하고 복잡도를 낮춰 최소 검증                               |
| 다른 사람의 가이드를 따라했지만 "모델 관리 연동"을 찾을 수 없음 | 버전이나 요금제가 다름                            | HTTP / API 플러그인 메인 가이드로 돌아가고, 엔터프라이즈 버전 기능에 먼저 의존하지 말 것 |

## FAQ

### Coze에서 Crazyrouter를 연동할 때 어떤 경로를 가장 추천하나요?

공개 문서에서는 HTTP / API 플러그인 또는 워크플로 HTTP 요청 노드 경로를 우선 추천합니다.

### "커스텀 모델 연동"을 메인 가이드로 작성하지 않는 이유는 무엇인가요?

Coze의 버전과 요금제에 따라 기능 차이가 크고, 공식 요금제 FAQ에서도 `커스텀 모델`을 엔터프라이즈 플래그십 버전 기능 중 하나로 분류하고 있기 때문입니다. 공개 문서는 재현 가능하고 진입 장벽이 낮은 HTTP 경로를 작성하는 것이 더 적합합니다.

### URL은 무엇을 입력해야 하나요?

`https://api.crazyrouter.com/v1/chat/completions`를 입력하세요.

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

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

### Claude나 더 많은 모델은 언제 추가해야 하나요?

먼저 단일 모델, 단일 노드, 단일 작업을 성공시킨 후 모델 화이트리스트를 점차 확대하세요.

<Note>
  목표가 "Coze가 먼저 Crazyrouter를 안정적으로 호출하도록 하는 것"이라면, 가장 중요한 것은 가장 복잡한 연동 방법을 추구하는 것이 아니라, 먼저 HTTP / API 플러그인으로 최소 체인을 성공시키는 것입니다.
</Note>