Quick Start: Get OmniRoute Running in 3 Minutes

1단계: OmniRoute 설치

원하는 방법을 선택하세요.

옵션 A: npm(권장)

npm install -g omniroute

옵션 B: Docker

docker run -d --name omniroute -p 20128:20128 diegosouzapw/omniroute:latest

:latest는 게시된 안정 SemVer 중 가장 높은 버전입니다. git main을 추적하지는 않습니다. GitOps에서는 diegosouzapw/omniroute:X.Y.Z로 버전을 고정하세요. 이미지 태그/릴리스 채널을 참조하세요.

옵션 C: 소스에서 설치

git clone https://github.com/diegosouzapw/OmniRoute.git
cd OmniRoute
npm install
npm run dev

---

2단계: OmniRoute 시작

omniroute

OmniRoute는 http://localhost:20128에서 시작됩니다. 대시보드가 자동으로 열립니다.

---

3단계: 무료 제공업체 연결

무료 제공업체를 연결하면 비용을 전혀 지불하지 않고도 OmniRoute를 사용할 수 있습니다.

옵션 A: Kiro(무료 Claude — 신용카드 불필요)

1. http://localhost:20128에서 대시보드를 엽니다
2. Providers → Add Provider로 이동합니다
3. Kiro AI를 선택합니다
4. Connect를 클릭합니다(API 키 불필요!)
5. 완료되었습니다! 이제 Claude 모델을 무료로 사용할 수 있습니다.

옵션 B: OpenCode Free(인증 불필요)

1. http://localhost:20128에서 대시보드를 엽니다
2. Providers → Add Provider로 이동합니다
3. OpenCode Free를 선택합니다
4. Connect를 클릭합니다(API 키 불필요!)
5. 완료되었습니다! 이제 여러 모델을 무료로 사용할 수 있습니다.

옵션 C: Pollinations(키 불필요)

1. http://localhost:20128에서 대시보드를 엽니다
2. Providers → Add Provider로 이동합니다
3. Pollinations를 선택합니다
4. Connect를 클릭합니다(API 키 불필요!)
5. 완료되었습니다! 이제 GPT-5, Claude, Gemini 등을 무료로 사용할 수 있습니다.

---

4단계: 정상 작동 확인

API Keys에서 새 키를 생성하세요. 이 키는 다시 표시되지 않으므로 안전하게 보관하세요. 이 키는 도구가 OmniRoute에 접근하기 위한 것이며, 업스트림 제공업체에 접근하기 위한 키가 아닙니다.

curl http://localhost:20128/v1/models -H "Authorization: Bearer YOUR_KEY"

연결된 모델 목록이 표시되어야 합니다.

---

5단계: IDE 또는 CLI가 OmniRoute를 가리키도록 설정

IDE 또는 CLI 도구에서 다음과 같이 설정하세요.

Base URL: http://localhost:20128/v1
API Key:  [Dashboard → Endpoints에서 복사]
Model:    auto

이것으로 끝입니다! 이제 IDE가 자동 제공업체 선택 기능과 함께 OmniRoute를 사용합니다.

IDE 예시: VSCode/Continue.dev

1. VSCode에서 Continue.dev 확장 프로그램을 설치합니다.
2. ~/.continue/config.yaml에 다음 줄을 추가합니다.

  - name: OmniRoute - Auto
    provider: openai
    model: auto
    apiBase: http://localhost:20128/v1
    apiKey: <YOUR_KEY>

3. Continue.dev 채팅 창에서 OmniRoute - Auto를 선택하면 OmniRoute로 요청을 보내게 됩니다.
4. (선택 사항) 독자를 위한 연습 문제 — IDE를 사용하여 다른 모든 사전 구성도 config.yaml에 추가해 보세요 😊

CLI 예시: Codex CLI

1. 운영 체제에서 환경 변수를 영구적으로 설정합니다. macOS/Linux의 경우(~/.bashrc 또는 ~/.zshrc에 추가):

export OMNIROUTE_API_KEY="<YOUR_KEY>"

Windows의 경우(Command Prompt):

setx OMNIROUTE_API_KEY <YOUR_KEY>

2. 이제 OmniRoute용으로 구성된 Codex를 실행해 보겠습니다. 다음을 실행하세요.

omniroute launch-codex --model auto

codex와 명령줄 매개변수를 사용해 엔드포인트와 API 키를 지정하여 수동으로 설정할 수도 있지만, 위 명령을 사용하면 OmniRoute가 모든 작업을 대신 처리합니다.

일반 실행기를 사용하면 다른 CLI도 동일하게 단일 명령으로 실행할 수 있습니다. omniroute run <target>은 claude, codex, aider, goose, opencode, qwen, gemini를 지원합니다(CLI 통합 참조).

3. 이제 CLI가 OmniRoute로 요청을 보내야 합니다.

도구의 요청이 OmniRoute로 라우팅되는지 확인

왼쪽 사이드바에서 Monitoring/Logs를 클릭하면 요청 세부 정보를 확인할 수 있습니다. 항목을 클릭하면 더 자세한 정보가 표시됩니다. 참고로 즐겨 사용하는 하네스에서 어떤 정보가 전송되는지도 확인할 수 있습니다. 이는 학습과 디버깅에 유용합니다.

---

다음 단계

• Auto-Combo 가이드 — OmniRoute가 최적의 AI를 선택하도록 설정
• 제공업체 가이드 — 더 많은 제공업체 연결(무료 및 유료)
• 무료 티어 가이드 — 신용카드 없이 무료 AI 사용
• 문제 해결 — 일반적인 문제 해결

---

자주 묻는 질문

“API 키가 필요한가요?”

아니요! 무료 제공업체(Kiro, OpenCode Free, Pollinations)는 API 키 없이 사용할 수 있습니다. 대시보드에서 연결하기만 하면 됩니다.

“auto란 무엇인가요?”

auto는 각 요청에 가장 적합한 제공업체를 OmniRoute가 자동으로 선택하도록 합니다. 속도, 비용, 품질 및 가용성을 고려합니다. 자세한 내용은 Auto-Combo 가이드를 참조하세요.

“비용은 얼마인가요?”

OmniRoute 자체는 무료 오픈 소스입니다. 사용하는 제공업체에 대해서만 비용을 지불하면 됩니다. 많은 제공업체가 무료 티어를 제공합니다. 무료 티어 가이드를 참조하세요.

“Claude Code / Cursor / Copilot과 함께 사용할 수 있나요?”

네! OmniRoute는 OpenAI 형식을 지원하는 모든 도구와 함께 사용할 수 있습니다. Base URL을 http://localhost:20128/v1로 설정하기만 하면 됩니다. 구체적인 설정 방법은 CLI 도구 가이드를 참조하세요.

“제공업체에 장애가 발생하면 어떻게 되나요?”

OmniRoute는 장애가 발생한 제공업체를 자동으로 건너뛰고 다음 제공업체를 시도합니다. 별도로 조치할 필요가 없습니다. 자세한 내용은 Auto-Combo 가이드를 참조하세요.

---

도움이 필요하신가요?

• 문제 해결 — 일반적인 문제와 해결 방법
• Discord — 커뮤니티 지원
• GitHub Issues — 버그 신고

---

undefined (a58000c7685f)