opencode 후기, Claude Code 갈아탈만한 이유 WSL 설치부터 MCP까지 정리

opencode가 처음 나왔을 때는 그냥 또 흔한 Claude Code 계열 CLI 클론이려니 하고 넘겼습니다. 그런데 요즘 정말 많은 CLI도구들 출시와함께 "Claude Code 정리하고 갈아탔다"는 글이 부쩍 보이길래 의심 반 호기심 반으로 WSL에 직접 깔아서 며칠 굴려봤습니다.

 

결론부터 말씀드리면 저는 지금 메인을 opencode로 바꿨습니다. Claude Code도 깔끔하고 좋긴 한데, 막상 며칠 같이 써보니 모델이 Anthropic 하나로 묶여 있는 점, 매달 빠져나가는 구독료, 그리고 MCP나 Skills 같은 확장을 마음대로 끼워넣기 애매한 점이 점점 거슬리더군요. opencode는 이 세 가지가 한꺼번에 풀립니다. 설치부터 인증, 줄바꿈 문제, 그리고 MCP·Skills·Plugin까지 어떻게 붙이는지 순서대로 정리해보겠습니다.

 

opencode가 뭐길래 다시 떠오르나

opencode는 SST 팀이 만든 오픈소스 터미널 AI 코딩 에이전트입니다. 굳이 한 줄로 말하면 터미널 안에서 돌아가는, 모델을 마음대로 갈아끼울 수 있는 코딩 에이전트입니다.

 

작년에 처음 공개됐을 때만 해도 Claude Code 카피 취급을 받았는데, 최근에 다시 회자되는 이유는 단순합니다. Claude Code는 Anthropic 모델만 쓸 수 있고 Cursor는 월 20달러 고정 구독이 부담스러운데, opencode는 본체가 오픈소스라 그 자체로는 공짜입니다. API 키만 본인이 가져오면 됩니다. 이걸 BYOK(Bring Your Own Key)라고 하는데, 사용량만큼만 내면 되니까 가볍게 쓰는 사람한테는 구독료가 통째로 빠지는 셈입니다.

 

거기에 MCP(Model Context Protocol) 서버를 자유롭게 붙일 수 있고, Skills로 자주 쓰는 작업 패턴을 정리해두거나 Plugin으로 도구를 직접 만들어 끼울 수도 있습니다. 한마디로 본인 작업 환경에 맞춰 조립하기 좋은 도구입니다.

 

무료로 쓸 수 있는지부터 정리

가장 많이 받는 질문이라 먼저 짚고 가겠습니다. opencode 본체는 완전 무료, 오픈소스입니다. 다만 AI 모델 호출 비용은 본인이 어떤 키를 꽂느냐에 따라 달라집니다.

 

OpenAI나 Anthropic 키를 직접 발급받아서 쓰면 사용량만큼 과금되고, OpenRouter를 거치면 일부 모델은 무료로 돌릴 수 있습니다. 로컬에 Ollama 같은 걸 띄워놨다면 그쪽으로 붙여서 0원으로 쓰는 것도 가능합니다.

 

Opencode 제공 무료모델 (상시 업데이트)

게다가 opencode는 자체 무료 모델도 기본 제공해서 인증 없이도 일단 띄워보고 분위기를 잡을 수 있습니다. 처음 써보시는 거면 이걸로 한번 돌려보고, 본격적으로 쓸 모델은 작업 패턴이 잡힌 다음에 결정하시는 게 부담이 적습니다.

 

Cursor처럼 매달 빠져나가는 고정 비용이 없다는 점, 이게 사용자들이 가장 매력적으로 느끼는 지점입니다.

 

WSL에 opencode 설치하는 방법

저는 WSL2 Ubuntu 24.04 환경에서 진행했습니다. 설치 방법은 두 가지인데 결론부터 말씀드리면 curl 한 줄짜리가 제일 깔끔합니다.

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

공식에서 권장하는 방식이고 Node 의존성 없이 단독으로 설치됩니다. 설치 끝나면 버전 정보랑 진행률 100% 뜨고 그 아래에 큰 opencode 로고가 박힙니다. PATH도 자동으로 `/home/사용자/.bashrc`에 잡아주는 게 보일 겁니다.

 

 

두 번째는 npm 글로벌 설치인데, 이미 Node 환경이 잘 잡혀있는 분들한테는 익숙하실 겁니다.

npm install -g opencode-ai

 

설치는 됐는데 opencode 명령어가 안 먹힐 때

여기서 막히는 분들이 많을 것 같아서 따로 적습니다. 저도 처음에 그랬습니다. 설치는 분명히 끝났다고 떴는데 막상 `opencode`라고 치니까 `command not found`가 뜨더군요.

PATH가 안 잡혀 있어서 그렇습니다. WSL은 설치 직후에 셸이 바뀐 PATH를 인식 못 하는 경우가 종종 있는데, 가장 확실한 건 그냥 터미널 창을 닫았다가 다시 여는 겁니다. `exec bash`로 셸을 재시작해도 되고요. 즉시 적용하고 싶으면 아래 명령어 한 줄로 해결됩니다.

source ~/.bashrc

 

위 사진처럼 source 명령 한 번 먹이고 다시 `opencode`를 치면 그때부터는 멀쩡하게 인식됩니다. 그래도 안 되면 PATH에 opencode 경로를 직접 박아주면 됩니다.

 

echo 'export PATH="$HOME/.opencode/bin:$PATH"' >> ~/.bashrc
source ~/.bashrc

 

 

처음 실행하면 보이는 화면

PATH가 잡혔으면 그냥 `opencode`라고 치면 TUI가 뜹니다. 처음에는 큼지막한 opencode 로고와 함께 입력창이 뜨고, 화면 우측 하단에 버전(저는 1.14.42)이 보이고, 가운데에 "Tip Run /connect to add an AI provider and start coding"이라는 안내가 뜹니다.

 

여기서 바로 질문을 던져도 기본 무료 모델로 답이 옵니다만, 본격적으로 쓸 거면 `/connect`로 본인이 쓸 provider를 붙이는 게 좋습니다.

 

/connect 명령어를 치면 Anthropic, OpenAI, OpenRouter, Google 같은 provider 목록이 뜨고, 본인이 쓸 곳 골라서 API 키만 넣으면 끝입니다. WSL은 GUI 브라우저가 기본으로 안 떠서 OAuth 로그인 흐름이 막히는 경우가 있는데, 이때는 OAuth 대신 API Key 옵션을 골라서 키를 직접 붙여넣는 방식으로 우회하시면 됩니다.

 

화면 좌측 상단에 보이는 `Build`는 현재 모드(작업 모드 vs Plan 모드 등)를 표시하고, `Big Pickle`이나 `OpenCode Zen` 같은 건 현재 선택된 모델 라벨입니다. `tab` 키로 에이전트를 전환할 수 있고, `ctrl+p`로 명령 팔레트를 띄울 수 있다는 안내도 같이 보입니다.

 

줄바꿈이 안 먹는다면 (Shift+Enter 문제)

여기서 한 번 더 막힙니다. 긴 프롬프트 입력하다가 Shift+Enter로 줄바꿈하려는데 그냥 전송돼버리는 경우, Windows Terminal을 쓰시는 분들에게 흔하게 일어납니다. Windows Terminal이 기본적으로 Shift+Enter 키 조합을 escape sequence로 변환해 보내지 않아서 opencode가 인식을 못 합니다.

 

가장 빠른 우회는 `Ctrl+J`입니다. 이건 ASCII Line Feed 문자라서 거의 모든 터미널이 그대로 전달해줍니다. opencode 기본 키바인딩에도 포함되어 있어서 별도 설정 없이 바로 됩니다.

 

설정으로 깔끔하게 해결하고 싶으면 Windows Terminal `settings.json`을 열어서 actions와 keybindings에 다음을 추가하시면 됩니다.

{
  "actions": [
    {
      "command": {
        "action": "sendInput",
        "input": "\u001b[13;2u"
      },
      "id": "User.sendInput.ShiftEnterCustom"
    }
  ],
  "keybindings": [
    {
      "keys": "shift+enter",
      "id": "User.sendInput.ShiftEnterCustom"
    }
  ]
}

저장하고 Windows Terminal을 완전히 닫았다가 다시 열면 그때부턴 Shift+Enter가 줄바꿈으로 잘 들어갑니다. WezTerm이나 Alacritty 같은 다른 터미널은 기본적으로 Shift+Enter가 잘 동작해서 이 설정 안 해도 됩니다.

 

npm 권한 에러(EACCES) 만났을 때

npm 방식으로 설치하다가 EACCES 권한 에러가 뜨는 분들도 있을 텐데, 여기서 sudo로 우회하는 건 비추입니다. 나중에 다른 글로벌 패키지 깔 때마다 권한 꼬여서 더 골치 아파집니다. 정석은 npm prefix를 홈 디렉토리로 옮기는 겁니다.

 

mkdir ~/.npm-global
npm config set prefix '~/.npm-global'
echo 'export PATH=~/.npm-global/bin:$PATH' >> ~/.bashrc
source ~/.bashrc

이 설정 한 번 해두면 앞으로 글로벌 패키지 설치할 때 권한 문제로 안 막힙니다.

 

opencode가 진짜 빛나는 부분, MCP 연동

여기부터가 제가 opencode로 갈아탄 진짜 이유입니다. opencode는 MCP(Model Context Protocol) 서버를 설정 파일에 적기만 하면 도구처럼 갖다 쓸 수 있습니다. GitHub, Sentry, 데이터베이스, 브라우저 자동화 같은 외부 도구를 에이전트가 직접 호출하게 만들 수 있다는 뜻입니다. 

설정 파일은 `~/.config/opencode/opencode.json`(전역) 또는 프로젝트 루트의 `opencode.json`(프로젝트별)에 둡니다. 형태는 이런 식입니다.

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "github": {
      "type": "local",
      "command": ["npx", "-y", "@modelcontextprotocol/server-github"],
      "environment": {
        "GITHUB_PERSONAL_ACCESS_TOKEN": "ghp_xxxxx"
      },
      "enabled": true
    },
    "playwright": {
      "type": "local",
      "command": ["npx", "-y", "@playwright/mcp"],
      "enabled": true
    }
  }
}

`type`을 `local`로 하면 로컬 프로세스로 MCP 서버를 띄우고, `remote`나 `http`로 하면 이미 떠 있는 MCP 서버에 붙습니다. 최근 버전부터는 HTTP Streaming, SSE 둘 다 지원해서 원격 서버 붙이기도 한결 편해졌습니다. 프로젝트별로 특정 MCP만 켜고 끄는 override도 가능해서, 회사 프로젝트에선 GitHub MCP 켜고 사이드 프로젝트에선 끄는 식으로 분리도 됩니다.

 

Claude Code도 MCP를 지원하긴 하지만, opencode는 설정 파일 한 군데서 전부 관리되고 프로젝트별 override가 자유로워서 MCP를 적극적으로 쓸수록 opencode 쪽이 훨씬 편해집니다.

 

Skills로 작업 패턴 저장하기

Skills는 자주 쓰는 작업 흐름이나 지시사항을 마크다운 파일로 저장해두고 에이전트가 필요할 때 꺼내 쓰게 하는 기능입니다. YAML 프론트매터 + 마크다운 본문 형태로, 토큰을 매번 컨텍스트에 다 박아넣지 않고 필요한 순간에만 로드하는 lazy loading 구조입니다.

 

저장 위치는 두 군데입니다.

~/.config/opencode/skills/   # 전역, 모든 프로젝트에서 공유
.opencode/skills/            # 프로젝트별

 

스킬 파일 예시는 이런 식입니다.

---
name: pr-review
description: PR 변경사항 리뷰하고 개선점 정리
---

다음 절차로 진행합니다.

1. `git diff main...HEAD`로 변경 파일 목록 확인
2. 각 파일에서 로직 변경 부분 위주로 검토
3. 잠재적 버그, 성능 이슈, 컨벤션 위반을 분리해서 정리
4. 마지막에 변경 요약과 머지 가능 여부 한 줄 의견 작성

 

이렇게 만들어두면 에이전트가 알아서 상황에 맞는 스킬을 발견해서 가져옵니다. 에이전트별로 어떤 스킬을 쓸 수 있는지 frontmatter에서 권한도 통제할 수 있어서, 특정 작업에만 특정 스킬을 노출시키는 식으로 정리할 수 있습니다.

 

저는 자주 쓰는 패턴(커밋 메시지 작성 규칙, 한국어 README 정리 양식, 디버깅 절차 같은 것들)을 스킬로 빼두고 나서 같은 지시를 매번 복붙할 일이 없어졌습니다. 이거 하나만으로도 Claude Code에서 못 누리던 편의를 챙길 수 있습니다.

 

Plugin과 Agent로 더 깊게 확장

Plugin은 도구나 훅, 커스텀 명령을 묶어서 배포할 수 있는 단위입니다. npm으로 설치하거나 직접 만들어서 `opencode.json`의 `plugin` 배열에 등록하면 끝입니다.

{
  "plugin": ["oh-my-openagent", "opencode-skills"]
}

대표적인 게 oh-my-openagent(예전 이름 oh-my-opencode)인데, 이건 양이 많아서 따로 2편으로 정리할 예정입니다. 핵심만 말씀드리면 단일 에이전트가 아니라 역할별 전문 에이전트(계획 담당, 구현 담당, 문서 담당 등)가 협업하는 구조로 바꿔주는 확장입니다.

 

며칠 써본 솔직한 후기

일주일 정도 메인으로 써봤습니다. 가장 인상적이었던 건 역시 모델을 자유롭게 갈아끼울 수 있다는 점입니다. 설정 몇 줄만 바꾸면 Claude Sonnet으로 코드 짜다가 GPT-5로 리뷰시키고, 간단한 텍스트 정리는 로컬 모델로 돌리는 식의 워크플로우가 자연스럽게 됩니다. Claude Code 쓸 때는 상상하기 어려웠던 자유도입니다.

 

그리고 실제로 20일날 claudecode opus의 서버 문제로 사용이 불가능한 순간이 있었는데 이럴때 간편하게 모델을 변환해서 다른 모델을 사용할 수 있었어서 작업에도 무리가 없었습니다.

 

SSH로 원격 서버에 들어가서 그대로 쓸 수 있다는 점도 의외로 컸습니다. 노트북을 바꿔도 셋업이 가볍고, 어디서 접속하든 같은 환경이 유지됩니다. 작은 프로젝트에서는 Cursor보다 인덱싱이 가벼워서 오히려 응답이 빠르게 느껴질 때도 있었습니다.

 

MCP, Skills, Plugin이 한 곳에 정리되어 있다는 게 제일 마음에 들었습니다. Claude Code에서 비슷한 걸 하려면 이것저것 우회해야 하는데, opencode는 설정 파일 하나만 보면 됩니다. 본인 작업 패턴이 명확한 분일수록 opencode 쪽이 결국 더 편해집니다.

아쉬운 점이 없는 건 아닙니다. 처음에는 키바인딩이 살짝 헷갈리고(특히 Shift+Enter), 설정할 게 Claude Code보다 많은 건 사실입니다. Claude Code가 셋업을 거의 안 해도 바로 잘 돌아가는 도구라면, opencode는 본인이 환경을 만들어가는 도구에 가깝습니다. 설정 자체가 부담스러운 분이라면 Claude Code 쪽이 편할 수 있습니다.