OpenCode 설치 및 LM Studio 연동으로 로컬 AI 코딩 환경 구축하기

최근 AI 코딩 에이전트 분야에서 가장 주목받는 도구 중 하나는 OpenCode입니다. Claude Code와 유사한 강력한 기능을 제공하면서도, 오픈소스 모델을 자유롭게 연동할 수 있다는 점이 큰 매력입니다. 특히 보안에 민감한 프로젝트를 진행하거나 API 비용이 부담스러운 개발자들에게 '로컬 LLM 연동'은 최고의 솔루션입니다.

Homebrew를 중심으로 OpenCode를 설치하고, LM Studio를 연동하여 나만의 무료 AI 사수를 만드는 방법을 상세히 알아보겠습니다.

---

1. 왜 OpenCode인가?

OpenCode는 단순한 코드 생성을 넘어, 터미널(CLI/TUI) 환경에서 프로젝트 전체 맥락을 분석하고 스스로 실행 계획을 세우는 자율형 코딩 에이전트입니다.

• 보안성: 로컬 모델을 사용하면 코드가 외부 서버로 전송되지 않습니다.
• 무상성: API 키 비용 걱정 없이 무제한으로 코드를 리팩토링하고 디버깅할 수 있습니다.
• 범용성: GPT-4o, Claude 3.5 Sonnet 같은 유료 모델부터 내 컴퓨터의 로컬 모델까지 자유롭게 스위칭이 가능합니다.

---

2. Homebrew를 활용한 필수 도구 설치

먼저 OpenCode를 구동하기 위한 기초 환경을 구축해야 합니다.

A. Node.js 설치

OpenCode는 Node.js 기반으로 작동하므로, 시스템에 Node가 설치되어 있어야 합니다.

brew install node

B. OpenCode 설치

공식 설치 스크립트를 통해 시스템 전체에서 사용할 수 있도록 설치합니다.

curl -fsSL https://opencode.ai/install | bash

설치가 완료되면 opencode --version을 입력해 버전(1.0.150 이상 권장)을 확인합니다.

C. LM Studio 설치

로컬에서 AI 모델을 돌려줄 엔진인 LM Studio 역시 Homebrew로 간단히 설치할 수 있습니다.

brew install --cask lm-studio

---

3. LM Studio 연동 및 모델 설정

이제 내 컴퓨터의 리소스를 사용하여 OpenCode가 답변을 생성하도록 설정할 차례입니다.

1. 모델 다운로드: LM Studio 실행 후, qwen2.5-coder-7b-instruct-mlx나 glm-4.7 등 코딩 능력이 검증된 모델을 검색하여 내려받습니다.
2. 로컬 서버 기동: * 왼쪽 메뉴의 Local Server 아이콘을 클릭합니다.

• 내려받은 모델을 상단에서 선택하고 Start Server를 누릅니다.
• 포트가 1234로 설정되어 있는지 확인합니다.

---

4. 핵심: OpenCode 설정 파일(opencode.json) 구성

OpenCode가 LM Studio의 API 서버를 인식하도록 설정 파일을 수정해야 합니다. 설정 파일은 보통 ~/.config/opencode/opencode.json 경로에 있습니다.

주의: 많은 사용자가 겪는 TypeError: [ERR_INVALID_URL] 오류를 방지하려면 baseURL 끝에 반드시 /v1을 붙여야 합니다.

{
  "$schema": "https://opencode.ai/config.json",
  "provider": {
    "lmstudio": {
      "npm": "@ai-sdk/openai-compatible",
      "options": {
        "baseURL": "http://localhost:1234/v1", // /v1 경로 필수!
        "apiKey": "lm-studio" // LM Studio는 아무 키나 입력해도 무방
      },
      "models": {
        "local-coder": { // 사용자가 지정할 모델 식별자
          "limit": {
            "context": 32000,
            "output": 4096
          }
        }
      }
    }
  }
}

---

5. 프로젝트 실전 활용법

모든 설정이 끝났다면, 실제 프로젝트 폴더로 이동하여 OpenCode를 활용해 봅시다.

① 프로젝트 초기화 (/init)

새로운 프로젝트에서 OpenCode를 처음 실행할 때 사용합니다. 프로젝트의 구조를 분석하고 최적의 작업 방식을 설정하는 AGENTS.md 파일을 생성합니다. 이 파일을 팀원들과 공유하면 동일한 AI 환경을 유지할 수 있습니다.

② 모델 선택 (/models)

실행 중 /models 명령어를 입력하면 설정한 lmstudio를 선택할 수 있습니다.

• 팁: 복잡한 아키텍처 설계는 잠시 Claude 3.5 Sonnet같은 다른 모델을 연동해 사용하고, 실제 코드 구현이나 반복적인 유닛 테스트 작성은 다시 LM Studio로 돌아와 비용을 절감하는 전략이 유용합니다.

③ 주요 슬래시 명령어

• /clear: 대화 맥락을 초기화하여 모델의 기억 용량을 확보합니다.
• /compact: 이전 대화를 요약하여 토큰 사용량을 최적화합니다.
• /connect: 새로운 API 공급자(OpenAI, Anthropic 등)를 즉석에서 연결합니다.

---

마치며

Homebrew를 통해 구축한 OpenCode와 LM Studio 조합은 개발자에게 '나만의 격리된 AI 실험실'을 제공합니다. 클라우드 API 호출 시 사용량을 다 써서 대기중이라면, 로컬 AI로 코딩을 경험해 보세요.

설정 과정에서 궁금한 점이나 오류가 발생한다면 댓글로 남겨주시면 아는 부분까지 알려드리겠습니다.

---