구성: 프로바이더, 에이전트, 라우팅

이 페이지는 ~/.revka/config.toml 중 어떤 모델이 응답할지, 에이전트 루프가 어떻게 실행될지, 요청이 어떻게 라우팅되고 재시도될지를 결정하는 부분의 필드 레퍼런스입니다. 여기에 나열된 모든 키에는 타입, 기본값, 의미가 명시되어 있으므로 config.toml을 직접 편집하면서 각 값이 무엇을 의미하는지 정확히 파악할 수 있습니다.

배포를 세밀하게 조정할 때 이 페이지를 참조하십시오. 프로바이더 선택, 툴 루프 횟수 제한, 느린 로컬 모델 제어, 폴백 설정, 명명된 프로바이더 프로파일 고정 등의 작업에 활용할 수 있습니다. 런타임에서 라우팅과 신뢰성이 동작하는 방식에 대한 개념적 설명은 라우팅, 신뢰성 & 튜닝을 참고하십시오. 파일 위치 및 우선순위 규칙은 구성 개요를 참고하십시오.

참고

여기에 나열된 일부 키는 다음 인바운드 채널 메시지 시점에 핫 리로드됩니다 — 데몬 재시작이 필요하지 않습니다: default_provider, default_model, api_key, api_url, 그리고 [reliability] 하위의 모든 항목이 해당됩니다. 에이전트 루프 및 페이싱 설정은 재시작 후 적용됩니다.

핵심 프로바이더 & 모델 키

이 최상위 키들(섹션 헤더 없이 config.toml 루트에 위치)은 가장 먼저 편집하는 항목입니다. 기본 프로바이더, 모델, 키, 요청 동작을 선택합니다.

default_provider      = "openrouter"
default_model         = "anthropic/claude-sonnet-4-6"
api_key               = "sk-or-..."
default_temperature   = 0.7
provider_timeout_secs = 120

키	타입	기본값	의미
api_key	string?	없음	프로바이더 API 키. REVKA_API_KEY 또는 API_KEY, 혹은 프로바이더별 환경 변수(예: OPENROUTER_API_KEY)로 재정의됩니다.
api_url	string?	없음	프로바이더 기본 URL 재정의(예: http://10.0.0.1:11434의 Ollama).
api_path	string?	없음	특수 엔드포인트를 위한 커스텀 API 경로 접미사(예: /v2/generate).
default_provider	string	"openrouter"	기본 프로바이더 ID. 별칭 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?	미설정	출력 토큰 수를 제한합니다. 기본 제한에서 402 오류가 발생하는 OpenRouter 모델에 설정하십시오.
extra_headers	map	{}	프로바이더 호출에 추가할 HTTP 헤더; 환경 변수 REVKA_EXTRA_HEADERS는 Key:Value,Key2:Value2 형식.

팁

자격증명 해석 순서는 다음과 같습니다: (1) config의 명시적 api_key, (2) 프로바이더별 환경 변수(예: ANTHROPIC_API_KEY), (3) 범용 REVKA_API_KEY / API_KEY. 전체 프로바이더 목록 및 프로바이더별 환경 변수는 프로바이더 카탈로그를 참고하십시오.

[agent] — 에이전트 오케스트레이션

[agent] 섹션은 툴 호출 루프, 컨텍스트 예산, 압축, 턴별 툴 필터링을 제어합니다. 에이전트가 수행할 수 있는 툴 턴 횟수와 컨텍스트 윈도우 관리 방식을 조정하는 곳입니다.

[agent]
max_tool_iterations = 60
parallel_tools      = true
compact_context     = true
max_context_tokens  = 1050000

[[agent.tool_filter_groups]]
mode  = "always"
tools = ["mcp_vikunja_*"]

[[agent.tool_filter_groups]]
mode     = "dynamic"
tools    = ["mcp_browser_*"]
keywords = ["browse", "website", "url"]

키	타입	기본값	의미
compact_context	bool	true	13B 이하 소형 모델에 적합한 컴팩트 부트스트랩을 사용합니다.
max_tool_iterations	u32	60	메시지당 최대 툴 호출 턴 수; 0은 안전한 내부 기본값인 10으로 대체됩니다(채널 루프 내).
max_history_messages	u32	1000	유지할 최대 대화 히스토리 메시지 수.
max_context_tokens	u32	1050000	압축이 트리거되기 전의 토큰 예산.
parallel_tools	bool	true	독립적인 툴 호출을 동시에 실행합니다.
tool_dispatcher	string	"auto"	툴 디스패치 전략.
tool_call_dedup_exempt	array	[]	중복 호출 억제에서 제외할 툴 목록.
tool_filter_groups	array	[]	턴별 MCP 툴 스키마 필터(아래 참고).
max_system_prompt_chars	u32	0 (무제한)	소형 컨텍스트 모델을 위해 시스템 프롬프트를 N자로 잘라냅니다.
max_tool_result_chars	u32	50000	중간 잘라내기 전 툴 결과의 최대 문자 수.
keep_tool_context_turns	u32	2	전체 툴 호출/결과 메시지를 보존하는 최근 턴 수.
context_window_safety_ratio	f64	0.95	하드 실패 전 컨텍스트 윈도우 비율. 1.0으로 클램핑되며, 0 이하의 값은 0.95로 대체됩니다.

툴 필터 그룹

tool_filter_groups는 다수의 MCP 툴에 연결된 에이전트의 토큰 비용을 조절하는 가장 강력한 수단입니다. 각 [[agent.tool_filter_groups]] 테이블은 해당 턴에 특정 툴 스키마 집합을 주입할지 여부를 제어합니다:

필드	의미
mode	"always" (항상 주입) 또는 "dynamic" (키워드가 메시지와 일치할 때만 주입).
tools	툴 이름의 글로브 패턴, 예: "mcp_browser_*".
keywords	mode = "dynamic" 시: 메시지에 포함될 경우 그룹을 활성화하는 부분 문자열.

하위 섹션

[agent] 섹션에는 여러 튜닝 블록이 중첩됩니다:

• [agent.context_compression] — 압축 동작: enabled (true), threshold_ratio (0.5), protect_first_n (3), protect_last_n (4), max_passes (3), compact_tool_schemas (true).
• [agent.thinking] — 모델 추론 깊이 제어.
• [agent.history_pruning] — 오래된 히스토리의 토큰 효율적 정리.

참고

model_context_windows 키는 TOML 베어 키 표기에서 . 대신 _를 사용합니다. 간결한 오퍼레이터/서브 에이전트 핸드오프를 비활성화하려면 REVKA_TERSE_INTERNAL_OUTPUTS=0을 설정하십시오.

[pacing] — 느린 & 로컬 LLM 제어

[pacing] 섹션은 느리거나 로컬 백엔드(Ollama, llama.cpp, vLLM, SGLang)에서 타임아웃과 루프 감지 동작을 확장합니다. 클라우드 사용자는 일반적으로 이 설정이 필요하지 않습니다.

[pacing]
step_timeout_secs               = 120
loop_detection_min_elapsed_secs = 60
loop_ignore_tools               = ["browser_screenshot", "browser_navigate"]
message_timeout_scale_max       = 8

키	타입	기본값	의미
step_timeout_secs	u64?	미설정	전체 메시지 예산과 독립적인 단계별 LLM 추론 타임아웃. 이 타임아웃이 발동되어도 전체 예산은 소모되지 않습니다.
loop_detection_min_elapsed_secs	u64?	미설정	루프 감지가 카운트를 시작하기 전의 유예 기간.
loop_ignore_tools	array	[]	동일 출력 루프 감지에서 제외할 툴 목록.
message_timeout_scale_max	u32	4	메시지 타임아웃 예산 스케일링의 상한값(기본 channels_config.message_timeout_secs가 툴 루프 깊이에 따라 배율 적용).
loop_detection_enabled	bool	true	패턴 기반 루프 감지의 마스터 스위치.
loop_detection_window_size	u32	20	루프 감지기의 슬라이딩 윈도우 크기.
loop_detection_max_repeats	u32	3	경고가 발생하기 전 동일한 툴+인수 호출의 연속 횟수.

팁

로컬 모델이 느려서 기본 타임아웃이 생성 도중 요청을 끊는 경우, step_timeout_secs와 message_timeout_scale_max를 높이십시오. 로컬 모델에 대한 전반적인 안내는 커스텀 프로바이더 & 로컬 LLM을 참고하십시오.

[reliability] — 재시도 & 폴백

[reliability] 섹션은 기본 프로바이더를 3단계 복원력 전략으로 감쌉니다 — 모델 폴백 체인, 프로바이더 폴백 체인, 그리고 지수 백오프를 적용한 내부 재시도 루프입니다. 이 키들은 시작 시 및 revka doctor에 의해 검증되며, 다음 인바운드 채널 메시지 시점에 핫 리로드됩니다.

[reliability]
provider_retries    = 2        # attempts per provider before fallover
provider_backoff_ms = 500      # base backoff ms; doubles each retry, capped at 10000
fallback_providers  = ["anthropic", "openai"]
api_keys            = ["sk-second-key", "sk-third-key"]  # round-robin on 429

[reliability.model_fallbacks]
"claude-opus-4-20250514" = ["claude-sonnet-4-6-20250514", "gpt-4o"]

키	타입	기본값	의미
provider_retries	u32	2	다음 프로바이더로 전환하기 전 프로바이더당 시도 횟수.
provider_backoff_ms	u64	500	재시도마다 두 배씩 증가하는 기본 백오프(ms), 최대 10000.
fallback_providers	array	미설정	기본 프로바이더의 재시도가 소진된 후 순서대로 시도할 프로바이더 이름 목록.
api_keys	array	미설정	429 오류 시 라운드 로빈 순환에 사용할 추가 키 목록.
model_fallbacks	map	미설정	[reliability.model_fallbacks] 하위의 model → [fallback_model, …] 맵.

주의

인증 및 기타 4xx 오류(429/408 제외)는 재시도되지 않습니다 — 잘못된 키는 재시도 예산을 소모하지 않고 즉시 실패합니다. 컨텍스트 윈도우 초과는 별도 알림 없이 자동으로 히스토리를 잘라낸 후(시스템 메시지가 아닌 메시지의 오래된 절반 삭제) 재시도를 트리거합니다.

오류 분류, Retry-After 처리, 폴백 알림 채널 노출에 대한 개념적 모델은 라우팅, 신뢰성 & 튜닝에 문서화되어 있습니다.

[model_providers] — 명명된 프로바이더 프로파일

명명된 프로바이더 프로파일은 Codex 앱 서버 스타일 구성을 지원하며, 여러 엔드포인트(가장 일반적으로 Azure OpenAI 리소스/배포)를 안정적인 이름으로 정의할 수 있게 해줍니다.

[model_providers.azure-gpt4]
name                    = "openai"
base_url                = "https://my-resource.openai.azure.com"
azure_openai_resource   = "my-resource"
azure_openai_deployment = "gpt-4o"
azure_openai_api_version = "2024-08-01-preview"

필드	의미
name	사용할 기반 프로바이더 구현(예: openai).
base_url	엔드포인트 기본 URL.
api_path	커스텀 요청 경로 접미사.
wire_api	와이어 형식: responses 또는 chat_completions.
requires_openai_auth	OpenAI 스타일 인증 필요 여부.
azure_openai_resource	Azure 리소스 이름.
azure_openai_deployment	Azure 배포 이름(모델로 동작).
azure_openai_api_version	Azure API 버전.
max_tokens	프로파일별 출력 토큰 상한.

[[model_routes]] — 모델 라우팅 힌트

라우트는 심볼릭 hint: 이름을 구체적인 (provider, model) 쌍에 매핑합니다. 호출 측에서는 hint:reasoning 같은 안정적인 힌트를 사용하고, 모델 업그레이드는 라우트 편집만으로 처리할 수 있습니다.

[[model_routes]]
hint     = "reasoning"
provider = "openrouter"
model    = "anthropic/claude-opus-4-5"

[[model_routes]]
hint     = "fast"
provider = "groq"
model    = "llama-3.1-8b-instant"

필드	필수 여부	의미
hint	필수	고유한 심볼릭 이름(hint: 뒤에 오는 부분).
provider	필수	알려진 프로바이더 ID.
model	필수	해당 프로바이더와 함께 사용할 모델 ID.
api_key	선택	라우트별 키 재정의.

두 가지 특수 힌트 — hint:cost-optimized와 hint:cheapest — 는 [model_pricing] 데이터를 기준으로 라우트를 평가하여 가장 저렴한 라우트를 선택합니다. 알 수 없는 힌트는 힌트를 그대로 전달하면서 기본 프로바이더로 폴백됩니다. 에이전트는 model_routing_config 툴을 통해 라우트를 편집할 수 있습니다. revka doctor는 모든 라우트가 알려진 프로바이더를 가리키는지 검증합니다.

[[embedding_routes]] — 임베딩 라우팅

임베딩 라우트는 동일한 힌트 메커니즘을 메모리 임베딩 파이프라인에 적용하며, 추론 라우팅과 독립적으로 구성됩니다. [memory] embedding_model을 힌트로 지정하면 활성화됩니다.

[memory]
embedding_model = "hint:semantic"

[[embedding_routes]]
hint       = "semantic"
provider   = "openai"
model      = "text-embedding-3-small"
dimensions = 1536

필드	필수 여부	의미
hint	필수	embedding_model = "hint:<name>"으로 참조되는 심볼릭 이름.
provider	필수	none, openai, 또는 custom:<url> 중 하나.
model	필수	임베딩 모델 ID.
dimensions	선택	API 기본값이 스토리지 스키마와 다를 때 재정의.
api_key	선택	라우트별 키 재정의.

[query_classification] — 자동 힌트 라우팅

쿼리 분류는 수신 메시지의 내용에 따라 hint:를 자동으로 선택합니다 — LLM 호출 없이 순수 문자열 비교로 매칭합니다. 규칙은 우선순위 순서로 평가됩니다.

[query_classification]
enabled = true

[[query_classification.rules]]
hint       = "reasoning"
keywords   = ["explain", "analyze", "why"]
min_length = 200
priority   = 10

[[query_classification.rules]]
hint       = "fast"
keywords   = ["hi", "hello", "thanks"]
max_length = 50

키	타입	기본값	의미
enabled	bool	false	분류의 마스터 스위치.
rules	array	[]	우선순위 높은 순서로 평가되는 규칙 목록.

[[query_classification.rules]] 하위의 각 규칙:

키	타입	기본값	의미
hint	string	필수	구성된 [[model_routes]] 힌트와 일치해야 합니다.
keywords	array	[]	대소문자 구분 없는 부분 문자열 매칭.
patterns	array	[]	대소문자 구분하는 리터럴 매칭(예: 코드 펜스).
min_length	int	미설정	메시지가 최소 N자 이상일 때만 매칭.
max_length	int	미설정	메시지가 최대 N자 이하일 때만 매칭.
priority	int	0	높은 우선순위가 먼저 검사됩니다.

[runtime] — 추론 & 런타임 어댑터

[runtime] 섹션은 실행 모드와 모델 추론/사고 토글을 제어합니다. 추론 필드는 요청별 옵션의 일부로 모든 프로바이더에 전달됩니다.

[runtime]
reasoning_enabled = true            # or false; unset = provider defaults
reasoning_effort  = "high"          # minimal | low | medium | high | xhigh

키	타입	기본값	의미
reasoning_enabled	bool?	미설정	확장 사고 토글. 환경 변수 REVKA_REASONING_ENABLED / REASONING_ENABLED. Ollama에서는 think: true/false로 전송됩니다.
reasoning_effort	string?	미설정	추론 노력도: minimal, low, medium, high, xhigh. Codex 및 기타 노력도 인식 모델에서 사용됩니다.

참고

추론 토글은 이를 지원하는 모델에서만 적용됩니다. Ollama의 경우 네이티브 /api/chat 엔드포인트에서 think:로 전송되며, 미지원 모델에서는 무시됩니다.

[identity] — 에이전트 신원 형식

[identity] 섹션은 시스템 프롬프트에 주입될 신원 문서 형식을 선택합니다: OpenClaw(기본 스타일) 또는 AIEOS.

[identity]
format     = "aieos"
aieos_path = "identity.json"   # workspace-relative
# or inline:
# aieos_inline = '{"name": "Revka", ...}'

키	의미
format	신원 문서 형식(openclaw 또는 aieos).
aieos_path	AIEOS 신원 JSON 파일의 워크스페이스 상대 경로.
aieos_inline	aieos_path 대신 사용하는 인라인 AIEOS 신원 JSON.

관련 위임 에이전트 설정

기본 에이전트는 명명된 서브 에이전트와 스웜에 작업을 위임할 수 있습니다. 이 설정들은 별도 섹션에 있지만 위의 루프 설정과 상호작용합니다:

• [agents.<name>] — 위임 서브 에이전트 구성(프로바이더, 모델, agentic, allowed_tools, max_iterations, 타임아웃). [operator]는 오퍼레이터 세션에서 agent.max_tool_iterations를 재정의할 수 있습니다. 에이전트, 팀 & 스웜을 참고하십시오.
• [swarms.<name>] — sequential, parallel, 또는 router 전략을 가진 에이전트의 조율된 그룹.

팁

revka doctor는 프로바이더, 모델, 온도, 폴백 프로바이더, 모델 라우트, 임베딩 라우트, 위임 에이전트 프로바이더를 한 번에 검증합니다 — 이 파일을 편집한 후 실행하십시오. 진단을 참고하십시오.

다음 단계

구성 개요 구성 파일 위치, 우선순위, 전체 섹션 맵.

라우팅, 신뢰성 & 튜닝 힌트 라우팅, 폴백, 재시도가 런타임에서 동작하는 방식.

프로바이더 카탈로그 모든 프로바이더: ID, 별칭, 기본 URL, 환경 변수, 기능.

커스텀 프로바이더 & 로컬 LLM Revka를 Ollama, llama.cpp, vLLM 및 커스텀 엔드포인트에 연결합니다.

진단 revka doctor가 프로바이더, 라우트, 폴백을 검증합니다.

구성: 채널, 툴 & 통합 채널 및 툴 구성을 위한 대응 레퍼런스.