---
read_when:
    - 유료 API를 호출할 수 있는 기능이 무엇인지 파악하고 싶습니다
    - 키, 비용, 그리고 사용량 가시성을 감사해야 합니다
    - '`/status` 또는 `/usage` 비용 보고를 설명하고 있습니다'
summary: 무엇이 비용을 발생시킬 수 있는지, 어떤 키가 사용되는지, 그리고 사용량을 확인하는 방법을 감사하세요
title: API 사용량 및 비용
x-i18n:
    generated_at: "2026-04-13T08:50:33Z"
    model: gpt-5.4
    provider: openai
    source_hash: f5077e74d38ef781ac7a72603e9f9e3829a628b95c5a9967915ab0f321565429
    source_path: reference/api-usage-costs.md
    workflow: 15
---

# API 사용량 및 비용

이 문서는 **API 키를 호출할 수 있는 기능**과 해당 비용이 어디에 표시되는지를 정리합니다. 이 문서는
provider 사용량이나 유료 API 호출을 발생시킬 수 있는 OpenClaw 기능에 초점을 맞춥니다.

## 비용이 표시되는 위치 (채팅 + CLI)

**세션별 비용 스냅샷**

- `/status`는 현재 세션 모델, 컨텍스트 사용량, 마지막 응답 토큰을 표시합니다.
- 모델이 **API 키 인증**을 사용하는 경우 `/status`는 마지막 응답에 대한 **추정 비용**도 표시합니다.
- 라이브 세션 메타데이터가 충분하지 않으면 `/status`는 최신 transcript usage
  항목에서 토큰/캐시 카운터와 활성 runtime 모델 레이블을 복구할 수 있습니다. 기존의 0이 아닌 라이브 값이 여전히 우선하며, 저장된 총계가 없거나 더 작을 때는 prompt 크기의 transcript 총계가 우선될 수 있습니다.

**메시지별 비용 푸터**

- `/usage full`은 **추정 비용**(API 키 전용)을 포함한 사용량 푸터를 모든 응답에 추가합니다.
- `/usage tokens`는 토큰만 표시합니다. subscription 스타일 OAuth/토큰 및 CLI 흐름에서는 달러 비용을 숨깁니다.
- Gemini CLI 참고: CLI가 JSON 출력을 반환하면 OpenClaw는 `stats`에서 사용량을 읽고, `stats.cached`를 `cacheRead`로 정규화하며, 필요할 때 `stats.input_tokens - stats.cached`에서 입력 토큰을 계산합니다.

Anthropic 참고: Anthropic 직원이 OpenClaw 스타일 Claude CLI 사용이 다시 허용된다고 알려왔으므로, Anthropic이 새 정책을 발표하지 않는 한 OpenClaw는 Claude CLI 재사용 및 `claude -p` 사용을 이 통합에서 허용된 것으로 취급합니다.
Anthropic은 여전히 OpenClaw가 `/usage full`에 표시할 수 있는 메시지별 달러 추정치를 제공하지 않습니다.

**CLI 사용량 기간(provider 할당량)**

- `openclaw status --usage`와 `openclaw channels list`는 provider **사용량 기간**
  (메시지별 비용이 아닌 할당량 스냅샷)을 표시합니다.
- 사람이 읽는 출력은 provider 전반에 걸쳐 `X% 남음` 형식으로 정규화됩니다.
- 현재 사용량 기간 provider: Anthropic, GitHub Copilot, Gemini CLI,
  OpenAI Codex, MiniMax, Xiaomi, z.ai.
- MiniMax 참고: 원시 `usage_percent` / `usagePercent` 필드는 남은 할당량을 의미하므로 OpenClaw는 표시 전에 이를 반전합니다. 개수 기반 필드가 있으면 여전히 그것이 우선합니다. provider가 `model_remains`를 반환하면 OpenClaw는 chat-model 항목을 우선하고, 필요하면 타임스탬프에서 기간 레이블을 계산하며, plan 레이블에 모델 이름을 포함합니다.
- 해당 할당량 기간의 usage 인증은 가능하면 provider별 hook에서 가져오며, 그렇지 않으면 OpenClaw는 auth profile, env 또는 config에서 일치하는 OAuth/API 키 자격 증명으로 대체합니다.

자세한 내용과 예시는 [토큰 사용량 및 비용](/ko/reference/token-use)을 참조하세요.

## 키가 검색되는 방식

OpenClaw는 다음 위치에서 자격 증명을 가져올 수 있습니다.

- **Auth profile** (에이전트별, `auth-profiles.json`에 저장).
- **환경 변수** (예: `OPENAI_API_KEY`, `BRAVE_API_KEY`, `FIRECRAWL_API_KEY`).
- **Config** (`models.providers.*.apiKey`, `plugins.entries.*.config.webSearch.apiKey`,
  `plugins.entries.firecrawl.config.webFetch.apiKey`, `memorySearch.*`,
  `talk.providers.*.apiKey`).
- **Skills** (`skills.entries.<name>.apiKey`) — 키를 skill 프로세스 env로 내보낼 수 있습니다.

## 키 비용이 발생할 수 있는 기능

### 1) 코어 모델 응답 (채팅 + 도구)

모든 응답 또는 도구 호출은 **현재 모델 provider**(OpenAI, Anthropic 등)를 사용합니다. 이것이
사용량과 비용의 주요 원인입니다.

여기에는 OpenClaw의 로컬 UI 바깥에서 여전히 과금되는 subscription 스타일 hosted provider도 포함되며, 예를 들어 **OpenAI Codex**, **Alibaba Cloud Model Studio
Coding Plan**, **MiniMax Coding Plan**, **Z.AI / GLM Coding Plan**, 그리고
**Extra Usage**가 활성화된 Anthropic의 OpenClaw Claude-login 경로가 있습니다.

표시 방식은 [Models](/ko/providers/models)의 가격 설정과 [토큰 사용량 및 비용](/ko/reference/token-use)을 참조하세요.

### 2) 미디어 이해 (오디오/이미지/비디오)

수신된 미디어는 응답이 실행되기 전에 요약/전사될 수 있습니다. 이 과정에서 모델/provider API를 사용합니다.

- 오디오: OpenAI / Groq / Deepgram / Google / Mistral.
- 이미지: OpenAI / OpenRouter / Anthropic / Google / MiniMax / Moonshot / Qwen / Z.AI.
- 비디오: Google / Qwen / Moonshot.

[미디어 이해](/ko/nodes/media-understanding)를 참조하세요.

### 3) 이미지 및 비디오 생성

공유 생성 기능도 provider 키 비용을 발생시킬 수 있습니다.

- 이미지 생성: OpenAI / Google / fal / MiniMax
- 비디오 생성: Qwen

`agents.defaults.imageGenerationModel`이 설정되지 않은 경우
이미지 생성은 auth 기반 provider 기본값을 추론할 수 있습니다. 현재 비디오 생성은
`qwen/wan2.6-t2v`와 같은 명시적인 `agents.defaults.videoGenerationModel`이 필요합니다.

[이미지 생성](/ko/tools/image-generation), [Qwen Cloud](/ko/providers/qwen),
[Models](/ko/concepts/models)를 참조하세요.

### 4) 메모리 임베딩 + 시맨틱 검색

시맨틱 메모리 검색은 원격 provider로 구성된 경우 **임베딩 API**를 사용합니다.

- `memorySearch.provider = "openai"` → OpenAI 임베딩
- `memorySearch.provider = "gemini"` → Gemini 임베딩
- `memorySearch.provider = "voyage"` → Voyage 임베딩
- `memorySearch.provider = "mistral"` → Mistral 임베딩
- `memorySearch.provider = "lmstudio"` → LM Studio 임베딩 (로컬/셀프 호스팅)
- `memorySearch.provider = "ollama"` → Ollama 임베딩 (로컬/셀프 호스팅, 일반적으로 hosted API 과금 없음)
- 로컬 임베딩이 실패할 경우 선택적으로 원격 provider로 대체 가능

`memorySearch.provider = "local"`로 설정하면 로컬로 유지할 수 있습니다(API 사용 없음).

[Memory](/ko/concepts/memory)를 참조하세요.

### 5) 웹 검색 도구

`web_search`는 provider에 따라 사용 요금이 발생할 수 있습니다.

- **Brave Search API**: `BRAVE_API_KEY` 또는 `plugins.entries.brave.config.webSearch.apiKey`
- **Exa**: `EXA_API_KEY` 또는 `plugins.entries.exa.config.webSearch.apiKey`
- **Firecrawl**: `FIRECRAWL_API_KEY` 또는 `plugins.entries.firecrawl.config.webSearch.apiKey`
- **Gemini (Google Search)**: `GEMINI_API_KEY` 또는 `plugins.entries.google.config.webSearch.apiKey`
- **Grok (xAI)**: `XAI_API_KEY` 또는 `plugins.entries.xai.config.webSearch.apiKey`
- **Kimi (Moonshot)**: `KIMI_API_KEY`, `MOONSHOT_API_KEY`, 또는 `plugins.entries.moonshot.config.webSearch.apiKey`
- **MiniMax Search**: `MINIMAX_CODE_PLAN_KEY`, `MINIMAX_CODING_API_KEY`, `MINIMAX_API_KEY`, 또는 `plugins.entries.minimax.config.webSearch.apiKey`
- **Ollama Web Search**: 기본적으로 키가 필요 없지만, 접근 가능한 Ollama 호스트와 `ollama signin`이 필요합니다. 호스트에 인증이 필요한 경우 일반 Ollama provider bearer auth를 재사용할 수도 있습니다.
- **Perplexity Search API**: `PERPLEXITY_API_KEY`, `OPENROUTER_API_KEY`, 또는 `plugins.entries.perplexity.config.webSearch.apiKey`
- **Tavily**: `TAVILY_API_KEY` 또는 `plugins.entries.tavily.config.webSearch.apiKey`
- **DuckDuckGo**: 키 없는 대체 수단(API 과금 없음, 하지만 비공식적이며 HTML 기반)
- **SearXNG**: `SEARXNG_BASE_URL` 또는 `plugins.entries.searxng.config.webSearch.baseUrl` (키 없음/셀프 호스팅, hosted API 과금 없음)

레거시 `tools.web.search.*` provider 경로도 임시 호환성 shim을 통해 여전히 로드되지만, 더 이상 권장되는 config 표면은 아닙니다.

**Brave Search 무료 크레딧:** 각 Brave 요금제에는 매월 갱신되는
\$5의 무료 크레딧이 포함됩니다. Search 요금제 비용은 요청 1,000건당 \$5이므로, 이 크레딧으로
매월 1,000건의 요청을 무료로 처리할 수 있습니다. 예상치 못한 과금을 방지하려면 Brave 대시보드에서 사용 한도를 설정하세요.

[웹 도구](/ko/tools/web)를 참조하세요.

### 5) 웹 가져오기 도구 (Firecrawl)

`web_fetch`는 API 키가 있으면 **Firecrawl**을 호출할 수 있습니다.

- `FIRECRAWL_API_KEY` 또는 `plugins.entries.firecrawl.config.webFetch.apiKey`

Firecrawl이 구성되지 않았으면 이 도구는 직접 fetch + readability로 대체됩니다(유료 API 없음).

[웹 도구](/ko/tools/web)를 참조하세요.

### 6) Provider 사용량 스냅샷 (상태/헬스)

일부 상태 명령은 할당량 기간이나 인증 상태를 표시하기 위해 **provider 사용량 엔드포인트**를 호출합니다.
이들은 일반적으로 호출량이 적지만 여전히 provider API를 호출합니다.

- `openclaw status --usage`
- `openclaw models status --json`

[Models CLI](/cli/models)를 참조하세요.

### 7) Compaction 안전장치 요약

Compaction 안전장치는 세션 기록을 **현재 모델**로 요약할 수 있으며,
실행 시 provider API를 호출합니다.

[세션 관리 + Compaction](/ko/reference/session-management-compaction)을 참조하세요.

### 8) 모델 스캔 / 프로브

`openclaw models scan`은 OpenRouter 모델을 프로브할 수 있으며,
프로브가 활성화되면 `OPENROUTER_API_KEY`를 사용합니다.

[Models CLI](/cli/models)를 참조하세요.

### 9) Talk (음성)

Talk 모드는 구성된 경우 **ElevenLabs**를 호출할 수 있습니다.

- `ELEVENLABS_API_KEY` 또는 `talk.providers.elevenlabs.apiKey`

[Talk mode](/ko/nodes/talk)를 참조하세요.

### 10) Skills (서드파티 API)

Skills는 `skills.entries.<name>.apiKey`에 `apiKey`를 저장할 수 있습니다. skill이 해당 키를 외부
API에 사용하면, 그 skill의 provider에 따라 비용이 발생할 수 있습니다.

[Skills](/ko/tools/skills)를 참조하세요.
