2026년 OmniRoute Cursor 설정: 다중 모델 게이트웨이

Cursor와 Claude Code에 같은 http://localhost:20128/v1 주소를 넣었더니 한쪽이 인증 오류를 반환합니다.

가장 빠른 해결법은 같은 OmniRoute 인스턴스를 사용하되 Claude Code에는 /v1 없는 루트 주소를 넣고, Cursor는 데스크톱과 CLI를 나눠 설정하는 것입니다.

이 글이 필요한 사용자

Cursor와 Claude Code를 동시에 사용하면서 모델 인증 정보와 라우팅 규칙을 한곳에서 관리하려는 개인 개발자에게 적합합니다.
원격 맥에서 AI Gateway와 코딩 에이전트를 계속 실행하려는 엔지니어, 여러 제공자에 장애 대응 경로를 만들려는 소규모 팀의 기술 책임자도 대상입니다.

마지막 업데이트: 2026년 8월 12일
명령과 endpoint는 OmniRoute 최신 CLI 도구 표, Claude Code 공식 게이트웨이 문서, Cursor 공식 문서를 기준으로 확인했습니다.

같은 서버와 같은 주소는 서로 다른 개념입니다

대표적인 실패 설정은 다음과 같습니다.

Cursor      → http://localhost:20128/v1
Claude Code → http://localhost:20128/v1
OmniRoute   → 여러 모델 제공자

문제는 두 클라이언트가 주소 뒤에 붙은 경로를 같은 방식으로 처리하지 않는다는 점입니다.

OmniRoute의 OpenAI 호환 입구는 보통 /v1 경로를 사용합니다. 반면 Claude Code는 Anthropic Messages API 형식으로 게이트웨이에 연결하며, ANTHROPIC_BASE_URL에는 게이트웨이 루트 주소를 넣어야 합니다. Claude Code가 뒤에 /v1/messages를 붙이므로 주소에 /v1을 다시 넣으면 경로가 겹칠 수 있습니다. OmniRoute의 Claude Code 설정 문서와 Claude Code의 공식 게이트웨이 안내에서 이 연결 방식을 확인할 수 있습니다.

요청 흐름은 다음처럼 이해하면 됩니다.

Cursor 데스크톱 또는 Cursor CLI
              │
              ├─ 호환 입구
              │
Claude Code ──┤
              ▼
       하나의 OmniRoute 인스턴스
              │
       자동 라우팅과 fallback
              │
    여러 모델 제공자와 인증 키

즉, 통합되는 것은 서버와 라우팅 정책입니다. 클라이언트의 설정 문자열, 인증 변수, 지원 기능까지 같아지는 것은 아닙니다.

서비스부터 모델 목록까지 최소 경로를 닫습니다

모델 설정을 먼저 만지면 원인을 놓치기 쉽습니다. 다음 순서로 서비스 자체를 확인합니다.

1. OmniRoute를 설치하고 실행합니다.
2. 대시보드에서 추론용 API 키를 만듭니다.
3. 클라이언트와 같은 컴퓨터라면 localhost로 연결합니다.
4. /health 응답을 확인합니다.
5. /v1/models 응답을 확인합니다.
6. 실제 대화 요청을 한 번 보냅니다.
7. 그 뒤에 Cursor와 Claude Code를 각각 연결합니다.

로컬 실행 예시는 다음처럼 구성합니다.

export OMNIROUTE_API_KEY="<여기에_게이트웨이_키>"

curl http://localhost:20128/health

curl http://localhost:20128/v1/models \
  -H "Authorization: Bearer $OMNIROUTE_API_KEY"

OmniRoute의 CLI 통합 문서에서는 로컬 기본 포트를 20128로 설명하며, 실행 중인 서버에서 모델 목록을 읽어 각 도구의 설정을 생성합니다. CLI 통합 표와 원격 옵션을 기준으로 확인할 수 있습니다.

최소 대화 요청은 사용 중인 모델 식별자로 바꿔 실행합니다.

curl http://localhost:20128/v1/chat/completions \
  -H "Authorization: Bearer $OMNIROUTE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "<provider>/<model>",
    "messages": [
      {"role": "user", "content": "응답 경로를 확인해 주세요."}
    ]
  }'

대시보드가 열린다고 연결이 끝난 것은 아닙니다. 다음 세 가지 응답을 모두 확보해야 합니다.

• 건강 확인 요청이 성공함
• 모델 목록에 실제 사용할 모델이 나타남
• 최소 대화 요청이 응답하고 최종 모델 정보가 로그에 남음

주의: localhost는 요청을 보낸 컴퓨터 자신을 뜻합니다. OmniRoute를 원격 맥에 설치했다면 노트북의 localhost가 아니라 원격 맥에서 접근 가능한 주소를 사용해야 합니다. 외부 전체에 포트를 열기보다 사설 네트워크, 터널, 방화벽 허용 목록으로 범위를 제한해야 합니다.

Claude Code는 루트 주소로 연결합니다

Claude Code에 /v1을 붙여야 하나요?

붙이지 않는 것이 기본입니다. 다음처럼 설정합니다.

export ANTHROPIC_BASE_URL="http://localhost:20128"
export ANTHROPIC_AUTH_TOKEN="<여기에_게이트웨이_키>"
export ANTHROPIC_MODEL="<provider>/<model>"

ANTHROPIC_API_KEY를 대체 인증 변수로 사용할 수도 있지만, 두 인증 변수를 동시에 넣으면 우선순위를 예측하기 어려워집니다. 한 가지 방식만 남기는 편이 안전합니다. 환경 변수를 바꾼 뒤에는 Claude Code 프로세스를 완전히 종료하고 다시 시작해야 합니다. OmniRoute 문서도 환경 변수가 시작 시점에 읽힌다고 설명합니다. OmniRoute의 Claude Code 설정 문서

주 흐름은 자동 실행 명령을 이용하는 방식입니다.

omniroute launch \
  --remote "http://<원격_맥_주소>:20128" \
  --api-key "<여기에_게이트웨이_키>"

로컬 서버라면 다음처럼 실행합니다.

omniroute launch

모델별 프로필이 필요하면 다음 순서를 사용합니다.

omniroute setup-claude
omniroute launch --profile "<생성된_프로필>"

이 방식은 서버 상태와 모델 목록을 먼저 확인한 뒤 Claude Code를 실행하는 장점이 있습니다. 수동 설정이 필요하다면 settings.json 안의 env 항목에 같은 변수를 넣을 수 있습니다. 다만 키를 설정 파일에 직접 저장하지 말고 셸 환경 변수나 비밀 저장소를 이용해야 합니다.

Claude Code의 모델 선택기에 모든 OmniRoute 모델이 표시된다고 기대하면 안 됩니다. OmniRoute 문서에 따르면 게이트웨이 모델 검색을 켜도 목록 노출에는 모델 이름 조건이 있습니다. 비표준 모델은 ANTHROPIC_MODEL로 명시해야 합니다.

export CLAUDE_CODE_ENABLE_GATEWAY_MODEL_DISCOVERY="1"
export ANTHROPIC_MODEL="<provider>/<model>"

Anthropic 공식 문서도 외부 게이트웨이가 Claude Code의 기능과 요청 형식을 계속 전달해야 하며, 비 Claude 모델 라우팅은 게이트웨이 구현에 달려 있다고 설명합니다. 따라서 모델 목록이 비어 있을 때는 제공자 연결, 모델 식별자, 검색 기능을 따로 점검해야 합니다. Claude Code 공식 게이트웨이 안내

Cursor 데스크톱과 CLI는 같은 입구가 아닙니다

OmniRoute의 Cursor 설정 명령은 데스크톱 설정 파일을 직접 덮어쓰는 방식이 아닙니다. 현재 문서상 omniroute setup-cursor는 Cursor 내부 설정에 입력할 절차를 출력합니다. Cursor 설정은 일반 텍스트 파일이 아니라 내부 저장 구조를 사용하기 때문입니다. CLI 통합 표와 원격 옵션

Cursor 데스크톱에서는 먼저 외부 API 키가 적용되는 모델 범위를 확인해야 합니다. Cursor 공식 문서에 따르면 사용자 API 키는 표준 채팅 모델에 적용되지만, 탭 자동 완성처럼 특수 모델이 필요한 기능은 Cursor 자체 모델을 계속 사용할 수 있습니다. 따라서 “Cursor의 모든 기능이 OmniRoute를 거친다”고 가정하면 안 됩니다. Cursor API 키 공식 안내를 기준으로 기능별 적용 범위를 확인합니다.

Cursor CLI는 데스크톱의 모델 설정 화면과 다릅니다. 공식 CLI 문서에는 인증 상태 확인, API 키, 사용자 지정 endpoint 옵션이 별도로 안내되어 있습니다. Cursor CLI 인증 문서와 CLI 매개 변수 문서를 기준으로 실행합니다.

export CURSOR_API_KEY="<여기에_키>"

cursor-agent status

cursor-agent \
  --endpoint "http://localhost:20128/v1" \
  "간단한 코드 검토를 실행해 주세요."

이때 MCP를 endpoint 설정으로 착각하면 안 됩니다. MCP는 도구와 외부 작업 서버를 연결하는 경로입니다. Cursor 데스크톱의 표준 채팅, Cursor CLI의 모델 요청, MCP 도구 호출은 각각 별도로 성공해야 합니다.

모델은 바뀌는데 fallback은 왜 멈출까요?

단일 모델 직접 호출과 자동 라우팅은 다릅니다.

• 단일 모델 호출: 지정한 제공자 하나만 사용합니다.
• 자동 라우팅: OmniRoute가 정책에 따라 대상을 선택합니다.
• 사용자 지정 fallback: 첫 대상이 실패했을 때 다음 대상을 정한 순서로 시도합니다.

fallback을 검증하려면 연결된 제공자가 적어도 2개 있어야 합니다. 첫 모델 하나만 연결한 상태에서는 전환 경로가 존재하지 않습니다. 또한 단순히 모델 목록에 여러 이름이 보이는 것과 실제로 서로 다른 인증 키를 통해 요청이 가능한 것은 다릅니다.

모델 한도의 소진 뒤 자동 전환이 일어나지 않는다면 무엇부터 봐야 하나요?

다음 조건을 순서대로 확인합니다.

1. 첫 번째 제공자의 인증 키가 만료되지 않았는지 확인합니다.
2. 두 번째 제공자가 같은 요청 형식을 지원하는지 확인합니다.
3. fallback 체인에 두 모델이 실제로 등록됐는지 확인합니다.
4. 오류가 재시도 가능한 오류인지 확인합니다.
5. 최종 응답의 모델 식별자를 확인합니다.
6. OmniRoute 라우팅 로그에서 건너뛴 대상과 선택된 대상을 확인합니다.

반복 가능한 장애 훈련은 다음처럼 진행합니다.

첫 번째 모델: <provider-a>/<model-a>
두 번째 모델: <provider-b>/<model-b>

1. 첫 번째 키를 일시적으로 비활성화합니다.
2. 같은 프롬프트를 다시 보냅니다.
3. 오류 로그에 첫 번째 실패가 남는지 확인합니다.
4. 최종 응답이 두 번째 모델에서 왔는지 확인합니다.
5. 첫 번째 키를 복구하고 같은 요청을 다시 실행합니다.

프로젝트 문서에는 자동으로 실패한 제공자를 건너뛰고 다음 대상을 시도하는 동작이 설명되어 있습니다. 다만 무료 사용량, 제공자 수, 압축 효과 같은 수치는 프로젝트 자체 설명이므로 독립적인 성능 측정값으로 해석하면 안 됩니다. OmniRoute 빠른 시작 문서의 설명도 이 범위에서만 참고해야 합니다.

어떤 배포 방식을 선택할지 조건으로 나눕니다

다음 조건으로 결정하면 설정을 불필요하게 복잡하게 만들지 않을 수 있습니다.

• OmniRoute와 두 클라이언트가 한 대의 맥에 있고 짧게 테스트한다면
  localhost로 구성합니다. 가장 빠르고 외부 노출이 없습니다.

• 맥이 잠자기 상태가 되거나 네트워크가 자주 바뀐다면
  지속 실행되는 원격 맥으로 옮깁니다. 클라이언트에는 원격 주소를 넣고 접근 키를 분리합니다.

• Cursor 데스크톱 표준 채팅만 필요하다면
  Cursor의 사용자 API 키와 호환 입구를 먼저 검증합니다. 자동 완성과 내장 기능까지 같은 경로라고 가정하지 않습니다.

• Cursor CLI와 Claude Code를 자동화하려면
  Claude Code는 omniroute launch 또는 ANTHROPIC_BASE_URL을 사용하고, Cursor CLI는 자체 endpoint 옵션을 별도로 확인합니다.

• 팀원이 같은 게이트웨이를 공유한다면
  개인별 키를 발급하고 서버 접근 범위를 제한합니다. 하나의 관리자 키를 모든 개발자에게 복사하지 않습니다.

원격 배포에서는 서비스가 실제로 접근 가능한지부터 확인합니다.

curl "http://<원격_맥_주소>:20128/health"

curl "http://<원격_맥_주소>:20128/v1/models" \
  -H "Authorization: Bearer <여기에_게이트웨이_키>"

원격 맥을 선택할 때는 온라인 유지 시간, 여러 기기에서의 접근, 팀 공유 여부를 기준으로 판단합니다. 직접 운영하는 맥은 물리 자원과 권한을 통제하기 쉽지만, 잠자기 설정, 네트워크 변경, 재부팅 뒤 자동 시작을 직접 관리해야 합니다. 반대로 지속 실행되는 클라우드 맥은 이런 중단 요인을 줄일 수 있지만, 장시간 고정 부하가 필요하지 않은 단기 테스트에는 과할 수 있습니다.

최종 인수 확인표

다음 항목을 모두 통과한 뒤에 팀에 배포합니다.

현재 노트북에서 실행하는 구성은 짧은 테스트와 개인 작업에 적합합니다. 하지만 노트북을 닫거나 잠자기 상태로 두면 Cursor와 Claude Code 모두 게이트웨이에 접근할 수 없습니다. 네트워크가 바뀌면 localhost 구성도 작업 환경에 따라 달라집니다.

이런 이유로 개인 단기 검증은 로컬에서 끝내고, 지속 실행과 여러 기기 접근이 필요해지는 시점에 원격 맥으로 옮기는 방식이 가장 안전합니다. 원격 개발 환경의 온라인 유지 조건과 접속 방식을 더 세밀하게 비교하려면 MacHTML 원격 맥 콘솔 안내와 MacHTML 도움말을 함께 확인하면 됩니다.

마지막으로 현재 방식과 맥 대여 방식을 비교해 보십시오. 개인 맥에서 OmniRoute를 계속 실행하면 잠자기, 네트워크 변경, 재부팅 뒤 수동 복구가 반복될 수 있습니다. 팀원이 같은 게이트웨이를 쓰려면 포트 공개와 키 권한도 직접 관리해야 합니다. 반면 MacHTML의 지속 실행 환경을 사용하면 개발용 맥을 별도로 점유하지 않고, 원격 접속을 기준으로 Cursor와 Claude Code를 운영할 수 있습니다. 단기 실험이나 물리 장치 접근이 필요한 작업은 로컬 맥이 낫지만, 온라인 상태와 복구 절차가 중요한 AI Agent 작업이라면 원격 맥 대여가 더 관리하기 쉬운 선택입니다.

더 읽기: 여러 인공지능 코딩 도구를 함께 쓸 때 필요한 연산 자원 살펴보기 모델 장애에 대비한 게이트웨이 전환과 공급자 경로 설정 익히기