MacOS에서 로컬 코딩 에이전트(Local Coding Agent) 실행하기

적절한 성능을 갖춘 Apple Silicon Mac이라면 어디에서든 로컬 코딩 에이전트 (local coding agent)를 실행할 수 있습니다. python이 설치되어 있어야 합니다.

모델 선택하기 (Selecting a model)

우리는 mlx-community를 사용할 것입니다. Hugging Face API를 사용하여 모델 목록을 나열할 수 있습니다. 예를 들어 gemma 모델을 사용하고 싶다고 가정해 봅시다. Qwen, Llama 등 다른 모델들도 있습니다.

curl -s "https://huggingface.co/api/models?author=mlx-community&sort=downloads&limit=1000" \
  | jq -r '.[].id' \
  | grep -i gemma

다음과 같은 모델 목록이 나타날 것입니다 (여기에 보이는 것보다 훨씬 더 많으며, 샘플만 보여줍니다):

mlx-community/gemma-3-4b-it-qat-4bit
mlx-community/gemma-4-12B-it-8bit
mlx-community/gemma-4-e2b-it-4bit
...

명명 규칙은 {모델 이름}-{모델 크기}-{만약 'it'라면, instruction tuned (에이전트 작업에 좋음)}-{가중치 정밀도 / 양자화 (weight precision / quantization)}입니다.

이 이름들에는 많은 정보가 담겨 있지만, 여러분의 기기에 맞는 모델을 선택하는 데 필요한 정보가 포함되어 있습니다.

모델 선택을 돕는 도구

시스템을 기반으로 로컬 모델을 선택하는 데 도움을 주는 MacOS CLI를 만들었습니다: https://github.com/ruarfff/help-pick-local-model

모델 로컬 서빙하기 (Serving a model locally)

1. 의존성 설치:

   pip install mlx mlx-lm mlx-vlm

또는 uv를 사용하는 경우:

   uv tool install mlx-lm && uv tool install mlx-vlm

2. 선택한 모델로 로컬 서버 시작:

   mlx_lm.server --model mlx-community/gemma-4-26B-A4B-it-OptiQ-4bit --port 7777

첫 번째 단계에서는 로컬 모델, 특히 Apple Silicon에서 모델을 실행하는 데 도움이 되는 몇 가지 의존성을 설치합니다.

두 번째 단계는 모델의 크기에 따라 시간이 다소 걸릴 수 있습니다.

텍스트 이상의 기능을 지원하는 멀티모달 모델 (unified model)을 사용하는 경우, 대신 mlx_vlm을 사용합니다. 예:

   mlx_vlm.server --model mlx-community/gemma-4-12B-it-OptiQ-4bit --port 7777

저는 개발 시 사용하는 다른 일반적인 포트들과 충돌하는 것을 피하기 위해 포트를 7777로 선택했습니다.

1. 코딩 에이전트(coding agent) 도구를 로컬 서버로 지정합니다.

3단계는 사용 중인 도구에 따라 달라집니다. 몇 가지 도구를 다루어 보겠지만, 여러분이 사용하는 도구가 무엇이든 해당 기능이 있다면 아마도 어떻게 하는지에 대한 문서(docs)가 있을 것입니다.

로컬 모델을 사용하도록 코딩 에이전트 설정하기

대부분의 코딩 에이전트는 BYOM (Bring Your Own Model, 직접 모델 가져오기)을 허용하지만, 그 경험은 제각각입니다.

Copilot

Github copilot CLI의 경우, 직접 모델을 가져올 수 있지만 환경 변수(environment variables)로 구성된 전용 세션을 시작해야 합니다.

저는 다음과 같은 셸 함수(shell function)를 사용합니다:

copilot-local-mlx() {
  export COPILOT_PROVIDER_TYPE=openai
  export COPILOT_PROVIDER_BASE_URL=http://127.0.0.1:7777/v1
...

이 내용을 ~/.bashrc, ~/.zshrc 등에 추가하면 copilot-local-mlx를 실행하여 로컬 모델로 copilot을 실행할 수 있습니다.

당연히 자신의 설정에 맞게 설정을 수정해야 합니다.

OpenCode

~/.config/opencode/opencode.json 파일에서 OpenCode를 구성할 수 있습니다. 제가 한 것처럼 포트 7777에서 로컬 모델을 실행 중이라면, 이 내용을 opencode.json 파일에 추가하여 OpenCode에서 모델을 사용할 수 있게 할 수 있습니다:

{
  "$schema": "https://opencode.ai/config.json",
  "model": "local-mlx/mlx-community/gemma-4-12B-it-OptiQ-4bit",
...

저처럼 nix를 사용한다면, 이를 home manager 설정에 추가할 수 있습니다:

xdg.configFile."opencode/opencode.json".text = builtins.toJSON {
  "$schema" = "https://opencode.ai/config.json";
  provider = {
...

OpenCode를 재시작하고, /models를 실행한 뒤 로컬 모델을 선택하세요.

Pi

Pi의 경우, 우리의 models.json을 업데이트할 수 있습니다.

파일이 존재하는지 확인하고 에디터를 여세요.

mkdir -p ~/.pi/agent
vim ~/.pi/agent/models.json

로컬 모델을 다음과 같이 설정하세요:

{
  "providers": {
    "local-mlx": {
...