🔷 05. Oh-My-OpenCode 설치

설치부터 인증까지 한 번에 끝내는 실습 문서입니다. 그대로 따라하면 설치 성공 여부를 즉시 확인할 수 있습니다.

설치 목적이 아직 헷갈리면 먼저 04. Oh-My-OpenCode 개요를 보고 오세요. (무엇인지/왜 설치하는지/체감 이점 정리)

Ubuntu에서 bunx가 막힐 때 먼저 확인할 것

Ubuntu 사용자는 bunx oh-my-opencode install 단계에서 처음 막히기 쉽습니다. 이유는 간단합니다. bunx는 Node.js 명령이 아니라 Bun에 포함된 실행기라서, OpenCode만 설치되어 있어도 Bun이 없으면 바로 실행되지 않습니다.

가장 빠른 해결은 Bun 설치 → PATH 반영 → bunx 확인 → 설치 실행 순서로 가는 것입니다. Bun 공식 문서도 Linux에서는 unzip 패키지를 먼저 준비하고, 설치 후 bun --version으로 검증하라고 안내합니다.

sudo apt update
sudo apt install -y unzip
curl -fsSL https://bun.com/install | bash
 
# bash면 ~/.bashrc, zsh면 ~/.zshrc 다시 불러오기
source ~/.bashrc
 
bun --version
bunx --version

• bun: command not found가 뜨면 설치가 아직 안 끝났거나 PATH 반영이 안 된 상태입니다.
• bun은 되는데 bunx가 안 보이면 터미널을 새로 열거나 source ~/.bashrc / source ~/.zshrc를 다시 실행해 보세요.
• 회사 서버처럼 Bun 추가 설치가 부담되면 아래 대안처럼 npx oh-my-opencode install로 먼저 진행할 수도 있습니다. 다만 원문은 bunx 경로를 기본 추천합니다.

공식 참고

• Bun 설치 문서: https://bun.sh/docs/installation
• Oh-My-OpenCode 설치 원문: https://github.com/code-yeongyu/oh-my-opencode/blob/dev/docs/guide/installation.md

빠르게 실행 (복붙)

opencode --version
 
# Ubuntu에서 bunx가 처음이면 먼저 Bun 설치
sudo apt update && sudo apt install -y unzip
curl -fsSL https://bun.com/install | bash
source ~/.bashrc   # zsh 사용자는 source ~/.zshrc
bun --version
bunx --version
 
bunx oh-my-opencode install
bunx oh-my-opencode install --no-tui --claude=yes --openai=yes --gemini=yes --copilot=no
cat ~/.config/opencode/opencode.json
opencode auth login

flowchart TD
A[버전 확인] --> B[구독 옵션]
B --> C[설치]
C --> D[검증]
D --> E[인증]

단계별 적용

1) OpenCode 설치 확인

• 설명: opencode --version으로 OpenCode 선설치를 확인합니다. 없으면 먼저 OpenCode 설치를 끝냅니다.
• 실행 예시: opencode --version

2) 구독 플래그 결정

• 설명: Claude/OpenAI/Gemini/Copilot/OpenCode-Zen/Z.ai 사용 여부를 먼저 정하고 설치 플래그로 변환합니다.
• 실행 예시: bunx oh-my-opencode install

3) 설치 실행

• 설명: interactive(bunx ... install) 또는 non-interactive(--no-tui)로 설치합니다. Ubuntu에서 bunx: command not found가 뜨면 Bun 설치와 PATH 반영부터 먼저 끝내야 합니다.
• 실행 예시: bunx oh-my-opencode install --no-tui --claude=yes --openai=yes --gemini=yes --copilot=no
• Ubuntu 빠른 점검: bun --version && bunx --version

4) 설치 결과 검증

• 설명: ~/.config/opencode/opencode.json에서 plugin 등록 여부를 확인합니다.
• 실행 예시: cat ~/.config/opencode/opencode.json

5) 공급자 인증

• 설명: opencode auth login으로 Anthropic/Google/GitHub 등 필요한 인증을 진행합니다.
• 실행 예시: opencode auth login

Ubuntu에서 실제로 많이 막히는 두 가지

1) bunx: command not found

가장 흔한 경우입니다. OpenCode는 이미 설치돼 있어서 opencode --version은 잘 나오는데, 정작 bunx oh-my-opencode install에서 멈춥니다. 이럴 때는 OpenCode 문제가 아니라 Bun 런타임이 아직 없는 상태일 가능성이 큽니다.

확인 순서는 짧게 잡는 게 좋습니다.

opencode --version
bun --version
bunx --version

• 첫 줄만 되고 뒤의 두 줄이 안 되면 Bun 설치를 먼저 끝내면 됩니다.
• 설치 직후에도 안 되면 터미널을 새로 열거나 source ~/.bashrc, source ~/.zshrc를 다시 실행해 PATH를 반영하세요.

공식 기준 참고

• Bun 설치: https://bun.sh/docs/installation

2) 설치는 됐는데 플러그인이 안 보임

명령은 통과했는데 ~/.config/opencode/opencode.json에 oh-my-opencode가 안 보이면 설치가 중간에 실패했거나, 다른 셸/계정에서 실행했을 가능성을 먼저 봐야 합니다.

cat ~/.config/opencode/opencode.json

여기서 플러그인 배열에 oh-my-opencode가 보여야 다음 단계로 넘어가도 됩니다. 보이지 않으면 설치를 한 번 더 실행하고, 그래도 같으면 npx oh-my-opencode install로 한 번 교차 확인해보는 편이 빠릅니다.

빠른 현장 예시

• 개인 Ubuntu 노트북: Node.js와 OpenCode만 먼저 설치해 둔 상태에서 bunx를 바로 쳤다가 막히는 경우가 많습니다. 이때는 Bun 설치만 추가하면 대부분 바로 해결됩니다.
• 클라우드 Ubuntu 서버: SSH로 접속해 설치할 때는 Bun 설치 후 현재 셸에 PATH가 반영되지 않아 같은 오류가 반복되기도 합니다. 이런 경우는 새 로그인 세션을 열거나 source ~/.bashrc로 바로 확인하는 편이 가장 빠릅니다.

다음 읽기

• 04. Oh-My-OpenCode 개요
• 07. CLI 가이드
• 08. 설정 가이드
• 13. 트러블슈팅 예시

부록) 원문 코드 스니펫 (검수용, 초보자는 건너뛰기)

bunx oh-my-opencode install # recommended
npx oh-my-opencode install # alternative

bunx oh-my-opencode install --no-tui --claude=<yes|no|max20> --gemini=<yes|no> --copilot=<yes|no> [--openai=<yes|no>] [--opencode-zen=<yes|no>] [--zai-coding-plan=<yes|no>]

opencode --version  # Should be 1.0.150 or higher
cat ~/.config/opencode/opencode.json  # Should contain "oh-my-opencode" in plugin array

opencode auth login
# Interactive Terminal: find Provider: Select Anthropic
# Interactive Terminal: find Login method: Select Claude Pro/Max
# Guide user through OAuth flow in browser
# Wait for completion
# Verify success and confirm with user

{
  "plugin": [
    "oh-my-opencode",
    "opencode-antigravity-auth@latest"
  ]
}

{
  "agents": {
    "multimodal-looker": { "model": "google/antigravity-gemini-3-flash" }
  }
}

opencode auth login
# Interactive Terminal: Provider: Select Google
# Interactive Terminal: Login method: Select OAuth with Google (Antigravity)
# Complete sign-in in browser (auto-detected)
# Optional: Add more Google accounts for multi-account load balancing
# Verify success and confirm with user

bunx oh-my-opencode install
# Select your subscriptions (Claude, ChatGPT, Gemini)
# When prompted: "Do you have a GitHub Copilot subscription?" → Select "Yes"

마무리 체크

• 위 “빠르게 실행” 명령을 최소 1개 실행했다.
• 실패 시 “원문 실행 코드 확장”의 관련 코드를 사용해 재검증했다.
• 원본 항목 대조 인덱스에서 빠진 기능이 없는지 확인했다.

이 문서는 AI를 활용해 초안을 정리했고, 명령어와 설치 흐름은 공식 문서 기준으로 다시 확인했습니다.

---

출처

• 원문(로컬): oh-my-opencode/docs/guide/installation.md
• 원문(GitHub): https://github.com/code-yeongyu/oh-my-opencode/blob/dev/docs/guide/installation.md