이 포스팅은 쿠팡 파트너스 활동의 일환으로, 이에 따른 일정액의 수수료를 제공받습니다.
맥 로컬 LLM 설치 방법, OMLX 설정부터 클로드 코드 연결까지
맥 로컬 LLM(인터넷 서버가 아니라 내 맥에서 직접 돌리는 대형 언어 모델)을 OMLX로 설치하고 클로드 코드에 연결하는 방법을 24단계로 안내한다. LM Studio·

맥 로컬 LLM 도구로 OMLX를 고르는 이유, 디스크에 남는 캐시
맥에서 무엇으로 로컬 모델을 돌릴지 고민한다면 OMLX가 좋은 답이다. OMLX는 애플이 만든 머신러닝 라이브러리 MLX를 바탕으로, 맥 메뉴바에서 모델 서버를 켜고 끄게 해 주는 앱이다.
가장 큰 장점은 캐시다. 캐시(cache)는 한 번 계산한 결과를 저장해 두고 다시 쓰는 것이다. OMLX는 캐시 블록(cache block)을 safetensors 포맷으로 디스크에 저장한다. 그래서 콜드 스타트(cold start, 앱이나 서버를 막 켠 상태)에서도 결과가 빠르게 나온다. 자주 쓰는 뜨거운(hot) 블록은 RAM에 두고 차가운(cold) 블록은 SSD로 내려보낸다. 오래 안 쓴 것부터 지우는 LRU(Least Recently Used) 방식이다.
OMLX 안내 문구에는 "Previously seen prefixes are restored across requests and server restarts, never recomputed."라는 문장이 있다. 이전에 본 프리픽스(대화 앞부분)는 요청 간에도, 서버를 재시작한 뒤에도 복원되고 다시 계산하지 않는다는 뜻이다. 에이전트를 여러 개 돌리거나 하니스(harness, AI 코딩 도구)를 여러 개 쓸 때 특히 쓸모가 크다.
공개된 성능 수치는 M3 Ultra에 RAM 512GB 기준이다. 컨텍스트(AI가 한 번에 기억하는 대화 분량)가 쌓여도 성능을 크게 희생하지 않고, MLX LM의 기본 KV 캐시 저장 방식보다 속도가 올라간다.
OMLX의 위치도 알아 두면 좋다. MLX LM 위에 만들어진 도구다. MLX LM은 "as close to the metal"이라는 표현대로 하드웨어에 가까운 저수준 파이썬 라이브러리이고, OMLX는 그 위에 기능을 많이 얹었다.
Ollama와 LM Studio 대신 OMLX를 쓰는 이유
Ollama 쪽 이유는 단순하다. MLX 모델 지원을 천천히 롤아웃하는 중이고, 한 시점 기준으로 MLX 모델이 1개뿐이었다. Qwen 3.5였던 것으로 보인다.
LM Studio는 사정이 다르다. 여러 모델을 내려받기 좋은 단순한 화면이고 MLX 모델을 콕 집어 받을 수도 있다. 처음 시작하기에는 아주 좋은 도구다. 문제는 그다음이다. 점점 비대해져서(bloated) 더 정제된 도구를 찾게 된다. 로컬 LLM을 돌릴 때는 앱이 자원을 덜 먹는 쪽이 낫다. RAM은 앱이 아니라 LLM에 남겨 두는 것이 이 선택의 기준이다.
시작 전에 준비할 것
- Apple Silicon 맥(M1 이후 칩). 아래 시연 장비는 M5 Max에 RAM 128GB다. 내 맥의 칩과 메모리는 화면 왼쪽 위 사과 메뉴, "이 Mac에 관하여"에서 확인한다
- 넉넉한 RAM. 36GB 모델을 돌리는데 실제로는 약 80GB를 썼다
- 넉넉한 SSD 여유 공간. 캐시가 디스크에 쌓인다. 시연 중 이미 1.5GB였다
- Hugging Face(AI 모델 파일을 공유하는 사이트)에서 모델을 받을 인터넷 연결
- 선택: Claude Code(아래 시연용), opencode(컨텍스트를 아끼려면 이쪽), Pi, Tailscale(집 밖에서 내 컴퓨터에 안전하게 접속하게 해 주는 서비스)
1부. OMLX 내려받아 설치하기 (1~4단계)
- 브라우저에서 OMLX의 GitHub 릴리스 페이지를 연다. OMLX는 모든 배포를 GitHub로 한다. 구글이나 github.com 검색창에
omlx를 쳐서 저장소를 찾고, 저장소 오른쪽의 Releases를 누른다. 확인: 릴리스 목록이 보인다 - 페이지를 아래로 내려 최신 stable 빌드를 찾는다. 위쪽에는 프리릴리스(pre-release, 시험판)도 있으니 안정판을 원하면 내려가야 한다. 확인: latest stable build에 해당하는 릴리스가 보인다
- 그 릴리스의 Assets 목록에서
.dmg파일을 내려받는다. zip을 받아 직접 빌드할 수도 있지만 초보라면 DMG가 편하다. 확인: .dmg 파일이 다운로드 폴더에 생긴다 - 받은 DMG를 더블 클릭하고, 나온 창에서 OMLX 아이콘을 "Applications(응용 프로그램)" 폴더로 끌어다 놓는다. 응용 프로그램 폴더에서 OMLX를 연다. "확인되지 않은 개발자" 경고로 안 열리면 시스템 설정, 개인정보 보호 및 보안으로 가서 아래쪽의 "그래도 열기"를 누른다. 확인: 화면 맨 위 메뉴바에 OMLX 메뉴 아이콘이 생긴다
2부. OMLX 설정 화면 열기 (5~6단계)
- 메뉴바의 OMLX 아이콘을 클릭한다. 확인: 메뉴가 펼쳐진다
- 메뉴에서 Settings(설정)를 선택한다. 같은 메뉴에서 웹 대시보드도 열 수 있지만 설정 화면이 더 깔끔하다. 확인: 설정 창이 열린다
3부. 맥에서 돌릴 MLX 모델 고르기 (7~11단계)
- 브라우저에서 Hugging Face(huggingface.co)를 연다. ModelScope에서도 받을 수 있다. 확인: 모델 검색 화면이 뜬다
- 원하는 모델 이름을 검색한다. Gemma 계열 모델을 예로 들 수 있다. 확인: 검색 결과가 나온다
- 검색어에 MLX를 같이 넣어 다시 검색하고, 가장 좋은 MLX 양자화 버전을 찾는다. 양자화(quantization)는 모델 숫자의 정밀도를 낮춰 용량을 줄이는 것이다. MLX용으로 변환된 모델은
mlx-community라는 계정에 많이 모여 있으니 mlx-community Qwen처럼 검색하면 빠르다. 확인: MLX 변환본이 결과에 보인다 - 에이전트 용도라면 MoE(mixture of experts, 질문마다 모델 일부만 깨워 쓰는 구조) 모델을 고른다. 에이전틱 작업에는 MoE 모델이 잘 맞는다. 이 시연에서는 8비트 MoE 모델을 고르고, 이후 단계에서는 Qwen을 쓴다. 모델 이름에
8bit,4bit가 붙은 것이 양자화 수준이고, 숫자가 작을수록 RAM을 덜 먹는다. 확인: 모델 페이지가 열린다 - 그 모델 페이지의 URL(주소창 주소)을 복사한다. 확인: 클립보드에 주소가 담긴다
모델을 직접 양자화하는 방법도 있지만 이 글에서는 다루지 않는다.
4부. 모델 내려받고 교체하기 (12~17단계)
- OMLX 설정 창으로 돌아온다. 확인: 설정 화면이 앞으로 나온다
- 복사한 URL을 모델 입력란에 붙여넣는다(
Command + V). 확인: 주소가 입력된다 - 다운로드를 시작한다. 확인: 다운로드가 문제없이 진행된다
- 다운로드가 끝날 때까지 기다린다. 확인: 설정의 models 목록에 새 모델이 보인다
- 쓰지 않을 기존 모델을 언로드(eject, 메모리에서 내림)한다. 시연에서는 기존에 쓰던 Gemma 계열 모델을 내렸다. 확인: 기존 모델이 메모리에서 내려간다
- 새로 받은 모델을 로드한다. 확인: 새 모델이 로드된 상태가 된다
5부. 서버 정보 확인하기 (18~20단계)
- 설정의 server(서버) 항목으로 들어간다. 확인: 여러 엔드포인트(다른 프로그램이 모델에 접속하는 주소) 목록이 표시되고 각 엔드포인트가 무엇인지 안내가 보인다
- 메뉴에서 web dashboard(웹 대시보드)를 연다. 무엇을 해야 하는지 대시보드가 더 잘 보여 준다. 확인: 브라우저에 대시보드가 열린다
- 대시보드에서 사용할 모델(Qwen)을 선택한다. 확인: 그 모델로 실행할 코드가 화면에 표시된다
20단계의 코드와 base URL(접속 주소)은 대시보드에 뜬 값을 그대로 복사해 쓰면 된다. 연결 형식은 아래 6부와 "opencode에 붙이는 법"에 적었다. Tailscale을 쓰고 있다면 엔드포인트 목록에 내 Tailscale 네트워크 주소도 함께 나온다. 그 주소로 다른 기기에서도 이 로컬 모델을 돌릴 수 있다.
6부. 로컬 LLM을 클로드 코드에 붙여 테스트하기 (21~24단계)
- 대시보드 퀵스타트 항목에서 "OMLX with Claude Code"를 고른다. 확인: Claude Code 연동 안내가 뜬다
- 안내대로 Claude Code가 OMLX 서버를 보게 하고, 모델로 Qwen을 선택한다. Claude Code를 다른 서버에 붙일 때는 보통 환경 변수(프로그램에 넘겨주는 설정값)를 쓴다. 터미널(응용 프로그램, 유틸리티, 터미널)을 열고 아래 형식으로 입력한다. 따옴표 안은 대시보드에 나온 실제 값으로 바꾼다. 확인: 모델이 Qwen으로 잡힌다
export ANTHROPIC_BASE_URL="대시보드에 나온 OMLX 주소"
export ANTHROPIC_AUTH_TOKEN="OMLX에서 만든 API 키"
claude --model "대시보드에 나온 모델 이름"
- 프롬프트로 아래를 입력한다. 확인: 응답이 생성되기 시작한다
tell me about this code base
- 활동 모니터(Activity Monitor)를 열어 GPU 기록을 확인한다. 응용 프로그램, 유틸리티 폴더에서 활동 모니터를 열고, 맨 위 메뉴의 "윈도우"에서 "GPU 기록"을 고른다(
Command + 4). 확인: GPU 사용이 올라가는 것이 보인다
선택 A. 컨텍스트 크기 조절하기
A1. 설정의 models 항목으로 들어간다. 확인: 모델 목록이 보인다 A2. 사용 중인 모델(Qwen)을 연다. 확인: 그 모델의 세부 설정이 열린다 A3. context size(컨텍스트 크기) 값을 바꾼다. Qwen의 컨텍스트 크기는 262144이고, 비교하자면 LM Studio 기본값은 약 4,000이다. 확인: 값이 입력된다 A4. 모델을 다시 로드한다. 리로드해야 값이 적용된다. 확인: 바뀐 컨텍스트 크기로 모델이 올라온다
사실 이 값은 손대지 않는 편이 낫다. 컨텍스트 창이 다 찰 때까지 그냥 쓰면 된다. SSD에 캐시가 저장되므로 지금까지 작업한 성능 이득을 잃지 않는다.
선택 B. 캐시 확인하고 비우기
B1. 대시보드의 캐시 화면을 연다. 확인: 속도와 캐시된 토큰 수, 효율 이득이 보인다 B2. 쌓인 캐시 용량을 확인한다. 확인: 시연에서는 이미 1.5GB가 쌓여 있었다 B3. 필요하면 캐시를 비운다. 확인: 캐시가 지워진다
선택 C. Pi에 OMLX 프로바이더 추가하기
Pi는 여러 프로바이더(모델 제공처)를 골라 쓸 수 있는 AI 코딩 도구다.
C1. Pi의 프로바이더 설정을 연다. 확인: 프로바이더 목록이 보인다
C2. 새 프로바이더를 만들고 이름을 OMLXQwenHi
다른 도구도 같은 방식으로, 시스템에 맞는 설정 파일에 같은 값을 넣으면 된다. OpenClaw도 마찬가지다.
opencode에 OMLX 붙이는 법
opencode는 OpenAI 방식 주소를 쓰는 서버를 opencode.json 설정 파일로 붙일 수 있다. 홈 폴더의 .config/opencode/opencode.json 파일을 만들고 아래 형식으로 적는다. 주소와 모델 이름은 OMLX 대시보드에 나온 값으로 바꾼다.
{
"$schema": "https://opencode.ai/config.json",
"provider": {
"omlx": {
"npm": "@ai-sdk/openai-compatible",
"name": "OMLX (local)",
"options": {
"baseURL": "대시보드에 나온 OpenAI 호환 주소",
"apiKey": "OMLX에서 만든 API 키"
},
"models": {
"대시보드에 나온 모델 이름": { "name": "Qwen local" }
}
}
}
}
저장한 뒤 터미널에서 opencode/models
실제로 돌려 보니 나온 RAM과 캐시 숫자
RAM 숫자가 가장 눈에 띈다. 모델 자체는 36GB인데 실사용 RAM은 약 80GB였다. 컨텍스트가 필요 RAM을 크게 끌어올리기 때문이다. 그래서 컨텍스트 크기를 모델 설정에서 조절할 수 있게 되어 있다.
캐시 화면에서는 속도와 캐시된 토큰 수, 효율 이득을 볼 수 있고 쓸수록 쌓인다. 시연 도중 이미 1.5GB였다.
어떤 클라이언트에 붙일까, 클로드 코드와 opencode
위 시연은 Claude Code로 했지만 로컬 모델을 오래 쓸 때는 opencode가 낫다. 이유는 두 가지다. Claude Code는 컨텍스트 소모(context blow)가 큰 것으로 알려져 있다. 그리고 로컬 하드웨어는 자원이 제한적이라 컨텍스트를 아껴야 한다. 연결 형식은 위 "opencode에 OMLX 붙이는 법"에 적었다.
네트워크 너머로 쓰는 방법은 두 가지다. 집 안 네트워크에서 쓰거나, Tailscale로 집 밖에서 접속한다. Tailscale은 맥과 다른 기기에 같은 계정으로 앱을 깔면 서로를 내부망처럼 볼 수 있게 해 준다. 그때 OMLX 서버 목록에 뜨는 Tailscale 주소를 쓰면 된다.
맥 로컬 LLM 따라 하다 막히기 쉬운 지점
- 모델은 36GB인데 RAM을 80GB씩 쓴다: 컨텍스트가 필요 RAM을 끌어올린다. 컨텍스트 크기를 줄인다
- 컨텍스트 값을 바꿨는데 그대로다: 모델을 리로드해야 적용된다
- 컨텍스트가 습관적으로 작게 잡힌다: LM Studio 기본이 약 4,000이라 그렇다. 모델이 지원하는 값(예: 262144)으로 올린다
- Ollama에서 MLX 모델을 못 찾는다: MLX 지원이 롤아웃 중이라 모델이 거의 없다
- 앱이 무겁고 RAM을 잡아먹는다: LM Studio가 비대해진 탓이다. 가벼운 쪽으로 옮겨 RAM을 LLM에 남긴다
- Claude Code에서 컨텍스트가 금방 찬다: opencode로 바꾼다
- SSD 용량이 계속 준다: 캐시 블록을 디스크에 저장하기 때문이다. 캐시를 비운다
- OMLX 앱이 안 열린다: 인터넷에서 받은 앱이라 막힌 것이다. 시스템 설정, 개인정보 보호 및 보안에서 "그래도 열기"를 누른다
- Claude Code가 OMLX 대신 원래 클라우드 모델로 붙는다: 환경 변수를 입력한 그 터미널 창에서
claude를 실행해야 한다. 새 창을 열면 값이 사라진다
OMLX 설정 되돌리는 법
- 모델을 메모리에서 내리려면: 설정의 models에서 언로드(eject)한다.
- 디스크 캐시를 지우려면: 대시보드 캐시 화면에서 비운다.
- OMLX를 지우려면: 메뉴바 아이콘에서 종료(Quit)한 뒤, 응용 프로그램 폴더의 OMLX를 휴지통으로 끌어다 놓는다. 내려받은 모델과 캐시 파일은 따로 남을 수 있으니, 지우기 전에 설정 화면에서 모델 저장 위치를 확인해 두고 그 폴더도 정리한다.
- Claude Code를 원래대로 쓰려면: 새 터미널 창을 열어
claude를 실행한다. 환경 변수를 셸 설정 파일( ~/.zshrc)에 적어 뒀다면 그 줄을 지운다.
끝내기 전 확인할 것
- 메뉴바에 OMLX 아이콘이 있다
- 설정의 models 목록에 MLX 양자화 모델이 있고 로드돼 있다
- 웹 대시보드에서 엔드포인트와 실행 코드를 확인했다
- Claude Code나 Pi, opencode에서 로컬 모델이 응답한다
- 캐시 화면에서 캐시된 토큰과 효율 이득이 올라가는 게 보인다
- RAM 사용량이 감당 가능한 수준인지 확인했다. 36GB 모델에 약 80GB를 썼다
OMLX에 자리를 잡은 뒤에도 MLX LM은 따로 시험해 볼 만하다. 특히 학습(training) 쪽은 MLX LM에서 다룬다.
자주 묻는 질문
맥에서 로컬 LLM을 돌리려면 RAM이 얼마나 필요한가요?
모델 파일 크기보다 훨씬 넉넉해야 한다. 36GB 모델을 돌리는 데 실제로 약 80GB의 RAM을 썼고, 컨텍스트가 길수록 더 먹는다. RAM이 적으면 4비트처럼 더 작게 양자화된 모델을 고르거나 컨텍스트 크기를 줄인다.
OMLX와 LM Studio, Ollama는 무엇이 다른가요?
셋 다 내 컴퓨터에서 모델을 돌리는 도구다. LM Studio는 시작하기 좋지만 무거워졌고, Ollama는 MLX 모델 지원이 아직 적다. OMLX는 MLX LM 위에 만든 가벼운 메뉴바 앱이고, 캐시를 디스크에 저장해 재시작 뒤에도 다시 계산하지 않는다는 점이 장점이다.
클로드 코드를 로컬 모델에 연결할 수 있나요?
된다. OMLX 대시보드의 "OMLX with Claude Code" 안내를 따르면 되고, 보통은 ANTHROPIC_BASE_URLANTHROPIC_AUTH_TOKEN 환경 변수로 접속 주소와 키를 넘긴다. 다만 컨텍스트 소모가 커서, 로컬 모델을 오래 쓸 때는 opencode가 더 알맞다.
MLX 모델은 어디서 받나요?
Hugging Face에서 모델 이름과 MLX를 함께 검색한다. mlx-community 계정에 MLX용으로 변환된 모델이 많다. 모델 페이지 주소를 복사해 OMLX 설정의 모델 입력란에 붙여 넣으면 내려받아진다.
이 글의 본문은 아래 원본 유튜브 영상의 내용을 바탕으로 쓸모연구소가 다시 정리해 쓴 것입니다. 세부 내용과 최신 정보는 원본 영상과 공식 안내에서 확인해 주세요.
원본 영상 보러가기 ↗