opencode는 터미널에서 프로젝트 파일을 읽고 수정하며 명령을 실행하는 오픈소스 AI 코딩 에이전트다. Real Python의 가이드는 Python 개발자가 OpenCode를 설치하고 Gemini API 키를 연결한 뒤, 작은 주사위 프로그램을 분석·리팩터링하는 흐름으로 AI 보조 코딩의 기본 동작을 익히게 한다.
1. 설치와 실행
macOS·Linux에서는 공식 설치 스크립트가 가장 간단하다.
curl -fsSL https://opencode.ai/install | bash
opencode --version
opencode대안으로 Homebrew 또는 npm 패키지를 사용할 수 있다.
brew install anomalyco/tap/opencode
npm install -g opencode-aiWindows에서는 WSL 환경을 권장한다. 프로젝트도 Windows 드라이브보다 WSL 파일시스템 안에 두는 편이 성능과 파일 감시 측면에서 안정적이다.
2. AI provider 연결
OpenCode TUI에서 /connect를 입력하고 Google을 선택한 뒤 Google AI Studio API 키를 붙여 넣는다. 가이드는 무료 Gemini tier를 예제로 사용하지만 Anthropic, OpenAI, GitHub Copilot 등도 연결할 수 있다.
모델은 /models로 바꿀 수 있다. 기본 예제는 일상적 Python 작업에 속도와 품질 균형이 좋은 Gemini Flash 계열을 사용한다.
3. TUI 기본 조작
| 조작 | 역할 |
|---|---|
/connect | provider/API 키 추가 |
/models | 모델 선택 |
/init | 현재 프로젝트용 AGENTS.md 생성 |
/new | 새 세션 시작 |
/undo | 마지막 메시지와 파일 변경 되돌리기 |
/compact | 긴 세션 요약 |
@filename | 특정 파일을 컨텍스트로 포함 |
!command | 셸 명령 실행 결과를 대화에 포함 |
Tab | Plan/Build 모드 전환 |
Plan 모드는 변경 전에 접근을 논의하는 데 좋고, Build 모드는 실제 파일 수정을 진행할 때 쓴다.
4. Python 예제 리팩터링 흐름
가이드는 간단한 dice.py 스크립트를 만들고 OpenCode에게 다음 일을 맡긴다.
- 프로젝트 구조와 코드 의도 설명
AGENTS.md로 Python 스타일·테스트 지침 생성- 함수 분리와 타입 힌트 등 리팩터링 계획 작성
- Build 모드에서 코드 수정
- 테스트 또는 실행 명령으로 동작 검증
핵심은 “한 번에 다 고쳐 줘”보다 작은 요청으로 코드베이스 이해, 계획, 수정, 검증을 나누는 것이다. OpenCode는 파일 컨텍스트를 직접 읽을 수 있으므로 긴 코드를 프롬프트에 붙여 넣지 않아도 된다.
사용 대상
- Python 입문자가 AI 코딩 에이전트를 처음 써 보고 싶을 때
- 기존 CLI 중심 워크플로에 AI 보조를 붙이고 싶을 때
- 무료 또는 저비용 provider로 코딩 에이전트 경험을 테스트하고 싶을 때
- claude-code나 codex와 비교할 오픈소스 대안을 찾을 때
관련 문서
- opencode — OpenCode 토픽 개요
- opencode-tutorial-local-ai-coder — Ollama + Qwen3-Coder 로컬 AI 코딩 환경
- coding-agent-tips-harness-comparison-2026 — 주요 코딩 에이전트 하네스 비교
참고 자료
- How to Use OpenCode for AI-Assisted Python Coding — Real Python (2026-05-14)