문제 해결

설치, 데몬, 로그인, 모델, 검색, 세션 복구, 프로토콜 연결 문제의 증상과 해결 방법을 다룹니다.

이 문서에서 다루는 내용

• 설치 문제 해결하기
• 데몬 상태 확인하기
• 로그인과 모델 연결 확인하기
• 검색과 브라우저 확인하기
• 대화와 문맥 복구하기
• 연결 문제 확인하기

설치 문제 해결하기

snowpea: command not found

증상: snowpea 설치 직후 셸에서 snowpea: command not found 가 출력됩니다.

원인: ~/.local/bin 이 현재 열려 있는 셸의 PATH 에 없습니다. 인스톨러는 셸 프로필에 줄을 추가하지만 이미 열려 있는 셸의 환경은 변경하지 못합니다.

해결:

1. 새 터미널을 열거나 셸 프로필을 다시 읽습니다.
2. 설치 위치와 현재 PATH 를 확인합니다.

ls ~/.local/bin/snowpea
echo $PATH

3. SNOWPEA_BIN_DIR 로 설치 위치를 바꿨는지 확인합니다.

설치 스크립트가 중간에 실패했습니다

증상: 설치 스크립트가 완료되지 않고 중간 단계에서 실패합니다.

원인: 네트워크, 권한, 도구 설치 단계 중 하나가 실패했습니다. 설치 스크립트는 멱등하게 실행됩니다.

해결:

1. 설치 스크립트를 다시 실행합니다.
2. 같은 단계에서 다시 실패하면 드라이런으로 실행할 작업을 확인합니다.

curl -fsSL https://raw.githubusercontent.com/Wafour-Developer/snowpea-agent/main/installer/install.sh -o install.sh
sh install.sh --dry-run

3. 실패한 단계를 직접 실행합니다.

curl -LsSf https://astral.sh/uv/install.sh | sh     # uv
uv tool install snowpea-agent

회사 프록시 뒤, 또는 오프라인 머신

증상: 회사 프록시 뒤나 오프라인 머신에서 uv tool install 이 실패합니다.

원인: uv tool install 은 PyPI에 접속해야 합니다.

해결:

1. 인스톨러를 실행하기 전에 HTTPS_PROXY 를 설정합니다.
2. 오프라인 설치가 필요하면 휠 파일을 가져와 직접 설치합니다.

uv tool install ./snowpea_agent-0.1.0-py3-none-any.whl

3. 인스톨러의 패키지 출처를 바꿔야 하면 SNOWPEA_WHEEL_URL 과 SNOWPEA_INSTALL_SOURCE 를 설정합니다.

터미널 UI가 안 뜹니다 — Node가 없거나 너무 낮습니다

증상: 터미널 UI(TUI)가 시작되지 않습니다.

원인: TUI에는 Node 20 이상이 필요합니다. 헤드리스 실행과 모든 snowpea 서브커맨드는 Node 없이 실행됩니다.

해결:

1. 패키지 매니저나 nodejs.org에서 Node 20 이상을 설치합니다.
2. Node 버전을 확인합니다.

node --version

3. snowpea 를 다시 실행합니다.
4. TUI 없이 동작을 확인해야 하면 헤드리스 실행을 사용합니다.

snowpea -c "hello" --json

업데이트 후 Cannot read properties of undefined (reading 'rawCall')

증상: 업데이트 후 Cannot read properties of undefined (reading 'rawCall') 오류가 출력됩니다.

원인: 이전 자동 업데이트가 남긴 상태가 현재 실행 코드와 맞지 않습니다.

해결:

1. 현재 main 을 강제로 다시 설치합니다.

uv tool install --force --reinstall 'snowpea-agent[images] @ git+https://github.com/Wafour-Developer/snowpea-agent@main'

2. 실행 중인 작업이 없을 때 데몬을 멈춥니다.

snowpea daemon stop

3. snowpea 를 다시 실행하여 새 데몬 코드를 로드합니다.

데몬 상태 확인하기

데몬이 시작되지 않습니다

증상: 데몬(snowpea core)이 시작되지 않습니다.

원인: 데몬 로그에 시작 실패 원인이 기록되어 있거나, 죽은 프로세스의 포트 정보가 남아 있을 수 있습니다.

해결:

1. $SNOWPEA_HOME/logs/daemon.log 를 확인합니다.
2. 데몬 상태를 확인하고 재시작합니다.

snowpea daemon status
snowpea daemon stop
snowpea daemon start

3. daemon.json 에 적힌 pid가 이미 죽은 상태이면 daemon.json 을 삭제합니다.

포트가 이미 쓰이고 있습니다

증상: 데몬 포트가 이미 사용 중이라는 오류가 발생합니다.

원인: 데몬은 시작할 때 루프백 포트를 고르고 $SNOWPEA_HOME/daemon.json 에 {port, pid, token, startedAt, protocolVersion} 를 기록합니다. 포트 충돌은 대부분 이전 데몬이 아직 살아 있거나, 죽은 데몬의 daemon.json 이 남아 있는 상태입니다.

해결:

1. 기록된 pid가 살아 있는지 확인합니다.

snowpea daemon status      # pid가 살아 있는지 확인

2. 데몬을 멈춥니다.

snowpea daemon stop

3. 다른 프로그램이 해당 포트를 사용 중이면 데몬을 다시 시작하여 다른 포트를 선택하게 합니다.
4. 활성 헬스 체크가 필요하면 /health 를 호출합니다.

curl "http://127.0.0.1:$(python -c 'import json;print(json.load(open("'"$HOME"'/.snowpea/daemon.json"))["port"])')/health"

exit 3 — 데몬에 접속하지 못함

증상: 헤드리스 실행이 exit 3 으로 끝납니다.

원인: 데몬이 없거나 클라이언트가 데몬에 접속하지 못했습니다. SNOWPEA_HOME 이 다르면 다른 데몬을 사용합니다.

해결:

1. 데몬 상태를 확인합니다.

snowpea daemon status

2. 평소와 다른 SNOWPEA_HOME 을 지정했는지 확인합니다.

여러 프로젝트가 서로의 세션을 봅니다

증상: 여러 프로젝트에서 같은 세션 목록이 보입니다.

원인: 같은 SNOWPEA_HOME 은 같은 데몬과 같은 세션 집합을 사용합니다.

해결:

1. 프로젝트별 격리가 필요하면 SNOWPEA_HOME 을 나눕니다.

SNOWPEA_HOME=~/.snowpea-work snowpea
SNOWPEA_HOME=/tmp/snowpea-ci snowpea -c "…" --mode plan

2. 헤드리스 실행에서는 --home DIR 을 사용합니다.

로그인과 모델 연결 확인하기

디바이스 코드 로그인이 HTTP 403 으로 실패합니다

증상: 디바이스 코드 로그인에서 device authorization failed (HTTP 403) 이 출력됩니다.

원인: 일부 네트워크나 계정에서 같은 요청이 다른 곳에서는 성공해도 HTTP 403 으로 실패할 수 있습니다. 마법사는 벤더가 준 오류 문구를 출력하고 인증 방식을 다시 묻습니다.

해결:

1. 마법사에서 1=API key 를 선택하고 키를 붙여 넣습니다.
2. 또는 3=OAuth token 을 선택하고 토큰을 입력합니다.
3. 명령줄에서는 API 키를 설정합니다.

snowpea setup --vendor openai --key sk-your-key-here

4. 명령줄에서 토큰을 입력할 때는 값을 생략하여 셸 히스토리에 남기지 않습니다.

snowpea provider login openai --token      # 값을 생략해야 셸 히스토리에 남지 않습니다

login_unsupported

증상: 로그인 시 login_unsupported 가 출력됩니다.

원인: 브라우저 로그인을 지원하는 벤더는 openai(디바이스 코드)와 openrouter(OAuth PKCE)입니다. Gemini는 Google ADC 로그인을 사용하고, 나머지 벤더는 login_unsupported 와 대신 실행할 명령을 반환합니다.

해결:

1. 해당 벤더에 필요한 설정 명령을 실행합니다.

snowpea setup --vendor deepseek --key sk-your-key-here

프로바이더가 설정되지 않았다고 합니다

증상: 프로바이더가 설정되지 않았다는 오류가 출력됩니다.

원인: 사용할 벤더는 SNOWPEA_PROVIDER 환경변수, 명령줄의 --provider 또는 세션의 provider 인자, settings.json 의 providers.default, 설정된 첫 번째 벤더 순서로 결정됩니다. 예상과 다른 벤더가 선택되면 SNOWPEA_PROVIDER 가 export 되어 있을 수 있습니다.

해결:

1. 설정된 프로바이더 목록을 확인합니다.

snowpea provider list
snowpea provider list --json

2. SNOWPEA_PROVIDER 환경변수가 설정되어 있는지 확인합니다.

원격/헤드리스 머신에서 Gemini 로그인

증상: 원격 또는 헤드리스 머신에서 Gemini 로그인을 진행할 브라우저가 없습니다.

원인: 데스크톱의 snowpea provider login gemini 는 Google ADC 로그인을 엽니다.

해결:

1. 토큰 입력 방식으로 로그인합니다.

snowpea provider login gemini --token

2. 값을 생략하여 가려진 프롬프트로 입력하고 셸 히스토리에 남기지 않습니다.

로컬 모델이 말은 하는데 아무것도 하지 않습니다

증상: 로컬 모델이 대화는 하지만 도구 호출을 실행하지 않습니다.

원인: /v1/chat/completions 를 지원하는 서버에는 연결할 수 있지만, 도구 호출은 로드한 모델이 지원해야 합니다. 지원하지 않는 모델이면 에이전트는 대화만 할 수 있고 행동하지 못합니다.

해결:

1. 도구 호출을 지원하는 모델로 설정합니다.

snowpea setup --vendor local --base-url http://localhost:11434/v1 --model qwen3:8b

검색과 브라우저 확인하기

브라우저 툴이 바이너리를 내려받겠다고 합니다

증상: 브라우저 툴이 실행 중 바이너리를 내려받겠다고 표시합니다.

원인: 기본 브라우저 제공자 local_chromium 은 Playwright로 헤드리스 Chromium을 실행합니다. 바이너리가 없으면 첫 실행에서 내려받습니다.

해결:

1. 온라인 환경에서는 다운로드를 허용합니다.
2. 오프라인 머신에서는 바이너리를 미리 받아 두거나 브라우저 카테고리를 끕니다.

snowpea setup --tools -browser

3. 다른 제공자(camoufox, browser_use_local, browserbase, firecrawl_cloud)는 설정 전까지 browser_provider_unavailable 로 응답합니다.

웹 검색이 안 됩니다

증상: 웹 검색이 응답하지 않습니다.

원인: 설정된 검색 제공자가 사용할 수 없거나, 키가 필요한 제공자에 키가 없습니다. ddgs 는 키가 필요 없습니다.

해결:

1. 실제 질의를 실행하여 응답한 제공자와 건너뛴 제공자의 이유를 확인합니다.

snowpea search test "snowpea agent github"
snowpea search test "snowpea agent github" --json
snowpea tools list --json

2. tools list 에서 web_search 가 exa_free → ddgs 처럼 표시되면 설정된 아이디가 동작하지 못해 대체된 것입니다.
3. 키가 필요한 제공자를 선택했다면 키를 설정합니다.

web_extract 가 특정 URL을 거부합니다

증상: web_extract 가 특정 URL을 거부합니다.

원인: 사설 대역, 루프백, 링크 로컬 주소는 거부됩니다. 가져온 페이지는 tools.max_output_chars(기본 20000)에서 잘립니다.

해결:

1. 공용으로 접근 가능한 URL을 사용합니다.
2. 출력이 잘리면 tools.max_output_chars 설정을 조정합니다.

미디어 툴이 tool_inactive 로 답합니다

증상: 미디어 툴이 tool_inactive 로 응답합니다.

원인: image_generate, video_generate, music_generate, text_to_speech 는 항상 등록되어 있지만 자격 증명이 생기기 전까지 inactive 입니다.

해결:

1. 해당 미디어 제공자의 자격 증명을 설정합니다.
2. 설정 후 재시작 없이 도구 상태가 active 로 바뀝니다.

대화와 문맥 복구하기

컨텍스트가 가득 찼습니다

증상: 상태 줄의 ctx 가 85%를 넘으면 빨갛게 되고 [!!] context 85% — /compact to free space 줄이 표시됩니다.

원인: 현재 대화가 모델의 컨텍스트 창 한도에 가까워졌습니다. ctx 12.3k used 처럼 퍼센트 없이 표시되면 데몬이 이 모델의 창 크기를 알지 못하는 상태입니다.

해결:

1. /compact 를 실행하고 선택 인자로 남길 내용을 지정합니다.

/compact 이 리팩터링에서 무엇을 바꿨는지는 꼭 남겨줘

2. context.autoCompactPercent 를 넘길 것 같은 턴은 데몬이 자동으로 압축합니다.
3. 퍼센트가 표시되지 않으면 providers.<vendor>.context_window 를 설정합니다.

/resume 이 거부됩니다

증상: /resume 또는 /sessions 가 거부됩니다.

원인: 실행 중인 턴 아래에서 전사를 교체하면 현재 턴의 전사가 일관되지 않습니다. 같은 이유로 살아 있는 세션은 삭제되지 않고 /session clear 는 그 세션을 건너뜁니다.

해결:

1. 현재 턴이 끝날 때까지 기다립니다.
2. 또는 Esc 로 실행 중인 턴을 중단한 뒤 다시 시도합니다.

연결 문제 확인하기

protocol_incompatible

증상: protocol_incompatible 이 출력됩니다.

원인: 클라이언트와 데몬의 프로토콜 메이저 버전이 다릅니다. 패키지는 업그레이드됐지만 이전 데몬이 아직 메모리에 떠 있을 때 발생할 수 있습니다.

해결:

1. 데몬을 멈춥니다.

snowpea daemon stop

2. 버전을 확인합니다.

snowpea --version

3. snowpea 를 다시 실행합니다.

snowpea

4. 데스크톱 앱을 쓰고 있다면 하단 상태 표시줄의 합의된 프로토콜 버전을 확인하고 앱과 코어를 같이 올립니다.
5. 현재 프로토콜은 1.5.0이고, 전체 스키마는 프로토콜 레퍼런스에 있습니다.

unauthorized

증상: unauthorized 가 출력됩니다.

원인: system.hello 보다 먼저 다른 메서드를 호출했거나 토큰이 틀렸습니다. 토큰은 $SNOWPEA_HOME/token 에 있고, 접속 직후 첫 호출은 system.hello 여야 합니다.

해결:

1. 직접 만든 클라이언트의 첫 호출이 system.hello 인지 확인합니다.
2. $SNOWPEA_HOME/token 의 토큰을 사용했는지 확인합니다.
3. 프로토콜의 핸드셰이크 절을 확인합니다.

도움 요청하기

도움 요청에는 재현에 필요한 로그, 버전, 상태, 명령을 포함합니다.

1. $SNOWPEA_HOME/logs/daemon.log 의 마지막 50줄을 준비합니다.
2. snowpea --version 과 snowpea daemon status 의 출력을 준비합니다.
3. 재현 명령 한 줄을 준비합니다.
4. 이슈를 엽니다.

다음 단계

자주 묻는 질문개념과 선택지를 확인합니다.→설치 다시 보기지원 환경과 설치 단계를 확인합니다.→