프로바이더 빠른 시작

Revka는 단일 통합 인터페이스를 통해 모델 프로바이더와 통신합니다. 따라서 프로바이더를 선택하는 것은 대부분 두 가지 설정, 즉 default_provider와 API 키, 그리고 올바른 모델 ID를 지정하는 것으로 충분합니다. 이 페이지에서는 가장 많이 사용되는 세 가지 프로바이더인 OpenRouter(기본값), Anthropic, OpenAI로 채팅을 시작하는 방법을 안내합니다. 또한 Revka가 자격 증명을 확인하는 방식과 환경 변수를 통해 실행 시 프로바이더를 재정의하는 방법도 설명합니다.

아직 Revka를 설치하지 않았다면 설치와 빠른 시작을 먼저 진행하세요. 지원되는 전체 백엔드 목록은 프로바이더 카탈로그를 참고하세요.

프로바이더 설정 작동 방식

~/.revka/config.toml의 세 가지 최상위 키가 사용할 모델을 결정합니다.

키	타입	기본값	설명
default_provider	String	"openrouter"	프로바이더 ID (별칭 model_provider). 환경 변수: REVKA_PROVIDER 또는 PROVIDER (레거시).
default_model	String	"anthropic/claude-sonnet-4-6"	모델 ID (별칭 model). 환경 변수: REVKA_MODEL.
api_key	String?	없음	프로바이더 API 키. 환경 변수: REVKA_API_KEY 또는 API_KEY.

세 가지를 가장 빠르게 설정하려면 revka onboard를 실행하세요. 이 명령은 config.toml을 자동으로 생성합니다. 대화형 모드로 실행하거나, 비대화형 설정을 위해 플래그로 값을 직접 전달할 수 있습니다.

revka onboard                                          # 대화형 마법사
revka onboard --api-key sk-or-... --provider openrouter  # 비대화형

~/.revka/config.toml을 직접 수정하거나, 환경 변수만으로 자격 증명을 제공할 수도 있습니다. 자세한 내용은 아래 자격 증명 확인 순서를 참고하세요.

팁

revka providers를 실행하면 Revka가 알고 있는 모든 프로바이더의 ID와 별칭을 확인할 수 있습니다. 현재 활성화된 프로바이더는 별도로 표시되며, 커스텀 엔드포인트의 경우 custom:<URL> / anthropic-custom:<URL> 항목으로 나타납니다.

첫 번째 채팅 실행

프로바이더와 키가 설정되면 revka agent로 단발성 메시지를 전송할 수 있습니다.

revka agent -m "Say hello in one sentence."

-m 플래그를 생략하면 대화형 세션이 시작됩니다. revka agent의 주요 플래그는 다음과 같습니다.

플래그	설명
-m, --message <TEXT>	단일 메시지 전송 (대화형 루프 없음).
-p, --provider <ID>	이 실행에 한해 설정된 default_provider를 재정의합니다.
--model <MODEL_ID>	이 실행에 한해 설정된 default_model을 재정의합니다.
-t, --temperature <0.0-2.0>	이 실행에 한해 설정된 temperature를 재정의합니다.

이를 활용하면 설정 파일을 변경하지 않고도 프로바이더를 테스트할 수 있습니다.

revka agent -p openrouter --model openai/gpt-4o -m "Hello"
revka agent -p anthropic --model claude-sonnet-4-5-20250929 -m "Hello"

프로바이더 선택

OpenRouter (default)

OpenRouter는 Revka의 기본 프로바이더입니다. 키 하나로 여러 벤더의 200개 이상의 모델에 접근할 수 있으며, 모델 ID는 provider/model-name 형식을 사용합니다(예: anthropic/claude-sonnet-4-6).

1. OpenRouter API 키를 발급받으세요 — sk-or-로 시작합니다.

2. 다음과 같이 설정합니다.

   ~/.revka/config.toml

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

   또는 환경 변수로 설정할 수 있습니다.

   export OPENROUTER_API_KEY="sk-or-..."

3. 채팅을 실행합니다.

   revka agent -m "Hello from OpenRouter"

주의

일부 OpenRouter 모델에서는 기본 출력 한도(65536)로 인해 HTTP 402 오류가 발생할 수 있습니다. 이 경우 설정에서 provider_max_tokens를 더 낮은 값으로 설정하세요. 요청 타임아웃은 provider_timeout_secs로 조정할 수 있습니다(기본값 120).

Anthropic

Anthropic 프로바이더는 Anthropic Messages API에 직접 연결하며, 네이티브 툴 호출, 비전, 프롬프트 캐싱, SSE 스트리밍을 지원합니다.

1. Anthropic API 키를 발급받으세요 — sk-ant-로 시작합니다.

2. 다음과 같이 설정합니다.

   ~/.revka/config.toml

   default_provider = "anthropic"
   default_model    = "claude-sonnet-4-5-20250929"
   api_key          = "sk-ant-..."

   또는 환경 변수로 설정할 수 있습니다.

   export ANTHROPIC_API_KEY="sk-ant-..."

3. 채팅을 실행합니다.

   revka agent -p anthropic -m "Hello from Claude"

인증 환경 변수와 우선순위. Anthropic 프로바이더는 두 가지 변수를 읽습니다.

• ANTHROPIC_OAUTH_TOKEN — 설정/OAuth 토큰으로, 우선 확인됩니다. 일반 API 사용이 아닌 구독 인증 설정 플로우에 사용됩니다.
• ANTHROPIC_API_KEY — 대부분의 사용자가 사용하는 표준 sk-ant-… API 키입니다.

기본 max_tokens는 4096이며, provider_max_tokens로 재정의할 수 있습니다.

주의

claude-opus-4-7 계열 모델은 temperature 파라미터가 더 이상 지원되지 않습니다. Revka는 이를 자동으로 생략합니다(접두사 일치 방식이므로 claude-opus-4-7-*와 같은 패치 변형도 포함됩니다). 다른 경로로 해당 모델에 temperature를 강제 적용하면 Anthropic이 HTTP 400을 반환합니다.

OpenAI

OpenAI 프로바이더는 Chat Completions API(/v1/chat/completions)를 사용하며, 네이티브 툴 호출과 o 및 o3 계열 모델의 reasoning-content 필드를 지원합니다.

1. OpenAI API 키를 발급받으세요 — sk-로 시작합니다.

2. 다음과 같이 설정합니다.

   ~/.revka/config.toml

   default_provider = "openai"
   default_model    = "gpt-4o"
   api_key          = "sk-..."

   또는 환경 변수로 설정할 수 있습니다.

   export OPENAI_API_KEY="sk-..."

3. 채팅을 실행합니다.

   revka agent -p openai -m "Hello from OpenAI"

호환 가능한 엔드포인트나 프록시된 엔드포인트를 사용하려면 api_url 설정 키로 기본 URL을 재정의하세요.

default_provider = "openai"
default_model    = "gpt-4o"
api_url          = "https://api.openai.com"   # custom base

참고

로컬 모델, 자체 호스팅 엔드포인트, 또는 구독 기반 로그인(Codex, Gemini CLI, Claude Code)을 사용하려면 커스텀 프로바이더 & 로컬 LLM, 로컬·자체 호스팅·커스텀 엔드포인트, OAuth & 구독 프로바이더를 참고하세요.

자격 증명 확인 순서

Revka는 프로바이더를 구성할 때 고정된 세 단계 우선순위로 API 키를 확인합니다. 비어 있지 않은 첫 번째 값이 사용됩니다.

1. 명시적 설정 값 — config.toml의 api_key 키.

2. 프로바이더별 환경 변수 — 예: OPENROUTER_API_KEY, ANTHROPIC_API_KEY, OPENAI_API_KEY.

3. 일반 폴백 — REVKA_API_KEY, 이후 API_KEY.

따라서 프로바이더별 변수는 항상 일반 REVKA_API_KEY/API_KEY 폴백보다 우선합니다. 단, anthropic, openai, groq 프로바이더의 경우에는 프로바이더별 환경 변수(예: ANTHROPIC_API_KEY, OPENAI_API_KEY, GROQ_API_KEY)가 config.toml의 api_key 값보다 우선합니다. 이는 환경 변수가 우선해야 하는 멀티 프로바이더 및 커스텀 게이트웨이 설정을 지원하기 위함입니다. 그 외 프로바이더에서는 config.toml에 설정된 키가 환경 변수보다 우선합니다.

참고

Revka는 현재 작업 디렉터리의 .env 파일을 자동으로 로드하지 않습니다. 단, 워크스페이스 .env 파일(~/.revka/workspace/.env)은 시작 시 자동으로 로드되므로, 해당 파일에 키를 넣으면 export 없이도 적용됩니다. CWD .env의 경우 쉘에서 변수를 직접 export하거나, 파일을 직접 source하거나, direnv와 같은 도구를 사용하세요.

프로바이더별 키 변수

각 프로바이더에는 선택적으로 사용할 수 있는 키 변수가 있습니다. 주요 항목은 다음과 같습니다.

프로바이더	키 환경 변수	키 접두사
openrouter	OPENROUTER_API_KEY	sk-or-
anthropic	ANTHROPIC_API_KEY (또는 ANTHROPIC_OAUTH_TOKEN)	sk-ant-
openai	OPENAI_API_KEY	sk-
groq	GROQ_API_KEY	gsk_
perplexity	PERPLEXITY_API_KEY	pplx-
xai	XAI_API_KEY	xai-

전체 프로바이더 목록과 키 변수는 프로바이더 카탈로그를 참고하세요.

API 키 불일치 감지

프로바이더를 구성하기 전에 Revka는 확인된 키의 접두사가 선택된 프로바이더와 일치하는지 검사하고, 명확히 불일치할 경우 읽기 쉬운 오류를 발생시킵니다. 예를 들어 openai 프로바이더에 sk-ant- 키를 사용한 경우가 이에 해당합니다. 이는 키를 혼동하는 일반적인 복사·붙여넣기 실수를 위한 디버깅 보조 기능입니다. custom: 프로바이더와 커스텀 api_url이 설정된 프로바이더에서는 이 검사가 건너뜁니다.

팁

키가 업스트림 API 오류 응답 본문에 노출될 경우, Revka는 토큰과 유사한 패턴(sk-, ghp_ 등)을 자동으로 삭제하고 [REDACTED]로 표시합니다. 프로바이더 오류는 500자로 잘려 표시됩니다.

REVKA_PROVIDER로 프로바이더 재정의

config.toml을 수정하지 않고도 환경 변수를 사용해 실행 시 프로바이더를 전환할 수 있습니다. 두 가지 변수가 있으며 우선순위가 다릅니다.

변수	동작
REVKA_PROVIDER	비어 있지 않으면 항상 설정보다 우선합니다.
PROVIDER	레거시 폴백 — 설정의 default_provider가 설정되지 않았거나 여전히 openrouter인 경우에만 적용됩니다.

설정에 관계없이 프로바이더를 강제 지정하려면 REVKA_PROVIDER를 사용하세요.

REVKA_PROVIDER=anthropic revka agent -m "Hello"
REVKA_PROVIDER=ollama revka agent --model llama3.2 -m "Hello"

주의

환경 변수만 사용하던 설정에서 컨테이너로 마이그레이션하는 경우 주의가 필요합니다. Docker 환경에서 PROVIDER=openrouter를 설정해도 config.toml에 명시적으로 설정된 비기본 프로바이더를 재정의하지 않습니다. 강제로 재정의해야 한다면 REVKA_PROVIDER를 사용하세요.

프로바이더 환경 변수 재정의

프로바이더 자체 외에도, 핵심 런타임 설정 전체를 환경 변수로 지정할 수 있습니다. 이 변수들은 시작 시 해당 config.toml 키를 재정의합니다.

변수	매핑되는 설정 키
REVKA_PROVIDER / PROVIDER (레거시)	default_provider
REVKA_MODEL	default_model
REVKA_API_KEY / API_KEY	api_key
REVKA_TEMPERATURE	default_temperature
REVKA_EXTRA_HEADERS	extra_headers (형식: Key:Value,Key2:Value2)
REVKA_REASONING_ENABLED / REASONING_ENABLED	확장 사고 모드

환경 변수만으로 완전히 구성한 실행 예시는 다음과 같습니다.

export REVKA_PROVIDER="anthropic"
export REVKA_MODEL="claude-sonnet-4-5-20250929"
export ANTHROPIC_API_KEY="sk-ant-..."
revka agent -m "Configured entirely from the environment"

설정 확인

본격적인 개발 전에 프로바이더와 키가 정상 작동하는지 확인하세요.

revka doctor models                       # 설정된 모든 프로바이더 점검
revka doctor models --provider anthropic  # 단일 프로바이더 점검
revka models list                         # 현재 프로바이더의 캐시된 모델 목록
revka models refresh                      # 프로바이더에서 모델 카탈로그 갱신
revka models status                       # 현재 프로바이더와 모델 표시

revka doctor models는 프로바이더별로 ok / auth-error / error 상태를 포함한 연결 매트릭스를 출력합니다. 잘못된 키나 접근 불가능한 엔드포인트를 가장 빠르게 파악할 수 있는 방법입니다. 전체 revka doctor 실행 시 프로바이더, 모델, 키 설정도 함께 검증됩니다. 전체 보고서는 진단을 참고하세요.

다음 단계

프로바이더 카탈로그 지원되는 모든 프로바이더의 ID, 별칭, 기본 URL, 환경 변수, 기능을 확인하세요.

클라우드 API 프로바이더 Gemini, AWS Bedrock, Azure OpenAI 설정 방법.

로컬 & 커스텀 엔드포인트 Ollama, llama.cpp, vLLM 및 custom: / anthropic-custom: 접두사 사용법.

OAuth & 구독 프로바이더 Codex, Gemini CLI, Claude Code, Copilot 및 OAuth 로그인.

라우팅, 안정성 & 튜닝 폴백 체인, 모델 라우팅 힌트, 타임아웃, max-tokens 설정.

에이전트와 채팅 CLI에서 대화형 세션과 단발성 쿼리를 실행하는 방법.