Opencode 사용후기 및 사용방법 정리

Opencode란?

OpenCode는 Claude Code처럼 “말로 시키면 코드 작업을 해주는” 코딩 에이전트입니다.

클로드 코드와의 차이점은 오픈소스라서 누구나 소스코드를 확인할 수 있고, OpenAI·Claude·Gemini 등 여러 LLM을 API 키로 골라 연결해 쓸 수 있다는 점입니다.

최근 유행을 타기 시작했지만, 2025년 6월달에 정식 출시되었고 베타는 그 이전부터 개발되어 온 만큼, 생각보다 역사가 긴 편입니다.

그러면 Oh my opencode란?

Claude Code가 marketplace를 통해 외부 플러그인을 추가할 수 있는 것처럼 OpenCode 역시 Plugin 을 지원합니다.

Oh my opencode는 OpenCode 위에서 동작하는 플러그인으로, 기본 시스템 프롬프트만으로는 아쉬운 부분들을 아래에서 소개할 기능들로 보완해줍니다.

Opencode 의 기능들

MCP

websearch (Exa 기반 실시간 웹검색)
context7 (공식 문서 조회)
grep_app (공개 GitHub 코드 검색)

Agents

다양한 agent 가 상황에 따라 적절한 모델과 프롬프트로 작업을 진행합니다

시시푸스 Sisyphus (Claude Opus 4.5) - 기본 에이전트
- 전체 에이전트를 관리 / 작업 계획, 위임, 병렬 실행
- TODO 중심 워크플로우
oracle (GPT-5.2)
- 아키텍처 설계 / 코드 리뷰 / 기술·전략 판단
librarian (GLM-4.7 Free)
- 다중 레포 분석 / 문서 탐색 / 구현 예제 및 근거 기반 리서치
explore (Grok / Gemini 3 Flash / Claude Haiku)
- 빠른 코드 탐색 / 패턴 매칭 / 환경에 따라 모델 자동 선택
frontend-ui-ux-engineer (Gemini 3 Pro)
- UI/UX 설계 및 구현
document-writer (Gemini 3 Flash)
- 기술 문서 작성 / 읽기 쉬운 자연스러운 문장
multimodal-looker (Gemini 3 Flash)
- 이미지, PDF, 다이어그램 분석 / 시각 자료에서 정보 추출

예시로 설명해보면, 사용자가 시시푸스(Sisyphus) 에이전트에게 아래처럼 질문을 던졌을 때:

우리 서비스에서 로그인 상태가 가끔 갑자기 풀리는데, 원인 좀 찾아서 해결 방향까지 정리해줘.

시시푸스는 문제를 쪼개서 다음과 같이 하위 에이전트에게 작업을 위임해 병렬로 진행합니다.

@explore“세션/로그아웃” 패턴과 최근 의심스러운 변경 사항을 신속히 스캔해.
@librarian 세션/쿠키/토큰이 구현된 위치를 찾아내고 흐름을 요약해.
@oracle 견고한 세션 아키텍처와 완화 방안(예: 리프레시, 회전, 캐시/CDN 상호작용)을 제안해

Tool

위에서 언급된 MCP 이외에도 Oh my opencode가 기본 OpenCode에 추가로 제공하는 도구(Tool)들이 있습니다.

session_list / session_read / session_search / session_info
- 세션을 목록으로 확인하거나 특정 세션을 읽고/검색하고/메타 정보를 조회할 수 있습니다.
lsp_*
- LSP(Language Server Protocol) 기반 기능들을 호출해 코드 탐색/분석을 보조합니다.
call_omo_agent
- 작업 성격에 맞게 적절한 하위 에이전트가 자동으로 실행되도록 라우팅/오케스트레이션을 도와줍니다.

Hooks

에이전트가 의도한 방식으로 작업하도록, Hook을 통해 동작을 강제하거나 검증 단계를 끼워 넣을 수 있습니다.

예를 들어 comment-checker는 코드 수정 이후 AI가 불필요한 설명(주석/코멘트)을 코드에 끼워 넣었는지를 검사합니다.

이 외에도 todo-continuation-enforcer, context-window-monitor, session-recovery, session-notification 등 20개가 넘는 Hook이 제공되어, 에이전트를 더 쉽게 컨트롤하고 코드 품질을 일정하게 유지하는 데 도움을 줍니다.

Ultrawork

프롬프트에 ultrawork 또는 ulw를 입력하면 ULTRAWORK 모드가 활성화됩니다.

이때 추가 프롬프트가 함께 적용되어 병렬 에이전트 실행, 플래닝, 검증(체크) 같은 과정을 더 강하게 강제하며 작업을 진행합니다.

기타 커맨드

/ralph-loop - 작업이 완료될 때까지 중단 없이 에이전트 루프를 계속 실행합니다.

1주일간 사용 후기

그동안 Claude Code를 비롯해 에이전트 도구의 활용성을 높이려는 여러 프레임워크와 플러그인들이 등장했습니다. 하지만 막상 사용해 보면 토큰 소모만 많을 뿐, 기대만큼의 실질적인 효용을 느끼기 어려운 경우가 많았습니다.

반면, Oh my opencode는 완성도가 상당히 높다는 인상을 받았습니다. 별도의 학습 없이도 즉시 실무에 적용할 수 있는 구성이 큰 장점이더군요.

특히 그간 Claude Code의 잔버그(스크롤 깜빡임 등)로 인해 피로감이 컸는데, 드디어 '오래 정착할 수 있겠다' 싶은 도구를 찾은 기분입니다. 당분간은 OpenCode를 주력으로 사용할 계획입니다.

Anthropic의 Opencode 차단 관련 내용

Anthropic의 Claude 모델은 API 비용이 꽤 높은 편이지만, Claude Max 구독을 활용하면 상대적으로 저렴하게 이용할 수 있었습니다. 그 이후 Claude Code가 출시되면서, 이를 우회해 구독 토큰을 제3자 도구에 연결하려는 시도가 늘었고, 관련 도구들과 Anthropic 사이에 기술적 차단과 우회가 반복되는 공방이 이어져 왔습니다.

그런데 OpenCode + OhMyOpencode 조합이 유행하면서 우회 사용량이 눈에 띄게 증가하자, 2026년 1월 초부터 Anthropic이 공식적으로 OpenCode를 언급하며 백엔드 업데이트와 각종 검증을 강화했고, 그 결과 일부 서드파티 경로가 차단되는 상황이 발생했습니다.

약관 위반 및 계정 정지 리스크

Anthropic은 이런 형태의 사용을 서비스 이용약관(ToS) 위반으로 보는 쪽에 가깝고, 커뮤니티에서도 “계정 제재” 리스크가 있다는 보고가 꾸준히 올라옵니다. (Github Issue, Issue 2, Article)

글 작성 시점 기준으로는 우회가 되어 실제 사용은 가능하지만 약관 관점에서 권장하기는 어려운 상황입니다.

OmO README 언급: https://github.com/code-yeongyu/oh-my-opencode?tab=readme-ov-file#full

반대로 ‘공식 지원’ 쪽으로 움직이는 사례도 있음

흥미로운 건, 모든 회사가 같은 방향으로 움직이는 건 아니라는 점입니다.

OpenAI: ChatGPT Plus/Pro 구독을 OpenCode에서 사용할 수 있도록 공식적으로 협력하였습니다
GitHub Copilot: GitHub Copilot 구독으로 OpenCode에서 공식 사용이 가능합니다

설치 및 사용가이드 (Opencode + Oh my opencode)

아래는 Opencode + Oh my opencode를 처음 설치해서 사용하는 방법입니다.

(운영체제/셸 환경에 따라 경로/권한 이슈가 있을 수 있음.)

1) Bun 설치하기

Node/Bun 기반 도구라서 Bun 설치가 먼저 필요합니다.
터미널을 실행하고 아래 명령어를 순차적으로 실행해주세요

macOS / Linux

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

설치 후 현재 터미널에서 bun이 인식이 안 되면 보통 아래 중 하나가 필요합니다.

# zsh
source ~/.zshrc

# bash
source ~/.bashrc

그리고 버전 확인:

bun --version

Windows (PowerShell)

powershell -c "irm bun.sh/install.ps1|iex"

설치 후 PowerShell/터미널을 새로 열고:

bun --version

올바르게 버전이 표시되는지 확인해주세요

2) Opencode 설치하기

전역 설치:

bun add -g opencode-ai

정상 설치 확인:

opencode --version

2-1) Opencode 데스크탑 앱 설치하기

최근 베타로 출시된 데스크탑 앱을 설치하실 수도 있습니다.

다운로드 페이지 👉 https://opencode.ai/download

앱 설치후, 반드시 CLI 도 함께 설치해주세요. (메뉴 → Install CLI)

3) Oh my opencode 설치하기

터미널에서 다음 명령어를 실행해주세요:

bunx oh-my-opencode install

만약 설치에 문제가 생긴다면, 에이전트(Claude Code, Cursor, Antigravity 등) 에서 다음 프롬프트로 설치를 진행해주세요:

Install and configure by following the instructions here <https://raw.githubusercontent.com/code-yeongyu/oh-my-opencode/refs/heads/master/README.md>

4) 로그인하기 (모델 연결)

Opencode는 사용할 모델(Claude/ChatGPT/Gemini 등) 를 연결해야 사용할 수 있습니다

터미널에서 연결

opencode auth login

키보드 화살표키로 모델(Provider) 선택, 엔터
- Anthropic(클로드), OpenAI(GPT, Codex), Google (Gemini)
안내에 따라 설치를 진행합니다

데스크탑 앱

왼쪽 하단 + 버튼 클릭
원하는 Provider 선택
- Anthropic(클로드), OpenAI(GPT, Codex), Google (Gemini)

5) 기본 실행 및 사용팁

기본적으로 클로드 코드/커서 등 다른 에이전트 도구들과 비슷하기에 어렵지 않게 사용하실 수 있습니다.

데스크탑 앱에서 사용하기

위 설치 섹션을 참고하여 데스크탑 앱 설치 후, Opencode 앱을 실행합니다.

터미널 버전 사용하기

터미널에서 Opencode 실행:

opencode

이후 프롬프트를 입력하여 사용하실 수 있습니다.

기본 사용팁

테마변경 - Ctrl + P → Switch Theme
라이트 모드 <> 다크모드 전환하기 - Ctrl + P→ Toggle appearance
Web UI - Ctrl + P → Open Web UI
- 터미널 환경이 익숙하지 않을때, 웹에서 오픈코드를 사용하실 수 있습니다

에디터에서 사용하기

vscode/windsurf/cursor 등 에디터에서 확장프로그램 opencode 를 설치해주세요

핵심 단축키/기능 정리 (OpenCode)

빠른 실행 (Quick Launch)
- 단축키: Mac Cmd + Esc | Windows/Linux Ctrl + Esc
- 동작: OpenCode를 터미널 화면을 반쯤 나눠서(splits) 열거나, 이미 열려 있으면 그 터미널로 포커스 이동.
새 세션 시작 (New Session)
- 단축키: Mac Cmd + Shift + Esc | Windows/Linux Ctrl + Shift + Esc
- 동작: 기존 세션이 열려 있어도 무조건 새 OpenCode 터미널 세션을 시작.
- 대안: UI의 OpenCode 버튼을 눌러서도 가능.
컨텍스트 자동 공유 (Context Awareness)
- 동작: 지금 보고 있는 선택 영역/현재 탭 정보가 자동으로 OpenCode에 공유돼서, 맥락 이어서 작업하기 편함.
파일 참조 삽입 (File Reference Shortcuts)
- 단축키: Mac Cmd + Option + K | Windows/Linux Alt + Ctrl + K
- 동작: 대화/입력창에 파일 참조를 빠르게 삽입.
- 예시: @File#L37-42 → 파일의 37~42줄을 가리키는 참조를 넣음.

7) Ohmyopencode 를 이용하여 개발하기

이전에 클로드 코드를 사용했듯 동일하게 사용하시면 됩니다.

단 한가지, 복잡한 작업을 처리할때 ulw(또는 ultrawork) 키워드를 프롬프트에 포함해주세요.

Opencode 기능 파해치기

0) 설정파일 사용방법

claude code 에서 <프로젝트>/.claude 를 사용하듯,opencode도 <프로젝트>/.opencode 를 사용합니다

└─ <project-root>/
   ├─ opencode.json              # 프로젝트별 설정 (전역/remote보다 우선)
   └─ .opencode/                 # “디렉터리 기반” 확장 설정들
      ├─ agents/                 # 에이전트 정의들
      ├─ commands/               # 커맨드/단축 실행 정의들
      └─ skills/                 # 프로젝트 로컬 스킬

Claude code 설정 호환

Oh my opencode 덕분에 Claude Code와 opencode 의 설정은 호환됩니다.
따라서 아래의 세부적인 Opencode 사용방법을 모르셔도, 기존 Claude 설정을 그대로 사용하실 수도 있습니다

  ┌─────────────────────┐     ┌─────────────────────┐
  │     Claude Code     │     │      OpenCode       │
  │   (Anthropic 공식)    │     │    (SST 오픈소스)    │
  ├─────────────────────┤     ├─────────────────────┤
  │ ~/.claude/          │  ✗  │ ~/.config/opencode/ │
  │ settings.json hooks │  ✗  │ Plugin SDK          │
  │ .mcp.json           │  ✗  │ opencode.json       │
  │ commands/*.md       │  ✗  │ 자체 command 시스템   │
  └─────────────────────┘     └─────────────────────┘
           ↓                           ↓
     원래는 서로 호환 안됨

oh-my-opencode 플러그인이 Claude Code 설정을 읽어서 OpenCode가 이해하는 형식으로 변환해줍니다:

  ┌─────────────────────────────────────────────────────────┐
  │                    oh-my-opencode                        │
  │  ┌───────────────────────────────────────────────────┐  │
  │  │            Claude Code 호환 레이어                  │  │
  │  │                                                   │  │
  │  │  ~/.claude/settings.json  ──→  tool.execute.*    │  │
  │  │  ~/.claude/.mcp.json      ──→  OpenCode MCP      │  │
  │  │  ~/.claude/commands/      ──→  slashcommand tool │  │
  │  │  ~/.claude/todos/         ──→  session state     │  │
  │  │  ~/.claude/transcripts/   ──→  로그 기록          │  │
  │  └───────────────────────────────────────────────────┘  │
  └─────────────────────────────────────────────────────────┘
                            ↓
                OpenCode Plugin SDK

비활성화 하고싶다면 ~/.config/opencode/oh-my-opencode.json 을 수정해주세요

  {
    "claude_code": {
      "mcp": false,
      "commands": false,
      "skills": false,
      "agents": false,
      "hooks": false,
      "plugins": false
    }
  }

*자세한 내용은 https://opencode.ai/docs/config/ 를 확인해주세요

1) AGENTS.md

클로드 코드에서의 CLAUDE.md 와 완전 동일한 역할의 파일입니다.

Opencode 에서는 AGENTS.md 를 대신 사용합니다.

만약 CLAUDE.md 를 계속 사용하고 싶다면, 다음과 같이 설정을 커스텀하실 수 있습니다.

{
  "$schema": "<https://opencode.ai/config.json>",
  "instructions": ["CLAUDE.md"]
}

*자세한 내용은 https://opencode.ai/docs/rules/ 를 확인해주세요

2) MCP 설치하기

https://opencode.ai/docs/mcp-servers

현재 데스크탑 앱 또는 웹에서는 MCP 설치를 지원하지 않습니다. 번거롭지만 설정 파일을 직접 수정하여야 합니다 🥲

~/.config/opencode/opencode.json 경로의 파일을 에디터로 열어주세요.
“mcp” → “mcp-tool-name” → config 항목을 수정하여 MCP 를 추가할 수 있습니다
- config 에 어떤 JSON 설정을 입력해야할지 모르겠다면, opencode mcp add 명렬어로 config 를 추가할 수 있습니다

설치 예시 - Linear

다음과 같이 config 를 수정합니다

{
  ...
	"mcp": {
	  ...
	  "linear": {
      "type": "remote",
      "url": "<https://mcp.linear.app/mcp>",
      "oauth": {}
    }
  }
}

터미널에서 opencode mcp auth 명령어를 실행해 로그인합니다

설치 예시 - Context7

*context7은 기본적으로 Ohmyopencode 를 통해 설정되어 있습니다.

{
  ...
	"mcp": {
	  ...
		"context7": {
      "type": "remote",
      "url": "<https://mcp.context7.com/mcp>"
    }
  }
}

설치예시 - Chrome dev tools

{
  "mcp": {
    "chrome-devtools": {
      "type": "local",
      "command": [
        "npx",
        "-y",
        "chrome-devtools-mcp@latest"
      ],
      "enabled": false
    }
  }
}

특정 Agents에서만 MCP 허용하기

Claude code 에서는 지원하지 않는 기능이지만 opencode 에서는 특정 Agent 에서만 MCP 활성화, 메인 에이전트에서는 비활성화 하는 방식으로 토큰을 절약할 수 있습니다

{
  "$schema": "<https://opencode.ai/config.json>",
  "mcp": {
    "my-mcp": {
      "type": "local",
      "command": ["bun", "x", "my-mcp-command"],
      "enabled": true
    }
  },
  "tools": {
    "my-mcp*": false
  },
  "agent": {
    "my-agent": {
      "tools": {
        "my-mcp*": true
      }
    }
  }
}

MCP 설치 확인하기

방법 1) 터미널에서 opencode mcp list 실행
방법 2) Opencode 앱 실행(MCP 설치이후 재시작 필요) → 세션 클릭 → 우측 상단 MCP 메뉴 클릭

3) Skills 만들어 사용하기

https://opencode.ai/docs/skills/

4) Agents 만들어 사용하기

https://opencode.ai/docs/agents/

가능한 다양한 내용을 쉽게 설명하려 노력했지만 모든 내용을 포함하고 있지는 않습니다.

사용 중 추가로 궁금한 점이 생긴다면 아래 공식 문서와 자료를 참고해 주세요.

Oh My Opencode: https://github.com/code-yeongyu/oh-my-opencode
Opencode 공식 문서: https://opencode.ai/docs/

물론, 직접 읽을 필요는 없고 에이전트에게 질문하면 됩니다.

예)

<https://github.com/code-yeongyu/oh-my-opencode
ohmyopencode가 그래서 뭐라는건지 전혀 모르겠어

https://opencode.ai/docs/
Opencode에 hook을 설정하려면 어떻게 해야해?