설정 마법사

라우트 /setup. 최초 실행에서는 마법사가 곧 앱입니다. 프롬프트에 답할 수 있는 프로바이더가 없으면 다른 무엇보다 먼저 마법사가 열리고, 끝내거나 미루기 전까지는 내비게이션 레일이 보이지 않습니다. 그 뒤로는 설정의 Run setup wizard(설정 마법사 실행)로 언제든 다시 열 수 있습니다.

마법사는 명령줄의 snowpea setup과 같은 항목을 같은 순서로 묻고, 같은 settings.json 키를 씁니다. 어느 쪽을 쓰든 결과가 같고, 다시 실행해도 나머지가 초기화되는 것이 아니라 원하는 한 가지만 바뀝니다.

일곱 단계

단계	묻는 내용
① LLM 프로바이더	벤더와 자격 증명(API 키, 브라우저 로그인, 디바이스 코드, 붙여 넣은 OAuth 토큰), 모델 — 모델 목록의 출처까지 — 추가 모델, 기본 모델, 에이전트별 모델 지정
② 웹 검색 프로바이더	어떤 검색 백엔드를 쓸지와 그 API 키 또는 인스턴스 URL. ★ 기본값인 ddgs는 둘 다 필요 없음
③ 브라우저 프로바이더	browser_* 도구가 무엇을 구동할지. 기본값은 local_chromium
④ 오디오	입력과 출력을, 행동 먼저로: 권장 CPU 엔진을 설치하거나 특정 엔진을 고정합니다. 그다음 목소리, 자동 읽기 여부, 시험 문장을 들려주는 버튼
⑤ 도구 범주	어떤 도구 그룹을 켤지, 그리고 스킬 레지스트리 퍼블리셔 토큰
⑥ 메신저	Telegram, Discord, Slack의 봇 토큰과, 그 플랫폼에서의 내 계정 id
⑦ 요약	각 단계의 현재 상태, 그리고 Save 또는 Cancel

왼쪽 레일에는 단계 이름만이 아니라 그 단계가 지금 가진 답이 함께 적힙니다. 그래서 요약 화면은 처음 보는 내용이 아니라 내내 보고 있던 내용을 확인해 줍니다. 레일의 항목을 고르면 그 단계로 돌아가며, 요약의 Edit 버튼도 같은 일을 합니다.

오디오 단계

이 단계는 목록이 아니라 행동이 먼저입니다. 첫 실행에서 쓸모 있는 질문은 "이 아홉 개 중 무엇"이 아니라 "일단 되는 것을 하나 달라"이기 때문입니다.

Voice in(입력)과 Voice out(출력)은 설정되지 않은 상태로 시작하며, 이는 그쪽 음성이 꺼져 있다는 뜻입니다. 맨 위 줄이 그렇게 알려 주고, 그 아래에 snowpea가 권하는 엔진이 나옵니다. 언제나 CPU에서 도는 것입니다. Recommended: SenseVoiceSmall (CPU) 옆의 Install 버튼에는 키보드 초점이 미리 가 있습니다. snowpea가 받아올 수 있는 다른 엔진은 그 옆에 **Install <엔진>…**으로 나옵니다.

설치는 선택이 아닙니다. Install은 엔진을 받아오기만 하고 설정은 바꾸지 않습니다. 끝나면 그 엔진이 아래 선택기에 나타나고 초점이 옮겨 가며 installed — select it to use it이라고 알려 줍니다. 고정하는 것은 선택이고, 그때 왼쪽 목록의 이 단계 답도 not set에서 그 엔진으로 바뀝니다.

**Choose a specific engine…**는 선택기를 엽니다. 지금 이 컴퓨터에서 동작하는 엔진과 Off, 사용자 지정 명령, 유료 호스티드 서비스가 들어 있습니다. 그 안의 각 줄도 저마다 이어지는 곳이 있습니다. 채워 넣을 명령 템플릿, 붙여 넣을 키, 또는 그냥 선택입니다. 설치되지 않은 엔진은 이 선택기에 없습니다. 고정해 봐야 다음 턴이 쓸 수 없는 것을 고르는 일이기 때문입니다. 그것들은 설정 → Audio에 있고, 거기에는 줄마다 Install 버튼이 달린 전체 목록이 있습니다.

엔진을 고정하고 나면 이 단계는 거기서 따라 나오는 두 가지를 묻습니다. 입력에는 어떤 언어를 말할지, 출력에는 언어마다 어떤 목소리를 쓸지입니다. 둘 다 설정 → Audio에 있는 것과 같은 조작 장치라서, 여기서 한 선택을 나중에 다시 할 필요는 없습니다.

Skip은 이 단계 전체를 설정되지 않은 채로 둡니다. 설정에서 다시 손대기 전까지 음성은 꺼져 있습니다.

자격 증명

Save 전에는 아무것도 기록되지 않습니다. Save를 누르면 자격 증명을 입력한 벤더마다 provider.configure를 한 번씩 호출하고, 모든 단계의 내용을 담아 전역 설정 문서에 한 번 기록합니다.

비밀 값은 되읽히지 않습니다. 이미 저장된 키와 토큰은 "저장됨"으로 표시되고 입력란은 비어 있습니다. 비워 두면 저장된 값이 유지되고, 입력하면 교체됩니다.

paid · key required로 표시된 프로바이더를 고르면 — 검색의 Tavily, 브라우저의 Browserbase나 Firecrawl Cloud — 목록 아래에 키 입력란이 열립니다. 이 키는 선택 사항이 아닙니다. 키 없이는 단계를 넘어갈 수 없고 Save도 거부됩니다. 자격 증명 없이 고른 프로바이더는 여기서는 설정된 것처럼 보이지만 실제로는 첫 도구 호출에서 실패하기 때문입니다. 안내 문구가 정직한 두 가지 길을 알려 줍니다. 다른 프로바이더를 고르거나, 그 단계를 건너뛰는 것입니다.

key optional로 표시된 프로바이더는 같은 입력란을 열지만 막지는 않습니다. 키가 없어도 동작하고, 키는 더 나은 등급을 살 뿐입니다.

선택 사항처럼 보이지만 아닌 항목이 하나 더 있습니다. 메신저에 내 user id가 없으면 대화는 되지만 승인은 되지 않습니다. 게이트웨이는 지정되지 않은 계정의 승인 조작을 모두 거부합니다. 플랫폼마다 id를 알려주는 곳이 다르고, 입력란 아래 힌트가 그곳을 알려줍니다.

검색 키는 search.credentials.<프로바이더>.api_key에, 브라우저 키는 browser.credentials.<프로바이더>.api_key에 저장됩니다.

빠른 설정

첫 단계의 Quick setup(빠른 설정)은 입력한 프로바이더·자격 증명·모델만 받아들이고 검색, 브라우저, 오디오, 도구, 메신저는 기본값으로 둔 채 바로 요약으로 넘어갑니다. 건너뛴 단계는 요약에 default로 표시되며, Save 전에 언제든 열어볼 수 있습니다.

건너뛰기

Skip — keep defaults는 그 단계의 값을 그대로 둔 채 넘어가고, 그 값도 다른 답과 똑같이 기록됩니다. 전부 건너뛰어도 ddgs와 local_chromium이 기록되는 이유입니다.

Skip for now(지금은 건너뛰기)는 최초 실행에서 마법사를 아예 떠납니다. 설정을 안내했다는 사실을 기록하고 앱을 열며, Setup incomplete — no provider is configured, so prompts will not run(설정 미완료 — 프로바이더가 없어 프롬프트가 실행되지 않음) 배너를 남깁니다. 배너에는 여기로 돌아오는 버튼이 있고, 닫기 버튼은 없습니다. 설정을 마치면 사라집니다.

요약 화면의 Cancel은 이번 실행을 버립니다. 아무것도 기록되지 않습니다.

키보드

단계가 열리는 순간부터 키보드가 목록에 올라가 있습니다.

키	동작
↑ / ↓	선택지 사이 이동
Space	체크박스 단계(도구, 메신저)의 행 토글
Enter	강조된 선택지를 택하고 계속
Esc	대화 상자 닫기

불러오지 못할 때

벤더와 프로바이더의 목록은 core에서 오므로, 마법사는 무언가를 제시하기 전에 연결을 기다립니다. 계속 기다리기만 한다면 문제는 마법사가 아니라 core에 있습니다. 상태 표시줄이 무슨 일이 있었는지 알려주며, 그동안 Skip for now로 앱에 들어갈 수 있습니다.