OmniRoute 사용법, 클로드 한도 차면 무료 모델로 넘기는 법

OmniRoute 사용법을 중심으로, 클로드(Claude)와 함께 자주 거론되는 오픈소스 세 가지가 각각 무엇을 하는지 알려 드립니다. 대화를 기억하게 하는 claude-mem, 프로젝트에 맞는 설정을 추천하는 claude-code-setup, 사용량 한도가 차면 다른 모델로 넘겨 주는 OmniRoute입니다. 설치 순서와 함께, 코드가 외부로 나갈 수 있다는 점과 약관 문제도 짚었습니다.

클로드와 함께 쓰는 오픈소스 3가지

세 도구는 하는 일이 서로 다릅니다.

• claude-mem: 이전 대화 내용을 다음 대화에 이어 줍니다. 매번 "우리 프로젝트는 어디 있고 이 파일은 어디 있고"를 다시 설명하지 않아도 됩니다.
• claude-code-setup: 내 프로젝트를 훑어보고 무엇을 깔면 좋을지 추천합니다. 쓸데없는 것은 빼라는 조언까지 줍니다.
• OmniRoute(옴니루트): 토큰 사용량 한도가 다 차면 알아서 다른 모델, 무료 모델까지 넘겨서 계속 쓰게 해 줍니다.

"이거 모르면 클로드 성능이 10%로 떨어진다"는 식의 소개가 붙기도 하지만, 그런 숫자를 잰 자료는 없습니다. 세 도구는 성능을 올린다기보다 불편 하나씩을 덜어 주는 도구로 보는 게 맞습니다. 깃허브 별(관심 표시) 수는 2026년 10월 중순 기준으로 claude-mem이 10만 개를 넘었고, OmniRoute는 7만 6천 개 남짓입니다. 별 수는 계속 바뀝니다.

claude-mem과 claude-code-setup 설치 명령

두 도구는 Claude Code(터미널에서 내 폴더의 파일을 읽고 고치는 Anthropic의 코딩 도구)의 플러그인입니다. 클로드 코드 채팅창에 입력해서 설치합니다.

claude-mem: 이전 대화를 기억하게 한다

claude-mem은 Anthropic 공식 목록이 아니라 개발자 저장소(thedotmack/claude-mem)를 먼저 등록한 뒤 설치합니다. 저장소 안내 기준 명령은 아래와 같습니다.

/plugin marketplace add thedotmack/claude-mem
/plugin install claude-mem

설치한 뒤 클로드 코드를 껐다가 다시 켜야 적용됩니다.

claude-code-setup: 프로젝트에 맞는 설정을 추천한다

claude-code-setup은 Anthropic 공식 플러그인 목록(claude-plugins-official)에 들어 있습니다. 내 프로젝트를 읽고 훅, 스킬, MCP 서버 같은 자동화를 추천하는데, 파일은 고치지 않는 읽기 전용입니다.

/plugin install claude-code-setup@claude-plugins-official

설치 뒤 "이 프로젝트에 맞는 자동화를 추천해줘"라고 요청하면 추천 목록과 이유가 나옵니다. 추천받은 것 중 무엇을 깔지는 직접 고릅니다.

OmniRoute는 어떻게 무료 모델로 넘기나

OmniRoute는 AI 게이트웨이(내 컴퓨터에 띄워 두는 중계 서버)입니다. 코딩 도구는 OmniRoute 주소 하나만 바라보고, OmniRoute가 뒤에서 여러 AI 회사의 모델 가운데 하나를 골라 요청을 보냅니다. MIT 라이선스 오픈소스이고, 저장소는 diegosouzapw/OmniRoute입니다.

모델을 고르는 순서는 네 단계로 나뉩니다. 저장소 안내 기준으로 구독 요금제, API 키, 저렴한 유료 모델, 무료 모델 순입니다. 앞 단계의 한도가 차거나 공급자가 응답하지 않으면 다음 단계의 쓸 수 있는 모델로 넘어갑니다. 이렇게 묶은 모델 순서를 콤보(combo)라고 부르고, 모델 이름에 auto를 넣으면 연결해 둔 공급자로 콤보를 자동으로 짜 줍니다.

무료 모델로 넘어가면 답의 품질과 말투가 클로드와 달라집니다. 무료 구간은 각 공급자가 정하는 것이라 예고 없이 바뀔 수 있다고 저장소도 적어 두었습니다.

OmniRoute 설치와 Claude Code 연결 순서

저장소 README의 빠른 시작 기준입니다. 터미널(맥은 Cmd+Space를 누르고 "terminal" 입력)에서 진행합니다.

1. Node.js 버전을 확인합니다. npm 패키지 기준으로 22.x는 22.22.2 이상, 또는 24.x 이상 27 미만이 필요합니다.

node -v

2. OmniRoute를 설치합니다.

npm install -g omniroute

3. OmniRoute를 실행합니다.
   • 확인: 브라우저에서 http://localhost:20128을 열면 대시보드가 보입니다. API 주소는 http://localhost:20128/v1입니다.

omniroute

4. 대시보드의 Providers(공급자) 메뉴에서 쓸 공급자를 연결합니다. 무료 구간을 주는 공급자도 여기서 고릅니다.
5. 대시보드의 Endpoints 메뉴에서 OmniRoute용 API 키를 복사합니다.
6. 연결이 됐는지 확인합니다. YOUR_KEY 자리에 복사한 키를 넣습니다.
   • 확인: 연결한 모델 목록이 나옵니다.

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

7. Claude Code를 OmniRoute를 거쳐 실행합니다. README 예시는 아래와 같고, --model 뒤에는 6단계 목록에 있는 모델 이름을 넣습니다.

omniroute run claude --model openai/gpt-5.4

설정 파일을 직접 고치지 않고, 이 명령으로 켠 클로드 코드에만 OmniRoute가 적용됩니다. 평소처럼 claude로 켜면 원래대로 Anthropic에 바로 연결됩니다.

코드가 외부로 나갈 수 있다: 연습용 폴더에서만

OmniRoute는 내 컴퓨터에서 돌지만, 요청 내용은 그때그때 고른 공급자에게 그대로 보내집니다. 클로드 코드는 작업 중에 파일 내용을 모델에 보내므로, 무료 모델로 넘어가는 순간 내 코드도 그 공급자에게 갑니다. 무료 구간은 공급자마다 데이터 처리 정책이 다르고, 입력을 서비스 개선에 쓸 수 있다고 적어 둔 곳도 있습니다.

그래서 회사 코드나 고객 정보가 든 폴더에는 쓰지 않고, 연습용 프로젝트에서만 써 보는 것이 안전합니다. 비밀번호나 API 키가 든 .env 파일이 있는 폴더도 피합니다.

약관도 따로 봐야 합니다. 앤트로픽은 Claude Pro·Max 같은 구독 계정의 로그인 토큰을 Claude Code와 Claude.ai 밖의 다른 도구에서 쓰는 것을 소비자 약관 위반으로 안내하고 있습니다. 게이트웨이에 클로드 모델을 붙일 때는 API 키 방식을 쓰고, 다른 공급자의 무료 구간도 각자 약관을 확인합니다. OmniRoute 저장소도 약관상 피해야 할 공급자는 자동 라우팅에서 기본으로 뺀다고 적어 두었습니다.

설치가 막힐 때 확인할 것

저장소 이름이 비슷한 게 여러 개다

OmniRoute는 복사본(포크) 저장소가 여럿 있습니다. 공식 저장소는 diegosouzapw/OmniRoute이고, npm 패키지 이름은 omniroute입니다. 다른 이름으로 받으면 내용이 다를 수 있습니다.

npm 설치 중 경고가 뜬다

npm warn ERESOLVE 같은 경고는 무시해도 된다고 README가 안내합니다. 오류로 멈추면 Node.js 버전부터 다시 확인합니다.

클로드 코드에서 claude-mem이 안 보인다

클로드 코드를 다시 켰는지 봅니다. 그다음 /plugin을 입력해 Installed(설치됨) 탭에 claude-mem이 켜져 있는지 확인합니다.