OpenCode 사용법 가이드: 시작 방법, 실전 팁 7가지, Oh My OpenCode와 함께 쓰는 법

Name

Soren Atelier

업데이트 2026. 3. 17.

OpenCode는 터미널 중심으로 동작하는 오픈소스 AI 코딩 에이전트입니다. 데스크톱 앱, IDE extension, provider-agnostic 모델 레이어까지 갖추고 있어서, 한국어 검색 의도에서 중요한 질문은 "무엇을 할 수 있나?"보다 "언제 기본 OpenCode로 충분하고, 언제 Oh My OpenCode 같은 orchestration layer를 더해야 하나?"에 가깝습니다.

가장 실용적인 시작법은 분명합니다. OpenCode만 먼저 익히는 것입니다. plan / build 흐름을 이해하고, 실제 AGENTS.md를 만들고, 권한과 custom command를 다루는 감각을 먼저 잡으세요. 그다음에야 더 강한 multi-model routing, background specialist, 더 공격적인 실행 흐름이 필요한 경우 Oh My OpenCode를 붙이는 편이 좋습니다.

먼저 큰 그림이 필요하다면 AI Coding 토픽 페이지, Codex 사용법 가이드, 병렬 코드 에이전트 가이드를 함께 보면 좋습니다. 상위 레벨에서 다른 에이전트 프레임워크와 비교하고 싶다면 OpenClaw vs ZeroClaw vs Pi Agent vs Nanobot도 함께 보는 편이 유용합니다.

빠른 결론: OpenCode만 쓸까, Oh My OpenCode까지 붙일까?

OpenCode만으로도 대부분의 개발자가 필요한 핵심 루프는 충분히 커버됩니다. 코드베이스를 이해하고, 변경을 계획하고, 안전하게 편집하고, 터미널 중심으로 작업하는 흐름입니다. Oh My OpenCode와의 조합은 유용하지만, 첫 단계는 아닙니다.

OpenCode는 정확히 무엇인가

OpenCode는 터미널 우선 흐름에 맞춘 오픈소스 AI coding agent입니다. 공식 문서와 현재 README는 이를 다음처럼 설명합니다.

• TUI 우선 코딩 에이전트
• beta 상태의 데스크톱 앱
• IDE extension
• OpenAI, Anthropic, Google 등 다양한 backend와 함께 쓸 수 있는 provider-agnostic 시스템
• built-in agents, permissions, custom commands, rules, formatting, LSP support를 포함한 도구 묶음

중요한 관점은 이것입니다. OpenCode는 단순한 채팅창이 아니라 agent workflow surface입니다. 아래처럼 쓸 수 있습니다.

• 낯선 repo 빠르게 훑기
• 편집 전에 변경 계획 세우기
• 파일 수정과 shell command 실행
• AGENTS.md로 프로젝트 규칙 만들기
• 반복 가능한 slash command 정의하기
• repo 위험도에 맞춰 권한을 조이거나 풀기

참고할 점도 하나 있습니다. 오래된 튜토리얼은 이미 링크와 배포 경로가 바뀌었을 수 있습니다. 2026년 3월 17일 기준 현재 OpenCode 릴리스는 **anomalyco/opencode**에서 배포되며, 최신 GitHub 릴리스는 **v1.2.27**이고 2026년 3월 16일에 공개되었습니다. 옛날 archived repo나 redirect만 남은 페이지를 보면 현재 설치 대상이 아니라 과거 맥락일 가능성이 큽니다.

OpenCode 시작 방법

1. OpenCode 설치하기

공식 quick start는 다음입니다.

curl -fsSL https://opencode.ai/install | bash

Homebrew, npm, Scoop, Chocolatey, mise, nix 같은 경로도 있지만, 빨리 시작하려면 install script가 가장 간단합니다.

2. provider를 연결하고 실제 프로젝트를 열기

실행 후에는 공식 문서가 다음 흐름을 권장합니다.

/connect

그다음 TUI에서 opencode를 선택하고 opencode.ai/auth에서 인증하거나, 이미 쓰고 있는 provider를 설정하면 됩니다.

실무적으로는 처음부터 가장 큰 저장소를 잡지 않는 것이 좋습니다. 본인이 구조를 대략 알고 있어서 리뷰가 가능한 프로젝트부터 여는 편이 낫습니다.

3. 본격적인 작업 전에 /init 실행하기

OpenCode는 repo용 AGENTS.md 파일을 만들어 줍니다.

/init

이 파일은 에이전트에게 지속적인 project instruction을 줍니다. Git에 커밋해 두면 프롬프트 반복을 줄이고 세션 간 동작도 더 안정적입니다.

4. build보다 plan부터 시작하기

OpenCode에는 Tab으로 전환 가능한 built-in agent가 두 개 있습니다.

• build는 실제 개발 작업용
• plan은 분석과 코드 탐색용

첫 번째 작업은 plan으로 좁게 시작하는 편이 좋습니다.

이 저장소의 build, test, release 흐름을 요약해 주세요.
핵심 진입점도 알려 주세요.
아직 수정은 하지 마세요.

repo 구성이 맞아 보일 때만 build로 넘어가면 됩니다.

실전 팁 7가지

팁 1: 익숙하지 않은 코드베이스에서는 plan을 기본값으로 쓰기

문서가 plan과 build를 분리해 둔 이유는 안전 때문만이 아닙니다. 결과 품질에도 직접 영향을 줍니다.

처음부터 build로 들어가면 모델이 이해를 충분히 검증하기 전에 파일을 바꿔 버릴 수 있습니다. 반대로 plan부터 시작하면 architecture, naming, test flow, 예상 영향 범위를 먼저 확인할 수 있습니다.

예시는 이런 식이 좋습니다.

@src/auth/index.ts에서 인증 흐름을 설명해 주세요.
그다음 최소 수정안 2개를 제안해 주세요.
아직 편집은 하지 마세요.

@ 파일 참조는 OpenCode가 prompt 안에서 fuzzy file search를 지원하기 때문에 특히 유용합니다.

팁 2: /init과 AGENTS.md를 설정 잡무가 아니라 지렛대로 보기

많은 개발자가 이 단계를 문서 작업처럼 가볍게 봅니다.

하지만 핵심은 반대입니다. AGENTS.md에는 아래를 넣어 두는 게 좋습니다.

• build, test, lint 명령
• repo 구조와 package 경계
• 스타일 규칙과 review 기대값
• 건드리지 말아야 할 영역
• done 정의

이걸 빼고 매번 chat에서 규칙을 반복하면, 결과는 더 시끄러워지고 더 비싸집니다.

이 주제는 Claude Agent SDK로 Claude Code 스타일 에이전트 만들기와 같이 보면 좋습니다. agent를 만드는 관점에서도 같은 원칙이 적용됩니다.

팁 3: 기본 권한을 그대로 믿기 전에 먼저 조이기

OpenCode는 설정 가능하고, 공식 permissions 문서도 allow, ask, deny 같은 동작을 명시합니다.

새 저장소라면 시작 정책을 이렇게 두는 편이 실용적입니다.

{
  "$schema": "https://opencode.ai/config.json",
  "permission": {
    "edit": "ask",
    "bash": "ask"
  }
}

조금 느려지더라도 초반에는 예상 못 한 행동을 줄이는 편이 낫습니다. 익숙해진 뒤에 저위험 명령과 반복 편집부터 선택적으로 풀면 됩니다.

팁 4: 도구를 더 깔기 전에 custom command 몇 개부터 만들기

OpenCode는 /init, /undo, /redo, /share, /help 같은 built-in command를 제공합니다. 여기에 .opencode/commands/ 안의 설정이나 markdown 파일로 custom command를 더할 수도 있습니다.

즉, 많은 "고급 워크플로"는 아직 새 프레임워크가 없어도 됩니다. 예를 들면 다음 command를 만들 수 있습니다.

• /test
• /review
• /ship-check
• /seo-page

예시:

---
description: 현재 변경과 관련된 테스트를 실행합니다
agent: build
---
 
이번 세션에서 수정한 파일과 관련된 테스트만 실행해 주세요.
실패한 항목을 먼저 요약하고, 그다음 최소한의 수정안을 제안해 주세요.

이 방식은 자주 쓰는 프롬프트를 짧고 검토 가능하게 유지합니다.

팁 5: provider를 여러 개 엮기 전에 하나를 제대로 쓰기

OpenCode의 provider-agnostic 설계는 강점이지만, 동시에 초기 setup을 과하게 늘리게 만들 수도 있습니다.

처음부터 provider 5개, fallback chain 3개, custom model matrix를 다 엮지 마세요. 지금 이미 비용을 내고 있고 익숙한 provider부터 시작한 다음, OpenCode 자체의 동작을 이해한 뒤에 확장하는 편이 낫습니다.

이 카테고리가 처음이라면 Codex 사용법 가이드도 같이 읽어 보세요. 서로 다른 제품 방향이지만, "제약을 둔 작업이 tool sprawl보다 낫다"는 교훈은 같습니다.

팁 6: 터미널, 데스크톱, IDE가 각각 어디서 이기는지 구분하기

이제 OpenCode는 단일 terminal binary보다 큽니다.

터미널은 prompt-edit-test loop를 가장 빠르게 돌릴 때 좋습니다.

데스크톱 앱은 review visibility, session management, UI 편의성이 더 중요할 때 좋습니다.

IDE extension은 이미 쓰고 있는 editor가 control surface일 때 가장 자연스럽습니다.

문제는 하나를 영원히 잘못 고르는 게 아닙니다. 지금 작업에 맞지 않는 인터페이스를 쓰고도 그걸 agent 탓으로 돌리는 쪽이 더 문제입니다.

팁 7: 변경 정리는 OpenCode에 맡기되, diff는 사람이 봐야 한다

공식 문서에 따르면 OpenCode는 파일 수정 뒤 language-specific formatter를 자동으로 쓸 수 있습니다. 분명 유용하지만, formatter 지원이 곧 변경 품질은 아닙니다.

다음은 여전히 직접 확인해야 합니다.

• 구현이 요구사항과 실제로 맞는지
• 실행하려는 bash command가 적절한지
• AGENTS.md 지침을 따르고 있는지
• 이번 task에 비해 patch가 너무 넓지 않은지

AI coding agent는 타이핑을 줄여 줍니다. 엔지니어링 판단까지 대신해 주지는 않습니다.

Oh My OpenCode는 언제 붙여야 하나

Oh My OpenCode는 OpenCode 그 자체가 아닙니다. OpenCode를 바탕으로 한 더 강한 orchestration layer에 가깝습니다.

현재 프로젝트 문서와 README는 이를 다음처럼 설명합니다.

• specialist agent를 중심으로 한 더 강한 orchestration
• category 기반 model routing
• background agent와 parallel work
• MCP 중심 워크플로
• task가 끝날 때까지 계속 밀고 가는 실행 방식
• ultrawork / ulw 같은 명령

즉, 평범한 OpenCode만으로는 조금 가볍게 느껴질 때 이 조합이 빛납니다.

Oh My OpenCode의 장점은 OpenCode가 약해서가 아닙니다. delegation, orchestration, model specialization을 더 적극적으로 가져가고, 작업 시작 후에는 덜 손대고 싶어 하는 사용자에게 더 잘 맞는 harness라는 점입니다.

OpenCode와 Oh My OpenCode를 함께 쓰는 방법

1. 먼저 OpenCode 단독으로 안정화하기

테스트도 안 해 본 base tool 위에 harness를 바로 얹지 마세요.

추가하기 전에 최소한 다음은 되어야 합니다.

• OpenCode 설치
• provider 인증
• /init 실행
• plan 작업 1회 완료
• build 작업 1회 완료

이 baseline이 불안정하면 Oh My OpenCode를 붙여도 디버깅만 더 어려워집니다.

2. 설치 전에 이름을 정확히 이해하기

헷갈리기 쉬운 부분이 하나 있습니다.

• GitHub repo는 현재 code-yeongyu/oh-my-openagent
• branding과 package name은 여전히 Oh My OpenCode
• 설치 명령은 oh-my-opencode

2026년 3월 17일 기준으로는 같은 계보의 프로젝트로 보면 됩니다.

3. 공식 installer로 harness 설치하기

가장 간단한 수동 경로는 다음입니다.

bunx oh-my-opencode install

프로젝트 문서도 AI agent가 설치 가이드를 읽고 따라가도록 쓰는 방식을 권장합니다. 이 프로젝트의 workflow 철학과도 잘 맞습니다.

4. 모든 기능보다 먼저 하나의 고가치 명령부터 쓰기

대표적인 사용 패턴은 다음입니다.

ultrawork

짧은 alias는 이렇습니다.

ulw

이것도 유용하지만 magic처럼 대하면 안 됩니다. 먼저 중간 규모 task에서 써 보세요. 잘 맞는 예시는 다음과 같습니다.

• 특정 버그 수정과 관련 테스트
• 한 범위의 기능 구현
• noisy한 파일 묶음 정리
• 잘 아는 repo에서 병렬 탐색 + 구현

처음부터 잘 맞지 않는 경우도 분명합니다.

• 모호한 greenfield architecture
• rollback plan 없는 production migration
• 권한 정책 검토가 안 된 민감한 repo

5. 멀티모델 orchestration의 이점을 실제로 체감할 때 가장 좋다

Oh My OpenCode는 다음이 필요할수록 설득력이 커집니다.

• 계획, 추론, frontend 작업에 서로 다른 모델을 쓰고 싶음
• background specialist가 유용함
• MCP 사용 범위가 넓음
• subagent discipline이 더 강했으면 좋겠음

반대로 매일 하는 일이 "한 파일 고치고 테스트 돌리고 끝" 수준이면, OpenCode 단독으로 충분한 경우가 많습니다.

OpenCode 단독 vs OpenCode + Oh My OpenCode

실무적으로는 아래 순서가 가장 무난합니다.

1. OpenCode를 먼저 익힌다.
2. 제대로 된 AGENTS.md를 작성해 커밋한다.
3. custom command를 2~3개 추가한다.
4. 권한을 조인다.
5. 그다음에야 Oh My OpenCode가 필요한지 판단한다.

자주 하는 실수

OpenCode와 OpenClaw를 혼동하기

둘은 다른 프로젝트입니다.

만약 OpenClaw를 검색했지만 plan, build, /init, Oh My OpenCode 호환성이 있는 오픈소스 터미널 coding agent를 찾는 거라면, 거의 확실히 OpenCode를 의미합니다.

오래된 repo 링크를 그대로 믿기

OpenCode 관련 자료는 예전 repo 기준으로 설명된 경우가 많습니다. 무작정 따라가기 전에 설치 경로와 공식 문서를 다시 확인하는 편이 안전합니다.

baseline을 익히기 전에 harness부터 얹기

OpenCode의 기본 동작을 모르면, 이상한 결과가 base agent 때문인지, harness 때문인지, provider 때문인지, repo rule 때문인지 구분할 수 없습니다.

첫날부터 구독을 너무 많이 사기

provider 유연성은 좋지만, 대부분의 사용자는 이미 갖고 있는 모델 접근부터 시작하는 편이 더 낫습니다.

FAQ

OpenCode는 OpenClaw와 같은 건가요?

아닙니다. 둘은 다른 프로젝트입니다. 이 글은 opencode.ai에서 문서화된 오픈소스 AI coding agent인 OpenCode에 관한 내용입니다.

OpenCode를 잘 쓰려면 Oh My OpenCode가 꼭 필요한가요?

아닙니다. OpenCode는 단독으로도 충분히 유용합니다. Oh My OpenCode는 더 강한 orchestration, 더 opinionated한 delegation, 더 넓은 multi-model workflow가 필요할 때 유리합니다.

설치한 뒤 가장 먼저 뭘 해야 하나요?

/connect를 실행하고, 실제 프로젝트를 열고, /init을 실행한 뒤, plan으로 전환해서 변경을 요청하기 전에 repo 요약부터 받아 보세요.

터미널, 데스크톱, IDE 중 무엇부터 시작해야 하나요?

review-heavy한 데스크톱 워크플로나 editor-native 흐름을 이미 선호하는 게 아니라면, 터미널부터 시작하는 편이 가장 무난합니다.

Oh My OpenCode를 쓸 준비가 됐는지 가장 쉽게 판단하는 기준은 무엇인가요?

OpenCode 단독 사용이 이미 편하고, AGENTS.md가 제대로 갖춰져 있고, 하나의 agent가 여러 specialist pass를 오케스트레이션해 주길 자주 원한다면 준비된 상태입니다.

Related Guides

• AI Coding 토픽 페이지
• Codex 사용법 가이드
• 병렬 코드 에이전트 가이드
• Claude Agent SDK로 Claude Code 스타일 에이전트 만들기
• OpenClaw vs ZeroClaw vs Pi Agent vs Nanobot