OpenCode와 oh-my-opencode로 로컬 코딩 에이전트 켜기

노션에 “opencode 사용법”이라고 적어 둔 페이지가 있습니다. 나중에 보면 명령만 잔뜩인데, 막힐 때마다 그 페이지로 돌아갔습니다. 이 글은 그 메모를 블로그용으로 다듬은 버전입니다. API 키·봇 토큰 같은 값은 넣지 않았습니다.

OpenCode는 터미널/웹에서 돌아가는 코딩 에이전트 쪽에 가깝고, oh-my-opencode는 역할을 나눈 에이전트(플랜/빌드 등)를 얹는 플러그인입니다. “설치 → 한 번 실행 → 웹 UI → 플러그인” 순으로 가면 덜 헤맵니다.

Mac / Linux

공식 쪽이 npm이면:

sudo npm i -g opencode-ai
opencode --version
opencode

탭으로 Plan / Build를 바꿉니다. Plan은 설계, Build는 실제 수정에 가깝게 쓰는 식입니다. Ctrl+P로 모델을 고르고, /로 명령 목록을 봅니다.

웹으로 보려면 터미널을 하나 더 열어:

opencode web

127.0.0.1:포트가 안 뜨면, 웹을 먼저 열지 말고 CLI가 정상인지 확인한 뒤 웹을 엽니다. 경로·포트 추적을 못 할 때가 있었습니다.

oh-my-opencode:

# bun이 없으면
curl -fsSL https://bun.sh/install | bash
# 터미널을 완전히 닫았다가 다시 연 뒤
bun -v
npx oh-my-opencode install

구독이 없으면 설치 질문에 대체로 no를 골라도 됩니다. 다시 opencode를 켰을 때 Sisyphus 같은 에이전트 이름이 보이면 플러그인이 올라간 신호로 보면 됩니다. Planner 계열은 쓰기 권한이 없을 수 있으니, 읽기만 하는 단계와 수정 단계를 나눠 쓰는 편이 덜 위험합니다.

프롬프트 끝에 ulw처럼 강하게 돌리라는 관례를 쓰는 경우도 있습니다. 파일 몇 개짜리 예제보다 구조가 커지니, Git 상태를 자주 보는 게 좋습니다.

Windows (메모에 있던 길)

관리자 PowerShell이 아니라 일반 PowerShell에서 Scoop을 깝니다. 관리자로 하면 Scoop이 중단되는 경우가 있습니다.

irm get.scoop.sh | iex
# 정책 오류 시
Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser
scoop bucket add extras
scoop install extras/opencode
opencode --version

인증서 문제로 실행이 안 되면 NODE_TLS_REJECT_UNAUTHORIZED을 끄는 임시수가 메모에 있었는데, 회사망·보안 환경에서는 비추입니다. 가능하면 인증서 경로를 고치는 쪽을 택하세요.

bun + oh-my-opencode도 PowerShell 설치 스크립트 → bunx oh-my-opencode install 순서입니다. 안 되면 창을 닫고 다시 연 뒤 bun --version부터 확인합니다.

깨졌을 때

프로세스 정리 후 바이너리·캐시를 지우고 재설치하는 흐름이 메모에 있습니다. Mac 예:

pkill -f opencode || true
rm -rf ~/.opencode ~/.cache/opencode ~/.config/opencode
sudo npm cache clean --force
sudo npm install -g opencode-ai

Windows는 %USERPROFILE%\.opencode 등 설정 폴더를 지우는 식입니다. 재설치 후에도 웹보다 CLI 먼저.

모델은 어디에 연결하나

OpenCode/에이전트에 OpenRouter·Groq·로컬 Ollama 등을 붙일 수 있습니다. 키는 .env나 앱 설정에만 두고, 노션 전체 공개 페이지에 붙여 두지 마세요. 비용 감각은 OpenRouter 코딩 모델 비용을 참고하면 됩니다.

로컬에서 에이전트를 키우다 보면 “설치는 됐는데 모델이 안 붙는다”, “웹만 안 열린다”가 대부분입니다. 버전 확인 → CLI 대화 한 턴 → 웹 → 플러그인 순서를 지키면, 노션에 적었던 삽질을 한 바퀴 덜 돌 수 있습니다.