OpenCode 마스터하기: 로컬 우선 AI 코딩을 위한 완벽 가이드

OpenCode는 단순한 AI 코딩 도우미 그 이상입니다. 진정한 페어 프로그래머 역할을 하도록 설계된 로컬 우선 자율 코딩 에이전트입니다. 단순한 자동 완성 도구와 달리 OpenCode는 전체 저장소를 이해하고, 복잡한 리팩토링을 계획하고, 터미널 명령을 실행합니다. 이 모든 과정에서 님의 코드는 머신에 안전하게 유지됩니다.

이 완벽 가이드에서는 제로에서 시작하여 OpenCode의 가장 진보된 기능을 마스터하는 데 필요한 모든 것을 다룹니다.

1. 설치: 자율 코딩으로 가는 관문

시작하는 것은 매우 매끄럽게 설계되었습니다. OpenCode는 터미널에서 기본적으로 실행되므로 VS Code, JetBrains 또는 독립형 셸 등 작업하는 모든 곳에서 작동합니다.

빠른 설치 (Mac, Linux, Windows WSL)

가장 빠른 설치 방법은 공식 스크립트를 사용하는 것입니다:

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

대안: npm 패키지

Node.js를 통해 도구를 관리하는 것을 선호하는 경우 OpenCode를 전역으로 설치할 수 있습니다:

npm install -g opencode-ai

설치가 완료되면 opencode를 입력하여 설치를 확인하고 UI를 시작하세요.

2. 모델 및 제공업체: 무한한 선택 (BYOK)

OpenCode의 핵심 철학 중 하나는 모델 중립성입니다. 단일 "블랙 박스" 모델에 님을 가두지 않습니다. 대신, 님만의 키(BYOK)를 가져오거나 기존 AI 구독을 연결할 수 있습니다.

인증하기

선호하는 모델 제공업체를 연결하려면 다음을 실행하세요:

opencode auth login

이 대화형 명령은 다음을 통한 로그인을 안내합니다:

• Anthropic (Claude 4.5 Sonnet, Opus)
• OpenAI (GPT-5, o1-preview)
• Google (Gemini 3 Pro, 1.5 Pro)
• Models.dev (75개 이상의 오픈 소스 및 호스팅 모델 액세스)

모델 관리

작업에 따라 즉시 모델을 전환할 수 있습니다. 간단한 수정에는 더 빠른 모델을 사용하고, 아키텍처 계획에는 추론 능력이 뛰어난 모델을 사용하세요.

# 사용 가능한 모든 모델 나열
opencode models

# 새 제공업체 추가 후 모델 목록 새로 고침
opencode models --refresh

Ollama로 로컬 환경 구축

궁극의 개인 정보 보호 및 오프라인 기능을 위해 OpenCode는 Ollama를 통한 로컬 모델을 지원합니다. OpenCode를 로컬 인스턴스로 지정하면 데이터가 네트워크를 떠나지 않고 코딩할 수 있습니다. 이는 엔터프라이즈 환경이나 민감한 IP 작업에 완벽합니다.

3. 핵심 워크플로우: 대화형 vs. 일회성

OpenCode는 님이 일하는 방식에 적응합니다.

대화형 세션

OpenCode를 사용하는 가장 강력한 방법은 대화형 세션입니다. 프로젝트 루트에서 opencode를 실행하여 지속적인 채팅 환경으로 들어갑니다.

• 컨텍스트 인식: 에이전트는 파일 구조와 LSP 신호를 읽습니다.
• 멀티 턴: 계획을 구체화하고, 수정을 요청하고, 반복할 수 있습니다.
• 도구 사용: 에이전트는 자율적으로 파일을 읽고, 코드를 편집하고, 테스트를 실행할 수 있습니다.

일회성 명령

전체 대화가 필요하지 않은 빠른 작업의 경우 opencode run을 사용하세요. 이는 "지시하고 잊어버리는(fire and forget)" 방식에 완벽합니다.

# 코드베이스를 요약하고 개선 사항 제안
opencode run "Analyze this codebase and propose a refactoring plan for performance"

# 빠른 수정
opencode run "Fix the type error in src/utils/helper.ts"

4. 에이전트 및 권한: 안전 제일

AI에게 터미널과 파일 시스템에 대한 액세스 권한을 부여하려면 신뢰가 필요합니다. OpenCode는 강력한 권한 시스템과 전문화된 에이전트로 이 문제를 해결합니다.

세분화된 권한

에이전트가 수행할 수 있는 작업을 정확하게 제어합니다. 권한을 전역적으로 또는 세션별로 설정하세요:

• 허용 (Allow): 에이전트가 자동으로 명령을 실행하고 파일을 편집합니다.
• 질문 (Ask): 에이전트는 모든 작업에 대해 님의 승인을 요청해야 합니다(민감한 작업의 기본값).
• 거부 (Deny): 에이전트가 해당 작업을 수행하는 것이 엄격히 금지됩니다.

전문 에이전트: 계획 vs. 빌드

위험을 최소화하기 위해 분할 워크플로우를 권장합니다.

1. 계획 에이전트 (Plan Agent): "설계자" 모델을 사용하여 코드를 분석하고 전략을 초안합니다. 이 에이전트를 읽기 전용 또는 질문 모드로 유지하세요.
2. 빌드 에이전트 (Build Agent): 계획이 승인되면 변경 사항을 신속하게 실행하기 위해 허용 권한이 있는 "빌더" 에이전트로 전환하세요.

5. 고급 기능: 멀티 세션 및 공유

실제 엔지니어링은 선형적이지 않습니다. OpenCode는 멀티태스킹 요구 사항에 맞는 고급 워크플로우를 지원합니다.

병렬 세션

오래 걸리는 리팩토링이 빠른 버그 수정 작업을 방해하지 않도록 하세요. OpenCode를 사용하면 여러 병렬 세션을 실행할 수 있습니다.

• 세션 A: "인증 미들웨어 리팩토링."
• 세션 B: "홈페이지의 CSS z-index 버그 수정."

이 세션들은 독립적으로 작동하므로 작업 간에 컨텍스트가 섞이지 않습니다.

공유 가능한 링크

팀원에게 AI가 수행한 작업을 보여줘야 하나요? /share를 사용하여 세션의 엄격한 읽기 전용 로그를 생성하세요.

• 협업: PR 검토자에게 링크를 보내 변경 사항이 왜 이루어졌는지 확인할 수 있게 하세요.
• 문서화: 성공적인 세션을 미래 작업을 위한 "레시피"로 저장하세요.
• 개인 정보 제어: 공유는 기본적으로 비활성화되어 있습니다. 게시할 내용을 명시적으로 제어합니다.

결론

OpenCode는 제어권이나 개인 정보를 희생하지 않고 AI의 힘을 원하는 개발자를 위해 구축되었습니다. 올바른 모델 선택, 세분화된 권한 활용, 병렬 세션 사용 등 이러한 워크플로우를 마스터함으로써 OpenCode를 단순한 도우미에서 지칠 줄 모르는 자율적인 파트너로 변모시킬 수 있습니다.

시작할 준비가 되셨나요? 지금 OpenCode를 설치하고 로컬 우선 엔지니어링의 미래를 경험하세요.