오픈코드(OpeCode) 퀵스타트: 설치, 설정 및 실행 가이드

Oh My Opencode 는 OpenCode 를 **멀리 에이전트 코딩 하네스 (multi-agent coding harness)**로 변신시킵니다. 오케스트레이터가 작업을 병렬로 실행하는 전문 에이전트에게 위임합니다.

가장 간단한 정신적 모델은 다음과 같습니다: 플러그인을 설치한 다음, 전체 파워의 다중 에이전트 실행이 필요할 때 키워드 ultrawork(또는 ulw) 를 사용하세요.

이 빠른 시작 가이드는 설치 및 첫날 설정을 다룹니다. 설정을 완료하고 작동하면 다음을 참고하세요:

• 전문 에이전트 심층 분석 — 모델 라우팅 및 자체 호스팅 가이드와 함께 모든 에이전트 설명
• Oh My Opencode 경험 — 솔직한 벤치마크 및 실제 бил링 주의사항

더 넓은 AI 코딩 툴체인에 대해서는 AI 개발자 도구 개요 를 참조하세요. OpenCode 에 대한 샌드박스화되고 브라우저에서 실행 가능한 대안을 선호한다면, OpenHands 는 에이전트 코딩에 다른 아키텍처 접근 방식을 취합니다.

Oh My Opencode 가 존재하는 이유

OpenCode 는 터미널 UI 로 실행되며 스크립팅 및 자동화를 위한 비대화식 CLI 실행을 처리하는 오픈소스 AI 코딩 에이전트입니다.

Oh My Opencode 은 이 한계를 훨씬 더 높게 끌어올립니다. “시시포스 (Sisyphus)“에이전트를 중심으로 한 전체 오케스트레이션 레이어, 다중 전문가 협업, 더 긴밀한 도구 통합을 추가합니다. 그 결과로, 평소에는 여러 프롬프트를 모니터링해야 하는 복잡한 엔지니어링 작업이 단일 워크플로우에서 계획, 위임, 검증되는 시스템이 만들어집니다.

두 가지 개념이 끊임없이 등장하므로 다른 것보다 먼저 숙지하세요:

• Ultrawork 모드: 키워드 트리거 워크플로우 전환. 프롬프트에 ultrawork 또는 ulw 를 추가하면 병렬 백그라운드 실행, LSP 통합, 컨텍스트 관리, 자동 작업 분해가 활성화됩니다. 이는 단순한 스타일적인 선택이 아닙니다.
• 전문 에이전트: 아키텍처를 위한 @oracle, 연구 및 문서를 위한 @librarian 과 같은 이름이 붙은 역할입니다. 명시적으로 호출하거나 오케스트레이터가 자동으로 라우팅하도록 할 수 있습니다.

이 글에서는 Oh My Opencode, oh-my-opencode, Oh My OpenCode를 상호 교환적으로 사용합니다 — 모두 OpenCode 생태계의 동일한 플러그인을 지칭합니다.

사전 요구 사항 및 용어

먼저 OpenCode 가 설치되어 작동해야 합니다. 설치, 설정 및 시작 방법을 배우려면 OpenCode 빠른 시작 을 참조하세요.

기본적으로 opencode 는 인자가 없을 때 터미널 UI 를 시작하며, 비대화식 실행을 위해 opencode run ... 도 사용할 수 있습니다.

Oh My Opencode 은 최소 하나의 제공자가 설정되어 있어야 합니다. OpenCode 는 자격 증명, 환경 변수, 또는 프로젝트 .env 에서 제공자를 로드합니다. 이를 가장 빠르게 해결하는 방법은 다음과 같습니다:

opencode auth login
opencode auth list

자격 증명은 ~/.local/share/opencode/auth.json 에 저장됩니다.

미리 알아두어야 할 명명상의 특이점이 하나 있습니다: 업스트림 GitHub 저장소는 이제 oh-my-openagent (이전 oh-my-opencode) 로 브랜딩되어 있지만, 설정 파일의 플러그인 및 패키지 이름은 여전히 oh-my-opencode입니다. 두 이름 모두 커뮤니티 게시글에서 사용되지만, 동일한 것을 의미합니다.

설치 빠른 시작

CLI 설치기, 수동 저장소 복제, 또는 “에이전트가 설치하도록 함"을 포함한 여러 경로가 있습니다. 반복 가능한 설치 흐름을 원하는지 완전한 수동 제어를 원하는지에 따라 올바른 선택이 달라집니다.

Bun 이 설치되어 있다면, bunx 는 Bun 의 npx 와 동등하며 별도의 전역 설치 단계 없이 npm 패키지를 빠르게 실행하도록 설계되었습니다.

리눅스에서 bunx 설치:

curl -fsSL https://bun.com/install | bash

OpenCode 를 통한 자동 설치

OpenCode 에서 프롬프트를 실행하면 OmO 가 자동으로 설치됩니다.

• OpenCode, CursorAI, 또는 CloudeCode 를 시작합니다.
• 아래 프롬프트를 복사하여 실행하세요 (설치 세부 정보: https://github.com/code-yeongyu/oh-my-openagent)

Install and configure oh-my-opencode by following the instructions here:
https://raw.githubusercontent.com/code-yeongyu/oh-my-openagent/refs/heads/dev/docs/guide/installation.md

이 명령은 사용자의 LLM 구독에 대해 몇 가지 질문을 하고 OpenCode 플러그인에 Oh My Opencode 를 등록합니다.

수동 경로: bunx 또는 npx 를 사용하여 Oh My Opencode 설치기 실행

제공자에 대해 질문하고 자동으로 “최적” 설정을 생성하는 대화형 설치기, 그리고 자동화 및 에이전트를 위한 비대화형 모드를 제공합니다.

대화형 설치:

bunx oh-my-opencode install
# 또는 npm 도구를 선호하는 경우
npx oh-my-opencode install

비대화형 설치 (프라이비셔닝 스크립트, CI 이미지 또는 “에이전트 설치"에 유용):

bunx oh-my-opencode install --no-tui \
  --claude=<yes|no|max20> \
  --openai=<yes|no> \
  --gemini=<yes|no> \
  --copilot=<yes|no>

설치기가 상위 수준에서 수행하는 작업:

• OpenCode 설정에 플러그인 등록
• 제공가 가용성 및 폴백 규칙을 사용하여 모델 할당 생성
• OpenCode 설정 파일과 함께 oh-my-opencode 설정 작성

수동 경로: 저장소 복제 및 설치 스크립트 실행

“인간” 수동 흐름도 있습니다: 저장소를 복제하고 종속성을 설치한 다음 설치 스크립트를 실행합니다. 이 스크립트는 OpenCode 설정 위치를 감지하고 백업을 만든 다음 설정을 병합합니다.

git clone https://github.com/code-yeongyu/oh-my-opencode.git ~/.oh-my-opencode
cd ~/.oh-my-opencode
npm install
npm run install

스크립트가 자동으로 OpenCode 설정을 찾을 수 없는 경우, 설치기를 다시 실행하기 전에 설정 경로 환경 변수를 명시적으로 설정하세요.

빠른 검증 체크리스트

설치 후 다음 세 가지를 확인하세요:

• Oh My Opencode 설정 파일이 인식된 위치에 존재하는지
• 전문 에이전트를 호출할 수 있는지
• ultrawork 키워드 트리거가 예상대로 작동하는지

복사하여 사용할 예시:

# 플러그인 설정 파일 표시 (설치 환경에 맞는 위치 시도)
cat .opencode/oh-my-opencode.json
cat ~/.config/opencode/oh-my-opencode.json

# 빠른 에이전트 테스트
opencode run "Use @oracle to analyse the architecture of the current project"

# 빠른 ultrawork 트리거 테스트
opencode run "ulw list all configuration files in this project"

세 가지 모두 통과하면 단순히 설치된 것이 아니라 실제로 준비가 된 것입니다.

설정 및 튜닝

설정 위치 및 우선순위 작동 방식

Oh My Opencode 은 우선순위에 따라 설정 파일을 검색하며, 프로젝트 수준의 설정이 사용자 수준 설정보다 우선합니다. 문서화된 검색 순서는 다음과 같습니다:

• .opencode/oh-my-opencode.json (프로젝트 수준, 최고 우선순위)
• ~/.config/opencode/oh-my-opencode.json (macOS 및 Linux 의 사용자 수준)
• %APPDATA%\opencode\oh-my-opencode.json (Windows 의 사용자 수준)

OpenCode 자체도 여러 설정 소스를 지원하며, 키가 충돌할 때만 뒤쪽 소스가 앞쪽 소스를 덮어쓰며 병합합니다. 이는 일반적으로 안정적인 글로벌 기본값과 저장소별 오버라이드를 모두 원하기 때문에 중요합니다.

합리적인 설정을 위한 JSONC 지원

OpenCode 와 Oh My Opencode 은 모두 JSONC 를 지원하므로, 파싱을 깨뜨리지 않고 설정 파일에 주석과.trailing commas 를 유지할 수 있습니다. 이는 특정 제한이나 모델이 선택된 이유를 문서화하는 데 특히 유용합니다.

“ultrawork” 키워드 및 활성화 기능

ultrawork(또는 ulw) 는 가장 많이 사용할 모드 전환입니다. 작업 설명에 추가하면 시스템이 백그라운드 병렬 실행, LSP 통합, 컨텍스트 관리, 자동 작업 분해를 활성화합니다. 이는 모델에 대한 힌트가 아니라 전체 실행 구조를 변경하는 하드 트리거입니다.

병렬성 및 백그라운드 작업

Oh My Opencode 은 sisyphus.max_concurrent_tasks 를 통해 백그라운드 실행을 위한 병렬성 제어를 제공합니다.

여기서 높은 병렬성을 추구하지 마세요. 각 제공자 플랜에는 한계가 있습니다 — 예를 들어 Claude Max20 은 3 개의 병렬 작업이 최대입니다 — 이를 초과하면 불완전한 완료와 디버깅하기 어려운 타임아웃이 발생합니다. 보수적으로 시작한 후 깨끗한 실행을 통해만 증가시키세요.

최소한의 병렬성 설정은 다음과 같습니다:

{
  "sisyphus": {
    "enabled": true,
    "max_concurrent_tasks": 2,
    "task_timeout": 300
  }
}

병렬성 2 는 대부분의 플랜에 안전한 시작점입니다.

에이전트별 및 카테고리별 모델 라우팅

Oh My Opencode 은 다른 작업이 다른 모델에서 이익을 본다는 아이디어를 중심으로 설계되었으며, 설정은 다음을 지원합니다:

• 에이전트별 모델 선택, 변형 및 프롬프트 확장
• “빠른” 작업과 “심층” 작업을 위한 카테고리 기반 라우팅
• 선호하는 제공자가 사용할 수 없을 때의 폴백 모델

전문 에이전트 심층 분석에서는 모델 라우팅 시스템 전체를 자세히 다룹니다 — 특정 에이전트를 잘못된 모델 패밀리로 전환해서는 안 되는 이유, 완전한 폴백 체인, 자체 호스팅 설정을 위해 모델을 안전하게 오버라이드하는 방법 등이 포함되어 있습니다.

모델 해석은 계층적입니다: 명시적 오버라이드가 우선하고, 다음으로 제공자 폴백, 시스템 기본값이 적용됩니다. 폴백 체인은 네이티브 제공자로 시작하며, 다른 대안이 없으면 GitHub Copilot 과 같은 대안으로 내려갈 수 있습니다 — 이는 잘못 구성된 에이전트가 침묵으로 실패할 가능성이 낮음을 의미하며, 단순히 더 약한 모델을 사용할 뿐입니다.

적용 가능한 실용적인 시작 설정 (JSONC 권장):

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

  // 제공자 한계를 신뢰할 때까지 병렬성을 보수적으로 유지
  "sisyphus": {
    "enabled": true,
    "max_concurrent_tasks": 2,
    "task_timeout": 300
  },

  // 에이전트 튜닝
  "agents": {
    "oracle": {
      "enabled": true,
      "model": "openai/gpt-5.2",
      "variant": "high",
      "temperature": 0.7,
      "prompt_append": "Provide concise tradeoffs and a clear recommendation"
    },
    "librarian": {
      "enabled": true,
      "model": "google/gemini-3.1-pro"
    }
  },

  // 빠른 쿼리와 심층 작업을 위한 카테고리 라우팅
  "categories": {
    "quick": { "model": "opencode/gpt-5-nano" },
    "visual-engineering": { "model": "google/gemini-3.1-pro" }
  }
}

$schema 필드는 유지할 가치가 있습니다 — 대부분의 에디터에서 자동 완성을 활성화하고, 에이전트 이름의 오타를 실행 전에 잡아줍니다.

MCP 통합 및 훅

Oh My Opencode 은 MCP(Model Context Protocol) 서버를 지원하며, 설정 블록에서 서버 명령, 인자, 환경 변수를 정의합니다.

실제로는 더 쉬운 방법은 설정 파일을 직접 건드리지 않고 opencode mcp 명령 그룹을 통해 OpenCode 에서 MCP 를 직접 관리하는 것입니다 — 추가, 목록, OAuth 인증을 처리합니다.

복사 가능한 워크플로우 예시

아래 두 예시는 의도적으로 “실제 저장소” 형식으로 설계되었습니다: 오케스트레이션 트리거 방법, 전문 에이전트 활용 방법, 결과 검증 방법을 보여줍니다.

예시: Oracle 과 저장소 맵을 활용한 아키텍처 검토

새 코드베이스에 합류하거나 서비스를 인수받았으며 아키텍처에 대한 신속하고 실행 가능한 개요가 필요할 때 사용하세요. Oracle 은 읽기 전용 전문가입니다 — 변경을 만들 수 없고 조언만 제공합니다.

프로젝트 루트에서 실행하세요:

opencode

OpenCode 는 인자가 없을 때 기본적으로 터미널 UI 를 시작합니다.

그런 다음 Oracle 에 아키텍처 분석 및 구체적인 리팩토링 또는 모듈화 계획을 요청하세요:

Use @oracle to analyse the architecture of this repository.
Identify the key bounded contexts, major dependency edges, and the highest risk components.
End with a refactoring plan that can be executed in small PRs.

로그 또는 스크립팅의 경우 TUI 를 완전히 건너뛰고 opencode run 을 사용하세요:

opencode run "Use @oracle to analyse the architecture of this repository and propose a staged refactor plan"

opencode run 은 프롬프트를 직접 전달하고 완료되면 종료됩니다 — CI 단계나 자동화 파이프라인에 정확히 필요한 기능입니다.

예시: ultrawork 오케스트레이션을 통한 전체 기능 구현

여러 파일이나 계층에 영향을 미치는 기능이 필요하거나, 백그라운드 작업 및 전문 에이전트를 자동으로 활성화하고 싶을 때 사용하세요.

ultrawork 프롬프트로 시작하세요:

opencode run "ultrawork implement a new /health endpoint with readiness and liveness checks, add tests, update documentation, and verify it runs locally"

ultrawork 키워드는 모든 설정된 전문 에이전트, 백그라운드 작업 병렬성, 더 깊은 도구를 한 번에 활성화합니다. 계획, 구현, 테스트를 위한 별도의 프롬프트가 필요하지 않습니다.

ultrawork 를 사용할 때 여전히 전문 에이전트 행위를 명시적으로 유도할 수 있습니다. 예를 들어 아키텍처 설계를 먼저 강제할 수 있습니다:

opencode run "ultrawork ask @oracle to design the endpoint contract and dependencies first, then implement with minimal changes and add tests"

ultrawork 와 @oracle 과 같은 명시적 에이전트 언급을 결합하는 것이 가장 좋습니다: 전체 오케스트레이션을 얻으면서도 어떤 전문가가 중요한 설계 결정을 처리할지 통제합니다.

더 큰 ultrawork 작업에 대해 올바르게 해야 할 한 가지: 제공자 한계 내에서 병렬성을 유지하세요. 2 로 시작한 후 몇 가지 작업을 깨끗하게 실행한 다음 증가할지 결정하세요. 플랜의 한계를 넘어서는 것이 더 빠르지 않습니다 — 신뢰할 수 없게 만듭니다.

문제 해결 및 모범 사례

Ultrawork 키워드가 트리거되지 않음

ulw 또는 ultrawork가 무시되는 경우, 플러그인 로딩 및 버전 호환성을 확인하는 신호로 여기세요. 키워드 감지가 예상되는 ultrawork 모드 프롬프트를 삽입하지 않는 것으로 보고된 최소 하나의 회귀가 있으며, 조사가 전용 키워드 감지 훅을 가리켰습니다.

실제로 가장 빠른 수정 방법은 다음과 같습니다:

• 플러그인이 등록되어 있고 설정 파일이 있는지 확인 (앞의 검증 체크리스트 참조)
• 키워드 감지가 회귀되는 버전이라면 OpenCode 또는 플러그인을 업그레이드

설치 스크립트가 OpenCode 설정을 찾지 못함

OpenCode 가 설치되어 있는지 확인 (opencode --version) 한 다음, 설치기를 다시 실행하기 전에 명시적인 설정 경로 환경 변수를 설정하세요.

너무 많은 백그라운드 작업 또는 스로틀링 문제

속도 제한, 타임아웃, 또는 불완전한 완료에 도달한 경우, 해결책은 항상 동일합니다: 병렬성을 줄이고 재실행하세요. 제공자가 이미 스로틀링하고 있을 때 더 높은 병렬성을 추구하는 것은 잃는 싸움입니다.

ultrawork 를 사용해서는 안 될 때

Ultrawork 는 강력하지만 무료는 아닙니다 — 각 병렬 에이전트는 토큰 비용이 발생하며 속도 제한에 포함됩니다. 이를 대형 리팩토링, 풀스택 기능 작업, 복잡한 다단계 작업에 예약하세요. 작은 단일 파일 편집이나 간단한 질문에는 일반 프롬프트가 더 빠르고 저렴합니다.

실용적인 규칙:

• 작은 편집과 간단한 질문에는 일반 프롬프트 사용
• 시스템이 저장소에서 분해, 위임, 실행, 검증을 수행하도록 원할 때 ultrawork 사용

제공자 약관에 대한 준수 참고사항

이 생태계 주변의 일부 커뮤니티 논의는 제공자 제한 및 서비스 약관, 특히 제 3 자 OAuth 및 호환성 레이어를 다룹니다. 이는 실제 제약입니다 — 대규모로 자동화 또는 병렬 워크플로우를 실행하기 전에 제공자의 약관을 검토하고, 작동하는 통합이 허용된다는 것을 가정하지 마세요.

더 깊게 탐험할 준비가 되셨나요? 전문 에이전트 심층 분석 은 모든 에이전트의 역할, 모델 요구사항, 자체 호스팅 옵션을 설명합니다. 솔직한 성능 데이터와 커뮤니티가 보고한 бил링 위험에 대해서는 Oh My Opencode 경험 글 을 참조하세요.