oh-my-opencode 설치 및 사용방법

oh-my-opencode는 OpenCode 위에서 동작하는 플러그인(에이전트 하네스)이라, 먼저 OpenCode가 설치·동작하는 상태여야 합니다.

1. 사전 준비

OpenCode 설치·버전 확인
- opencode –version 실행 시 1.0.150 이상이면 충분합니다.
Node.js와 bun (또는 최소 Node.js만) 준비
- oh-my-opencode는 npm 패키지로 배포되고 bunx 또는 npx로 실행합니다.

2. 기본 설치 방법

터미널에서 다음 중 하나를 실행합니다.

bash

bunx oh-my-opencode install

# bun이 없다면

npx oh-my-opencode install

위 명령은 자동으로 다음을 수행합니다.
- 시스템에서 opencode/opencode-desktop 위치와 버전 탐지
- 최소 버전 요구사항(1.0.150 이상) 확인
- 현재 OS/아키텍처에 맞는 oh-my-opencode 바이너리 다운로드
- OpenCode 설정 디렉터리에 oh-my-opencode.json 생성 및 플러그인 활성화 설정

Windows 포함 각 플랫폼에서 설정 파일은 보통 다음 경로에 생성됩니다.

공통: ~/.config/opencode/oh-my-opencode.json
Windows 폴백: %APPDATA%\opencode\oh-my-opencode.json

3. 설치 후 동작 확인

OpenCode 실행
- opencode (또는 opencode.exe) 실행 후 TUI가 뜨는지 확인합니다.
oh-my-opencode 활성 여부
- 설치가 정상이라면, OpenCode 실행 시 백그라운드 에이전트 팀(Sisyphus, Oracle, Librarian 등)을 로드하는 로그가 출력되고, 에이전트 오케스트레이션 기능을 사용할 수 있습니다.

예: 하나의 프로젝트에서 메인 에이전트(Sisyphus)가 작업을 쪼개고, Oracle/Librarian/프론트엔드 에이전트 등이 병렬로 실행되는 형태로 동작합니다.

4. 기본 사용 흐름

설치가 끝난 뒤에는 “OpenCode + oh-my-opencode” 조합으로 개발을 진행합니다.

프로젝트 디렉터리에서 opencode 실행
초기화
- /init 또는 OpenCode의 초기 스캔 기능으로 프로젝트 구조를 파악시킵니다.
멀티 에이전트 활용
- 메인 에이전트에게 자연어로 “이 기능 구현해줘”처럼 요청하면,
  - 설계, 구현, 테스트, 리팩토링을 각각 담당하는 서브 에이전트들이 백그라운드에서 병렬로 작업을 진행합니다.
oh-my-opencode.json 커스터마이징
- 설치 시 생성된 oh-my-opencode.json에서
  - 각 역할(Sisyphus, Oracle, Librarian, Frontend 등)에 쓰일 모델,
  - LSP, AST-grep, MCP 서버 연동 여부 등을 세밀하게 조정할 수 있습니다.

5. (참고) 설치 옵션/플래그

CLI 설치 시 TUI 없이 지정형 설치도 가능합니다.

bash

bunx oh-my-opencode install --no-tui \

  --claude=<yes|no|max20> \

  --chatgpt=<yes|no> \

  --gemini=<yes|no>

각 플래그는 어떤 AI 프로바이더를 얼마나 사용할지(예: Claude를 최대 20회까지) 미리 정해서 설정에 반영합니다.

gemma3를 Ollama로 띄워서 OpenCode + oh-my-opencode에서 쓰는 기본 샘플은 “opencode.json + oh-my-opencode.json” 두 군데만 잡아주면 됩니다.

1. Ollama에서 gemma3 준비

먼저 모델을 내려받고 서버가 떠 있어야 합니다.

bash

ollama serve            # 안 떠 있으면 먼저 실행

ollama pull gemma3:4b   # 또는 원하는 크기 (1b/4b/12b/27b 등)

ollama run gemma3       # 정상 응답 나오는지만 한번 확인

기본 엔드포인트: http://localhost:11434/v1 입니다.

2. OpenCode 설정 (opencode.json)

Windows 기준 경로 예시입니다.

C:\Users<USER>\AppData\Roaming\opencode\opencode.json

파일이 없다면 폴더/파일을 만들어 두고 아래처럼 Ollama provider를 정의합니다.

json

{

  "$schema": "https://opencode.ai/config.json",

  "provider": {

    "ollama": {

      "npm": "@ai-sdk/openai-compatible",

      "name": "Ollama (Local)",

      "options": {

        "baseURL": "http://localhost:11434/v1"

      },

      "models": {

        "gemma3:4b": {

          "name": "Gemma3 4B (Local)"

        }

      }

    }

  },

  "agents": {

    "coder": {

      "model": "ollama/gemma3:4b",

      "tools": true

    }

  }

}

key 포인트
- provider.ollama.options.baseURL 에 Ollama 주소 지정.
- models 아래 모델 ID는 Ollama 모델 이름(gemma3:4b 등) 그대로.
- agents.coder.model 에 "ollama/gemma3:4b"처럼 providerID/모델ID 형식 사용.

이 상태에서 opencode 실행 후 /model 치면 ollama/gemma3:4b가 목록에 나와야 합니다.

3. oh-my-opencode 설정 (oh-my-opencode.json)

oh-my-opencode에서 에이전트별로 어떤 모델을 쓸지 매핑해 줍니다.

Windows 기준 위치 예시.

C:\Users<USER>\AppData\Roaming\opencode\oh-my-opencode.json

예시 (Sisyphus/Oracle에 gemma3, 가벼운 작업은 qwen3:8b 같이 섞는 패턴):

json

{

  "$schema": "https://raw.githubusercontent.com/code-yeongyu/oh-my-opencode/master/assets/oh-my-opencode.schema.json",

  "google_auth": false,

  "agents": {

    "Sisyphus": {

      "model": "ollama/gemma3:4b",

      "description": "Main orchestrator with Gemma3 4B"

    },

    "oracle": {

      "model": "ollama/gemma3:4b",

      "description": "Deeper reasoning / code review with Gemma3 4B"

    },

    "librarian": {

      "model": "ollama/gemma3:4b",

      "description": "Docs & repo search with Gemma3 4B"

    },

    "explore": {

      "model": "ollama/gemma3:4b",

      "description": "Code navigation & quick questions"

    }

  }

}

qwen3도 같이 쓰고 싶으면 opencode.json에 qwen3:8b 모델을 추가하고, explore나 librarian만 "ollama/qwen3:8b"로 바꾸면 됩니다.

4. 동작 체크 순서 요약

ollama serve 실행, ollama run gemma3로 응답 확인.
opencode.json에 provider.ollama + models.gemma3:4b + agents.coder 설정.
oh-my-opencode.json에 각 에이전트의 model을 "ollama/gemma3:4b"로 지정.
opencode.exe 실행 → /models에서 ollama/gemma3:4b 선택, oh-my-opencode 팀이 gemma3 기반으로 뜨는지만 확인.