맥 로컬 LLM 설치 방법, OMLX 설정부터 클로드 코드 연결까지

맥 로컬 LLM(인터넷 서버가 아니라 내 맥에서 직접 돌리는 대형 언어 모델)을 OMLX로 설치하고 클로드 코드에 연결하는 방법을 24단계로 정리했다. LM Studio와 Ollama를 거쳐 OMLX에 정착한 이유, 디스크에 남는 캐시의 장점, RAM 사용량 숫자도 함께 담았다. 영상이 소리 내어 읽지 않은 연결 설정은 일반적인 형식으로 채워 넣었다.

맥 로컬 LLM 도구로 OMLX를 고른 이유, 디스크에 남는 캐시

Samuel Gregory 채널의 9분짜리 영어 영상은 맥에서 무엇으로 로컬 모델을 돌릴지에 OMLX라고 답한다. OMLX는 애플이 만든 머신러닝 라이브러리 MLX를 바탕으로, 맥 메뉴바에서 모델 서버를 켜고 끄게 해 주는 앱이다. 영상 앞부분 약 64초는 자막이 비어 있어 옮기지 못했다.

장점으로 가장 먼저 꼽는 건 캐시다. 캐시(cache)는 한 번 계산한 결과를 저장해 두고 다시 쓰는 것이다. OMLX는 캐시 블록(cache block)을 safetensors 포맷으로 디스크에 저장하기 때문에, 콜드 스타트(cold start, 앱이나 서버를 막 켠 상태)에서도 빠르게 결과가 나온다고 화자는 말한다. 자주 쓰는 뜨거운(hot) 블록은 RAM에 두고 차가운(cold) 블록은 SSD로 내려보내며, 오래 안 쓴 것부터 지우는 LRU(Least Recently Used) 방식이다.

화면에 비친 문장은 이렇다. "Previously seen prefixes are restored across requests and server restarts, never recomputed." 이전에 본 프리픽스(대화 앞부분)는 요청 간에도, 서버를 재시작한 뒤에도 복원되며 절대 다시 계산되지 않는다는 뜻이다. 에이전트를 여러 개 돌리거나 하니스(harness, AI 코딩 도구)를 여러 개 쓸 때 특히 유용하다는 평이다.

한 가지 짚어 둘 것이 있다. 영상에서 읽어 준 성능 수치는 M3 Ultra에 RAM 512GB 기준이고, 화자 본인 장비는 M5 Max에 RAM 128GB다. 컨텍스트(AI가 한 번에 기억하는 대화 분량)가 쌓여도 성능을 크게 희생하지 않고 MLX LM의 기본 KV 캐시 저장 방식보다 속도가 올라가는 게 보인다고 하는데, 화면을 보며 한 설명이고 구체적인 토큰 수치는 발화에 없다.

OMLX 자체의 위치도 분명하다. MLX LM 위에 만들어진 도구다. MLX LM은 "as close to the metal"이라는 표현대로 하드웨어에 가까운 저수준 파이썬 라이브러리이고, OMLX는 그 위에 기능을 많이 얹은 것이라는 설명이다.

왜 Ollama와 LM Studio를 떠났나

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단계)

1. 브라우저에서 OMLX의 GitHub 릴리스 페이지를 연다. "모든 걸 GitHub에 배포한다"는 설명대로다. 저장소 주소는 영상에서 읽지 않으니, 구글이나 github.com 검색창에 omlx를 쳐서 저장소를 찾고, 저장소 오른쪽의 Releases를 누른다. 확인: 릴리스 목록이 보인다
2. 페이지를 아래로 내려 최신 stable 빌드를 찾는다. 위쪽에는 프리릴리스(pre-release, 시험판)도 있으니 안정판을 원하면 내려가야 한다. 확인: latest stable build에 해당하는 릴리스가 보인다
3. 그 릴리스의 Assets 목록에서 .dmg 파일을 내려받는다. zip을 받아 직접 빌드할 수도 있다고 하지만 초보라면 DMG가 편하다. 확인: .dmg 파일이 다운로드 폴더에 생긴다
4. 받은 DMG를 더블 클릭하고, 나온 창에서 OMLX 아이콘을 "Applications(응용 프로그램)" 폴더로 끌어다 놓는다. 응용 프로그램 폴더에서 OMLX를 연다. "확인되지 않은 개발자" 경고로 안 열리면 시스템 설정, 개인정보 보호 및 보안으로 가서 아래쪽의 "그래도 열기"를 누른다. 확인: 화면 맨 위 메뉴바에 OMLX 메뉴 아이콘이 생긴다

2부. OMLX 설정 화면 열기 (5~6단계)

5. 메뉴바의 OMLX 아이콘을 클릭한다. 확인: 메뉴가 펼쳐진다
6. 메뉴에서 Settings(설정)를 선택한다. 같은 메뉴에서 웹 대시보드도 열 수 있지만, 화자는 설정 화면이 더 깔끔하다고 본다. 확인: 설정 창이 열린다

3부. 맥에서 돌릴 모델 고르기 (7~11단계)

7. 브라우저에서 Hugging Face(huggingface.co)를 연다. ModelScope에서도 받을 수 있다. 확인: 모델 검색 화면이 뜬다
8. 원하는 모델 이름을 검색한다. 화자는 Gemma 계열 모델을 예로 든다. 확인: 검색 결과가 나온다
9. 검색어에 MLX를 같이 넣어 다시 검색한다. "나는 MLX를 검색해서 가장 좋은 MLX 양자화 버전을 찾는다"는 게 화자의 방법이다. 양자화(quantization)는 모델 숫자의 정밀도를 낮춰 용량을 줄이는 것이다. MLX용으로 변환된 모델은 mlx-community라는 계정에 많이 모여 있으니 mlx-community Qwen처럼 검색하면 빠르다. 확인: MLX 변환본이 결과에 보인다
10. 에이전트 용도라면 MoE(mixture of experts, 질문마다 모델 일부만 깨워 쓰는 구조) 모델을 고른다. "에이전틱 작업에는 MoE 모델을 본다"고 말한다. 화자가 고른 건 8비트 MoE 모델이고, 이후 시연에서는 Qwen을 쓴다. 모델 이름에 8bit, 4bit가 붙은 것이 양자화 수준이고, 숫자가 작을수록 RAM을 덜 먹는다. 확인: 모델 페이지가 열린다
11. 그 모델 페이지의 URL(주소창 주소)을 복사한다. 확인: 클립보드에 주소가 담긴다

직접 양자화하는 방법도 있지만 이번 편에서는 다루지 않는다고 넘어간다.

4부. 모델 내려받고 교체하기 (12~17단계)

12. OMLX 설정 창으로 돌아온다. 확인: 설정 화면이 앞으로 나온다
13. 복사한 URL을 모델 입력란에 붙여넣는다(Command + V). 확인: 주소가 입력된다
14. 다운로드를 시작한다. 확인: 다운로드가 진행된다. "문제없이 받아진다"는 말이 나온다
15. 다운로드가 끝날 때까지 기다린다. 확인: 설정의 models 목록에 새 모델이 보인다
16. 쓰지 않을 기존 모델을 언로드(eject, 메모리에서 내림)한다. 화자는 기존에 쓰던 Gemma 계열 모델을 내렸다. 확인: 기존 모델이 메모리에서 내려간다
17. 새로 받은 모델을 로드한다. 확인: 새 모델이 로드된 상태가 된다

5부. 서버 정보 확인하기 (18~20단계)

18. 설정의 server(서버) 항목으로 들어간다. 확인: 여러 엔드포인트(다른 프로그램이 모델에 접속하는 주소) 목록이 표시되고 각 엔드포인트가 무엇인지 안내가 보인다
19. 메뉴에서 web dashboard(웹 대시보드)를 연다. "무엇을 해야 하는지 더 잘 보여준다"는 이유다. 확인: 브라우저에 대시보드가 열린다
20. 대시보드에서 사용할 모델(Qwen)을 선택한다. 확인: 그 모델로 실행할 코드가 화면에 표시된다

20단계의 코드와 base URL(접속 주소)은 영상에서 읽지 않는다. 대시보드에 뜬 값을 그대로 복사해 쓰면 되고, 연결 형식은 아래 6부와 "opencode에 붙이는 법"에 적었다. 엔드포인트 목록에는 화자 본인의 Tailscale 네트워크 주소도 함께 나와서, 이 로컬 모델을 그쪽에서도 돌릴 수 있다고 한다.

6부. 로컬 LLM을 클로드 코드에 붙여 테스트하기 (21~24단계)

21. 대시보드 퀵스타트 항목에서 "OMLX with Claude Code"를 고른다. 확인: Claude Code 연동 안내가 뜬다
22. 안내대로 Claude Code가 OMLX 서버를 보게 하고, 모델로 Qwen을 선택한다. Claude Code를 다른 서버에 붙일 때는 보통 환경 변수(프로그램에 넘겨주는 설정값)를 쓴다. 터미널(응용 프로그램, 유틸리티, 터미널)을 열고 아래 형식으로 입력한다. 따옴표 안은 대시보드에 나온 실제 값으로 바꾼다. 확인: 모델이 Qwen으로 잡힌다

export ANTHROPIC_BASE_URL="대시보드에 나온 OMLX 주소"
export ANTHROPIC_AUTH_TOKEN="OMLX에서 만든 API 키"
claude --model "대시보드에 나온 모델 이름"

23. 프롬프트로 아래를 입력한다. 확인: 응답이 생성되기 시작한다

tell me about this code base

24. 활동 모니터(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. 새 프로바이더를 만들고 이름을 OMLX로 한다. 확인: 새 항목이 생긴다 C3. OMLX에서 설정된 base URL을 입력한다. 확인: 주소가 저장된다 C4. OMLX 설치 때 만든 API 키를 입력한다. 확인: 키가 저장된다 C5. Pi를 연다. 확인: Pi 화면이 열린다 C6. 모델 선택 항목으로 간다. 확인: 모델 검색창이 뜬다 C7. Qwen을 입력해 모델을 고른다. 확인: 모델이 선택된다 C8. Hi를 보내 응답을 확인한다. 확인: 로컬 모델이 Pi 안에서 답한다

같은 방식으로 시스템에 따라 설정 파일을 반복 적용하면 되고, OpenClaw도 마찬가지라고 언급한다.

{
  "$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" }
      }
    }
  }
}

출처: youtu.be/…