Cursor / Claude Code / Cherry Studio를 커스텀 AI 게이트웨이에 연결하는 가이드
주요 AI 도구는 모두 커스텀 API를 지원합니다——즉, 자신의 게이트웨이(4-4 AI 등)로 방향을 바꿔 키와 과금을 통일할 수 있습니다. 본문은 가장 많이 쓰는 세 도구의 설정 방법과 공통 오류 해결 사고방식을 다룹니다.
https://www.4-4.vip/v1)을 예로 하며 다른 OpenAI 호환 게이트웨이도 마찬가지입니다.Cursor
Cursor의 대화 모델은 커스텀 OpenAI 호환 인터페이스를 사용할 수 있습니다:
Settings → Models열기(또는Models설정 페이지);OpenAI API Key영역을 펼쳐 설정: 게이트웨이 키(sk-...) 입력;Override OpenAI Base URL체크/입력:https://www.4-4.vip/v1;- 모델 목록에 게이트웨이에서 사용 가능한 모델명 추가(게이트웨이 채널명과 완전히 일치, 대소문자 구분);
- Verify 클릭해 검증이 통과되면 대화 하단에서 커스텀 모델로 전환하면 됩니다.
참고: Cursor 내장 Tab 보완, Composer 일부 기능은 Cursor 자체 서비스를 사용하므로 이 설정의 영향을 받지 않습니다. 커스텀 모델은 주로 Chat 대화에 사용됩니다.
Claude Code
Claude Code는 Anthropic 프로토콜을 사용합니다. 게이트웨이 연결의 전제는 게이트웨이가 Anthropic 프로토콜 엔드포인트(/v1/messages)를 지원하는 것입니다——new-api 생태계 기반 게이트웨이(4-4 AI 포함)는 이 프로토콜 변환을 지원하며, Claude 프로토콜 요청은 변환되어 실제 모델 채널로 라우팅됩니다.
환경 변수로 설정합니다(claude를 시작하는 터미널에서):
export ANTHROPIC_BASE_URL="https://www.4-4.vip"
export ANTHROPIC_AUTH_TOKEN="sk-YOUR_GATEWAY_KEY"
# start
claude
Windows PowerShell에서는:
$env:ANTHROPIC_BASE_URL = "https://www.4-4.vip"
$env:ANTHROPIC_AUTH_TOKEN = "sk-YOUR_GATEWAY_KEY"
Cherry Studio
Cherry Studio는 커스텀 OpenAI 호환 공급자 지원이 가장 직접적입니다:
설정 → 모델 서비스에서 OpenAI 호환 공급자 추가/선택;- API 주소에
https://www.4-4.vip/v1입력(일부 버전은 /v1을 자동 보완하니 중복 주의); - API 키에 게이트웨이 키 입력;
- 모델 관리에서 사용 가능한 모델명을 수동 추가하고 저장 후 대화에서 선택.
공통 법칙: 모든 OpenAI 호환 도구
시중의 많은 도구(LobeChat, Open WebUI, 몰입형 번역, 각종 IDE 플러그인)의 설정 절차는 같습니다. 세 가지 세트를 기억하세요:
| 설정 항목 | 값 | 흔한 함정 |
|---|---|---|
| Base URL | https://www.4-4.vip/v1 | 도구에 따라 /v1을 붙이는 경우와 붙이지 않는 경우가 있습니다——404가 나오면 먼저 /v1 붙였다 뗐다 해보세요 |
| API Key | 게이트웨이 키(sk-...) | 앞뒤 공백, 키 만료, 크레딧 소진 |
| 모델명 | 게이트웨이 채널의 이름 | 게이트웨이 측과 완전히 일치해야 하며 도구 프리셋에 없는 이름은 사용 불가 |
오류 해결 매뉴얼(빠른 참조)
401 Unauthorized
- 키 복사에 공백/줄바꿈이 섞임 → 다시 복사;
- 키가 비활성화되었거나 크레딧 소진 → 게이트웨이 콘솔 토큰 페이지에서 확인;
- Authorization 헤더 형식 오류 → 반드시
Bearer sk-...형식이어야 함.
404 Not Found
- Base URL 경로가 틀림 → "/v1 있음"과 "/v1 없음"을 바꿔가며 테스트;
- 도구가 요청하는 프로토콜 엔드포인트를 게이트웨이가 미지원 → 게이트웨이가 해당 프로토콜(OpenAI /v1/chat/completions 또는 Anthropic /v1/messages)을 지원하는지 확인.
400 Model Not Found / 사용 가능한 채널 없음
- 모델명이 게이트웨이 채널과 불일치 → 콘솔 모델/채널 페이지에서 이름 확인;
- 채널이 비활성화되었거나 그룹에 권한 없음 → 토큰의 모델 범위와 그룹 설정 확인.
스트리밍 출력 중단 / 무응답
- 회사 프록시가 SSE를 버퍼링 → 직접 연결 네트워크로 테스트;
- 도구 타임아웃이 너무 짧음 → 타임아웃 증가. 긴 텍스트 작업은 먼저 게이트웨이 측 강제 타임아웃 여부 확인.
자주 묻는 질문(FAQ)
게이트웨이를 거치면 데이터가 안전한가요?
요청은 게이트웨이를 거쳐 상류 모델 채널로 전달됩니다. 게이트웨이 선택 시 로그와 프라이버시 정책을 확인하고, 민감 데이터는 게이트웨이 측에서 대화 로그 저장을 끄거나 데이터를 저장하지 않는 채널을 사용하세요.
한 도구에서 여러 게이트웨이를 동시에 설정할 수 있나요?
대부분의 도구는 다중 공급자 설정과 즉시 전환을 지원합니다(예: Cherry Studio, Cursor). 도구별로 다른 토큰을 쓰면 사용량 집계와 한도 설정도 분리할 수 있습니다.
도구마다 각 공급자에 직접 연결하는 것보다 통합 게이트웨이를 권하는 이유는?
세 가지 이유: 키 중앙 관리(유출 면 축소), 통합 과금과 사용량 가시화(여러 플랫폼에서 대조 불필요), 모델 언제든 교체(공급자 분리, 전환은 게이트웨이 설정 변경만).
관련 글
하나의 키로 GLM, DeepSeek, Qwen 등 주요 모델에 통합 연결. 통합 과금과 사용량 시각화를 지원합니다.
모델 및 요금 보기 가입하고 사용하기