환경 변수 설정

이 강의를 마치면

✅ SSH, Devcontainer, WSL 등 원격 환경에서 Plannotator를 올바르게 설정할 수 있습니다
✅ 고정 포트를 사용하여 포트 충돌과 잦은 포트 포워딩 설정을 피할 수 있습니다
✅ 사용자 지정 브라우저로 계획 검토 화면을 열 수 있습니다
✅ URL 공유 기능을 활성화하거나 비활성화할 수 있습니다
✅ 각 환경 변수의 기본값과 동작을 이해할 수 있습니다

현재 겪고 있는 문제

문제 1: SSH나 Devcontainer에서 Plannotator를 사용할 때 브라우저가 자동으로 열리지 않거나 로컬 서버에 접속할 수 없습니다.

문제 2: Plannotator를 재시작할 때마다 랜덤 포트를 사용하여 포트 포워딩 설정을 계속 업데이트해야 합니다.

문제 3: 시스템 기본 브라우저가 사용 습관에 맞지 않아 특정 브라우저에서 계획을 확인하고 싶습니다.

문제 4: 보안상의 이유로 URL 공유 기능을 비활성화하여 계획이 실수로 공유되는 것을 방지하고 싶습니다.

Plannotator가 도와드립니다:

환경 변수를 통해 원격 환경을 자동 감지하고 브라우저 자동 열기를 비활성화합니다
고정 포트로 포트 포워딩 설정을 간편하게 합니다
사용자 지정 브라우저를 지원합니다
환경 변수로 URL 공유 기능을 제어합니다

이 기능이 필요한 상황

사용 시나리오:

SSH 원격 서버에서 Claude Code 또는 OpenCode 사용
Devcontainer 컨테이너에서 개발
WSL(Windows Subsystem for Linux) 환경에서 작업
고정 포트로 포트 포워딩 설정 간소화 필요
특정 브라우저(Chrome, Firefox 등) 사용 희망
기업 보안 정책으로 URL 공유 기능 비활성화 필요

적합하지 않은 상황:

로컬 개발 환경에서 기본 브라우저 사용 시(환경 변수 불필요)
포트 포워딩이 필요 없는 경우(완전한 로컬 개발)

핵심 개념

환경 변수란?

환경 변수는 운영 체제가 제공하는 키-값 쌍 설정 메커니즘입니다. Plannotator는 환경 변수를 읽어 다양한 실행 환경(로컬 또는 원격)에 적응합니다.

왜 환경 변수가 필요한가요?

Plannotator는 기본적으로 로컬 개발 환경에서 사용한다고 가정합니다:

로컬 모드: 랜덤 포트(포트 충돌 방지)
로컬 모드: 시스템 기본 브라우저 자동 열기
로컬 모드: URL 공유 기능 활성화

하지만 원격 환경(SSH, Devcontainer, WSL)에서는 이러한 기본 동작을 조정해야 합니다:

원격 모드: 고정 포트 사용(포트 포워딩 편의)
원격 모드: 브라우저 자동 열기 비활성화(호스트 머신에서 열어야 함)
원격 모드: URL 공유 비활성화 필요(보안 고려)

환경 변수를 사용하면 코드 수정 없이 다양한 환경에서 Plannotator의 동작을 조정할 수 있습니다.

환경 변수 우선순위

Plannotator가 환경 변수를 읽는 우선순위:

명시적 환경 변수 > 기본 동작

예시:
PLANNOTATOR_PORT=3000 > 원격 모드 기본 포트 19432 > 로컬 모드 랜덤 포트

이것은 다음을 의미합니다:

PLANNOTATOR_PORT를 설정하면 원격 모드 여부와 관계없이 해당 포트를 사용합니다
PLANNOTATOR_PORT를 설정하지 않으면 원격 모드는 19432, 로컬 모드는 랜덤 포트를 사용합니다

🎒 시작하기 전 준비

환경 변수를 설정하기 전에 확인하세요:

[ ] Plannotator 설치 완료(Claude Code 설치 또는 OpenCode 설치)
[ ] 현재 실행 환경 파악(로컬, SSH, Devcontainer, WSL)
[ ] (원격 환경) 포트 포워딩 설정 완료(SSH의 -L 매개변수 또는 Devcontainer의 forwardPorts)

따라하기

1단계: 원격 모드 설정(SSH, Devcontainer, WSL)

왜 필요한가요 원격 모드는 자동으로 고정 포트를 사용하고 브라우저 자동 열기를 비활성화하여 SSH, Devcontainer, WSL 등의 환경에 적합합니다.

설정 방법

macOS/Linux/WSL (Bash)Windows PowerShellWindows CMD

bash

export PLANNOTATOR_REMOTE=1

powershell

$env:PLANNOTATOR_REMOTE="1"

cmd

set PLANNOTATOR_REMOTE=1

예상 결과: 시각적 피드백 없이 환경 변수가 설정됩니다.

영구 적용(권장):

~/.bashrc 또는 ~/.zshrcPowerShell Profile시스템 환경 변수

bash

echo 'export PLANNOTATOR_REMOTE=1' >> ~/.bashrc
source ~/.bashrc

powershell

[Environment]::SetEnvironmentVariable('PLANNOTATOR_REMOTE', '1', 'User')

cmd

# "시스템 속성 > 환경 변수" 화면에서 추가

2단계: 고정 포트 설정(원격 환경 필수)

왜 필요한가요 원격 환경에서는 포트 포워딩 설정을 위해 고정 포트가 필요합니다. 로컬 환경에서도 고정 포트가 필요하면 설정할 수 있습니다.

기본 포트 규칙:

로컬 모드(PLANNOTATOR_REMOTE 미설정): 랜덤 포트(0)
원격 모드(PLANNOTATOR_REMOTE=1): 기본값 19432
PLANNOTATOR_PORT 명시적 설정: 지정된 포트 사용

설정 방법

macOS/Linux/WSL (Bash)Windows PowerShellWindows CMD

bash

# 19432로 설정(원격 모드 기본값)
export PLANNOTATOR_PORT=19432

# 또는 사용자 지정 포트
export PLANNOTATOR_PORT=3000

powershell

$env:PLANNOTATOR_PORT="19432"

cmd

set PLANNOTATOR_PORT=19432

예상 결과: 시각적 피드백 없이 환경 변수가 설정됩니다.

체크포인트 ✅: 포트 적용 확인

Claude Code 또는 OpenCode를 재시작한 후 계획 검토를 트리거하고 터미널 출력의 URL을 확인하세요:

bash

# 로컬 모드 출력(랜덤 포트)
http://localhost:54321

# 원격 모드 출력(고정 포트 19432)
http://localhost:19432

포트 포워딩 설정 예시:

SSH 원격 개발:

bash

ssh -L 19432:localhost:19432 user@remote-server

Devcontainer(.devcontainer/devcontainer.json):

json

{
  "forwardPorts": [19432]
}

3단계: 사용자 지정 브라우저 설정

왜 필요한가요 시스템 기본 브라우저가 원하는 것이 아닐 수 있습니다(예: Chrome에서 작업하지만 기본값이 Safari인 경우).

설정 방법

macOS (Bash)Linux (Bash)Windows PowerShellWindows CMD

bash

# 애플리케이션 이름 사용(macOS 지원)
export PLANNOTATOR_BROWSER="Google Chrome"

# 또는 전체 경로 사용
export PLANNOTATOR_BROWSER="/Applications/Google Chrome.app"

bash

# 실행 파일 경로 사용
export PLANNOTATOR_BROWSER="/usr/bin/firefox"

# 또는 상대 경로 사용(PATH에 있는 경우)
export PLANNOTATOR_BROWSER="firefox"

powershell

# 실행 파일 경로 사용
$env:PLANNOTATOR_BROWSER="C:\Program Files\Google\Chrome\Application\chrome.exe"

cmd

set PLANNOTATOR_BROWSER=C:\Program Files\Google\Chrome\Application\chrome.exe

예상 결과: 다음 계획 검토 트리거 시 Plannotator가 지정된 브라우저에서 열립니다.

체크포인트 ✅: 브라우저 적용 확인

재시작 후 계획 검토를 트리거하고 확인하세요:

macOS: 지정된 애플리케이션이 열림
Windows: 지정된 브라우저 프로세스가 시작됨
Linux: 지정된 브라우저 명령이 실행됨

일반적인 브라우저 경로:

운영 체제	브라우저	경로/명령
macOS	Chrome	`Google Chrome` 또는 `/Applications/Google Chrome.app`
macOS	Firefox	`Firefox` 또는 `/Applications/Firefox.app`
macOS	Safari	`Safari`
Linux	Chrome	`google-chrome` 또는 `/usr/bin/google-chrome`
Linux	Firefox	`firefox` 또는 `/usr/bin/firefox`
Windows	Chrome	`C:\Program Files\Google\Chrome\Application\chrome.exe`
Windows	Firefox	`C:\Program Files\Mozilla Firefox\firefox.exe`

4단계: URL 공유 기능 설정

왜 필요한가요 URL 공유 기능은 기본적으로 활성화되어 있지만, 보안상의 이유(예: 기업 환경)로 이 기능을 비활성화해야 할 수 있습니다.

기본 동작:

PLANNOTATOR_SHARE 미설정: URL 공유 활성화
disabled로 설정: URL 공유 비활성화

설정 방법

macOS/Linux/WSL (Bash)Windows PowerShellWindows CMD

bash

# URL 공유 비활성화
export PLANNOTATOR_SHARE="disabled"

powershell

$env:PLANNOTATOR_SHARE="disabled"

cmd

set PLANNOTATOR_SHARE=disabled

예상 결과: Export 버튼 클릭 시 "Share as URL" 옵션이 사라지거나 사용할 수 없게 됩니다.

체크포인트 ✅: URL 공유 비활성화 확인

Claude Code 또는 OpenCode 재시작
아무 계획 검토나 열기
오른쪽 상단 "Export" 버튼 클릭
옵션 목록 확인

활성화 상태(기본값):

✅ "Share"와 "Raw Diff" 두 개의 탭 표시
✅ "Share" 탭에 공유 가능한 URL과 복사 버튼 표시

비활성화 상태(PLANNOTATOR_SHARE="disabled"):

✅ "Raw Diff" 내용 바로 표시
✅ "Copy"와 "Download .diff" 버튼 표시
❌ "Share" 탭과 공유 URL 기능 없음

5단계: 모든 환경 변수 확인

왜 필요한가요 모든 환경 변수가 올바르게 설정되었고 예상대로 작동하는지 확인합니다.

확인 방법

bash

# macOS/Linux/WSL
echo "PLANNOTATOR_REMOTE=$PLANNOTATOR_REMOTE"
echo "PLANNOTATOR_PORT=$PLANNOTATOR_PORT"
echo "PLANNOTATOR_BROWSER=$PLANNOTATOR_BROWSER"
echo "PLANNOTATOR_SHARE=$PLANNOTATOR_SHARE"

powershell

# Windows PowerShell
Write-Host "PLANNOTATOR_REMOTE=$env:PLANNOTATOR_REMOTE"
Write-Host "PLANNOTATOR_PORT=$env:PLANNOTATOR_PORT"
Write-Host "PLANNOTATOR_BROWSER=$env:PLANNOTATOR_BROWSER"
Write-Host "PLANNOTATOR_SHARE=$env:PLANNOTATOR_SHARE"

예상 결과: 설정된 모든 환경 변수와 그 값이 표시됩니다.

예상 출력 예시(원격 환경 설정):

bash

PLANNOTATOR_REMOTE=1
PLANNOTATOR_PORT=19432
PLANNOTATOR_BROWSER=
PLANNOTATOR_SHARE=

예상 출력 예시(로컬 환경 설정):

bash

PLANNOTATOR_REMOTE=
PLANNOTATOR_PORT=
PLANNOTATOR_BROWSER=Google Chrome
PLANNOTATOR_SHARE=disabled

자주 발생하는 문제

문제 1: 환경 변수가 적용되지 않음

증상: 환경 변수를 설정한 후에도 Plannotator 동작이 변경되지 않습니다.

원인: 환경 변수는 새 터미널 세션에서만 적용되거나 애플리케이션 재시작이 필요합니다.

해결 방법:

환경 변수가 설정 파일(예: ~/.bashrc)에 영구적으로 저장되었는지 확인
터미널을 재시작하거나 source ~/.bashrc 실행
Claude Code 또는 OpenCode 재시작

문제 2: 포트가 이미 사용 중

증상: PLANNOTATOR_PORT 설정 후 시작 실패.

원인: 지정된 포트가 다른 프로세스에서 이미 사용 중입니다.

해결 방법:

bash

# 포트 사용 확인(macOS/Linux)
lsof -i :19432

# 포트 변경
export PLANNOTATOR_PORT=19433

문제 3: 브라우저 경로 오류

증상: PLANNOTATOR_BROWSER 설정 후 브라우저가 열리지 않습니다.

원인: 경로가 올바르지 않거나 파일이 존재하지 않습니다.

해결 방법:

macOS: 전체 경로 대신 애플리케이션 이름 사용(예: Google Chrome)
Linux/Windows: which 또는 where 명령으로 실행 파일 경로 확인
bash
```
which firefox  # Linux
where chrome   # Windows
```

문제 4: 원격 모드에서 브라우저가 예기치 않게 열림

증상: PLANNOTATOR_REMOTE=1 설정 후에도 원격 서버에서 브라우저가 열립니다.

원인: PLANNOTATOR_REMOTE 값이 "1" 또는 "true"가 아닙니다.

해결 방법:

bash

# 올바른 값
export PLANNOTATOR_REMOTE=1
export PLANNOTATOR_REMOTE=true

# 잘못된 값(적용되지 않음)
export PLANNOTATOR_REMOTE=yes
export PLANNOTATOR_REMOTE=enabled

문제 5: URL 공유 비활성화 후에도 옵션이 표시됨

증상: PLANNOTATOR_SHARE=disabled 설정 후에도 "Share as URL"이 여전히 보입니다.

원인: 적용하려면 애플리케이션 재시작이 필요합니다.

해결 방법: Claude Code 또는 OpenCode를 재시작하세요.

이 강의 요약

이 강의에서는 Plannotator의 4가지 핵심 환경 변수를 배웠습니다:

환경 변수	용도	기본값	적용 시나리오
`PLANNOTATOR_REMOTE`	원격 모드 스위치	미설정(로컬 모드)	SSH, Devcontainer, WSL
`PLANNOTATOR_PORT`	고정 포트	원격 모드 19432, 로컬 모드 랜덤	포트 포워딩 필요 또는 포트 충돌 방지
`PLANNOTATOR_BROWSER`	사용자 지정 브라우저	시스템 기본 브라우저	특정 브라우저 사용 희망
`PLANNOTATOR_SHARE`	URL 공유 스위치	미설정(활성화)	공유 기능 비활성화 필요

핵심 포인트:

원격 모드는 자동으로 고정 포트를 사용하고 브라우저 자동 열기를 비활성화합니다
명시적으로 설정된 환경 변수가 기본 동작보다 우선합니다
환경 변수 수정 후 애플리케이션 재시작이 필요합니다
기업 환경에서는 URL 공유 기능 비활성화가 필요할 수 있습니다

다음 강의 예고

다음 강의에서는 **자주 묻는 질문**을 배웁니다.
배우게 될 내용:
포트 충돌 문제 해결 방법
브라우저가 열리지 않는 상황 처리
계획이 표시되지 않는 오류 수정
디버깅 팁과 로그 확인 방법

부록: 소스 코드 참조

소스 코드 위치 보기

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

기능	파일 경로	라인 번호
원격 모드 감지	`packages/server/remote.ts`	16-29
포트 가져오기 로직	`packages/server/remote.ts`	34-49
브라우저 열기 로직	`packages/server/browser.ts`	45-74
URL 공유 스위치(Hook)	`apps/hook/server/index.ts`	44
URL 공유 스위치(OpenCode)	`apps/opencode-plugin/index.ts`	37-51

주요 상수:

DEFAULT_REMOTE_PORT = 19432: 원격 모드 기본 포트

주요 함수:

isRemoteSession(): 원격 환경(SSH, Devcontainer, WSL)에서 실행 중인지 감지
getServerPort(): 서버 포트 가져오기(환경 변수 우선, 그 다음 원격 모드 기본값, 마지막으로 랜덤)
openBrowser(url): 지정된 브라우저 또는 시스템 기본 브라우저에서 URL 열기

환경 변수 설정 ​

이 강의를 마치면 ​

현재 겪고 있는 문제 ​

이 기능이 필요한 상황 ​

핵심 개념 ​

환경 변수란? ​

환경 변수 우선순위 ​

🎒 시작하기 전 준비 ​

따라하기 ​

1단계: 원격 모드 설정(SSH, Devcontainer, WSL) ​

2단계: 고정 포트 설정(원격 환경 필수) ​

3단계: 사용자 지정 브라우저 설정 ​

4단계: URL 공유 기능 설정 ​

5단계: 모든 환경 변수 확인 ​

자주 발생하는 문제 ​

문제 1: 환경 변수가 적용되지 않음 ​

문제 2: 포트가 이미 사용 중 ​

문제 3: 브라우저 경로 오류 ​

문제 4: 원격 모드에서 브라우저가 예기치 않게 열림 ​

문제 5: URL 공유 비활성화 후에도 옵션이 표시됨 ​

이 강의 요약 ​

다음 강의 예고 ​

부록: 소스 코드 참조 ​

환경 변수 설정

이 강의를 마치면

현재 겪고 있는 문제

이 기능이 필요한 상황

핵심 개념

환경 변수란?

환경 변수 우선순위

🎒 시작하기 전 준비

따라하기

1단계: 원격 모드 설정(SSH, Devcontainer, WSL)

2단계: 고정 포트 설정(원격 환경 필수)

3단계: 사용자 지정 브라우저 설정

4단계: URL 공유 기능 설정

5단계: 모든 환경 변수 확인

자주 발생하는 문제

문제 1: 환경 변수가 적용되지 않음

문제 2: 포트가 이미 사용 중

문제 3: 브라우저 경로 오류

문제 4: 원격 모드에서 브라우저가 예기치 않게 열림

문제 5: URL 공유 비활성화 후에도 옵션이 표시됨

이 강의 요약

다음 강의 예고

부록: 소스 코드 참조