비용 추적 및 예산

Revka는 모든 LLM 호출의 예상 USD 비용을 추적하고, 이를 추가 전용 원장에 기록하며, 요청이 전송되기 전에 일별 및 월별 지출 한도를 적용할 수 있습니다. 이 페이지에서는 토큰 사용량 원장, [cost] 설정 섹션과 해당 가격 테이블, 세 가지 적용 모드(warn, block, route_down), 그리고 원장을 읽고 쓰는 게이트웨이 엔드포인트를 설명합니다.

에이전트의 지출에 상한선을 설정하거나, 예산 초과 전에 경고를 받거나, 사이드카/오퍼레이터 토큰 사용량을 단일 통합 지출 합계에 반영하려는 경우 이 페이지를 참조하십시오. 지출을 조회하는 방법(설정이 아닌)은 읽기 전용 비용 대시보드 페이지를 참조하십시오.

비용 추적 방식

에이전트가 모델을 호출할 때마다 Revka는 토큰 수와 설정된 모델별 가격을 기반으로 호출 비용을 계산하고, <workspace>/state/costs.jsonl 경로의 JSONL 원장에 레코드를 기록합니다. 파일은 처음 사용 시 자동으로 생성됩니다. 이전 버전의 .revka/costs.db가 있는 경우 첫 실행 시 JSONL 원장으로 마이그레이션됩니다.

호출당 비용은 다음과 같이 계산됩니다:

cost_usd = (input_tokens / 1_000_000) * input_price
         + (output_tokens / 1_000_000) * output_price

가격은 100만 토큰당 USD 단위이며, 아래의 [cost.prices] 테이블에서 가져옵니다. 모델에 일치하는 가격 항목이 없더라도 호출은 기록되며, 비용은 0.0으로 기록되고 디버그 로그가 남습니다. 즉, 토큰 수는 손실 없이 항상 기록됩니다. 원장의 잘못된 형식 줄은 읽기를 중단하지 않고 경고와 함께 건너뜁니다.

트래커는 세 가지 롤링 윈도우를 유지합니다:

• 세션 — 현재 데몬 프로세스 수명 동안의 집계. by_model, by_agent, by_source 분류는 이 윈도우만 반영합니다.
• 일별 — 전체 원장에서 재계산되는 오늘 하루 롤링 집계.
• 월별 — 전체 원장에서 재계산되는 해당 달력 월 집계.

게이트웨이, 채널, 수집된 사이드카 사용량이 모두 단일 프로세스 전역 트래커를 공유하므로, 모든 경로가 동일한 예산을 확인하고 업데이트합니다.

참고

예산은 세션이 아닌 프로세스 단위로 적용됩니다. 일별 및 월별 합계는 날짜 경계를 넘을 때 원장에서 재계산되므로, 장기 실행 데몬은 자정 및 각 월 시작 시 올바르게 리셋됩니다.

[cost] 섹션 설정

비용 추적은 ~/.revka/config.toml의 [cost] 아래에서 완전히 설정되며, 두 하위 테이블인 [cost.enforcement]와 [cost.prices]가 함께 사용됩니다.

[cost]
enabled = true
daily_limit_usd = 10.00      # default 10.00
monthly_limit_usd = 100.00   # default 100.00
warn_at_percent = 80         # default 80 — warn at 80% of the limit
allow_override = false       # default false

[cost.enforcement]
mode = "warn"                # "warn" | "block" | "route_down"
route_down_model = "fast"    # model hint to fall back to in route_down mode
reserve_percent = 10         # reserve 10% of the budget for critical ops

[cost.prices]
# USD per 1M tokens, { input, output }
"claude-sonnet-4-20250514" = { input = 3.0, output = 15.0 }
"gpt-4o" = { input = 2.5, output = 10.0 }
"gpt-4o-mini" = { input = 0.15, output = 0.60 }

[cost] 키

키	타입	기본값	설명
enabled	bool	true	마스터 스위치. false이면 레코드가 기록되지 않고, 예산이 확인되지 않으며, GET /api/cost는 0으로 초기화된 요약을 반환합니다.
daily_limit_usd	float	10.00	일별 지출 상한선 (USD).
monthly_limit_usd	float	100.00	월별(달력 월) 지출 상한선 (USD).
warn_at_percent	int (0–100)	80	예상 지출이 한도의 해당 비율을 초과하면 경고를 표시합니다.
allow_override	bool	false	--override 플래그로 하드 한도를 우회하는 것을 허용합니다.

[cost.enforcement] 키

키	타입	기본값	설명
mode	string	"warn"	한도 도달 시 동작: warn, block, 또는 route_down (아래 참조).
route_down_model	string?	미설정	mode = "route_down"이고 예산이 초과될 때 폴백할 모델 힌트.
reserve_percent	int (0–100)	10	중요한 작업을 위해 예산의 해당 비율을 예약합니다.

[cost.prices] — 가격 테이블

각 항목은 모델 키를 100만 토큰당 USD 단위의 { input, output } 가격에 매핑합니다. 가격 조회는 퍼지 방식으로 다음 순서로 시도합니다:

1. 모델 ID 정확 일치 (gpt-4o).
2. provider/model 일치 (openai/gpt-4o).
3. 마지막 / 이후의 접미사 (예: anthropic/claude-sonnet-4는 claude-sonnet-4 키와 일치).
4. 끝에 붙은 숫자 날짜 세그먼트를 제거한 후 접두사 일치.

이를 통해 일반적으로 테이블을 순수 모델 이름으로 키 설정해도, 프로바이더가 ID에 접두사를 붙이는 방식과 관계없이 일치합니다. 일치하는 항목이 없는 모델은 비용 0으로 기록됩니다.

주의

일별/월별 한도를 설정했지만 [cost.prices]를 비워두면, 모든 호출이 cost_usd = 0.0으로 기록되어 절대 예산에 도달하지 않습니다. 한도는 실제로 사용하는 모델의 가격이 설정된 경우에만 작동합니다. 라우팅 설정에 있는 모든 모델에 대해 [cost.prices]를 채워 넣으십시오.

적용 모드

각 LLM 호출 전에 트래커는 현재 지출 + 예상 비용을 일별 및 월별 한도와 비교하여 세 가지 상태 중 하나를 반환합니다: 허용, 경고 (임계값을 초과했지만 호출 진행), 초과 (한도를 넘을 것으로 예상). 경고와 초과 확인 모두 현재 지출이 아닌 예상 합계를 기준으로 비교합니다. mode는 한도 초과 시의 동작을 결정합니다.

warn

mode = "warn" (기본값)은 절대 차단하지 않습니다. 예상 지출이 한도의 warn_at_percent를 초과하면 경고가 기록되고 요청은 계속 진행됩니다. 하드 한도를 초과하게 되더라도 마찬가지로 로그만 남기고 호출은 진행됩니다. 이 모드는 강제 적용 전에 지출을 관찰하고 한도를 조정하는 데 사용하십시오.

[cost.enforcement]
mode = "warn"

block

mode = "block"은 일별 또는 월별 한도를 초과할 요청을 거부합니다. 에이전트는 호출을 수행하는 대신 예산 초과 오류를 받습니다. 이는 엄격한 가드레일로, 예산이 소진되면 아무것도 실행되지 않습니다.

[cost.enforcement]
mode = "block"

긴급한 중요 작업을 위해 --override 플래그로 오퍼레이터 탈출구를 원한다면 allow_override = true와 함께 사용하십시오.

route_down

mode = "route_down"은 에이전트를 계속 실행하되 다운그레이드합니다: 예산이 초과되면 호출을 차단하는 대신 route_down_model에 지정된 더 저렴한 모델로 전환합니다. 이는 품질과 연속성을 교환하는 방식으로, 에이전트가 중단되지 않고 예산 모델에서 계속 응답합니다.

[cost.enforcement]
mode = "route_down"
route_down_model = "fast"   # a model hint defined in [[model_routes]]

폴백이 구체적인 프로바이더 + 모델로 해석되도록 대상을 모델 라우트 힌트로 정의하십시오.

참고

reserve_percent (기본값 10)는 중요한 작업을 위해 예산의 일부를 예약해 두므로, 명목 한도보다 약간 일찍 적용이 시작됩니다. 음수 또는 NaN 비용 추정값은 모드에 관계없이 항상 오류로 거부됩니다.

게이트웨이 비용 엔드포인트

게이트웨이는 두 가지 비용 엔드포인트를 제공합니다. 하나는 요약을 읽는 엔드포인트이고, 다른 하나는 사이드카가 사용량을 수집하기 위한 엔드포인트입니다.

비용 요약 읽기

GET /api/cost

인증이 필요 없습니다. 이는 읽기 전용 오퍼레이터 텔레메트리입니다. CostSummary를 반환합니다:

{
  "cost": {
    "session_cost_usd": 0.4213,
    "daily_cost_usd": 1.8740,
    "monthly_cost_usd": 22.5106,
    "total_tokens": 1542300,
    "request_count": 318,
    "by_model": {
      "anthropic/claude-sonnet-4-6": {
        "model": "anthropic/claude-sonnet-4-6",
        "cost_usd": 0.4013,
        "total_tokens": 1410200,
        "request_count": 286
      }
    },
    "by_agent": {},
    "by_source": {
      "gateway": { "source": "gateway", "cost_usd": 0.30, "total_tokens": 980000, "request_count": 210 }
    },
    "budget": {
      "enabled": true,
      "daily_limit_usd": 10.0,
      "monthly_limit_usd": 100.0,
      "warn_at_percent": 80,
      "daily_remaining_usd": 8.126,
      "monthly_remaining_usd": 77.489,
      "daily_percent": 18.74,
      "monthly_percent": 22.51,
      "state": "ok"
    }
  }
}

필드	설명
session_cost_usd / daily_cost_usd / monthly_cost_usd	각 롤링 윈도우의 지출.
total_tokens / request_count	세션 윈도우의 토큰 및 호출 합계.
by_model	세션에 대한 모델별 ModelStats (비용, 토큰, 요청 수).
by_agent	사이드카/오퍼레이터 agent_id별 분류, 중첩된 by_model 포함.
by_source	gateway, channel, sidecar, 또는 runtime (태그 없는 레코드) 기준의 출처별 분류.
budget	BudgetStatus: 한도, 잔여량, 사용률, state (ok / warning / exceeded / disabled).

추적이 비활성화되면 엔드포인트는 오류 대신 budget.state = "disabled"로 설정된 0 초기화 요약을 반환합니다.

사이드카 사용량 수집

외부 사이드카(오퍼레이터 MCP, 에이전트 서브프로세스)는 전체 시스템의 지출이 통합되도록 토큰 사용량을 동일한 전역 원장으로 전송합니다:

POST /api/cost/usage
X-Revka-Service-Token: <service_token>
Content-Type: application/json

{
  "model": "gpt-4o",
  "provider": "openai",
  "input_tokens": 1000,
  "output_tokens": 250,
  "source": "sidecar",
  "agent_id": "my-agent",
  "agent_title": "My Agent"
}

model만 필수이며, provider, input_tokens, output_tokens, source, agent_id, agent_title은 선택 사항입니다. 비용은 내부 호출과 동일하게 [cost.prices]에서 계산됩니다. 성공 시:

{ "recorded": true, "usage": { "model": "gpt-4o", "input_tokens": 1000, "output_tokens": 250, "total_tokens": 1250, "cost_usd": 0.005, "timestamp": "2026-06-18T09:00:00Z" } }

비용 추적이 비활성화된 경우 { "recorded": false, "reason": "cost tracking disabled" }를 반환합니다.

주의

POST /api/cost/usage는 X-Revka-Service-Token 헤더가 필수입니다. 이는 무단 비용 원장 조작을 방지합니다. GET /api/cost는 텔레메트리만 읽으므로 의도적으로 인증이 없습니다. source를 생략하면 기본값은 "sidecar"입니다.

오퍼레이터 측 예산 도구

오퍼레이터 MCP는 동일한 [cost] 설정을 읽고 멀티 에이전트 워크플로우에 예산 가시성을 제공합니다:

• get_budget_status() — 설정된 한도에 대한 세션/일별/월별 지출을 모델별 분류와 함께 반환합니다. 게이트웨이 엔드포인트가 보고하는 것과 동일한 수치입니다.
• system_dashboard(include_costs=...) — 비용, 에이전트, 워크플로우, 상태 보기를 결합한 단일 호출 스냅샷.
• 워크플로우 max_cost_usd — 선언형 워크플로우의 실행별 비용 상한선. 전역 일별/월별 예산과 독립적으로, 실행 비용이 상한을 초과하면 해당 실행이 중단됩니다. 워크플로우 & SOP 개요를 참조하십시오.

max_cost_usd는 개별 팬아웃 또는 정제 루프의 비용을 제한하는 데 사용하고, [cost] 한도는 전체 지출을 제한하는 데 사용하십시오.

설정 확인

1. 가격 및 한도를 추가합니다. 라우팅하는 모델에 대해 [cost.prices]를 채우고, 빠른 적용 테스트를 위해 낮은 daily_limit_usd를 설정합니다.

2. 몇 가지 요청을 실행한 후 원장 요약을 읽습니다:

   curl http://127.0.0.1:42617/api/cost

3. 수치가 변하는지 확인합니다. daily_cost_usd와 budget.daily_percent가 증가해야 합니다. 실제 호출 후에도 0에 머무른다면 [cost.prices] 키가 실제 사용 중인 모델 ID와 일치하지 않는 것입니다. 위의 퍼지 매칭 규칙을 확인하십시오.

4. 적용을 테스트합니다. 아주 낮은 한도로 mode = "block"을 설정하고, 한도를 초과할 것으로 예상되면 요청이 거부되는지 확인합니다.

관련 페이지

크론, 비용 및 설정 페이지 모델별 막대 차트와 지출 윈도우가 포함된 읽기 전용 /cost 대시보드.

비용, 감사, ClawHub 및 자격 증명 API 전체 게이트웨이 API 참조의 /api/cost 엔드포인트.

관찰 가능성 및 추적 Prometheus 토큰 메트릭, OTel 비용 속성, 옵저버 파이프라인.

라우팅, 안정성 및 튜닝 route_down 모드가 폴백할 모델 라우트 힌트를 정의합니다.

설정 개요 [cost]를 포함한 모든 config.toml 섹션 및 키.

에이전트 생성 및 조율 오퍼레이터 MCP 예산 도구와 워크플로우 max_cost_usd 상한선.