Oh My OpenCode 설치 가이드: 초급자도 할 수 있는 설정 방법

Oh My OpenCode 설치 가이드

OpenCode를 설치해본 분들은 “기본 기능도 꽤 좋은데, 사람들이 말하는 ‘다중 에이전트 개발환경’은 어떻게 만드는 거지?”라는 궁금증이 생길 겁니다.

바로 그 지점을 해결해주는 확장팩이 Oh My OpenCode입니다.
하지만 초급 개발자에게 이 확장팩은 조금 낯설 수 있습니다.

  • 설정 파일은 어디에 두는지?
  • 어떤 agent 들이 기본 제공되는지?
  • JSON 템플릿은 어떻게 구성해야 하는지?
  • 모델·도구·규칙이 어떻게 연결되는지?

이번 글에서는 이 모든 고민을 해결할 수 있도록
“설치 → 설정파일 생성 → 에이전트 연결 → 규칙 적용”의 전체 과정을 실제 예제 중심으로 매우 쉽고 실전적으로 정리합니다.

1. 설치 준비: 어떤 방식으로 설치할까?

opencode plugins install oh-my-opencode image

Oh My OpenCode는 OpenCode 플러그인 형태로 동작합니다.
설치는 명령어 하나로 해결됩니다.

opencode plugins install oh-my-opencode

설치가 잘 되었는지 확인하려면

opencode plugins list

여기에서 아래와 같이 oh-my-opencode가 보이면 정상입니다.

opencode plugins list image

2. 설정 파일을 어디에 둘까?

설정은 두 종류가 있습니다.

✔ 프로젝트 전역 설정

.yourproject/
  └── .opencode/
         └── oh-my-opencode.json

프로젝트마다 다른 규칙·에이전트 구성을 적용하고 싶을 때 사용합니다.

✔ 사용자 전체(global) 설정

~/.config/opencode/oh-my-opencode.json

모든 프로젝트에 공통 설정을 적용하고 싶을 때 사용합니다.
초급자는 global 설정 → 프로젝트별 override 방식이 유지보수하기 쉽습니다.

Oh My OpenCode 설치 가이드 image 2

3. 기본 JSON 템플릿

아래 JSON을 그대로 복사해서
~/.config/opencode/oh-my-opencode.json
에 넣으면 기본 기능이 바로 작동합니다.

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

  "agents": {
    "oracle": {
      "model": "openai/gpt-5.2",
      "instructions": "You act as an architect-level reviewer. Explain your reasoning clearly."
    },
    "explore": {
      "model": "xai/grok-code",
      "instructions": "Fast code search and browsing."
    },
    "frontend": {
      "model": "google/gemini-3-pro-preview",
      "instructions": "Help with UI/UX and frontend code."
    },
    "document": {
      "model": "google/gemini-3-pro-preview",
      "instructions": "Write clear documentation for code and APIs."
    }
  },

  "rules": {
    "enabled": true
  },

  "hooks": {
    "keyword-detector": true,
    "auto-compact": true,
    "todo-enforcer": true
  }
}

이 템플릿은 초급자가 다루기 좋은 다음 특성을 갖고 있습니다.

  • 역할이 분명한 4개 에이전트 구성
  • 자동 규칙 주입 활성화
  • 자동 요약(auto-compact), 작업 완료 안내(todo-enforce) 활성화
  • keyword detector를 통해 “리팩터링”, “정리해줘” 같은 자연어 표현 반응

4. 에이전트 커스텀: 역할을 바꾸거나 새로 만들기

Oh My OpenCode의 진짜 힘은 “직무 기반 에이전트”를
내 프로젝트에 맞게 만들 수 있다는 점입니다.

예: Django 프로젝트용 “Model Specialist” 추가하기

"agents": {
  "model-specialist": {
    "model": "anthropic/claude-4-5-sonnet",
    "instructions": "You focus on database models, migrations, and schema design. Suggest improvements and ensure consistency."
  }
}

이제 TUI에서 다음처럼 호출할 수 있습니다:

@model-specialist 모델 구조 한번 검토해줘.

提示

초급자라면 agent 1~2개만 추가하고,
익숙해지면 5~6개까지 확장하는 것이 좋습니다.

5. 규칙(Rules) 기능 사용법: “프로젝트의 관점”을 AI에게 심기

규칙은 일반적인 terminal AI IDE 와 달리
프로젝트별 문맥과 원칙을 AI에게 자동 학습시키는 기능입니다.

예: src/auth 디렉터리에서만 적용되는 규칙 추가하기
프로젝트 내부에 다음 파일 생성

src/auth/AGENTS.md

내용 예:

# Authentication rules
- Always handle tokens with secure patterns.
- Never store raw passwords.
- Follow the existing session management flow.

이제 auth 관련 파일을 열면 AI는 자동으로 이 규칙을 참고합니다.

6. Hooks(자동화 기능) 이해하기

hooks는 AI coding agent 가 동작하는 방법과 타이밍을 자동 조정하는 기능입니다.

초급자가 꼭 알아야 하는 3가지

✔ keyword-detector

  • “정리해줘”, “찾아줘”, “리팩터링” 같은 키워드 감지
  • 자동으로 분석 모드 또는 구조화 모드 전환

✔ auto-compact

  • 대화가 너무 길어지면 자동 요약 + 맥락 유지
  • 터미널 환경에서 매우 중요한 기능

✔ todo-enforcer

  • 작업 중 TODO를 발견하면 “해야 할 일”로 다시 안내

이 기능들은 초급자가 “망가뜨리기 쉬운 흐름”을 보호해 줍니다.

7. MCP(외부 도구) 연동하기 — 필수는 아니지만 매우 강력함

초급자는 스킵해도 되지만, 나중에 쓰면 정말 유용한 기능입니다.

예: 웹 검색 MCP 활성화

"mcp": {
  "websearch_exa": true
}

이러면 자연어로 이렇게 말할 수 있습니다:

이 코드와 비슷한 패턴이 GitHub에 있는지 찾아줘.

8. 초급 개발자를 위한 권장 설정 순서

아래 순서대로 설정하면 시행착오가 거의 없습니다.

  1. global 설정 파일 생성 (~/.config/opencode/oh-my-opencode.json)
  2. 기본 agent 3~4개 등록 (@oracle, @explore, @document 등)
  3. keyword-detector / auto-compact 활성화
  4. 프로젝트 루트에 AGENTS.md 1개 생성
  5. auth, billing 같은 핵심 폴더에만 추가 AGENTS.md 배치
  6. 필요한 순간에만 MCP 연동

이 6단계면 거의 모든 초급자–중급자 개발환경은 안정적으로 구성됩니다.

9. 실제 예시: “이 커밋 구조 괜찮아?”라고 물어보는 시나리오

설정을 마쳤다면 이제 다음과 같은 대화 흐름이 가능합니다:

@oracle 지금 src 디렉터리 전체 구조가 너무 무거운 느낌이야.
각 폴더 기능을 기반으로 리팩터링 제안해줘.

或

@document 방금 만든 기능을 팀 문서에 넣을 버전으로 요약해줘.

或

@explore 이 함수가 어디서 호출되는지 전부 찾아줘.

초급 개발자도 “에이전트에게 맡길 수 있는 순간”이 크게 확장됩니다.

组织起来

이번 글에서는Oh My OpenCode의 설치 및 설정 방법을
초급 개발자도 어렵지 않게 따라 할 수 있는 수준으로 정리했습니다.

핵심 요점은 다음과 같습니다.

  • 설치는 한 줄이면 끝
  • 설정 파일은 global → project override 방식이 편함
  • agent 구성은 회사 조직처럼 역할 중심으로 만들면 잘 작동
  • 규칙(AGENTS.md)은 프로젝트 관점을 AI에게 심어주는 핵심 방법
  • hooks는 초급자를 보호하고 흐름을 자동화해주는 보조 시스템

이제 다음 글에서는 다중 에이전트 기반 작업 흐름(ultrawork) 실전 예시를 다룹니다.
여기서부터 OpenCode 개발 경험이 진짜 “레벨업”됩니다.

类似文章