구성 개요

Revka는 Revka 디렉터리(기본값: ~/.revka/config.toml)에 위치한 단일 TOML 파일 config.toml을 통해 구성됩니다. 기본 공급자 및 모델, 게이트웨이와 보안 정책, 메모리 백엔드, 채널 토큰, 도구, 사이드카 통합까지 모든 설정이 이 파일 하나에 담겨 있습니다. 이 페이지는 해당 파일의 전체 구조를 설명합니다. Revka가 어떤 config.toml을 불러올지 결정하는 방식, 처음 편집할 핵심 최상위 키, 머신 리더블 스키마 내보내기 방법, 전체 섹션 카탈로그, 그리고 재시작 없이 핫 리로드되는 키를 다룹니다.

이 페이지를 구성 레퍼런스의 진입점으로 활용하세요. 공급자, 채널, 도구, 플랫폼/보안 섹션은 각각 별도의 전용 페이지에서 설명하며, 아래 섹션 카탈로그에서 링크를 확인할 수 있습니다. 환경 변수 재정의 — .env 로딩 순서 및 전체 REVKA_* 표 — 는 CLI 개요 페이지에 있습니다. 이 페이지에서는 파일 탐색에 영향을 미치는 항목만 요약하고 나머지는 교차 링크로 연결합니다.

구성 파일 탐색 순서

전역 --config-dir 플래그(또는 이를 뒷받침하는 REVKA_CONFIG_DIR 변수)를 지정하지 않은 경우, Revka는 세 단계 우선순위 체계를 통해 불러올 config.toml을 결정합니다.

1. REVKA_WORKSPACE — 이 환경 변수가 설정되어 있으면 해당 워크스페이스 디렉터리가 절대적으로 우선하며, 구성 디렉터리는 이로부터 파생됩니다.
2. ~/.revka/active_workspace.toml — revka onboard가 작성하는 영구 마커 파일로, 선택된 워크스페이스 경로를 가리킵니다. 이 덕분에 매번 경로를 재지정하지 않아도 실행 간에 워크스페이스가 유지됩니다.
3. 기본값 — ~/.revka/config.toml.

REVKA_CONFIG_DIR(및 이를 뒷받침하는 --config-dir 플래그)은 전체 구성 디렉터리를 재정의하며, 구성 파일을 불러오기 전에 적용됩니다. 이 변수가 어떤 파일을 불러올지 자체를 결정하기 때문입니다. --config-dir은 서브커맨드 앞에 위치해야 하며, 빈 문자열은 거부됩니다.

# 명시적 구성 디렉터리 지정 (플래그는 자식 프로세스에도 REVKA_CONFIG_DIR로 설정됨)
revka --config-dir /srv/revka daemon

# 환경 변수를 통한 워크스페이스 재정의
REVKA_WORKSPACE=/data/workspace revka agent

주의

Homebrew로 설치한 경우 기본 경로가 /opt/homebrew/var/revka/로, 수동 설치 시 사용하는 ~/.revka/ 디렉터리와 다릅니다. revka onboard는 작성하는 구성이 서비스가 바라보는 경로와 다를 경우 경고를 표시합니다. 서비스로 실행하기 전에 워크스페이스를 복사하거나 링크로 연결해 두세요. macOS 라이프사이클 페이지를 참고하세요.

REVKA_WORKSPACE와 REVKA_CONFIG_DIR

두 파일 위치 변수는 서로 다릅니다.

변수	재정의 대상	동작
REVKA_CONFIG_DIR	--config-dir 플래그	전체 구성 디렉터리를 재정의합니다. 구성 파일 로딩 전에 읽힙니다. --config-dir 플래그를 설정하면 Revka가 생성하는 모든 자식 프로세스에도 이 변수가 내보내집니다.
REVKA_WORKSPACE	활성 워크스페이스 디렉터리	워크스페이스를 가리키며, 구성 디렉터리는 여기서 파생됩니다. active_workspace.toml 마커보다 우선합니다.

최초 실행(revka onboard) 시 워크스페이스를 생성하고, config.toml을 작성하며, 선택한 워크스페이스를 active_workspace.toml에 기록합니다. 전체 최초 실행 흐름은 온보딩 마법사를 참고하세요.

active_workspace.toml

~/.revka/active_workspace.toml은 revka onboard(마법사 2단계)가 작성하는 작은 마커 파일입니다. 선택한 워크스페이스 경로를 기록하므로, 이후 실행 시 REVKA_WORKSPACE를 매번 설정하지 않아도 동일한 워크스페이스와 config.toml을 불러옵니다. 탐색 체계에서 두 번째 단계에 해당합니다. REVKA_WORKSPACE가 이를 재정의하고, 이 파일은 기본 ~/.revka/config.toml을 재정의합니다.

참고

active_workspace.toml(자동으로 작성되는 워크스페이스 포인터)은 멀티 클라이언트 워크스페이스 격리 프로필을 제어하는 [workspace] 구성 섹션과는 무관합니다. [workspace] 섹션은 구성: 게이트웨이, 메모리, 보안 및 플랫폼을 참고하세요.

핵심 최상위 구성 키

다음은 config.toml의 루트에 위치한 키들로, 온보딩 이후 처음 편집하게 되는 항목입니다. 모두 revka onboard 또는 환경 변수를 통해 설정할 수도 있습니다.

# ~/.revka/config.toml — 핵심 최상위 키
default_provider = "openrouter"
default_model = "anthropic/claude-sonnet-4.6"
default_temperature = 0.7
provider_timeout_secs = 120
# api_key = "sk-..."          # 공급자 환경 변수 또는 시크릿 암호화를 권장
# api_url = "http://10.0.0.1:11434"   # 공급자 베이스 URL 재정의 (예: Ollama)
# language = "en"
# locale = "en-US"

키	타입	기본값	설명
api_key	String?	없음	공급자 API 키. REVKA_API_KEY / API_KEY 또는 공급자별 환경 변수로 재정의됩니다. 평문으로 저장하지 않도록 [secrets] 참고를 권장합니다.
api_url	String?	없음	공급자 베이스 URL 재정의 (예: http://10.0.0.1:11434의 Ollama).
api_path	String?	없음	사용자 정의 API 경로 접미사 (예: /v2/generate).
default_provider	String	"openrouter"	기본 모델 공급자. model_provider 별칭을 허용합니다. 환경 변수: REVKA_PROVIDER 또는 레거시 PROVIDER.
default_model	String	"anthropic/claude-sonnet-4.6"	기본 모델. model 별칭을 허용합니다. 환경 변수: REVKA_MODEL.
default_temperature	f64	0.7	유효 범위: 0.0–2.0. 환경 변수: REVKA_TEMPERATURE.
provider_timeout_secs	u64	120	LLM 공급자 호출의 HTTP 타임아웃(초).
provider_max_tokens	u32?	미설정	공급자의 기본 출력 토큰 한도를 재정의합니다. 기본값이 65536인 OpenRouter에서 일부 모델에 402 오류가 발생할 때 중요합니다.
extra_headers	Map<String,String>	{}	공급자 호출에 추가할 HTTP 헤더. 환경 변수: REVKA_EXTRA_HEADERS (Key:Value,Key2:Value2 형식).
language	String?	자동 감지	마법사 및 인터랙티브 화면의 UI 언어: "en" 또는 "ko". 우선순위: --lang > REVKA_LANG > 이 필드 > LC_ALL/LANG > 영어.
locale	String?	자동 감지	도구 설명의 로케일 (language와 별개이며 zh-CN, ja-JP 등 더 넓은 범위를 지원합니다). 환경 변수: REVKA_LOCALE.

참고

language와 locale은 서로 다른 필드입니다. language는 마법사/인터랙티브 UI에만 영향을 미치며 en/ko만 허용합니다. locale은 LLM에 전달되는 도구 설명의 로케일을 제어하며 더 넓은 범위를 지원합니다. 레거시 PROVIDER 변수는 구성의 기본값이 여전히 openrouter일 때만 재정의됩니다. REVKA_PROVIDER는 설정 시 항상 우선 적용됩니다.

전체 공급자 환경 변수 우선순위(명시적 api_key → 공급자별 환경 변수 → 일반 REVKA_API_KEY)와 완전한 REVKA_* 표는 CLI 개요를 참고하세요.

revka config schema

revka config schema는 전체 config.toml 계약에 대한 머신 리더블 **JSON Schema(draft 2020-12)**를 표준 출력으로 내보냅니다. 이 스키마는 사용 가능한 모든 키의 타입, 기본값, 설명을 문서화하므로, 구성 형식에 대한 공식 진실의 원천입니다. 가장 자주 사용하는 키만 다루는 이 페이지보다 범위가 넓습니다.

revka config schema                 # 표준 출력으로 출력
revka config schema > schema.json   # 툴링을 위해 저장

가장 일반적인 활용은 에디터 유효성 검사입니다. 내보낸 파일을 에디터의 JSON Schema 지원에 연결하면 config.toml 편집 중 자동 완성과 인라인 유효성 검사를 사용할 수 있습니다. 예를 들어 VS Code에서 Even Better TOML 확장을 사용하는 경우:

.vscode/settings.json

{
  "evenBetterToml.schema.associations": {
    ".*/config\\.toml$": "./schema.json"
  }
}

이 명령은 실행 중인 데몬이 필요 없고 네트워크 호출도 하지 않습니다. 단, 기존 구성 디렉터리는 불러옵니다.

섹션 카탈로그

핵심 키 아래에서 config.toml은 이름이 지정된 섹션(TOML 테이블)으로 구성됩니다. 각 섹션은 전용 레퍼런스 페이지에서 자세히 설명합니다.

공급자, 에이전트 및 라우팅 [model_providers], [agent], [pacing], [reliability], [[model_routes]], [[embedding_routes]], [query_classification], [agents.], [swarms], [delegate].

채널, 도구 및 통합 [channels_config], [mcp], [browser], [http_request], [web_search], [composio], [google_workspace], [transcription], [tts], [multimodal] 등.

게이트웨이, 메모리, 보안 및 플랫폼 [gateway], [tunnel], [proxy], [memory], [kumiho], [operator], [autonomy], [security.otp], [security.estop], [workspace], [secrets], [storage], [cost], [observability].

Cargo 기능 플래그 및 ADR 컴파일 시 기능 플래그가 필요한 섹션 (예: browser-native, hardware, observability-otel).

일부 섹션은 컴파일 시 Cargo 기능 플래그 뒤에 있습니다. 예를 들어 [browser]의 Rust 네이티브 백엔드는 browser-native, [hardware]는 hardware, [observability]의 OpenTelemetry 지원은 observability-otel이 필요합니다. Cargo 기능 플래그 및 ADR을 참고하세요.

핫 리로드 동작

일부 키는 데몬과 채널이 실행 중인 동안 핫 리로드됩니다. Revka는 config.toml을 감시하며 재시작 없이 다음 인바운드 채널 메시지 시 변경 사항을 적용합니다. 핫 리로드되는 키는 다음과 같습니다.

• default_provider
• default_model
• default_temperature
• api_key / api_url
• reliability.* (재시도 및 폴백 공급자)

# 다음 항목을 편집하고 저장하면 다음 인바운드 메시지 시 적용됩니다:
default_provider = "anthropic"
default_model = "claude-sonnet-4-6"
default_temperature = 0.4

[reliability]
fallback_providers = ["openai"]

그 외 모든 섹션은 변경 사항을 적용하기 위해 데몬 재시작(revka service restart 또는 중지 후 revka daemon 재실행)이 필요합니다.

주의

핫 리로드는 데몬 및 채널 런타임에만 적용됩니다. 인터랙티브 revka agent 세션은 구성을 핫 리로드하지 않습니다. 변경 사항을 반영하려면 세션을 재시작하세요. 채팅 세션 내에서 인채팅 런타임 명령(/models, /model <model-id>, /new)을 사용하여 공급자와 모델을 실시간으로 전환할 수도 있습니다. revka 채널 및 통합을 참고하세요.

예시

구성 파일 찾기

# 워크스페이스 재정의가 절대적으로 우선
REVKA_WORKSPACE=/data/workspace revka status

# 단일 명령에 특정 구성 디렉터리 강제 지정
revka --config-dir /srv/revka doctor

# 선택한 워크스페이스를 기록하는 마커 확인
revka status   # 활성 워크스페이스와 사용 중인 공급자/모델을 출력

핵심 키 편집

# 비대화형 공급자/모델/키 빠른 설정
revka onboard --api-key "sk-..." --provider openrouter \
  --model "anthropic/claude-sonnet-4-6"

# 또는 config.toml에서 기본 모델만 직접 설정
revka models set anthropic/claude-sonnet-4.6

스키마로 유효성 검사

revka config schema > schema.json
# config.toml 자동 완성을 위해 에디터에서 schema.json을 지정

다음 단계

CLI 개요 및 환경 --config-dir 플래그, .env 로딩 순서, 전체 REVKA_* 환경 변수 레퍼런스.

구성: 공급자, 에이전트 및 라우팅 기본 공급자/모델, 이름 있는 공급자 프로필, 라우팅, 폴백, 서브 에이전트.

구성: 게이트웨이, 메모리, 보안 및 플랫폼 게이트웨이, 터널, 프록시, 메모리/Kumiho, 자율성, OTP, e-stop, 워크스페이스 격리.

온보딩 마법사 config.toml과 active_workspace.toml을 작성하는 revka onboard 안내.