자주 묻는 질문
snowpea의 기본 개념, 권한 모드, CI 사용, 업데이트, 확장 방식을 다룹니다.
이 문서에서 다루는 내용:
- 기본부터 알아보기
- 모드와 권한
- 헤드리스와 CI
- 업데이트
- 프로토콜과 확장
- 다음 문서 고르기
기본부터 알아보기
snowpea는 정확히 무엇인가요?
내 컴퓨터에서 도는 오픈소스 멀티벤더 코딩 에이전트입니다. Python 코어가 로컬 데몬으로 상주하면서 상태가 있는 것은 전부 소유합니다 — 세션, 툴, 권한, 메모리, 스케줄, 메신저 바인딩. 클라이언트는 문서화된 WebSocket JSON-RPC 프로토콜로 그 데몬에 붙습니다. 지금 있는 클라이언트는 세 가지입니다. 터미널 UI, 데스크톱 앱 (snowpea desktop), 그리고 헤드리스 CLI.
데이터는 어디로 가나요?
데몬이 도는 이 컴퓨터에 남습니다. $SNOWPEA_HOME(기본 ~/.snowpea, Windows는 %LOCALAPPDATA%\snowpea)에 세션 DB(state.db), 설정(settings.json), 자격 증명(credentials.json, 모드 0600), 로그, 첨부, 음성 파일이 들어갑니다. 프로젝트별 설정은 <project>/.snowpea/settings.json 입니다. 밖으로 나가는 것은 내가 고른 LLM 벤더로 보내는 프롬프트와, 내가 켠 검색·브라우저 제공자로 가는 요청뿐입니다.
비밀 값은 settings.json 에 절대 기록되지 않고 로그에도 남지 않습니다.
어떤 벤더를 써야 하나요?
이미 계정이 있는 곳. 어댑터가 네이티브든 OpenAI 호환이든 snowpea 안에서의 사용감은 같습니다. 아무 계정도 없다면 local 로 vLLM · Ollama · LM Studio · llama.cpp 서버를 붙일 수 있는데, 이때는 툴 호출을 지원하는 모델이어야 합니다. 그렇지 않으면 에이전트가 말은 하는데 아무것도 하지 못합니다. 전체 목록은 설정 에 있습니다.
유료 계정이 꼭 있어야 하나요?
LLM 벤더 말고는 없습니다. 기본 웹 검색 제공자 ddgs 는 키도 계정도 필요 없고, 기본 브라우저 제공자 local_chromium 은 내 컴퓨터에서 헤드리스 Chromium을 돌립니다.
목록에 있는 *_free 아이디들이 헷갈릴 수 있는데, 이것들은 키가 필요한 제품의 무료 티어이지 키 없는 엔드포인트가 아닙니다. Exa는 키 없이 402, Parallel과 Keenable과 Tavily는 401 로 답합니다. 예외는 exa_free 로, Exa의 공식 호스팅 MCP를 익명으로 쓰기 때문에 키를 묻지 않습니다(대신 속도 제한이 있습니다).
여러 클라이언트를 동시에 써도 되나요?
네. 같은 SNOWPEA_HOME 을 쓰는 클라이언트는 하나의 데몬을, 따라서 하나의 세션 집합을 공유합니다. 터미널에서 시작한 세션이 데스크톱 앱 사이드바에 그대로 있고, 앱에서 만든 스레드가 TUI에도 보입니다.
세션을 의도적으로 격리하려면 SNOWPEA_HOME 을 다르게 지정합니다. 그러면 별개의 데몬, 별개의 설정, 별개의 세션이 됩니다. CI에서 잡마다 격리가 필요할 때 쓰는 방법도 이것입니다.
SNOWPEA_HOME=/tmp/snowpea-ci snowpea -c "run the linter" --mode plan모드와 권한
기본 모드는 무엇인가요?
accept 입니다. 파일 읽기와 편집은 묻지 않고 하고, 셸 명령·네트워크 호출·메시지 전송은 먼저 묻습니다. Claude Code의 acceptEdits와 같은 자리입니다.
왜 같은 명령을 계속 승인하라고 하나요?
그게 허용 목록(allowlist)에 넣으라는 신호입니다. 허용 목록 항목은 ask 를 allow 로 올려 주지만 deny 는 절대 올리지 못합니다 — 즉 여기에 무엇을 넣어도 plan 모드가 약해지지 않습니다.
/allow ^git (status|diff|log)\b
/allow ^npm (run )?test$ --global
/allow tool:web_search
/allowlist패턴은 셸 명령에 대해 매칭되는 정규식입니다. 앵커를 걸고 좁게 작성합니다. ^git 한 줄은 git push --force 까지 열어 줍니다.
auto 모드는 위험한가요?
네. 아무것도 묻지 않습니다. 지켜보고 있을 때, 버려도 되는 컨테이너 안일 때, 또는 폭발 반경을 미리 생각해 둔 예약 작업에만 사용합니다. 개발 머신에서 프롬프트가 성가시다고 auto로 내리는 것은 잘못된 해법입니다 — 그건 허용 목록이 할 일입니다.
아무도 승인에 답하지 않으면?
기본 300초 후에 거절로 처리됩니다. approvals.timeoutSec이 지나면 거절로 처리되고 턴이 끝납니다. 타임아웃을 포함한 모든 결정은 $SNOWPEA_HOME/logs/approvals.jsonl 에 남습니다.
헤드리스와 CI
스크립트에서 어떻게 쓰나요?
snowpea -c "..." 는 UI 없이 한 턴만 돌리고 결정적인 종료 코드를 돌려줍니다. TTY가 없으면 물어볼 사람이 없으므로 승인 요청은 즉시 거절이 되고 4 로 끝납니다. 그럴 의도라면 명시합니다.
snowpea -c "run the linter" --approve-none| 코드 | 뜻 |
|---|---|
0 | 턴이 끝까지 완료 |
1 | 에이전트가 실패로 종료 |
2 | 사용법 또는 설정 오류 |
3 | 데몬에 접속하지 못함 |
4 | 승인이 거절됐거나 모드가 막음 |
5 | --timeout 경과 — 세션을 중단하고 닫음 |
4 가 핵심입니다. plan 모드에서 쓰기를 시도하면 mode_denied 오류와 함께 4 가 나오므로, plan 모드 자체가 CI에서 쓸 만한 읽기 전용 게이트가 됩니다.
CI에서 안전한 조합은?
읽기만 하는 작업이라면 plan 모드, 잃어도 되는 컨테이너 안이라면 auto 모드. 그리고 잡마다 SNOWPEA_HOME 을 따로 지정합니다. 데몬은 스텝이 끝나도 계속 살아 있으므로 러너가 오래 사는 종류라면 잡 끝에 snowpea daemon stop 을 넣어 두는 게 좋습니다.
업데이트
자동으로 업데이트되나요?
아니요. 하루에 한 번 백그라운드로 확인만 하고 답을 $SNOWPEA_HOME/update-check.json 에 캐시합니다. 내가 승낙하지 않으면 아무것도 설치되지 않습니다. 터미널 UI에 배너가 뜨면 빈 입력에서 U 를 누르거나 /update 를 치면 됩니다. 명령줄에서는 snowpea update --check 로 확인만, snowpea update 로 실행합니다.
{ "updates": { "check": true, "channel": "auto" } }check: false 는 매일 확인을 끕니다(/update 는 계속 동작). channel 은 auto, pypi, git 중 하나입니다.
직접 업그레이드했다면?
데몬을 꼭 멈추세요.
uv tool upgrade snowpea-agent
snowpea daemon stop돌고 있는 데몬은 예전 코드를 메모리에 들고 있습니다. 다음에 붙는 클라이언트가 지금 설치된 것과 맞지 않는 프로토콜 버전으로 핸드셰이크하게 됩니다.
프로토콜과 확장
직접 클라이언트를 만들 수 있나요?
네. 프로토콜은 문서화되어 있고 생성물입니다 — core/snowpea_core/server/protocol.py 가 진실의 원천이고, 거기서 프로토콜 레퍼런스와 sdk/src/protocol.ts 가 함께 생성됩니다. 현재 버전은 1.5.0입니다. 접속 직후 $SNOWPEA_HOME/token 의 토큰으로 system.hello 를 호출하고, 그 전의 다른 호출은 unauthorized 로 실패합니다. 개요는 프로토콜 에 있습니다.
플러그인이나 스킬은 어떻게 만드나요?
Claude Code 플러그인 형식을 그대로 씁니다 — SKILL.md, 훅, MCP 서버, 마켓플레이스. 플러그인 문서를 참조합니다. 데스크톱 앱의 스킬 화면에서 마켓플레이스를 검색하고 설치할 수도 있습니다.
코드가 다른 컴퓨터나 컨테이너에 있으면?
백엔드를 바꾸면 됩니다. local, docker, ssh 세 가지가 있고 /backend 또는 snowpea setup 으로 고릅니다. 백엔드 를 참조합니다.