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

# n8n 설정 가이드

> n8n에서 Crazyrouter를 통해 OpenAI 자격 증명, AI Agent 워크플로, HTTP Request 대체 방안을 설정하고 검증 및 문제 해결을 완료합니다

> 업데이트: 2026-06-06

n8n은 LLM 호출을 자동화 프로세스, Agent 노드, 승인 흐름, 비즈니스 시스템 연동에 접목하는 데 적합합니다. Crazyrouter와 연동할 때는 먼저 n8n의 OpenAI 자격 증명 경로로 최소 워크플로를 검증한 후, 더 유연한 HTTP Request 노드로 전환할지 결정하는 것을 권장합니다.

## 개요

n8n의 OpenAI 자격 증명 또는 AI 노드를 통해 워크플로 내 모델 요청을 Crazyrouter로 전달할 수 있습니다.

* 권장 프로토콜: `OpenAI-compatible API`
* 권장 연동 방식: n8n `OpenAI API` credential + 노드 단위 `Base URL`
* Base URL: `https://api.crazyrouter.com/v1`
* 인증 방식: `sk-...` 토큰
* 권장 첫 검증 모델: `gpt-5.5`

일부 노드가 필요한 파라미터나 최신 모델 기능을 지원하지 않는다면 `HTTP Request` 노드로 대체해 Crazyrouter 인터페이스를 직접 호출하세요.

## 이런 분께 적합합니다

* AI를 자동화 워크플로에 접목하고 싶은 분
* 폼, 데이터베이스, 승인, Webhook과 모델을 연동하고 싶은 분
* AI Agent 노드로 도구 호출을 오케스트레이션하고 싶은 분
* 시각적인 방식으로 Crazyrouter를 내부 비즈니스 프로세스에 연결하고 싶은 분

## 사용 프로토콜

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

n8n에서 Crazyrouter를 연동할 때는 다음을 입력하는 것을 권장합니다.

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

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

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

## 사전 조건

| 항목             | 설명                                                 |
| -------------- | -------------------------------------------------- |
| Crazyrouter 계정 | 먼저 [crazyrouter.com](https://crazyrouter.com)에서 가입 |
| Crazyrouter 토큰 | n8n 전용 `sk-...` 토큰을 별도로 생성하는 것을 권장                 |
| n8n            | 현재 안정 버전을 사용하고 AI 노드 사용 가능 여부 확인 권장                |
| 사용 가능한 모델      | `gpt-5.5`처럼 당일 실측으로 성공한 채팅 모델을 최소 1개 허용            |

권장 초기 화이트리스트:

* `gpt-5.5`
* `claude-opus-4-8`
* `gemini-3.1-pro`
* `text-embedding-3-large`(벡터 또는 검색 관련 노드를 사용하는 경우)

## 5분 빠른 시작

<Steps>
  <Step title="n8n 전용 토큰 생성">
    Crazyrouter 관리 화면에서 `n8n`이라는 이름의 토큰을 생성합니다. 처음에는 `gpt-5.5`와 `claude-opus-4-8`만 허용하는 것을 권장합니다.
  </Step>

  <Step title="OpenAI 자격 증명 추가">
    n8n에서 `Settings` → `Credentials` → `Add Credential`로 이동해 `OpenAI API` 또는 현재 버전에 해당하는 OpenAI 자격 증명 유형을 선택합니다.
  </Step>

  <Step title="자격 증명과 노드 정보 입력">
    먼저 자격 증명에 다음을 입력합니다.

    * `API Key`: 본인의 `sk-...`

    그런 다음 `OpenAI`, `OpenAI Chat Model` 또는 관련 AI 노드의 `Options`에서 다음을 설정합니다.

    * `Base URL`: `https://api.crazyrouter.com/v1`
  </Step>

  <Step title="최소 워크플로 생성">
    새 워크플로를 만들어 `Manual Trigger` → `OpenAI Chat Model` → `Output`을 사용하고, 모델은 먼저 `gpt-5.5`를 입력합니다.
  </Step>

  <Step title="첫 검증 완료">
    `OpenAI Chat Model` 노드에 `Reply only OK`처럼 간단한 입력을 주고 워크플로를 수동으로 실행합니다. 성공적으로 응답을 받으면 이후 AI Agent나 복잡한 워크플로 설정을 계속 진행합니다.
  </Step>
</Steps>

## 최소 워크플로 예시

### OpenAI Chat Model 노드

```json theme={null}
{
  "node": "OpenAI Chat Model",
  "parameters": {
    "model": "gpt-5.5",
    "messages": [
      { "role": "user", "content": "{{ $json.input }}" }
    ]
  }
}
```

### AI Agent 워크플로

가장 단순한 구조로 먼저 시작하는 것을 권장합니다.

1. `Manual Trigger`
2. `AI Agent`
3. `Output`

`AI Agent`에서 방금 생성한 Crazyrouter 자격 증명을 선택하고, 처음에는 간단한 도구 노드 하나만 연결해 모델 문제와 도구 문제가 섞이지 않도록 합니다.

## HTTP Request 대체 방안

다음과 같은 경우:

* 일부 n8n AI 노드가 아직 지원하지 않는 새 파라미터가 필요한 경우
* 더 유연한 요청 본문 제어가 필요한 경우
* headers, body, stream 파라미터를 더 명확하게 디버깅해야 하는 경우

`HTTP Request` 노드로 Crazyrouter를 직접 호출할 수 있습니다.

```http theme={null}
Method: POST
URL: https://api.crazyrouter.com/v1/chat/completions
Headers:
  Authorization: Bearer sk-xxx
  Content-Type: application/json
Body:
  {
    "model": "gpt-5.5",
    "messages": [
      {"role": "user", "content": "{{ $json.input }}"}
    ]
  }
```

<Tip>
  권장 순서는 먼저 OpenAI 자격 증명 + 네이티브 AI 노드로 검증을 마친 후, 노드 기능이 부족할 때만 `HTTP Request`로 전환하는 것입니다.
</Tip>

<Note>
  n8n 버전에 따라 `Base URL`이 자격 증명 페이지에 나타날 수도 있고, 특정 OpenAI / Chat Model 노드의 `Options`에 나타날 수도 있습니다. 현재 공식 문서에서 더 명확하게 언급하는 것은 노드 단위 `Base URL` 오버라이드 항목이므로, Crazyrouter를 연동할 때는 "자격 증명에는 Key, 노드에는 Base URL을 입력"하는 방식을 우선적으로 사용하는 것을 권장합니다.
</Note>

## 권장 모델 설정

| 사용 시나리오           | 권장 모델                    | 이유                        |
| ----------------- | ------------------------ | ------------------------- |
| 기본 워크플로 모델        | `gpt-5.5`                | 당일 실측 성공, n8n 주 기준선으로 적합  |
| 고품질 복잡 Agent 시나리오 | `claude-opus-4-8`        | 더 복잡한 해석과 긴 텍스트 작업에 적합    |
| Gemini 대체 옵션      | `gemini-3.1-pro`         | 두 번째 호환성 검증 경로를 보완하는 데 적합 |
| 검색 / 벡터 관련        | `text-embedding-3-large` | 이후 벡터 처리나 검색 증강 작업에 적합    |

권장 순서: 먼저 `gpt-5.5`로 최소 워크플로를 검증한 후, Agent, 도구, 배치 작업으로 확장합니다.

## 토큰 설정 모범 사례

| 설정        | 권장 사항                  | 설명                                         |
| --------- | ---------------------- | ------------------------------------------ |
| 전용 토큰     | 필수                     | n8n은 채팅 프런트엔드, CLI, SDK 예제와 토큰을 공유하지 않아야 함 |
| 모델 화이트리스트 | 강력 권장                  | 워크플로에서 실제로 사용할 모델만 허용                      |
| IP 제한     | 고정된 서버 출구 IP에서는 활성화 권장 | 로컬 디버깅과 클라우드를 혼용할 때는 신중하게 사용               |
| 할당량 상한    | 강력 권장                  | 자동화 작업은 재시도, 반복, 배치 처리로 빠르게 할당량을 소진할 수 있음  |
| 환경 분리     | 필수                     | 개발, 테스트, 프로덕션 워크플로에 서로 다른 토큰 사용            |
| 노드 등급화    | 권장                     | 빈도가 높은 작업에는 저비용 모델을, 핵심 작업에는 고성능 모델로 전환    |

## 검증 체크리스트

* [ ] `OpenAI API` 자격 증명이 성공적으로 저장됨
* [ ] 노드 단위 `Base URL`이 `https://api.crazyrouter.com/v1`로 설정됨
* [ ] `OpenAI Chat Model` 노드가 정상적으로 실행됨
* [ ] 첫 최소 워크플로가 성공적으로 응답을 반환함
* [ ] Agent가 필요한 경우 `AI Agent` 노드도 정상적으로 모델을 호출함
* [ ] Crazyrouter 관리 화면 로그에서 해당 요청을 확인할 수 있음
* [ ] 토큰 할당량과 모델 화이트리스트가 예상과 일치함
* [ ] 개발 / 테스트 / 프로덕션 워크플로가 토큰 분리를 완료함

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

| 현상                          | 흔한 원인                                 | 해결 방법                                                       |
| --------------------------- | ------------------------------------- | ----------------------------------------------------------- |
| 자격 증명 테스트 실패                | API Key가 잘못됐거나 Base URL 설정 위치를 잘못 입력함 | `sk-...`를 다시 확인하고, 현재 버전이 실제로 지원하는 위치에 `Base URL`을 입력했는지 확인 |
| 401 unauthorized            | 토큰이 만료됐거나 삭제됐거나 복사 시 공백이 포함됨          | 토큰을 재생성해 교체                                                 |
| 403 / model not allowed     | 노드에서 사용하는 모델이 화이트리스트에 없음              | Crazyrouter 관리 화면에서 해당 모델을 허용                               |
| 404                         | `Base URL`을 루트 도메인이나 전체 인터페이스 경로로 입력함 | `https://api.crazyrouter.com/v1`로 수정                        |
| 워크플로가 계속 재시도되며 비용이 빠르게 증가함  | 노드 오류 후 자동 재시도, 반복 설정이 부적절함           | 재시도 횟수를 제한하고 워크플로를 분리하며 할당량을 설정                             |
| AI Agent는 시작되지만 도구 호출이 불안정함 | 자격 증명 문제가 아니라 도구 체인이 너무 복잡함           | 먼저 간단한 도구 노드 하나만 남겨 검증                                      |
| 네이티브 AI 노드에 일부 파라미터가 없음     | n8n 노드 래핑이 아직 해당 기능을 다루지 못함           | `HTTP Request` 노드로 전환해 Crazyrouter를 직접 호출                   |
| 배치 작업 성능이 불안정함              | 모델 기능과 노드 래핑이 맞지 않음                   | 먼저 `gpt-5.5`로 최소 체인을 검증한 후 다른 모델로 확장                        |

## 성능 및 비용 관련 권장 사항

* 자동화 작업은 기본적으로 `gpt-5.5`를 기준선으로 사용
* 반복, 배치, 예약 작업에는 더 엄격한 할당량과 오류 알림을 설정
* 프로덕션 워크플로와 디버깅 워크플로를 서로 다른 토큰으로 분리
* AI Agent는 먼저 적은 도구, 짧은 체인으로 검증한 후 안정화되면 복잡한 오케스트레이션으로 확장
* 비용이 이상하게 증가하면 먼저 Crazyrouter 로그와 n8n 실행 기록을 확인해 재시도나 반복으로 인한 것인지 판단

## FAQ

### n8n에서 어떤 Base URL을 입력해야 하나요?

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

### Base URL은 자격 증명에 입력해야 하나요, 노드에 입력해야 하나요?

먼저 현재 사용 중인 n8n 버전의 화면을 확인하세요. 현재 공식 문서에서 더 명확히 언급하는 것은 노드 단위 `Base URL` 옵션입니다. 자격 증명 페이지에서도 입력을 지원한다면 거기에 입력해도 되지만, 첫 설정에서는 노드 단위 설정을 기준으로 하는 것을 권장합니다.

### 네이티브 AI 노드를 먼저 써야 하나요, HTTP Request를 써야 하나요?

먼저 네이티브 OpenAI 자격 증명과 AI 노드를 사용하고, 파라미터가 부족하거나 심층 디버깅이 필요할 때만 `HTTP Request`로 전환하세요.

### 처음에 추천하는 모델은 무엇인가요?

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

### 워크플로 비용이 갑자기 왜 높아지나요?

대개 단일 요청 자체가 아니라 반복, 배치 처리, 자동 재시도, 또는 여러 사람이 워크플로를 공유해서 발생하는 트리거 때문입니다.

### n8n은 반드시 여러 토큰으로 나눠야 하나요?

최소한 개발과 프로덕션은 분리하는 것을 강력히 권장하며, 빈도가 높은 작업은 별도로 더 나누는 것이 좋습니다.

<Note>
  n8n이 Crazyrouter와 연동된 후의 가치는 단순히 "모델을 호출할 수 있다"는 것이 아니라, 모델을 자동화 체인에 포함시킬 수 있다는 점입니다. 따라서 가장 중요한 것은 단일 대화의 성공 여부가 아니라 재시도, 반복, 배치 실행, 토큰 할당량을 동시에 제어하는 것입니다.
</Note>