온보딩 마법사 (revka onboard)

revka onboard는 Revka 설치 후 처음 실행하는 명령어입니다. 이 명령어는 워크스페이스를 생성하고, ~/.revka/config.toml을 작성하고, Python MCP 사이드카를 설치하며, 필요에 따라 데몬을 시작합니다. 같은 명령어가 세 가지 역할을 합니다.

• 대화형 마법사 — 터미널(TTY)에서 안내하는 9단계 설정.
• 빠른 설정 — CI, Docker, 스크립트 설치를 위한 무프롬프트 경로.
• 채널 복구 — 나머지 설정은 그대로 두고 채널 설정만 다시 실행.

Revka는 터미널 상태와 전달된 플래그를 기반으로 모드를 자동으로 선택하지만, 원하는 모드를 명시적으로 지정할 수도 있습니다. 온보딩이 완료되면 빠른 시작으로 이동하여 첫 번째 메시지를 보내보세요.

모드 선택

Revka는 터미널 상태와 플래그에 따라 실행 경로를 결정합니다.

조건	모드
--channels-only 전달됨	채널 복구 마법사
--quick 전달됨, 또는 --api-key / --provider / --model / --memory 중 하나 이상 전달됨	빠른 설정 (비대화형)
대화형 터미널 (stdin + stdout가 TTY), 또는 REVKA_INTERACTIVE=1	9단계 대화형 마법사
TTY 없음, 프로바이더 플래그 없음	기본값으로 빠른 설정

팁

터미널이 없는 환경(예: 래퍼 스크립트 내부)에서도 마법사를 강제 실행하려면 REVKA_INTERACTIVE=1을 설정하세요. 프로바이더 플래그는 항상 우선합니다. TTY 환경에서도 --api-key를 전달하면 빠른 설정으로 전환됩니다.

9단계 대화형 마법사

터미널에서 플래그 없이 마법사를 실행합니다.

revka onboard

1단계 전에 이중 언어 선택기(“Select your language / 언어를 선택하세요”)가 표시됩니다. 현재 활성화된 언어(--lang, REVKA_LANG, 또는 $LANG 기준)가 미리 선택되어 있으므로 Enter를 눌러 수락할 수 있습니다. 선택한 언어는 config.toml의 language 항목에 저장되어 이후 실행 시 기본값으로 사용됩니다.

마법사는 다음 9단계를 진행합니다.

1. 워크스페이스 — ~/.revka/workspace/를 생성하고 경로를 ~/.revka/active_workspace.toml에 기록하여 이후 모든 실행에서 Revka가 찾을 수 있도록 합니다.
2. AI 프로바이더 및 API 키 — 프로바이더를 선택하고 API 키를 입력합니다. 마법사가 프로바이더의 최신 모델 카탈로그를 가져와 실제 모델 ID를 선택할 수 있습니다.
3. 채널 — 메시징 채널(Telegram, Discord, Slack, WhatsApp, Lark 등)을 설정합니다. 허용 목록은 기본적으로 전체 거부 상태이므로 직접 자신을 명시적으로 추가해야 합니다.
4. 터널 — Cloudflare, ngrok, Tailscale 등을 통해 게이트웨이를 외부에 선택적으로 노출합니다. 터널로 게이트웨이 노출하기를 참고하세요.
5. 도구 모드 — Composio 관리형 OAuth 도구와 저장 데이터 암호화를 활성화합니다.
6. 하드웨어 — 시리얼, 네이티브 GPIO, 또는 디버그 프로브를 통한 물리적 환경 접근을 선택적으로 활성화합니다.
7. 메모리 — 메모리 백엔드를 선택합니다: SQLite, Kumiho 클라우드, Kumiho 로컬 커뮤니티 에디션, Markdown, 또는 없음.
8. 프로젝트 컨텍스트 — 이름, 시간대, 에이전트 이름, 소통 방식을 설정합니다. 이 정보로 워크스페이스 파일이 개인화됩니다.
9. 워크스페이스 스캐폴딩 — SOUL.md와 AGENTS.md를 작성하고 내장 Operator 워크플로 YAML 템플릿을 초기화합니다.

마법사는 기본적으로 Supervised 자율성과 워크스페이스 범위 접근 권한을 사용합니다. 자율성 수준 및 승인과 보안 모델을 참고하세요.

단계 완료 후

9단계가 모두 완료되면 마법사는 다음을 수행합니다.

• DreamState 메모리 통합 크론 작업 설정을 제안합니다(Kumiho 백엔드 전용 — 아래 참고).
• 제공된 경우 Kumiho 서비스 토큰을 <workspace>/.env에 작성합니다.
• Python MCP 사이드카(Kumiho + Operator)를 설치하여 즉시 사용 가능한 상태로 만듭니다. 설치를 거부하거나 실패해도 치명적이지 않습니다. 나중에 revka install --sidecars-only로 실행할 수 있습니다. Python MCP 사이드카 설치를 참고하세요.
• 요약을 출력한 후 지금 Revka 시작 여부를 묻습니다(데몬: 게이트웨이 대시보드 + 채널 + 스케줄러 + 하트비트). 수락하면 revka daemon이 포그라운드에서 실행되어 일회성 페어링 코드와 대시보드 URL을 확인할 수 있습니다.

gateway.require_pairing이 true(기본값)이면 마법사는 완료 시 대시보드 URL과 함께 다음 단계 페어링 안내를 출력합니다. 페어링 및 인증을 참고하세요.

기존 설정으로 다시 실행

설정이 이미 존재하는 상태에서 --force 없이 revka onboard를 실행하면, 마법사는 프로바이더 전용 업데이트 모드로 진입합니다. 프로바이더, 모델, API 키만 다시 묻고 해당 필드만 저장하며, 채널, 메모리, 터널, 훅 등 나머지 설정은 그대로 유지됩니다. --force를 사용하면 이 동작을 우회하고 9단계 마법사를 처음부터 다시 실행합니다.

빠른 설정 (비대화형)

빠른 설정(run_quick_setup)은 프롬프트 없이 적절한 기본 설정을 생성합니다. Docker, CI 파이프라인, 스크립트 부트스트랩에 권장되는 경로입니다.

# 최소: 프로바이더 + 키
revka onboard --api-key "sk-..." --provider openrouter

# 모델과 메모리 백엔드 포함
revka onboard --api-key "sk-..." --provider anthropic \
  --model claude-sonnet-4-20250514 --memory kumiho

# 기본값으로 빠른 설정 강제 실행 (프로바이더 플래그 없음)
revka onboard --quick

# 프롬프트 없이 기존 설정 덮어쓰기
revka onboard --api-key "sk-..." --provider openrouter --force

환경 변수만으로도 실행할 수 있습니다.

REVKA_API_KEY="sk-..." REVKA_PROVIDER="openrouter" revka onboard --quick

빠른 설정 기본값: 프로바이더 openrouter, 메모리 sqlite, 온도 0.7, 페어링이 필요한 127.0.0.1 게이트웨이, 터널 없음, Composio 없음.

설정 파일 위치: 빠른 설정은 REVKA_CONFIG_DIR(전체 설정 디렉토리)와 REVKA_WORKSPACE(워크스페이스 디렉토리, 설정 디렉토리 경로 도출에 사용)를 따릅니다. 둘 다 없으면 ~/.revka/를 사용합니다.

참고

--channels-only는 --api-key, --provider, --model, --memory, --force, --quick과 함께 사용할 수 없습니다. --reinit과 --channels-only도 상호 배타적입니다.

채널 복구 (--channels-only)

채널 토큰이 교체되었거나(예: Telegram 봇 토큰) 허용 목록을 수정해야 할 때, 채널 설정만 다시 실행할 수 있습니다. 나머지 설정은 그대로 유지됩니다.

revka onboard --channels-only

기존 설정을 불러온 뒤 3단계(채널)만 다시 실행하고 저장하는 빠른 단일 단계 마법사입니다. 실행 가능한 채널과 API 키가 설정되어 있으면 채널을 즉시 시작할지 묻습니다. 수락하면 REVKA_AUTOSTART_CHANNELS=1이 설정되어 마법사가 종료되는 즉시 채널 서버가 시작됩니다.

채널별 설정에 대해서는 메시징 채널 연결하기를 참고하세요.

플래그 참조

플래그	설명
--force	확인 없이 기존 설정을 덮어쓰고, 프로바이더 전용 업데이트 모드 대신 전체 마법사를 실행합니다.
--reinit	전체 설정 디렉토리를 타임스탬프 접미사가 붙은 이름으로 백업하고 처음부터 온보딩합니다. bin/ 아래의 설치된 바이너리는 보존됩니다. --channels-only와 함께 사용할 수 없습니다.
--channels-only	빠른 채널 복구 마법사만 실행합니다. --api-key, --provider, --model, --memory, --force, --quick과 함께 사용할 수 없습니다.
--api-key <KEY>	프로바이더 API 키. 빠른 설정을 트리거합니다.
--provider <ID>	프로바이더 이름. 예: openrouter, anthropic, openai. 빠른 설정을 트리거합니다. 기본값: openrouter.
--model <MODEL_ID>	모델 재정의. 빠른 설정을 트리거합니다.
--memory <kumiho|none>	빠른 설정의 메모리 백엔드 선택.
--quick	대화형 프롬프트를 건너뛰고 기본값으로 빠른 설정을 사용합니다.
--lang <en|ko>	마법사 UI 언어. REVKA_LANG과 $LANG을 재정의합니다.

언어 선택

마법사 UI 언어는 다음 우선순위로 결정됩니다: --lang 플래그 → REVKA_LANG → $LC_ALL / $LANG → 영어. 지원 값은 en과 ko입니다.

revka onboard --lang ko          # 한국어로 마법사 실행
REVKA_LANG=ko revka onboard      # 환경 변수로 동일하게 설정

이중 언어 0단계 선택기에서 런타임에 이를 재정의할 수 있으며, 최종 선택은 config.toml의 language에 저장됩니다.

--force vs --reinit

두 플래그는 혼동하기 쉽습니다.

• --force — 현재 설정을 프롬프트 없이 그 자리에서 덮어씁니다(프로바이더 전용 업데이트 경로도 건너뜁니다).
• --reinit — 기존 설정과 데이터를 타임스탬프가 붙은 백업 디렉토리로 이동하고(bin/ 폴더 제외) 완전히 새로 시작합니다. 백업 전에 y 확인을 요청합니다.

설정 보호

Revka는 실수로 설정이 손실되는 것을 방지합니다.

• 기존 설정이 있는 상태에서 revka onboard를 실행하면 채널, 메모리 등을 덮어쓰지 않고 프로바이더 전용 업데이트 모드로 실행됩니다.
• 비대화형 환경에서는 기존 설정을 덮어쓰려면 --force를 전달해야 합니다.
• --reinit은 초기화 전에 항상 백업을 수행하며, 먼저 확인을 요청합니다.
• 사이드카 설치 및 DreamState 단계는 치명적이지 않습니다. 거부하거나 실패해도 유효한 설정이 남습니다.

주의

Homebrew로 Revka를 설치한 경우, brew services는 Homebrew 접두사 하의 설정(예: /opt/homebrew/var/revka/)을 기본으로 사용합니다. 이는 마법사가 기본으로 작성하는 ~/.revka/ 디렉토리와 다릅니다. 두 경로가 다를 경우 마법사가 서비스 안내를 출력합니다. Revka를 서비스로 실행하기 전에 워크스페이스를 복사하거나 링크하세요.

DreamState 크론 작업 제안

Kumiho 메모리 백엔드를 선택하면, 마법사가 야간 DreamState 작업을 예약할지 묻습니다. DreamState는 Kumiho의 메모리 통합 사이클로, 최근 기억을 검토하고, 오래된 항목을 폐기하고, 태그와 메타데이터를 보강하며, 관련 항목 간의 그래프 엣지를 생성합니다.

실행 시간을 선택합니다.

옵션	크론 표현식
오전 2:00 (심야)	0 2 * * *
오전 3:00 (기본값)	0 3 * * *
오전 4:00 (이른 아침)	0 4 * * *
오전 6:00 (업무 전)	0 6 * * *
자정 12:00	0 0 * * *

작업은 격리된 세션에서 kumiho_memory_dream_state 도구를 실행합니다. 나중에 revka cron으로 추가, 변경, 삭제할 수 있습니다.

revka cron list
revka cron update <id> --expression '0 4 * * *'

그래프 메모리에 대한 자세한 내용은 Kumiho 그래프 메모리를 참고하세요.

환경 변수

변수	효과
REVKA_INTERACTIVE=1	TTY가 없어도 대화형 마법사를 강제 실행합니다.
REVKA_AUTOSTART_CHANNELS=1	온보딩 후 즉시 채널 서버를 시작합니다. “지금 채널 시작?” 프롬프트에 수락하면 자동으로 설정되며, 직접 설정할 수도 있습니다.
REVKA_LANG=<en|ko>	마법사 UI 언어(--lang보다 낮은 우선순위).
REVKA_CONFIG_DIR=<PATH>	전체 설정 디렉토리를 재정의합니다(빠른 설정에서 사용).
REVKA_WORKSPACE=<PATH>	워크스페이스 디렉토리를 재정의합니다. 설정 디렉토리는 이 경로에서 파생됩니다.
REVKA_API_KEY / REVKA_PROVIDER	비대화형으로 프로바이더 자격 증명을 지정합니다(빠른 설정을 트리거).

워크스페이스 스캐폴딩

마법사의 마지막 단계(및 빠른 설정)는 에이전트와 Operator가 의존하는 워크스페이스 레이아웃을 생성합니다.

• ~/.revka/workspace/ — 활성 워크스페이스. ~/.revka/active_workspace.toml에 기록됩니다.
• SOUL.md와 AGENTS.md — 8단계 입력 내용을 바탕으로 개인화된 아이덴티티 및 에이전트 지시 파일.
• <workspace>/operator_mcp/workflow/builtins/ — 내장 Operator 워크플로 YAML 템플릿.

업그레이드 후 등 언제든지 설정을 건드리지 않고 내장 워크플로를 다시 초기화할 수 있습니다.

revka workflows list           # 번들 템플릿 목록 보기
revka workflows sync           # 새 템플릿 복사 (비파괴적)
revka workflows sync --force   # 기존 파일 덮어쓰기

다음 단계

빠른 시작 첫 번째 메시지를 보내고 대시보드를 열어보세요.

Python MCP 사이드카 설치 메모리와 오케스트레이션을 위한 Kumiho + Operator 사이드카.

대시보드 실행 클라이언트를 페어링하고 웹 UI를 탐색하세요.

설정 개요 모든 config.toml 키, 기본값, 환경 변수 재정의.