모든 것이 빠르게 진화하는 AI 개발 도구의 세계가 존재합니다. 그동안 저는 Cursor와 Windsurf 같은 에이전트형 IDE, Blackbox와 같은 코드 어시스턴트, 그리고 Claude Code 및 Codex와 같은 자율 에이전트까지 모든 것을 테스트해 보았습니다. 이들은 모두 어느 시점에 제 워크플로우(workflow)에 잘 통합되었지만, 항상 동일한 문제에 부딪혔습니다. 바로 비용입니다.

처음에는 제공되는 가치가 비용을 정당화했습니다. 문제는 제가 이러한 도구들에 더 많이 의존하게 되면서 발생했습니다. 개인화되고 잘 설정된 환경을 갖추었음에도 불구하고, 사용 한계에 매우 빠르게 도달하곤 했습니다. 게다가 어떤 경우에는 과금 모델에 큰 변화가 있었습니다. 예를 들어 Windsurf는 일일 및 주간 할당량을 도입하여 업무 중간에 저를 멈추게 만들었고, 더 많은 크레딧을 구매하거나 플랜을 업그레이드하도록 강요했습니다.

그러던 중 OpenCode를 발견하게 되었습니다. 이것은 현재 제 워크플로우에 훨씬 더 큰 의미를 갖게 되었습니다. 지난 몇 주 동안 저는 멀티 에이전트 오케스트레이션(multi-agent orchestration)을 위해 Oh-My-OpenCode-Slim 플러그인을 사용하여 OpenCode를 기본 환경으로 채택했습니다.

이 글에서는 여러분이 어떻게 이 설정을 구성하고 초기 설치를 진행할 수 있는지 소개하고자 합니다.

왜 OpenCode인가?

OpenCode로 전환할 때 얻을 수 있는 가장 큰 이점 중 하나는 자유입니다. 이 도구는 무료이며 오픈 소스(open-source)이기 때문에, 월간 구독료를 지불하는 대신 API 사용량에 대해서만 비용을 지불하면 됩니다. 이는 폐쇄적인 도구에 갇히지 않고 다양한 모델을 실험할 수 있게 하여 큰 가능성을 열어줍니다.

OpenCode 자체에는 몇 가지 플랜이 있습니다: 저비용에 집중한 Go와 더 완전한 옵션인 Zen입니다. 또한 유연성이 완벽합니다: Claude 및 Kimi(5달러부터), Deepseek(최소 2달러 입금)와 같이 적은 비용으로 크레딧을 지불하며 다양한 AI 제공업체를 연결할 수 있으며, 수백 개의 모델을 보유한 OpenRouter와 같은 서비스도 이용할 수 있습니다.

또 다른 차별점은 커뮤니티입니다. 커뮤니티는 다양한 모델의 사용을 최적화하는 솔루션을 만들어내며, 이번 튜토리얼에서 멀티 에이전트 (multi-agents) 오케스트레이션을 위해 설정할 Oh-My-OpenCode-Slim 플러그인이 그 대표적인 사례입니다. 만약 Claude Code와 같은 도구를 사용해 본 경험이 있다면, OpenCode로의 전환은 매우 쉽고 직관적일 것입니다.

설치 가이드

OpenCode는 Linux, macOS, Windows에서 세 가지 형태인 그래픽 인터페이스 (GUI/Desktop), 터미널 (TUI), 그리고 **IDE 확장 프로그램 (Extension)**으로 사용할 수 있습니다. 다운로드 옵션은 공식 페이지에서 확인할 수 있습니다.

데스크톱 버전을 사용하더라도, 커뮤니티 플러그인을 사용하고자 한다면 터미널 버전을 함께 설치하는 것이 좋습니다. 일부 플러그인은 터미널 버전에서만 가능한 설정이 필요하기 때문입니다.

또한 Windows에서 최상의 경험을 위한 권장 사항은 공식 문서에 명시된 대로 최고의 성능을 보장하기 위해 WSL 환경 내에서 OpenCode를 실행하는 것입니다.

1. 터미널 버전 (TUI)

터미널 설치는 Bash 스크립트 또는 Node.js 패키지 관리자를 통해 직접 수행할 수 있습니다.

Bash 스크립트를 통한 설치:

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

Node.js를 통한 설치 (사용 중인 관리자를 선택하세요):

# npm
npm install -g opencode-ai

...

2. 데스크톱 버전

그래픽 인터페이스가 포함된 버전은 공식 사이트에서 직접 다운로드할 수 있으며, Linux(.deb 및 .rpm), macOS, Windows용 네이티브 패키지를 제공합니다.

초기 설정 및 구성

저는 터미널 사용을 중심으로 설명하겠습니다. 초기 설정 과정은 제공업체(providers)를 연결하고 프로젝트를 초기화하는 단 두 단계로 이루어집니다.

API 키 연결

AI 제공업체를 추가하려면 내부 명령어를 실행하세요:

/connect

터미널에 지원되는 제공업체 목록이 대화형으로 표시됩니다. 옵션을 선택하면 API 키, 기본 모델 (default model) 및 그 변형(variants)을 설정할 수 있습니다.

설정한 자격 증명(credentials)과 함께 삽입한 모든 provider를 OpenCode의 auth.json 파일에서 확인할 수 있습니다. 이 파일은 /home/<사용자-이름>/.local/share/opencode/auth.json 경로에 위치합니다.

터미널을 통해 직접 설정할 수 있는 많은 provider 목록이 있지만, 기본 목록에 없는 로컬 모델이나 서버를 사용하려는 경우 Custom Provider 옵션을 이용하십시오.

프로젝트 초기화하기 (Initializing a Project)

OpenCode를 프로젝트에서 사용할 때는, 초기 스캔(initial scan)을 요청하여 저장소 구조를 분석하고 기반 컨텍스트(context)를 생성하는 것이 권장됩니다. 이렇게 하면 새로운 세션을 시작할 때마다 모델이 애플리케이션 아키텍처를 이미 알게 됩니다.

OpenCode 자체의 스크립트를 실행하는 네이티브 명령어를 사용하여 harness 구축을 시작하는 것이 좋습니다:

/init

이 명령 뒤에는 에이전트가 가치 있는 정보, 즉 정확한 명령, 테스트 실행 순서, 아키텍처 세부 사항만을 추출하도록 안내하는 프롬프트가 실행됩니다. 스크립트는 모델이 실행 파일과 설정 파일에 집중하고, 일반적인 규칙은 무시하며, 질문을 최소화하도록 지시합니다. 이를 통해 최종 파일이 AI가 실제로 놓칠 수 있는 컨텍스트만을 보관하도록 보장합니다.

결과적으로 이 명령은 프로젝트 루트에 AGENTS.md 파일을 생성합니다. 새로운 기능이 구현될 때마다 AI가 이 파일을 자동으로 업데이트합니다.

권장 사항: 팀 간의 공유된 컨텍스트를 유지하고 향후 실행 시 활용할 수 있도록 AGENTS.md 파일을 Git에 버전 관리하고 커밋하세요.

에이전트 작동 방식

OpenCode는 기본적으로 두 개의 네이티브 에이전트가 설정되어 있습니다. Tab 키 또는 /agents 명령을 사용하여 에이전트 간 전환할 수 있습니다.

1. Plan 에이전트

분석, 아키텍처 및 계획에 특화되어 있습니다. 이 에이전트는 프로젝트의 파일을 변경하지 않습니다. Plan의 목적은 코드가 한 줄이라도 작성되기 전에 질문을 던지고, 요구 사항을 이해하며, 전략을 구조화하는 것입니다. 복잡한 작업 및 리팩터링 (Refactoring)에 권장되는 에이전트입니다.

2. Build 에이전트

실행 에이전트입니다. 코드를 변경하고, 파일을 생성하며, 필요한 수정을 적용합니다. 직접적인 지시와 함께 사용하거나, Plan 에이전트가 이전에 생성한 계획을 따라 사용할 수 있습니다.

커스텀 에이전트

네이티브 에이전트 외에도 비즈니스 규칙이나 반복적인 작업을 위한 특정 에이전트를 생성할 수 있습니다. 정의는 프로젝트 내의 /.opencode 디렉토리에 저장됩니다.

사용 세션 중에 커스텀 에이전트를 호출하려면 @ 문자에 에이전트 이름을 이어서 사용하세요:

이러한 커스텀 에이전트 외에도, 고급 멀티 에이전트 (multi-agent) 워크플로우 지원을 추가하는 Oh-My-OpenCode-Slim과 같이 커뮤니티에서 개발한 오케스트레이터 (orchestrators)를 설치하여 환경의 기능을 확장할 수 있습니다.

Oh-My-OpenCode-Slim 설정

Oh-My-OpenCode-Slim은 OpenCode에 6개의 전문 에이전트를 추가하는 멀티 에이전트 오케스트레이션 플러그인입니다. 각 에이전트는 개발의 특정 시나리오에서 역할을 수행합니다:

• Orchestrator: 작업을 완료하기 위해 다른 에이전트들을 조정합니다.
• Explorer: 코드베이스 (codebase)를 분석하여 수행해야 할 작업을 매핑합니다.
• Oracle: 복잡한 버그를 찾고 아키텍처 (architecture) 가이드를 제공합니다.
• Librarian: 온라인 문서에서 검색을 수행합니다.
• Designer: 사용자 인터페이스 및 사용자 경험 (UI/UX)을 담당합니다.
• Fixer: 코딩 작업을 병렬로 실행합니다.

에이전트 외에도, 이 플러그인에는 Skills (기술) 가 포함되어 있습니다. 이는 각 에이전트의 컨텍스트 (context)에 추가되는 프롬프트 (prompt) 지침으로, 특정 작업에 대한 행동 시나리오 역할을 합니다.

Github 공식 저장소에서 각 에이전트와 기술(skill)에 대한 더 자세한 정보와 각 에이전트별 권장 모델 목록을 확인할 수 있습니다 (권장 모델 설정 방법은 나중에 설명하겠습니다).

플러그인 설치

Oh-My-OpenCode-Slim을 설치하기 전에 중요한 주의 사항이 있습니다. 데스크톱 (desktop) 버전을 사용하더라도, 반드시 머신에 터미널 (terminal) 버전이 설치되어 있어야 합니다. 플러그인 설치 프로그램은 환경을 검증하기 위해 시스템에서 이 사항을 확인합니다.

설치 명령어는 다음과 같습니다:

bunx oh-my-opencode-slim@latest install

설치를 마친 후, ~/.config/opencode/oh-my-opencode-slim.json 경로에 있는 OpenCode 루트 폴더로 이동하여 플러그인 설정 파일을 찾으세요. 기본적으로 이 파일은 opencode-go 및 openai와 함께 사용하도록 사전 설정되어 있습니다.

가장 이상적인 방법은 각 에이전트를 사용자의 OpenCode에서 이미 API를 통해 설정해 둔 모델에 매핑하는 것입니다. 각 에이전트에 어떤 모델을 선택해야 할지 궁금하다면, 플러그인 저장소에서 유지 관리자가 테스트하고 권장하는 모델 목록을 확인할 수 있습니다.

에이전트의 모델을 변경하려면 해당 블록의 "model" 필드를 수정하기만 하면 됩니다. 아래는 OpenRouter를 통해 모델을 사용하는 설정 예시입니다:

{
  "$schema": "https://unpkg.com/oh-my-opencode-slim@latest/oh-my-opencode-slim.schema.json",
  "preset": "openrouter",
...

결론

OpenCode가 적절히 설정되고 Oh-My-OpenCode-Slim이 에이전트들을 오케스트레이션(Orchestration)함에 따라, 사용자는 효율적이고 통제 가능한 워크플로(Workflow)를 갖게 됩니다.

이 워크플로에서 제가 보는 가장 큰 장점은 자율성과 결합된 비용의 예측 가능성입니다. 개발의 각 단계에 사용할 모델을 직접 선택할 수 있으며, 가장 강력한 모델은 계획이나 아키텍처 설계에 할당하고, 더 가벼운 모델은 빠른 스캔 작업에 할당하여 사용할 수 있습니다.