Troubleshooting (한국어)

빠른 참조

OmniRoute를 처음 사용하시나요? 여기서 시작하세요. 다음 내용으로 문제의 90%를 해결할 수 있습니다.

표시되는 메시지	의미	해결 방법
“Can’t connect”	OmniRoute가 실행되고 있지 않음	`omniroute` 또는 `docker restart omniroute` 실행
“Invalid API key”	키가 잘못되었거나 만료됨	제공업체 웹사이트에서 키를 다시 복사
“Rate limit exceeded”	너무 많은 요청을 보내고 있음	1분간 기다리거나 자동 대체를 위해 `model: "auto"` 사용
“Quota exceeded”	무료/유료 할당량을 모두 사용함	더 많은 제공업체를 연결하거나 무료 제공업체(Kiro, Pollinations) 사용
“Slow responses”	제공업체가 혼잡하거나 지리적으로 멀리 있음	`model: "auto/fast"`를 사용하거나 더 빠른 제공업체(Groq, Cerebras) 연결
“Wrong provider used”	`auto`가 다른 제공업체를 선택함	정상입니다! `auto`는 최적의 제공업체를 선택합니다. `model: "openai/gpt-4o"`로 특정 제공업체 지정
“502 Bad Gateway”	제공업체가 중단됨	기다렸다가 재시도하거나 `model: "auto"`를 사용하여 제공업체 전환
“401 Unauthorized”	자격 증명이 잘못됨	API 키를 확인하거나 OAuth로 다시 인증
“omniroute is not recognized”	Windows PATH에 전역 node 모듈이 누락됨	npm 전역 접두사를 Windows PATH에 추가하세요. `npm config get prefix`로 확인할 수 있습니다.
“429 Too Many Requests”	요청 속도가 제한됨	1분간 기다리거나 더 많은 제공업체 연결

그래도 해결되지 않나요? 아래의 상세 문제 해결을 참조하거나 Discord에서 문의하세요.

상세 문제 해결

무료 제공업체의 요청 속도 제한(429 / 400 / 401)

증상: 무료/무인증 제공업체(opencode, auggie 등)에서 model: "auto"를 사용할 때 응답 대신 간헐적으로 HTTP 429, 400 또는 401이 발생합니다. 잠시 후 동일한 프롬프트를 재시도하면 요청이 성공하지만, 자동화(cron 작업, 에이전트, 스크립트)는 첫 번째 실패에서 중단됩니다.

근본 원인: 다음 세 가지 독립적인 실패 유형이 중첩됩니다.

제공업체 요청 속도 제한(429): 무료 등급에는 시간 구간별 할당량이 적용될 수 있습니다. 병렬 호출이 한꺼번에 발생하면 할당량이 소진되므로, 해당 시간 구간이 초기화될 때까지 다음 요청이 거부됩니다.
패스스루의 작동하지 않는 모델(400/401): auto/* 풀에는 카탈로그에는 등록되어 있지만 유효한 자격 증명이 없는 opencode의 패스스루 모델이 포함될 수 있습니다(예: oc/north-mini-code-free → 401). 자동 라우터가 해당 모델 중 하나를 시도했다가 실패하면, 대체 처리가 시작되기 전에 오류가 전파됩니다.
동시성 증폭(부하 상황에서 429): 여러 에이전트/cron 세션이 동시에 auto를 호출하면 총 요청 속도가 무료 제공업체가 허용할 수 있는 수준을 초과하여 정상적인 호출도 악의적인 요청으로 분류됩니다.

검증된 해결 방법(커뮤니티 보고, 2026-08-10): 무료 등급의 불안정성으로 인해 중단되는 대신 순환, 동시성, 대체 처리가 이를 흡수하도록 다음 세 가지 환경 변수를 조정하세요.

export OMNIROUTE_ROTATE_ON_400=true           # 400/401 발생 시 다른 모델/제공업체로 이동(작동하지 않는 패스스루 모델 건너뛰기)
export OMNIROUTE_CHAT_MAX_HEAVY_IN_FLIGHT=4   # 명시적인 고부하 요청 허용 상한(기본적으로 설정되지 않음: 요청 수 제한 없음, 아래 참고 사항 참조)
export OMNIROUTE_CHAT_ADMISSION_QUEUE_MS=5000 # 즉시 재시도 가능한 503을 반환하는 대신 고부하 요청 처리 용량을 더 오래, 제한된 시간 동안 대기

이 변수들을 OmniRoute 프로세스 환경(데몬, 예: LaunchAgent plist 또는 systemctl edit를 통해)에 설정한 다음 OmniRoute를 재시작하세요. 순환 플래그는 단일 설정 중 가장 큰 효과를 냅니다. 이 플래그는 치명적인 실패를 풀 내의 정상적인 제공업체에 대한 투명한 재시도로 전환합니다.

참고: OMNIROUTE_CHAT_MAX_HEAVY_IN_FLIGHT는 동시에 실행되는 고부하(긴 컨텍스트) 요청 수를 제한합니다. 이 제한은 요청 허용 게이트이며 제공업체 요청 속도 제한기가 아닙니다. #503-fanout 업데이트: 이 변수는 더 이상 기본값으로 설정되지 않습니다(이제 위와 같이 명시적으로 구성된 경우에만 적용됨). 대신 고부하 요청 허용은 호스트의 실제 메모리 상한에 따라 자동으로 조정되는, 자동 산출된 바이트 예산(OMNIROUTE_CHAT_MAX_INFLIGHT_BYTES)으로 제어됩니다. 따라서 새 배포에서는 이 변수를 전혀 설정하지 않아도 503 chat_admission_busy 거부가 훨씬 적게 발생합니다. 여기서 명시적으로 설정하는 방식도 문서에 설명된 대로 동일하게 작동합니다. 명시적인 바이트 예산 재정의 값은 8 MiB–2 GiB 범위로 제한됩니다. 413 body_exceeds_budget은 일시적인 오류가 아닙니다. 해당 바이트 예산을 늘리거나, OMNIROUTE_CHAT_HARD_MAX_BODY_BYTES를 낮추거나, 프로세스 메모리 상한을 늘리세요. inflight_bytes_budget으로 인한 요청 중단은 일시적인 경합이므로 재시도할 수 있습니다. 제공업체별 요청 속도 제한(open-sse/services/rateLimitManager.ts)은 RATE_LIMIT_MAX_WAIT_MS, RATE_LIMIT_MAX_QUEUE_DEPTH, RATE_LIMIT_AUTO_ENABLE로 별도 제어됩니다. 자세한 내용은 .env.example을 참조하세요.

작동 여부를 확인하는 방법: 에이전트/cron을 연속해서 빠르게 두 번 실행하고 두 실행 모두 성공하는지 확인하세요. 수정 전에는 일반적으로 두 번째 실행에서 429/401 오류가 발생합니다. 수정 후에는 오류가 발생하더라도 투명하게 재시도되어 호출이 완료됩니다. 또한 curl /monitoring/health를 실행하여 제공자 연결의 rateLimitedUntil 필드와 영향을 받는 제공자의 circuitBreakers.providerBreakers[].state를 확인할 수 있습니다. 상태는 CLOSED, DEGRADED, OPEN, HALF_OPEN 중 하나이며(src/shared/utils/circuitBreaker.ts 참조), 계속 실패하는 제공자는 재설정 기간이 지난 후 프로브가 허용되기 전까지 CLOSED → DEGRADED → OPEN으로 전환됩니다(HALF_OPEN).

여전히 429가 발생하는 경우: 해당 제공자의 활성 계정이 단순한 요청 속도 제한이 아니라 실제 _할당량_을 모두 소진한 것입니다. OmniRoute 대시보드 → Providers → Accounts에서 같은 제공자의 두 번째 계정을 추가하거나 다른 무료 제공자(예: routeway, auggie)를 함께 사용하세요. 순환은 일시적인 요청 속도 제한/400/401 문제에만 도움이 됩니다. 할당량이 완전히 소진된 경우에는 두 번째 자격 증명이나 다른 제공자가 필요합니다.

비전 모델(auto/vision, bazaarlink/*)에서 403이 발생하는 경우: 연결된 계정에 비전 기능이 포함된 유료 플랜이 없거나 API 키의 권한이 충분하지 않은 것입니다. 제공자 대시보드에서 키 범위에 비전/멀티모달 권한이 포함되어 있는지 확인하거나, 유료 티어 계정을 연결하여 비전 대상으로 유지하세요.

npm install 경고(ERESOLVE / peer / deprecated)

npm install -g omniroute를 실행하면 npm warn ERESOLVE, 피어 종속성 알림, deprecated 메시지와 같은 수많은 경고가 표시될 수 있습니다. 이는 예상된 동작이며 무해합니다. 출력에 added <N> packages가 표시되면 설치가 성공한 것입니다.

피어 종속성 해결 경고를 표시하지 않으려면 OmniRoute에서 지원하는 다음 설치 형식을 사용하세요.

npm install -g omniroute --legacy-peer-deps

--legacy-peer-deps는 ERESOLVE 및 피어 종속성 알림만 표시하지 않습니다. 지원 중단 알림은 전이적 서드 파티 패키지에서 발생하므로 계속 표시되며, 설치 실패를 의미하지 않습니다.

이러한 경고는 OmniRoute에서 제어할 수 없는 서드 파티 패키지의 오래된 피어 종속성 범위로 인해 발생합니다.

marked-terminal은 marked >=1 <16을 요구하지만 marked@18이 발견됨 — 실제로는 정상적으로 작동하며, 업스트림 피어 범위가 오래되었을 뿐입니다.
deprecated prebuild-install@7.1.3 — 전이적 네이티브 바이너리 가져오기 도우미입니다. 고정된 wreq-js 전송 바인딩을 설치하는 데 사용되지 않으며, 웹 쿠키 공급자 전송 설정에 실패했다는 의미도 아닙니다.

별도의 조치가 필요하지 않습니다 — 업스트림 패키지를 포크하지 않는 한 경고를 완전히 숨길 수 없습니다.

Gemini Web 및 Playwright Chromium

Gemini Web 요청에서 Playwright Chromium이 설치되지 않았다는 메시지와 함께 503이 반환된다면 npm 패키지는 존재하지만 브라우저 바이너리가 누락된 것입니다. Playwright는 의도적으로 브라우저 다운로드를 npm 패키지 설치와 별도로 유지하므로, 브라우저가 설치될 때까지 이 응답이 반환되는 것은 정상입니다.

전역 npm 설치의 경우 브라우저 캐시가 동일한 Playwright 설치에 속하도록 OmniRoute 패키지 디렉터리에서 Chromium을 설치하세요.

cd "$(npm root -g)/omniroute"
npx playwright install chromium

설치 후 OmniRoute를 다시 시작한 다음 Gemini Web 요청을 다시 시도하세요. Docker 이미지에서 OmniRoute를 실행하는 경우 Chromium과 해당 종속성이 포함된 -web 이미지(또는 runner-web 빌드 대상)를 사용하세요. 기본 이미지에는 포함되어 있지 않습니다.

빠른 해결 방법

문제	해결 방법
첫 로그인이 작동하지 않음	`.env`에 `INITIAL_PASSWORD`를 설정하세요(하드코딩된 기본값 없음).
대시보드가 잘못된 포트에서 열림	`PORT=20128` 및 `NEXT_PUBLIC_BASE_URL=http://localhost:20128`을 설정하세요.
로그가 디스크에 기록되지 않음	`APP_LOG_TO_FILE=true`를 설정하고 호출 로그 캡처가 활성화되어 있는지 확인하세요.
EACCES: 권한 거부	`~/.omniroute`를 재정의하려면 `DATA_DIR=/path/to/writable/dir`을 설정하세요.
라우팅 전략이 저장되지 않음	최신 v3.x 릴리스로 업데이트하세요(설정 지속성을 위한 Zod 스키마 수정 사항은 이전 버전에서 배포됨).
로그인 충돌 / 빈 페이지	Node.js 버전을 확인하세요. 아래의 Node.js 호환성을 참조하세요.
`dlopen` / `slice is not valid mach-o file` (macOS)	`cd $(npm root -g)/omniroute/app && npm rebuild better-sqlite3 && omniroute`를 실행하세요. 아래의 macOS 네이티브 모듈 다시 빌드를 참조하세요.
프록시 “fetch failed”	프록시 구성이 올바른 수준에 설정되어 있는지 확인하세요. 아래의 프록시 문제를 참조하세요.
Docker `curl: (56) Recv failure: Connection reset by peer`	Docker 포트 바인딩이 IPv6에 연결되었을 수 있습니다. IPv4를 강제하려면 `-p 127.0.0.1:20128:20128`을 사용하거나 `curl -4`로 테스트하세요. 아래의 Docker IPv6을 참조하세요.
바이러스 백신이 `README.md`를 격리함	오탐입니다. 아래의 바이러스 백신 오탐을 참조하세요.
Kaspersky가 데스크톱 앱을 트로이 목마로 탐지함	서명되지 않은 설치 프로그램에 대한 행위 기반 오탐입니다. 아래의 바이러스 백신 오탐을 참조하세요.

백신 오탐

Avast/AVG가 `README.md`를 `MD:HttpRequest-inf[Susp]`로 격리하는 문제

이는 오탐입니다. 어떤 파일도 감염되지 않았으며, 별도의 조치는 필요하지 않습니다.

Avast와 AVG는 HTTP 요청처럼 보이는 링크가 많이 포함된 일반 텍스트/Markdown 파일을 표시하는 휴리스틱을 실행합니다. OmniRoute의 README.md는 npm 패키지에 포함되어 배포되므로(package.json → files에 등록되어 있음), 전역 설치 시 node_modules/omniroute/README.md에 저장됩니다. 또한 이 파일에는 약 15개의 http://localhost:20128/... 예시(MCP HTTP/SSE 엔드포인트, A2A .well-known URL 및 curl 스니펫)가 포함되어 있습니다. 이 정도의 링크 밀도면 해당 휴리스틱이 작동하기에 충분합니다.

이 문제가 최근에야 시작되었다면, 파일의 성격이 바뀐 것은 아닙니다. README의 엔드포인트 표에 MCP HTTP + SSE + A2A가 추가되었고 curl 예시도 늘어나면서 임계값을 초과하게 된 것입니다.

이 파일은 실행 가능한 콘텐츠가 전혀 없는 단순한 문서입니다. 격리된 파일을 안전하게 복원할 수 있습니다.

조치 방법:

알림 중지 — 백신에서 설치 디렉터리를 제외 항목으로 추가하세요 (Avast: Settings → Exceptions). 전역 node_modules 경로 및/또는 OmniRoute 데이터 디렉터리(~/.omniroute/)를 추가하면 됩니다.
오탐 신고 — https://www.avast.com/false-positive-file-form.php에서 격리된 README.md를 첨부하여 신고하세요. 텍스트 파일에 과민 반응하는 공급업체의 휴리스틱 문제이므로, 이 방법이 모두에게 도움이 되는 해결책입니다.

프로젝트 측에서 이 문제를 “수정”하지 않는 이유: 모든 예시는 http://localhost를 사용하며, 자체 서명 인증서로 인한 불편 없이는 localhost에서 https를 사용할 수 없습니다. 특정 공급업체의 휴리스틱을 피하려고 문서를 변형하면 스캐너의 버그에 맞추기 위해 모든 독자의 사용성을 해치게 됩니다.

Kaspersky가 데스크톱 앱을 `PDM:Trojan.Win32.Generic`으로 표시하는 문제

이는 동작 기반 휴리스틱으로 인한 오탐입니다. 어떤 파일도 감염되지 않았습니다. Kaspersky의 PDM: 접두사는 알려진 악성 코드와 일치하는지 확인한 결과가 아니라, 설치 프로그램이 _수행하는 동작_을 판단하는 Proactive Defense Module(System Watcher)에서 탐지 결과가 나왔다는 의미입니다. 이 탐지가 발생하면 Kaspersky는 이미 기록한 파일까지 삭제하면서 전체 설치를 “롤백”하므로, 앱이 손상되거나 사라지게 됩니다.

탐지되는 파일은 데스크톱 앱에 번들로 포함된, 명시된 오픈 소스 의존성의 표준 구성 요소입니다. 예를 들면 다음과 같습니다.

resources/app/.build/next/node_modules/playwright-<hash>/lib/…/agentParser.js 및 workerProcessEntry.js — 앱 내 공급자 로그인과 브라우저 기반 채팅에 사용되는 브라우저 자동화 라이브러리인 Playwright입니다.
resources/app/.build/next/node_modules/@wreq-js/binding-win32-<arch>-msvc-<hash>/wreq-js.win32-<arch>-msvc.node — 웹 쿠키 공급자의 브라우저 지문 기반 HTTP에 사용되는 고정 버전의 wreq-js 네이티브 바인딩입니다(<arch>는 x64 또는 arm64).

탐지되는 이유: Windows 설치 프로그램은 아직 코드 서명되지 않았기 때문에, 서명되지 않은 NSIS 설치 프로그램은 평판이 전혀 없으며 동작 기반 휴리스틱이 최대 수준으로 엄격하게 작동합니다. 여기에 번들로 포함된 네이티브 DLL과 %LOCALAPPDATA%\Programs\OmniRoute 아래에 기록되는 수백 개의 .js 파일 (Next.js 독립 실행형 빌드에서 생성된 해시 접미사 포함 패키지 디렉터리 포함)이 결합되면 휴리스틱이 작동하기에 충분합니다. 코드 서명이 예정되어 있지만, 적용되기 전까지는 새 릴리스에서도 이 문제가 반복될 수 있습니다.

조치 방법:

먼저 다운로드 파일을 검증하세요(파일 변조 가능성을 배제합니다). 모든 릴리스는 latest.yml을 게시하며, 그 안의 sha512 필드(base64)는 OmniRoute.Setup.<version>.exe 설치 프로그램을 대상으로 합니다. 설치 프로그램이 있는 폴더에서 PowerShell을 열고 다음을 실행하세요.
터미널 창
```
$b = [System.Security.Cryptography.SHA512]::Create().ComputeHash(
  [System.IO.File]::ReadAllBytes("$PWD\OmniRoute.Setup.&lt;version&gt;.exe"))
[Convert]::ToBase64String($b)
```
출력값은 latest.yml → sha512와 일치해야 합니다. 일치하지 않으면 파일을 삭제하고 GitHub 릴리스 페이지에서만 다시 다운로드하세요.
복원 + 제외 — 롤백되어 격리된 항목을 복원하고 %LOCALAPPDATA%\Programs\OmniRoute를 제외 항목으로 추가한 다음 (Kaspersky → Settings → Threats and Exclusions) 다시 설치하세요.
오탐 신고 — https://opentip.kaspersky.com/. 사용자가 제출한 오탐 신고는 실제로 허용 목록 등록을 앞당기는 데 도움이 됩니다.

Node.js 호환성

로그인 페이지가 중단되거나 “Module self-registration” 오류가 표시됨

원인: OmniRoute에서 승인한 보안 런타임 최소 버전 범위를 벗어난 Node.js 버전을 사용하고 있습니다. 가장 흔한 경우는 OmniRoute에서 요구하는 보안 패치 최소 버전보다 낮은 Node 22 또는 24 패치 버전을 사용하는 것입니다.

증상:

로그인 페이지에 빈 화면이나 서버 오류가 표시됨
콘솔에 Error: Module did not self-register 또는 이와 유사한 네이티브 바인딩 오류가 표시됨
런타임이 지원되는 보안 정책 범위를 벗어난 경우 로그인 페이지에 사용 중인 Node 버전과 함께 주황색 경고 배너가 표시됨

해결 방법:

지원되는 Node.js LTS 릴리스를 설치합니다(권장: Node.js 24.x).
터미널 창
```
nvm install 24
nvm use 24
```
버전을 확인합니다. node --version은 24.x LTS 계열에서 v24.0.0 이상을 표시해야 합니다.
OmniRoute를 다시 설치합니다. npm install -g omniroute
다시 시작합니다. omniroute

지원되는 보안 버전: >=22.22.2 <23 또는 >=24.0.0 <27. Node.js 24.x LTS(Krypton)와 Node.js 26은 완전히 지원됩니다.

npm v11+: `better-sqlite3`이 설치되지 않음(Cannot find module)

원인: npm v11(Node.js 24+에 포함됨)은 기본적으로 선택적 종속성의 설치 스크립트를 차단합니다. better-sqlite3은 optionalDependencies에 나열되어 있고 네이티브 컴파일(node-gyp rebuild)이 필요하므로 npm이 이를 알림 없이 건너뜁니다.

증상:

서버 시작 시 Cannot find module 'better-sqlite3' 오류와 함께 중단됨
ls node_modules/better-sqlite3에 “No such file or directory”가 표시됨
npm ls better-sqlite3에 (empty)가 표시됨

해결 방법:

설치 스크립트를 승인하고 다시 설치합니다.
터미널 창
```
npm approve-scripts better-sqlite3
npm install
```

또는 사전 빌드된 패키지를 수동으로 설치합니다.

npm pack better-sqlite3@13.0.1
tar -xzf better-sqlite3-*.tgz -C node_modules
mv node_modules/package node_modules/better-sqlite3
rm better-sqlite3-*.tgz

정상 작동하는지 확인합니다. node -e "require('better-sqlite3')(':memory:').close(); console.log('OK')"

macOS: `dlopen` / “slice is not valid mach-o file”

원인: 전역 npm install -g omniroute 실행 후 패키지 내부의 better-sqlite3 네이티브 바이너리가 로컬에서 실행 중인 환경과 다른 아키텍처 또는 Node.js ABI용으로 컴파일되었을 수 있습니다. 사전 빌드된 바이너리가 사용 환경과 일치하지 않을 때 macOS(Apple Silicon 및 Intel 모두)에서 흔히 발생합니다.

증상:

서버 시작 직후 dlopen 오류와 함께 중단됨
오류에 slice is not valid mach-o file이 포함됨
전체 예시:

dlopen(/Users/&lt;user&gt;/.nvm/versions/node/v24.14.1/lib/node_modules/omniroute/app/node_modules/better-sqlite3/build/Release/better_sqlite3.node, 0x0001): tried: '...' (slice is not valid mach-o file)

해결 방법 — 로컬 환경에 맞게 다시 빌드(Node.js 다운그레이드 불필요):

cd $(npm root -g)/omniroute/app
npm rebuild better-sqlite3
omniroute

참고: 이 작업은 로컬 Node.js 버전 및 CPU 아키텍처에 맞게 네이티브 바인딩을 다시 컴파일하여 바이너리 불일치 문제를 해결합니다. 공식적으로 지원되는 런타임 범위는 **>=22.22.2 <23 또는 >=24.0.0 <27**입니다(src/shared/utils/nodeRuntimeSupport.ts의 SUPPORTED_NODE_RANGE, package.json의 engines 필드와 일치). Node.js 24.x LTS(Krypton)와 Node.js 26은 better-sqlite3 v12.x에서 완전히 지원됩니다.

프록시 문제

공급자 검증 시 “fetch failed”가 표시됨

원인: 이전에는 API 키 검증 엔드포인트(POST /api/providers/validate)가 프록시 구성을 우회했기 때문에 프록시 라우팅이 필요한 환경에서 오류가 발생했습니다.

해결 방법(v3.5.5+): 이제 이 문제가 해결되었습니다. 공급자 검증은 runWithProxyContext를 통해 라우팅되며 공급자 수준 및 전역 프록시 설정을 자동으로 따릅니다.

토큰 상태 확인이 “fetch failed” 오류와 함께 실패함

원인: 백그라운드 OAuth 토큰 갱신 시 연결별 프록시 구성이 확인되지 않았습니다.

해결 방법(v3.5.5+): 이제 토큰 상태 확인 스케줄러가 갱신을 시도하기 전에 연결별 프록시 구성을 확인합니다. v3.5.5+로 업데이트하세요.

SOCKS5 프록시에서 “invalid onRequestStart method”가 반환됨

원인: Node.js 22에서 undici@8 디스패처는 Node에 내장된 fetch() 구현과 호환되지 않습니다.

해결 방법(v3.5.5+): 이제 OmniRoute는 프록시 디스패처가 활성화된 경우 undici 자체의 fetch() 함수를 사용하여 일관된 동작을 보장합니다. v3.5.5+로 업데이트하세요.

WSL 환경의 MITM 프록시: Windows 호스트의 데스크톱 앱이 가로채지지 않음

원인: MITM 프록시와 해당 CA 인증서는 OmniRoute가 실행되는 환경에 설치됩니다. WSL에서 이 환경은 Linux 게스트인 반면, AI 데스크톱 앱(Kiro, Trae, Copilot, Zed, …)은 Windows 호스트에서 실행됩니다. 호스트 앱은 게스트의 인증서 저장소를 신뢰하지 않고 게스트의 시스템 프록시를 통해 라우팅되지 않으므로 데스크톱 트래픽 가로채기가 작동하지 않습니다.

권장 사항: 가로채려는 데스크톱 앱과 동일한 OS에서 OmniRoute를 네이티브로 실행하세요(Windows 앱은 Windows에서, macOS/Linux도 마찬가지). 호스트 앱을 대상으로 하면서 OmniRoute를 WSL 내부에서 계속 실행하려면 생성된 CA 인증서를 Windows 호스트에서 수동으로 신뢰하도록 설정하고, 각 호스트 앱의 네트워크/프록시 설정이 WSL 프록시 엔드포인트를 가리키도록 해야 합니다. 이는 지원되지 않으며 불안정한 구성입니다.

공급자 문제

“Language model did not provide messages”

원인: 공급자 할당량이 소진되었습니다.

해결 방법:

대시보드의 할당량 추적기를 확인합니다
대체 티어가 포함된 콤보를 사용합니다
더 저렴하거나 무료인 티어로 전환합니다

속도 제한

원인: 구독 할당량이 소진되었습니다.

해결 방법:

대체 경로 추가: cc/claude-opus-4-6 → glm/glm-4.7 → if/qwen3.8-max-preview
저렴한 백업으로 GLM/MiniMax 사용

OAuth 토큰 만료

OmniRoute는 토큰을 자동으로 갱신합니다. 문제가 지속되면 다음을 수행하세요.

대시보드 → 공급자 → 다시 연결
공급자 연결을 삭제한 후 다시 추가

Kiro 다중 계정: 두 번째 계정이 첫 번째 계정을 무효화함

원인: Kiro의 백엔드는 OIDC 클라이언트 등록당 하나의 활성 세션만 허용합니다. 두 계정이 등록된 동일한 클라이언트를 공유하는 경우(v3.8.0 이전에 가져온 연결), 한 계정의 토큰을 갱신하면 다른 계정의 갱신 토큰이 무효화됩니다.

해결 방법(v3.8.0+): 영향을 받는 연결을 다시 가져오세요. v3.8.0부터 토큰 가져오기, Google/GitHub 소셜 로그인 또는 자동 가져오기를 통해 생성되는 모든 새로운 Kiro 연결에는 전용 OIDC 클라이언트가 자동으로 등록됩니다. 따라서 연결이 완전히 격리되며, 한 계정을 갱신해도 다른 계정에는 아무런 영향을 주지 않습니다.

v3.8.0 이전에 가져온 연결에는 연결별 클라이언트 등록 정보가 없습니다. 이러한 연결은 공유 소셜 인증 갱신 엔드포인트를 계속 사용합니다. 연결을 격리하려면 대시보드 → 공급자에서 기존 연결을 삭제한 후 세 가지 가져오기 방식 중 하나를 통해 다시 추가하세요.

두 개의 Kiro 계정을 함께 추가하는 방법에 대한 전체 세부 정보와 단계별 지침은 docs/guides/KIRO_SETUP.md를 참조하세요.

클라우드 문제

클라우드 동기화 오류

BASE_URL이 실행 중인 인스턴스를 가리키는지 확인하세요(예: http://localhost:20128)
CLOUD_URL이 클라우드 엔드포인트를 가리키는지 확인하세요(예: https://omniroute.dev)
NEXT_PUBLIC_* 값을 서버 측 값과 일치하게 유지하세요

클라우드에서 `stream=false` 사용 시 500 반환

증상: 비스트리밍 호출 시 클라우드 엔드포인트에서 Unexpected token 'd'...가 발생합니다.

원인: 클라이언트는 JSON을 예상하지만 업스트림이 SSE 페이로드를 반환합니다.

해결 방법: 클라우드 직접 호출에는 stream=true를 사용하세요. 로컬 런타임에는 SSE→JSON 폴백이 포함되어 있습니다.

클라우드가 연결되었다고 표시되지만 “Invalid API key” 발생

로컬 대시보드(/api/keys)에서 새 키를 생성하세요
클라우드 동기화를 실행하세요: Enable Cloud → Sync Now
오래되었거나 동기화되지 않은 키는 클라우드에서 계속 401을 반환할 수 있습니다

Docker 문제

Docker IPv6 / 연결 재설정

증상: curl http://localhost:20128/v1/models가 curl: (56) Recv failure: Connection reset by peer를 반환합니다. 대시보드와 인증되지 않은 엔드포인트는 작동하지만 인증된 엔드포인트는 실패합니다. 인증 문제처럼 보이지만 실제로는 그렇지 않습니다.

원인: docker run -p 20128:20128은 0.0.0.0(IPv4)과 ::(IPv6) 모두에 포트를 공개하지만, 컨테이너 내부 프로세스는 IPv4에서만 수신 대기합니다. localhost가 먼저 ::1로 해석되는 호스트에서는 연결이 뒤에 리스너가 없는 IPv6 공개 포트로 전달되어 연결이 재설정됩니다.

해결 방법:

빠른 진단: curl -4 http://localhost:20128/v1/models를 실행하세요. -4를 사용하면 작동하지만 사용하지 않으면 실패하는 경우, IPv6 바인딩 불일치가 발생한 것입니다.
영구적인 해결 방법: docker run 명령에서 -p 127.0.0.1:20128:20128을 사용해 IPv4에 명시적으로 바인딩하세요:
터미널 창
```
docker run -d --name omniroute --restart unless-stopped --stop-timeout 40 \
  -p 127.0.0.1:20128:20128 -v omniroute-data:/app/data diegosouzapw/omniroute:latest
```
이렇게 하면 IPv4 바인딩이 강제되며, 프록시가 호스트의 모든 인터페이스에 노출되는 것도 방지할 수 있습니다.

CLI 도구가 설치되지 않은 것으로 표시됨

런타임 필드를 확인하세요: curl http://localhost:20128/api/cli-tools/runtime/codex | jq
포터블 모드에서는 runner-cli 이미지 타깃을 사용하세요(CLI 번들 포함)
호스트 마운트 모드에서는 CLI_EXTRA_PATHS를 설정하고 호스트의 bin 디렉터리를 읽기 전용으로 마운트하세요
installed=true이고 runnable=false인 경우: 바이너리를 찾았지만 상태 확인에 실패한 것입니다

빠른 런타임 검증

curl -s http://localhost:20128/api/cli-tools/codex-settings | jq '{installed,runnable,commandPath,runtimeMode,reason}'
curl -s http://localhost:20128/api/cli-tools/claude-settings | jq '{installed,runnable,commandPath,runtimeMode,reason}'
curl -s http://localhost:20128/api/cli-tools/openclaw-settings | jq '{installed,runnable,commandPath,runtimeMode,reason}'

비용 문제

높은 비용

Dashboard → Usage에서 사용량 통계를 확인하세요
기본 모델을 GLM/MiniMax로 변경하세요
중요하지 않은 작업에는 무료 티어(Qoder, Kiro)를 사용하세요
API 키별 비용 예산을 설정하세요: Dashboard → API Keys → Budget

디버깅

로그 파일 활성화

.env 파일에서 APP_LOG_TO_FILE=true를 설정하세요. 애플리케이션 로그는 logs/ 아래에 기록됩니다. 설정에서 호출 로그 파이프라인이 활성화된 경우 요청 아티팩트는 ${DATA_DIR}/call_logs/ 아래에 저장됩니다. 파이프라인 캡처가 활성화된 경우 스트림 청크 페이로드를 제외하려면 CALL_LOG_PIPELINE_CAPTURE_STREAM_CHUNKS=false를 설정하거나, 아티팩트의 최대 크기(KB)를 변경하려면 CALL_LOG_PIPELINE_MAX_SIZE_KB를 조정하세요.

제공자 상태 확인

# 상태 대시보드
http://localhost:20128/dashboard/health

# API 상태 확인
curl http://localhost:20128/api/monitoring/health

런타임 저장소

기본 상태: ${DATA_DIR}/storage.sqlite(제공자, 조합, 별칭, 키, 설정)
사용량: storage.sqlite의 SQLite 테이블(usage_history, call_logs, proxy_logs) + 선택적 ${DATA_DIR}/call_logs/
애플리케이션 로그: <repo>/logs/...(APP_LOG_TO_FILE=true인 경우)
호출 로그 아티팩트: 호출 로그 파이프라인이 활성화된 경우 ${DATA_DIR}/call_logs/YYYY-MM-DD/...

Request Logs 페이지의 Clean history 작업은 call_logs, 레거시 request_detail_logs, 로컬 ${DATA_DIR}/call_logs/ 아티팩트 디렉터리를 삭제합니다.

회로 차단기 문제

공급자가 OPEN 상태에서 멈춤

공급자의 회로 차단기가 OPEN 상태이면 쿨다운이 만료될 때까지 요청이 차단됩니다.

해결 방법:

대시보드 → 설정 → 복원력으로 이동합니다
영향을 받은 공급자의 회로 차단기 카드를 확인합니다
모두 재설정을 클릭하여 모든 차단기를 초기화하거나 쿨다운이 만료될 때까지 기다립니다
재설정하기 전에 공급자를 실제로 사용할 수 있는지 확인합니다

공급자의 회로 차단기가 계속 작동함

공급자가 반복적으로 OPEN 상태가 되는 경우:

대시보드 → 상태 → 공급자 상태에서 장애 패턴을 확인합니다
설정 → 복원력 → 공급자 프로필로 이동하여 장애 임계값을 높입니다
공급자가 API 제한을 변경했거나 재인증을 요구하는지 확인합니다
지연 시간 원격 측정 데이터를 검토합니다. 지연 시간이 길면 시간 초과로 인한 장애가 발생할 수 있습니다

오디오 전사 문제

“지원되지 않는 모델” 오류

첫 번째 세그먼트가 인증 정보를 보유한 공급자인 모델 ID를 사용합니다(openai/whisper-1, openrouter/deepgram/nova-3). deepgram/nova-3만 사용하려면 네이티브 Deepgram 키가 필요합니다.
대시보드 → 공급자에서 공급자가 연결되어 있는지 확인합니다

전사 결과가 비어 있거나 전사에 실패함

지원되는 오디오 형식을 확인합니다: mp3, wav, m4a, flac, ogg, webm
파일 크기가 공급자 제한 이내인지 확인합니다(일반적으로 25MB 미만)
공급자 카드에서 공급자 API 키의 유효성을 확인합니다

변환기 디버깅

형식 변환 문제를 디버깅하려면 대시보드 → 변환기를 사용합니다:

모드	사용 시점
플레이그라운드	입력/출력 형식을 나란히 비교합니다. 실패한 요청을 붙여 넣어 어떻게 변환되는지 확인합니다
채팅 테스터	실시간 메시지를 전송하고 헤더를 포함한 전체 요청/응답 페이로드를 검사합니다
테스트 벤치	여러 형식 조합에 대해 일괄 테스트를 실행하여 문제가 있는 변환을 찾습니다
라이브 모니터	실시간 요청 흐름을 모니터링하여 간헐적인 변환 문제를 포착합니다

일반적인 형식 문제

사고 태그가 표시되지 않음 — 대상 공급자가 사고 기능을 지원하는지와 사고 예산 설정을 확인합니다
도구 호출이 누락됨 — 일부 형식 변환에서는 지원되지 않는 필드가 제거될 수 있습니다. 플레이그라운드 모드에서 확인합니다
시스템 프롬프트가 누락됨 — Claude와 Gemini는 시스템 프롬프트를 서로 다르게 처리합니다. 변환 출력을 확인합니다
SDK가 객체 대신 원시 문자열을 반환함 — v1.x에서 해결되었습니다. 응답 정리기가 OpenAI SDK Pydantic 유효성 검사 실패를 일으키는 비표준 필드(x_groq, usage_breakdown 등)를 제거합니다. v3.x+에서도 이 문제가 계속 발생한다면 이슈를 등록해 주세요.
GLM/ERNIE가 system 역할을 거부함 — v1.x에서 해결되었습니다. 역할 정규화기가 호환되지 않는 모델에 대해 시스템 메시지를 사용자 메시지에 자동으로 병합합니다. v3.x+에서도 이 문제가 계속 발생한다면 이슈를 등록해 주세요.
developer 역할이 인식되지 않음 — v1.x에서 해결되었습니다. OpenAI 이외의 공급자에서는 자동으로 system으로 변환됩니다. v3.x+에서도 이 문제가 계속 발생한다면 이슈를 등록해 주세요.
Gemini에서 json_schema가 작동하지 않음 — v1.x에서 해결되었습니다. 이제 response_format이 Gemini의 responseMimeType + responseSchema로 변환됩니다. v3.x+에서도 이 문제가 계속 발생한다면 이슈를 등록해 주세요.

복원력 설정

자동 속도 제한이 트리거되지 않음

자동 속도 제한은 API 키 제공자에만 적용됩니다(OAuth/구독에는 적용되지 않음).
설정 → 복원력 → 제공자 프로필에서 자동 속도 제한이 활성화되어 있는지 확인하세요.
제공자가 429 상태 코드 또는 Retry-After 헤더를 반환하는지 확인하세요.

지수 백오프 조정

제공자 프로필은 다음 설정을 지원합니다.

기본 지연 시간 — 첫 번째 실패 후의 초기 대기 시간(기본값: 1초)
최대 지연 시간 — 최대 대기 시간 상한(기본값: 30초)
배수 — 연속 실패마다 지연 시간을 늘리는 정도(기본값: 2배)

썬더링 허드 방지

동시에 발생한 많은 요청이 속도 제한된 제공자에 도달하면 OmniRoute는 뮤텍스 + 자동 속도 제한을 사용하여 요청을 직렬화하고 연쇄적인 실패를 방지합니다. API 키 제공자에서는 자동으로 적용됩니다.

채팅 요청이 503 / chat_admission_busy로 실패함

증상:

채팅 완성 엔드포인트가 재시도 가능한 503 응답을 반환하며, 오류 코드는 chat_admission_busy입니다.
응답에는 Retry-After가 포함됩니다. #12135부터 이 값은 관찰된 점유 상태를 기반으로 산출됩니다. 요청이 이미 대기한 OMNIROUTE_CHAT_ADMISSION_QUEUE_MS 시간 범위와 현재 고부하 리스가 유지된 시간 중 더 큰 값을 사용하며, 초 단위 정수로 올림한 뒤 최대 60으로 제한합니다. 게이트가 유휴 상태일 때는 기존 최솟값이 유지됩니다. 바이트 기반 경로에서는 2초, 구조 기반 경로에서는 1초입니다(구조 기반 경로에는 reason: "structure_limit"도 포함됨).
다른 고부하 채팅이나 장시간 실행되는 스트리밍 응답이 아직 처리 중일 때 이러한 문제가 발생할 수 있습니다.

바이트 기반 응답 본문은 다음과 같습니다.

{
  "error": {
    "message": "Chat admission capacity is temporarily unavailable. Retry shortly.",
    "type": "server_error",
    "code": "chat_admission_busy"
  }
}

구조 기반 응답은 동일한 유형과 코드를 사용하며, 메시지는 Local chat admission capacity is busy for this structurally heavy request; upstream provider routing was not attempted. Retry shortly. 이고 reason: "structure_limit"가 포함됩니다. 기본 임계값에서 요청에 메시지가 200개 이상이거나, 도구가 64개 이상이거나, 예상 토큰이 32,000개 이상이면 구조적으로 고부하인 것으로 간주됩니다. 또한 제한된 구조 추정이 방문 노드 10,000개 또는 깊이 12의 한계에 도달하는 경우에도 마찬가지입니다.

원인: 이는 업스트림 제공자의 실패가 아니라 OmniRoute 내부의 의도적인 부하 차단입니다. 각 프로세스는 프로세스 로컬 가드를 사용하여 대용량 요청 본문을 보존하고 파싱하기 전에 제한된 고부하 처리 용량을 예약합니다. 고부하 리스는 SSE 응답의 전체 수명 동안 유지됩니다.

#503-팬아웃: 이 수정 전에는 가드가 호스트 메모리와 관계없이 동시성을 고정된 요청 개수 (OMNIROUTE_CHAT_MAX_HEAVY_IN_FLIGHT, 기본값 1)로 제한했습니다. 이 때문에 코딩 에이전트 팬아웃(여러 하위 에이전트/CLI, 통상적으로 256 KB를 초과하는 본문)은 유효 동시성이 약 1로 급감했으며, 완전히 정상적인 부하에서도 503 오류가 발생했습니다. 이제 가드는 자체 조정됩니다. 프로세스의 실제 메모리 상한을 기반으로 크기가 정해지는 자동 산출 수집 바이트 예산 (OMNIROUTE_CHAT_MAX_INFLIGHT_BYTES)으로 제어되며, 실시간 리소스 압력 신호도 참조합니다. 따라서 동시에 둘 이상의 고부하 요청이 도착했다는 이유만으로 차단하지 않고, 호스트가 실제로 메모리 압력을 받는 경우에만 부하를 차단합니다. 이전 개수 상한 (OMNIROUTE_CHAT_MAX_HEAVY_IN_FLIGHT)도 계속 적용되지만, 명시적으로 설정한 경우에만 적용됩니다.

용량이 사용 중이면 고부하 요청은 재시도 가능한 503으로 응답하기 전에 슬롯이 비워질 때까지 먼저 최대 OMNIROUTE_CHAT_ADMISSION_QUEUE_MS(기본값 2000, 0은 대기 비활성화) 동안 대기합니다. 이 제한된 대기는 고부하 하위 요청을 동시에 팬아웃하는 에이전트형 클라이언트 (OpenCode, Claude Code, Cursor)가 즉시 거부되어 전체 재시도 예산을 소진하고 작업 도중 중단되는 대신, 요청 버스트를 직렬화할 수 있도록 하기 위한 것입니다. 현재 고부하 리스 점유율, 결정된 바이트 예산 및 실시간 압력 심각도는 GET /api/monitoring/health → chatAdmission(inflightBytes, maxInflightBytes, budgetSource, pressureSeverity, countCapEnabled)에서 확인할 수 있습니다. 환경 변수를 변경하기 전에 이를 확인하세요. 설정 → 복원력 → 요청 대기열 → 동시 요청은 이를 제어하지 않습니다. 해당 설정은 별도의 제공자 요청 대기열 메커니즘을 제어합니다.

해결 방법:

먼저 재시도하세요. 클라이언트는 요청을 즉시 반복하는 대신 Retry-After를 준수하고 백오프를 사용해야 합니다.
설정을 조정하기 전에 /api/monitoring/health → chatAdmission을 확인하세요. countCapEnabled: false이고 maxInflightBytes가 충분히 크다면 자동 산출된 예산이 이미 정상적으로 작동하고 있다는 뜻입니다. pressureSeverity가 high/critical이면 호스트의 메모리가 실제로 부족하다는 뜻입니다. 이는 승인 관련 환경 변수로 해결할 수 없으며, RAM을 늘리거나 워크로드를 줄여야 합니다.
/api/monitoring/health에서 자동 산출된 예산이 호스트에 비해 실제로 너무 작다고 표시되는 경우에만(드문 경우이며, 컨테이너에서 베어메탈까지 이미 확장됨) 기존 요청 개수 상한으로 되돌아가는 대신 OMNIROUTE_CHAT_MAX_INFLIGHT_BYTES를 사용하여 직접 재정의하세요.

공식 승인 설정은 환경 변수 참조를 확인하세요.

선택 사항: RAG / LLM 장애 분류 체계(16가지 문제)

일부 OmniRoute 사용자는 RAG 또는 에이전트 스택 앞단에 게이트웨이를 배치합니다. 이러한 구성에서는 이상한 패턴이 흔히 나타납니다. OmniRoute는 정상으로 보이지만(프로바이더가 작동 중이고, 라우팅 프로필도 정상이며, 속도 제한 알림도 없음) 최종 답변은 여전히 잘못되는 경우입니다.

실제로 이러한 인시던트는 대개 게이트웨이 자체가 아니라 다운스트림 RAG 파이프라인에서 발생합니다.

이러한 장애를 설명하기 위한 공통 용어 체계가 필요하다면 WFGY ProblemMap을 사용할 수 있습니다. 이는 반복적으로 발생하는 16가지 RAG / LLM 장애 패턴을 정의한 외부 MIT 라이선스 텍스트 리소스입니다. 개괄적으로 다음 항목을 다룹니다.

검색 편향 및 손상된 컨텍스트 경계
비어 있거나 오래된 인덱스 및 벡터 저장소
임베딩과 의미 간 불일치
프롬프트 조합 및 컨텍스트 창 문제
논리 붕괴 및 과도하게 확신하는 답변
긴 체인 및 에이전트 조정 장애
멀티 에이전트 메모리 및 역할 편향
배포 및 부트스트랩 순서 문제

방법은 간단합니다.

잘못된 응답을 조사할 때 다음을 기록합니다.
- 사용자 작업 및 요청
- OmniRoute의 경로 또는 프로바이더 조합
- 다운스트림에서 사용된 모든 RAG 컨텍스트(검색된 문서, 도구 호출 등)
인시던트를 하나 또는 두 개의 WFGY ProblemMap 번호(No.1 … No.16)에 매핑합니다.
OmniRoute 로그 옆에 있는 자체 대시보드, 런북 또는 인시던트 추적기에 해당 번호를 저장합니다.
해당 WFGY 페이지를 사용하여 RAG 스택, 검색기 또는 라우팅 전략을 변경해야 하는지 판단합니다.

전체 텍스트와 구체적인 방법은 다음에서 확인할 수 있습니다(MIT 라이선스, 텍스트 전용).

WFGY ProblemMap README

OmniRoute 뒤에서 RAG 또는 에이전트 파이프라인을 실행하지 않는다면 이 섹션은 무시해도 됩니다.

v3.8.0 알려진 문제

v3.8.0 릴리스에만 해당하는 문제와 현재 해결 방법입니다. 이후 패치에서 수정 사항이 적용되면 해당 항목이 업데이트되거나 제거됩니다.

Devin CLI 인증 실패

증상:

Devin 기반 도구를 호출할 때 “Devin CLI not found” 또는 “auth failed”가 표시됨
CLI 런타임 검사에서 installed=false가 보고됨

원인:

CLI_DEVIN_BIN이 존재하지 않는 경로를 가리킴
호스트에 Devin CLI가 설치되어 있지 않음

해결 방법:

플랫폼에 맞는 Devin CLI를 설치합니다.
.env에서 CLI_DEVIN_BIN=/usr/local/bin/devin(또는 실제 경로)을 설정합니다.
OmniRoute를 다시 시작하고 Dashboard → CLI Tools에서 다시 테스트합니다.

모델 쿨다운 고착(수동 재설정)

증상:

만료 시간이 지났는데도 모델이 계속 쿨다운 상태로 표시됨
타임스탬프가 과거인데도 조합 라우팅에서 해당 모델을 계속 건너뜀

수동 재설정:

대시보드: Settings → Model Cooldowns → 영향을 받은 카드에서 Re-enable을 클릭합니다.
API: 관리 인증 헤더와 함께 DELETE /api/resilience/model-cooldowns를 호출합니다.

Command Code 프로바이더 연결이 403으로 실패함

증상:

Command Code 프로바이더 연결을 테스트할 때 403이 발생함
새로 추가한 후 프로바이더 카드에 “unauthorized”가 표시됨

원인: OAuth 흐름이 완료되지 않았습니다(콜백을 받지 못했거나 토큰이 저장되지 않음).

해결 방법:

CLI에서 omniroute providers를 실행하여 OAuth 흐름을 다시 시작하거나
Dashboard → Providers → Command Code → Reconnect에서 OAuth를 다시 실행합니다.

ModelScope에서 과도한 429 쿨다운이 발생함

증상:

적은 수의 요청이 짧은 시간에 집중된 후 ModelScope에서 매우 짧거나 즉각적인 쿨다운이 발생함
조합 라우팅이 예상보다 일찍 ModelScope를 건너뜀

원인: ModelScope는 프로바이더별 Retry-After 헤더를 생성합니다. v3.8.0에는 이러한 헤더를 위한 전용 처리 기능이 포함되어 있으므로, 이전 버전에서는 이를 일반적인 속도 제한 힌트로 잘못 해석합니다.

해결 방법:

v3.8.0 이상을 사용 중인지 확인합니다.
Settings → Resilience에서 useUpstream429BreakerHints 토글이 활성화되어 있는지 확인합니다.

프로덕션에서 OMNIROUTE_WS_BRIDGE_SECRET 누락

증상:

원격 프로덕션 호스트에서 실행할 때 모든 Codex/Responses WebSocket 브리지 요청에 401이 발생함
연결 직후 WebSocket 브리지 핸드셰이크가 즉시 종료됨

원인: 프로덕션 환경에 OMNIROUTE_WS_BRIDGE_SECRET 환경 변수가 없습니다.

해결 방법:

임의의 시크릿을 생성합니다: openssl rand -hex 32
프로덕션 서버 환경 및 브리지와 통신하는 모든 클라이언트에서 OMNIROUTE_WS_BRIDGE_SECRET=<random-secret>을 설정합니다.
OmniRoute를 다시 시작합니다.

Responses API: 백그라운드 모드가 동기식으로 강등됨

증상:

다음 경고가 로그에 기록됨: background mode degraded to synchronous
background: true 요청이 백그라운드 작업 핸들 대신 일반 동기식 응답을 반환함

원인: v3.8.0에서는 경고를 출력하면서 Responses API의 background: true를 의도적으로 동기식 실행으로 강등합니다. 완전한 비동기 백그라운드 실행은 향후 제공될 예정입니다.

해결 방법:

background 없이 호출하도록 클라이언트를 조정하거나
완전한 비동기 백그라운드 모드가 포함된 이후 릴리스를 기다립니다(변경 로그에서 추적).

느린 시작 / 준비 상태 시간 초과

CLI에 ⚠ Server did not respond within 60s가 표시되지만 서버가 실제로 작동 중이라면, 현재 환경에 설정된 준비 상태 검사 제한 시간이 너무 짧은 것입니다.

이 문제는 Windows(바이러스 백신, 파일 시스템 감시 도구) 또는 시작 작업 부하가 큰 컨테이너에서 흔히 발생합니다.

해결 방법 — 제한 시간 늘리기:

# 환경 변수 사용(시작할 때마다 유지됨):
export OMNIROUTE_READY_TIMEOUT_MS=180000   # 3분
omniroute serve

# CLI 플래그 사용(일회성):
omniroute serve --ready-timeout 180000

기본값은 60 000ms(60초)입니다. 이 경고는 정보 제공용일 뿐입니다. 서버는 백그라운드에서 계속 시작되며 부팅이 완료되면 접근할 수 있습니다.

OMNIROUTE_READY_TIMEOUT_MS에 대한 자세한 내용은 docs/reference/ENVIRONMENT.md를 참조하세요.

여전히 해결되지 않나요?

GitHub 이슈: github.com/diegosouzapw/OmniRoute/issues
아키텍처: 내부 세부 정보는 docs/architecture/ARCHITECTURE.md를 참조하세요
API 참조 문서: 모든 엔드포인트는 docs/reference/API_REFERENCE.md를 참조하세요
상태 대시보드: 실시간 시스템 상태는 Dashboard → Health에서 확인하세요
변환기: 형식 문제를 디버깅하려면 Dashboard → Translator를 사용하세요

OmniRoute 소스 코드 (a58000c7685f)

HagiCode

HagiCode는 구조화된 워크플로, 다중 에이전트 실행, Hero Dungeon 뷰를 갖춘 에이전트 코딩 작업 공간입니다.

더 스마트하고 빠르며 즐거운 에이전트 워크플로로 유용한 소프트웨어를 만드세요.

Smart구조화된 워크플로는 의도를 아이디어부터 배포까지 실행 가능한 경로로 바꿉니다.
Efficient다중 에이전트 워크플로로 조사, 구현, 검토를 병렬로 진행합니다.
FunHero Dungeon은 긴 코딩 세션을 시각적이고 협업적인 경험으로 만듭니다.

HagiCode 방문

Troubleshooting (한국어)

빠른 참조

상세 문제 해결

무료 제공업체의 요청 속도 제한(429 / 400 / 401)

npm install 경고(ERESOLVE / peer / deprecated)

Gemini Web 및 Playwright Chromium

빠른 해결 방법

백신 오탐

Avast/AVG가 README.md를 MD:HttpRequest-inf[Susp]로 격리하는 문제

Kaspersky가 데스크톱 앱을 PDM:Trojan.Win32.Generic으로 표시하는 문제

Node.js 호환성

로그인 페이지가 중단되거나 “Module self-registration” 오류가 표시됨

npm v11+: better-sqlite3이 설치되지 않음(Cannot find module)

macOS: dlopen / “slice is not valid mach-o file”

프록시 문제

공급자 검증 시 “fetch failed”가 표시됨

토큰 상태 확인이 “fetch failed” 오류와 함께 실패함

SOCKS5 프록시에서 “invalid onRequestStart method”가 반환됨

WSL 환경의 MITM 프록시: Windows 호스트의 데스크톱 앱이 가로채지지 않음

공급자 문제

“Language model did not provide messages”

속도 제한

OAuth 토큰 만료

Kiro 다중 계정: 두 번째 계정이 첫 번째 계정을 무효화함

클라우드 문제

클라우드 동기화 오류

클라우드에서 stream=false 사용 시 500 반환

클라우드가 연결되었다고 표시되지만 “Invalid API key” 발생

Docker 문제

Docker IPv6 / 연결 재설정

CLI 도구가 설치되지 않은 것으로 표시됨

빠른 런타임 검증

비용 문제

높은 비용

디버깅

로그 파일 활성화

제공자 상태 확인

런타임 저장소

회로 차단기 문제

공급자가 OPEN 상태에서 멈춤

공급자의 회로 차단기가 계속 작동함

오디오 전사 문제

“지원되지 않는 모델” 오류

전사 결과가 비어 있거나 전사에 실패함

변환기 디버깅

일반적인 형식 문제

복원력 설정

자동 속도 제한이 트리거되지 않음

지수 백오프 조정

썬더링 허드 방지

채팅 요청이 503 / chat_admission_busy로 실패함

선택 사항: RAG / LLM 장애 분류 체계(16가지 문제)

v3.8.0 알려진 문제

Devin CLI 인증 실패

모델 쿨다운 고착(수동 재설정)

Command Code 프로바이더 연결이 403으로 실패함

ModelScope에서 과도한 429 쿨다운이 발생함

프로덕션에서 OMNIROUTE_WS_BRIDGE_SECRET 누락

Responses API: 백그라운드 모드가 동기식으로 강등됨

느린 시작 / 준비 상태 시간 초과

여전히 해결되지 않나요?

HagiCode

Avast/AVG가 `README.md`를 `MD:HttpRequest-inf[Susp]`로 격리하는 문제

Kaspersky가 데스크톱 앱을 `PDM:Trojan.Win32.Generic`으로 표시하는 문제

npm v11+: `better-sqlite3`이 설치되지 않음(Cannot find module)

macOS: `dlopen` / “slice is not valid mach-o file”

클라우드에서 `stream=false` 사용 시 500 반환