Ollama로 OpenCode에 Gemma 4 설정하는 방법 (2026 가이드)

OpenCode는 OpenAI 호환 API라면 어디든 연동되는 터미널 기반 코딩 어시스턴트입니다. Gemma 4를 실행하는 로컬 Ollama 인스턴스에 연결하면, 코드가 외부로 전송되지 않는 무료 코딩 어시스턴트를 쓸 수 있습니다.

Apple Silicon Mac에서는 다음과 같이 설정합니다. Ollama를 설치하고, Gemma 4를 내려받은 뒤, OpenCode에 연결하면 됩니다.

준비물

• Apple Silicon(M1/M2/M3/M4/M5)과 최소 16GB 통합 메모리를 갖춘 Mac
• Homebrew가 설치된 macOS
• OpenCode 설치 — opencode.ai를 참고하거나 패키지 관리자로 설치

Gemma 4의 기본 8B 모델은 로드 시 약 9.6GB를 사용하므로, 16GB 통합 메모리면 Ollama와 OpenCode를 함께 문제없이 실행할 수 있습니다.

1단계: Ollama 설치

brew install --cask ollama-app

이 명령은 Ollama.app을 /Applications/에 설치하고 ollama CLI를 /opt/homebrew/bin/ollama에 설치합니다.

2단계: Ollama 시작

open -a Ollama

메뉴 바에 아이콘이 나타날 때까지 기다린 후, 서버가 실행 중인지 확인합니다:

ollama list

3단계: Gemma 4 내려받기

ollama pull gemma4

약 9.6GB를 다운로드합니다. 확인:

ollama list
# NAME             ID              SIZE      MODIFIED
# gemma4:latest    ...             9.6 GB    ...

테스트:

ollama run gemma4:latest "Hello, what model are you?"

GPU 가속 확인:

ollama ps
# Should show CPU/GPU split, e.g. 14%/86% CPU/GPU

Apple Silicon의 Ollama v0.19 이상은 Apple의 MLX 프레임워크를 자동으로 사용해 추론 속도를 높여 줍니다.

4단계: OpenCode에서 Gemma 4를 사용하도록 설정

OpenCode는 ~/.config/opencode/opencode.jsonc 파일을 사용합니다. Ollama를 사용자 지정 프로바이더로 추가합니다:

{
  "provider": {
    "ollama": {
      "npm": "@ai-sdk/openai-compatible",
      "options": {
        "baseURL": "http://localhost:11434/v1"
      },
      "models": {
        "gemma4:latest": {}
      }
    }
  }
}

Ollama는 로컬에서 실행되므로 API 키가 필요하지 않습니다. 다만 OpenCode는 인증 항목을 요구하므로 ~/.local/share/opencode/auth.json에 플레이스홀더를 추가합니다:

{
  "ollama": {
    "type": "api",
    "key": "ollama"
  }
}

OpenCode를 재시작하고 /models를 사용해 ollama/gemma4:latest로 전환하세요.

5단계: Gemma 4를 메모리에 유지

Ollama는 기본 설정으로 5분 동안 사용하지 않으면 모델을 메모리에서 내립니다. 하루 종일 사용하는 코딩 어시스턴트에서는 이 때문에 불필요한 콜드 스타트가 자주 생깁니다.

keep-alive를 무기한으로 설정하세요:

launchctl setenv OLLAMA_KEEP_ALIVE "-1"

적용하려면 Ollama를 재시작하세요. 재부팅 후에도 유지하려면 ~/.zshrc에 추가합니다:

export OLLAMA_KEEP_ALIVE="-1"

로그인 시 자동 실행을 켜려면: Ollama 메뉴 바 아이콘 클릭 → 로그인 시 실행(Launch at Login).

시작 시 자동 사전 로드

LaunchAgent를 생성해 재부팅 후에도 Gemma 4가 바로 준비되도록 합니다:

cat << 'EOF' > ~/Library/LaunchAgents/com.ollama.preload-gemma4.plist
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
    <key>Label</key>
    <string>com.ollama.preload-gemma4</string>
    <key>ProgramArguments</key>
    <array>
        <string>/opt/homebrew/bin/ollama</string>
        <string>run</string>
        <string>gemma4:latest</string>
        <string></string>
    </array>
    <key>RunAtLoad</key>
    <true/>
    <key>StartInterval</key>
    <integer>300</integer>
    <key>StandardOutPath</key>
    <string>/tmp/ollama-preload.log</string>
    <key>StandardErrorPath</key>
    <string>/tmp/ollama-preload.log</string>
</dict>
</plist>
EOF

launchctl load ~/Library/LaunchAgents/com.ollama.preload-gemma4.plist

이 설정은 5분마다 빈 프롬프트로 모델에 핑을 보내 메모리에 유지합니다.

OpenCode에서 Gemma 4가 잘 처리하는 작업

Gemma 4 8B는 무료이고 로컬에서 실행되며, 일상적인 코딩 작업에 놀라울 정도로 유용합니다:

• 코드 설명. 함수가 어떤 역할을 하는지, 모듈 구조가 어떻게 되어 있는지, 정규식이 무엇을 매칭하는지 물어보세요. 일반적인 코드베이스라면 명확하고 대체로 정확한 답변을 줍니다.
• 빠른 편집. 오타 수정, import 업데이트, 타입 정의에 필드 추가, 변수 이름 변경 같은 작업에 적합합니다. 단일 파일 수정이 이 모델의 강점입니다.
• 보일러플레이트 생성. 설정 파일, 테스트 스텁, API 라우트 스캐폴딩, Dockerfile 템플릿. 추론이 많이 필요하지 않은 일반적인 패턴에 유용합니다.
• 셸 명령어 도움. git 플래그나 jq 필터가 기억나지 않나요? Stack Overflow를 찾아보지 않아도 Gemma 4가 바로 명령어를 알려줍니다.

한계점

• 다단계 추론. 여러 파일에 걸친 계획이 필요하거나 복잡한 제어 흐름을 이해해야 하는 작업은 결과가 불완전해지는 경향이 있습니다.
• 대규모 리팩토링. 코드베이스 전체에 걸쳐 조율된 변경이 필요하면 8B 모델은 일관성을 잃습니다. 파일 단위로 작업하지만 전체 그림을 유지하지는 못합니다.
• 엣지 케이스와 미묘한 버그. Gemma 4는 명백한 문제는 잡아내지만, 깊은 도메인 지식이 필요하거나 예외 케이스를 꼼꼼히 따져야 찾을 수 있는 버그는 놓칩니다.

더 나아가기: Haimaker로 클라우드 모델 추가

로컬 Gemma 4는 기본적인 작업을 충분히 처리합니다. 복잡한 디버깅, 다중 파일 리팩토링, 깊은 추론이 필요한 작업처럼 한계에 부딪히면 클라우드 모델이 필요합니다. Haimaker는 API 키 하나로 Claude Opus, GPT-5, Gemini Pro 등을 제공합니다.

Ollama와 함께 Haimaker를 두 번째 프로바이더로 추가하세요:

{
  "provider": {
    "ollama": {
      "npm": "@ai-sdk/openai-compatible",
      "options": {
        "baseURL": "http://localhost:11434/v1"
      },
      "models": {
        "gemma4:latest": {}
      }
    },
    "haimaker": {
      "npm": "@ai-sdk/openai-compatible",
      "options": {
        "baseURL": "https://api.haimaker.ai/v1"
      },
      "models": {
        "anthropic/claude-sonnet-4-6": {},
        "openai/gpt-5": {},
        "google/gemini-2.5-pro": {}
      }
    }
  }
}

Haimaker API 키를 ~/.local/share/opencode/auth.json에 추가합니다:

{
  "ollama": {
    "type": "api",
    "key": "ollama"
  },
  "haimaker": {
    "type": "api",
    "key": "YOUR_HAIMAKER_API_KEY"
  }
}

이제 OpenCode에서 /models로 로컬 모델과 클라우드 모델을 전환할 수 있습니다. 간단한 작업은 Gemma 4로, 어려운 작업은 Sonnet이나 GPT-5로 전환하세요.

haimaker.ai에서 가입해 API 키를 받고 모델 카탈로그를 둘러보세요.

HAIMAKER API 키 받기

문제 해결

/models에 프로바이더가 표시되지 않음. 설정 파일을 수정한 뒤 OpenCode를 재시작하세요. OpenCode 실행 중에는 opencode.jsonc의 변경 사항이 반영되지 않습니다.

“Model not found” 오류. 설정의 모델 ID가 Ollama가 보고하는 것과 정확히 일치하는지 확인하세요. ollama list를 실행하고 표시된 이름을 그대로 사용하세요 — 보통 gemma4:latest입니다.

Ollama 인증 오류. Ollama는 인증이 필요하지 않지만, OpenCode의 프로바이더 시스템은 auth.json에 항목이 있어야 합니다. 플레이스홀더는 "key": "ollama" 값이면 충분합니다.

응답이 느림. Apple Silicon에서 MLX 가속을 받으려면 Ollama v0.19 이상을 사용해야 합니다. ollama --version를 실행해 버전을 확인하세요. 통합 메모리를 차지하는 다른 앱도 닫으세요. 탭을 많이 연 브라우저가 주된 원인입니다.

컨텍스트 윈도우 문제. Gemma 4는 큰 컨텍스트 윈도우를 지원하지만, 16GB 하드웨어에서는 안정적인 출력 품질을 위해 입력을 32K 토큰 이하로 유지하세요. 긴 프롬프트에서 응답 품질이 떨어진다면 이 때문일 가능성이 높습니다.

유용한 Ollama 명령어

명령어	설명
ollama list	다운로드된 모델 목록 표시
ollama ps	실행 중인 모델과 메모리 사용량 표시
ollama run gemma4:latest	대화형 채팅
ollama stop gemma4:latest	메모리에서 모델 언로드
ollama pull gemma4:latest	최신 버전으로 업데이트
ollama rm gemma4:latest	모델 삭제

---

이미 Haimaker를 OpenCode와 함께 사용하고 있나요? 더 많은 모델을 추가하려면 커스텀 프로바이더 설정 가이드를 참고하세요.