OpenCode 플러그인 설치

이 강의를 마치면 할 수 있는 것

OpenCode에서 Plannotator 플러그인 설치
submit_plan tool과 /plannotator-review 명령어 설정
환경 변수 설정 (원격 모드, 포트, 브라우저 등)
플러그인 설치 성공 여부 확인

현재 겪고 있는 어려움

OpenCode에서 AI Agent를 사용할 때, 계획 검토를 위해 터미널에서 일반 텍스트 계획을 읽어야 하므로 정확한 피드백을 주기 어렵습니다. 계획에 주석을 달고 메모를 추가하며, 피드백을 구조화된 형태로 Agent에게 자동으로 전송할 수 있는 시각적 인터페이스가 필요합니다.

언제 이 방법을 사용하나요

Plannotator 사용 전 필수: OpenCode 환경에서 개발하고 있으며, 대화형 계획 검토 경험을 원하는 경우.

🎒 시작하기 전 준비사항

[ ] OpenCode 설치 완료
[ ] 기본적인 opencode.json 설정 이해 (OpenCode 플러그인 시스템)

사전 지식

OpenCode의 기본 사용법을 아직 모르신다면, 먼저 OpenCode 공식 문서를 읽어보시기 바랍니다.

핵심 개념

Plannotator는 OpenCode에 두 가지 핵심 기능을 제공합니다:

submit_plan tool - Agent가 계획을 완료하면 호출하여 브라우저에서 대화형 검토 진행
/plannotator-review 명령어 - Git diff 코드 검토를 수동으로 실행

설치 과정은 두 단계로 나뉩니다:

opencode.json에 플러그인 설정 추가 (submit_plan tool 활성화)
설치 스크립트 실행 (/plannotator-review 명령어 획득)

따라하기

1단계: opencode.json으로 플러그인 설치

OpenCode 설정 파일(보통 프로젝트 루트 디렉토리 또는 사용자 설정 디렉토리에 위치)을 찾아 plugin 배열에 Plannotator를 추가합니다:

json

{
  "$schema": "https://opencode.ai/config.json",
  "plugin": ["@plannotator/opencode@latest"]
}

왜 이렇게 하나요opencode.json은 OpenCode의 플러그인 설정 파일입니다. 플러그인 이름을 추가하면 OpenCode가 자동으로 npm 저장소에서 플러그인을 다운로드하고 로드합니다.

확인 사항: OpenCode 시작 시 "Loading plugin: @plannotator/opencode..." 메시지가 표시되어야 합니다.

2단계: OpenCode 재시작

왜 이렇게 하나요 플러그인 설정 변경 후 적용하려면 재시작이 필요합니다.

확인 사항: OpenCode가 모든 플러그인을 다시 로드합니다.

3단계: 설치 스크립트 실행으로 슬래시 명령어 획득

macOS / Linux / WSLWindows PowerShell

bash

curl -fsSL https://plannotator.ai/install.sh | bash

powershell

irm https://plannotator.ai/install.ps1 | iex

왜 이렇게 하나요 이 스크립트는 다음을 수행합니다:

plannotator CLI 도구를 시스템에 다운로드
/plannotator-review 슬래시 명령어를 OpenCode에 설치
캐시된 플러그인 버전 정리

확인 사항: "Plannotator installed successfully!"와 같은 설치 성공 메시지가 표시되어야 합니다.

4단계: 설치 확인

OpenCode에서 플러그인이 정상적으로 작동하는지 확인합니다:

submit_plan tool 사용 가능 여부 확인:

대화에서 Agent에게 "submit_plan을 사용하여 계획을 제출해 주세요"라고 요청
플러그인이 정상이면 Agent가 이 tool을 보고 호출할 수 있어야 합니다

/plannotator-review 명령어 사용 가능 여부 확인:

입력창에 /plannotator-review 입력
플러그인이 정상이면 명령어 제안이 표시되어야 합니다

확인 사항: 두 기능 모두 오류 없이 정상적으로 사용할 수 있어야 합니다.

5단계: 환경 변수 설정 (선택사항)

Plannotator는 다음 환경 변수를 지원합니다. 필요에 따라 설정하세요:

환경 변수 설명

환경 변수	용도	기본값	예시
`PLANNOTATOR_REMOTE`	원격 모드 활성화 (devcontainer/SSH)	미설정	`export PLANNOTATOR_REMOTE=1`
`PLANNOTATOR_PORT`	고정 포트 (원격 모드 필수)	로컬 랜덤, 원격 19432	`export PLANNOTATOR_PORT=9999`
`PLANNOTATOR_BROWSER`	사용자 정의 브라우저 경로	시스템 기본값	`export PLANNOTATOR_BROWSER="/Applications/Google Chrome.app"`
`PLANNOTATOR_SHARE`	URL 공유 비활성화	활성화	`export PLANNOTATOR_SHARE=disabled`

원격 모드 설정 예시 (devcontainer/SSH):

.devcontainer/devcontainer.json에서:

json

{
  "containerEnv": {
    "PLANNOTATOR_REMOTE": "1",
    "PLANNOTATOR_PORT": "9999"
  },
  "forwardPorts": [9999]
}

왜 이렇게 하나요

원격 모드: 컨테이너나 원격 머신에서 OpenCode를 실행할 때, 고정 포트를 사용하고 브라우저를 자동으로 엽니다
포트 포워딩: 호스트 머신이 컨테이너 내부 서비스에 접근할 수 있게 합니다

확인 사항: Agent가 submit_plan을 호출하면 콘솔에 서버 URL이 표시됩니다 (브라우저가 자동으로 열리지 않음). 예:

Plannotator server running at http://localhost:9999

6단계: OpenCode 재시작 (환경 변수 수정 시)

5단계에서 환경 변수를 설정했다면, 설정을 적용하기 위해 OpenCode를 다시 재시작해야 합니다.

체크포인트 ✅

설치 완료 후 다음 사항을 확인하세요:

[ ] opencode.json에 @plannotator/opencode@latest 추가됨
[ ] OpenCode 재시작 후 플러그인 로드 오류 없음
[ ] /plannotator-review 입력 시 명령어 제안 표시됨
[ ] (선택사항) 환경 변수 설정 완료

자주 발생하는 문제

일반적인 오류 1: 플러그인 로드 실패

증상: OpenCode 시작 시 "Failed to load plugin @plannotator/opencode" 메시지 표시

가능한 원인:

네트워크 문제로 npm에서 다운로드 불가
npm 캐시 손상

해결 방법:

네트워크 연결 확인
설치 스크립트 실행 (플러그인 캐시 정리됨)
npm 캐시 수동 정리: npm cache clean --force

일반적인 오류 2: 슬래시 명령어 사용 불가

증상: /plannotator-review 입력 시 명령어 제안이 표시되지 않음

가능한 원인: 설치 스크립트가 성공적으로 실행되지 않음

해결 방법: 설치 스크립트 다시 실행 (3단계)

일반적인 오류 3: 원격 모드에서 브라우저가 열리지 않음

증상: devcontainer에서 submit_plan 호출 시 브라우저가 열리지 않음

가능한 원인:

PLANNOTATOR_REMOTE=1 미설정
포트 포워딩 미설정

해결 방법:

PLANNOTATOR_REMOTE=1 설정 확인
.devcontainer/devcontainer.json의 forwardPorts에 설정한 포트가 포함되어 있는지 확인
표시된 URL을 수동으로 접속: http://localhost:9999

일반적인 오류 4: 포트 충돌

증상: 서버 시작 실패, "Port already in use" 메시지 표시

가능한 원인: 이전 서버가 제대로 종료되지 않음

해결 방법:

PLANNOTATOR_PORT를 다른 포트로 변경
또는 포트를 사용 중인 프로세스를 수동으로 종료 (macOS/Linux: lsof -ti:9999 | xargs kill)

이번 강의 요약

이번 강의에서는 OpenCode에서 Plannotator 플러그인을 설치하고 설정하는 방법을 배웠습니다:

opencode.json으로 플러그인 추가 - submit_plan tool 활성화
설치 스크립트 실행 - /plannotator-review 슬래시 명령어 획득
환경 변수 설정 - 원격 모드 및 사용자 정의 요구사항 적용
설치 확인 - 플러그인 정상 작동 확인

설치 완료 후 다음을 할 수 있습니다:

Agent가 submit_plan을 사용하여 계획을 제출하고 대화형 검토 진행
/plannotator-review를 사용하여 Git diff를 수동으로 검토

다음 강의 예고

다음 강의에서는 **계획 검토 기초**를 배웁니다.
배울 내용:
AI가 생성한 계획 확인 방법
다양한 유형의 주석 추가 (삭제, 대체, 삽입, 코멘트)
계획 승인 또는 거부

부록: 소스 코드 참조

소스 코드 위치 보기

업데이트 날짜: 2026-01-24

기능	파일 경로	라인 번호
플러그인 엔트리 정의	`apps/opencode-plugin/index.ts`	34-280
`submit_plan` tool 정의	`apps/opencode-plugin/index.ts`	209-252
플러그인 설정 (opencode.json) 주입	`apps/opencode-plugin/index.ts`	55-63
환경 변수 읽기	`apps/opencode-plugin/index.ts`	37-51
계획 검토 서버 시작	`packages/server/index.ts`	전체
코드 검토 서버 시작	`packages/server/review.ts`	전체
원격 모드 감지	`packages/server/remote.ts`	전체

주요 상수:

PLANNOTATOR_REMOTE: 원격 모드 플래그 ("1" 또는 "true"로 설정하여 활성화)
PLANNOTATOR_PORT: 고정 포트 번호 (로컬 기본값 랜덤, 원격 기본값 19432)

주요 함수:

startPlannotatorServer(): 계획 검토 서버 시작
startReviewServer(): 코드 검토 서버 시작
getSharingEnabled(): URL 공유 스위치 상태 가져오기 (OpenCode 설정 또는 환경 변수에서)

OpenCode 플러그인 설치 ​

이 강의를 마치면 할 수 있는 것 ​

현재 겪고 있는 어려움 ​

언제 이 방법을 사용하나요 ​

🎒 시작하기 전 준비사항 ​

핵심 개념 ​

따라하기 ​

1단계: opencode.json으로 플러그인 설치 ​

2단계: OpenCode 재시작 ​

3단계: 설치 스크립트 실행으로 슬래시 명령어 획득 ​

4단계: 설치 확인 ​

5단계: 환경 변수 설정 (선택사항) ​

6단계: OpenCode 재시작 (환경 변수 수정 시) ​

체크포인트 ✅ ​

자주 발생하는 문제 ​

일반적인 오류 1: 플러그인 로드 실패 ​

일반적인 오류 2: 슬래시 명령어 사용 불가 ​

일반적인 오류 3: 원격 모드에서 브라우저가 열리지 않음 ​

일반적인 오류 4: 포트 충돌 ​

이번 강의 요약 ​

다음 강의 예고 ​

부록: 소스 코드 참조 ​

OpenCode 플러그인 설치

이 강의를 마치면 할 수 있는 것

현재 겪고 있는 어려움

언제 이 방법을 사용하나요

🎒 시작하기 전 준비사항

핵심 개념

따라하기

1단계: opencode.json으로 플러그인 설치

2단계: OpenCode 재시작

3단계: 설치 스크립트 실행으로 슬래시 명령어 획득

4단계: 설치 확인

5단계: 환경 변수 설정 (선택사항)

6단계: OpenCode 재시작 (환경 변수 수정 시)

체크포인트 ✅

자주 발생하는 문제

일반적인 오류 1: 플러그인 로드 실패

일반적인 오류 2: 슬래시 명령어 사용 불가

일반적인 오류 3: 원격 모드에서 브라우저가 열리지 않음

일반적인 오류 4: 포트 충돌

이번 강의 요약

다음 강의 예고

부록: 소스 코드 참조