From c45a5f077e08b4e6ef96b5948fd5acebe1523a95 Mon Sep 17 00:00:00 2001 From: "openclaw-docs-i18n[bot]" Date: Mon, 13 Apr 2026 08:52:39 +0000 Subject: [PATCH] chore(i18n): refresh ko translations --- docs/ko/concepts/model-providers.md | 625 +++++++++++++++++---------- docs/ko/gateway/local-models.md | 83 ++-- docs/ko/providers/index.md | 31 +- docs/ko/providers/lmstudio.md | 163 +++++++ docs/ko/reference/api-usage-costs.md | 149 +++---- 5 files changed, 691 insertions(+), 360 deletions(-) create mode 100644 docs/ko/providers/lmstudio.md diff --git a/docs/ko/concepts/model-providers.md b/docs/ko/concepts/model-providers.md index ff8a1b245..c86a96962 100644 --- a/docs/ko/concepts/model-providers.md +++ b/docs/ko/concepts/model-providers.md @@ -1,148 +1,273 @@ --- read_when: - - 제공자별 모델 설정 참조가 필요합니다 - - 모델 제공자를 위한 예제 구성이나 CLI 온보딩 명령이 필요합니다 -summary: 예제 구성과 CLI 흐름이 포함된 모델 제공자 개요 -title: 모델 제공자 + - 공급자별 모델 설정 참조가 필요합니다 + - 모델 공급자를 위한 예시 구성이나 CLI 온보딩 명령이 필요합니다 +summary: 모델 provider 개요와 예시 구성 + CLI 흐름 +title: 모델 Providers x-i18n: - generated_at: "2026-04-11T02:44:20Z" + generated_at: "2026-04-13T08:50:36Z" model: gpt-5.4 provider: openai - source_hash: 910ea7895e74c03910757d9d3e02825754b779b204eca7275b28422647ed0151 + source_hash: 66ba688c4b4366eec07667571e835d4cfeee684896e2ffae11d601b5fa0a4b98 source_path: concepts/model-providers.md workflow: 15 --- -# 모델 제공자 +# 모델 공급자 -이 페이지는 **LLM/모델 제공자**를 다룹니다(WhatsApp/Telegram 같은 채팅 채널이 아닙니다). -모델 선택 규칙은 [/concepts/models](/ko/concepts/models)를 참조하세요. +이 페이지는 **LLM/모델 공급자**를 다룹니다(WhatsApp/Telegram 같은 채팅 채널이 아님). +모델 선택 규칙은 [/concepts/models](/ko/concepts/models)을 참고하세요. ## 빠른 규칙 -- 모델 참조는 `provider/model` 형식을 사용합니다(예: `opencode/claude-opus-4-6`). +- 모델 참조는 `provider/model`을 사용합니다(예: `opencode/claude-opus-4-6`). - `agents.defaults.models`를 설정하면 허용 목록이 됩니다. - CLI 도우미: `openclaw onboard`, `openclaw models list`, `openclaw models set `. -- 대체 런타임 규칙, 쿨다운 프로브, 세션 재정의 지속성은 [/concepts/model-failover](/ko/concepts/model-failover)에 문서화되어 있습니다. -- `models.providers.*.models[].contextWindow`는 네이티브 모델 메타데이터이고, `models.providers.*.models[].contextTokens`는 실제 런타임 상한입니다. -- 제공자 플러그인은 `registerProvider({ catalog })`를 통해 모델 카탈로그를 주입할 수 있습니다. OpenClaw는 `models.json`을 작성하기 전에 그 출력을 `models.providers`에 병합합니다. -- 제공자 매니페스트는 `providerAuthEnvVars`와 `providerAuthAliases`를 선언할 수 있으므로, 일반적인 환경 변수 기반 인증 프로브와 제공자 변형은 플러그인 런타임을 로드할 필요가 없습니다. 이제 남아 있는 코어 환경 변수 맵은 비플러그인/코어 제공자와 Anthropic API 키 우선 온보딩 같은 일부 일반 우선순위 사례에만 사용됩니다. -- 제공자 플러그인은 `normalizeModelId`, `normalizeTransport`, `normalizeConfig`, `applyNativeStreamingUsageCompat`, `resolveConfigApiKey`, `resolveSyntheticAuth`, `shouldDeferSyntheticProfileAuth`, `resolveDynamicModel`, `prepareDynamicModel`, `normalizeResolvedModel`, `contributeResolvedModelCompat`, `capabilities`, `normalizeToolSchemas`, `inspectToolSchemas`, `resolveReasoningOutputMode`, `prepareExtraParams`, `createStreamFn`, `wrapStreamFn`, `resolveTransportTurnState`, `resolveWebSocketSessionPolicy`, `createEmbeddingProvider`, `formatApiKey`, `refreshOAuth`, `buildAuthDoctorHint`, `matchesContextOverflowError`, `classifyFailoverReason`, `isCacheTtlEligible`, `buildMissingAuthMessage`, `suppressBuiltInModel`, `augmentModelCatalog`, `isBinaryThinking`, `supportsXHighThinking`, `resolveDefaultThinkingLevel`, `applyConfigDefaults`, `isModernModelRef`, `prepareRuntimeAuth`, `resolveUsageAuth`, `fetchUsageSnapshot`, `onModelSelected`를 통해 제공자 런타임 동작도 소유할 수 있습니다. -- 참고: 제공자 런타임 `capabilities`는 공유 러너 메타데이터(제공자 계열, 전사/도구 관련 특성, 전송/캐시 힌트)입니다. 이는 플러그인이 등록하는 항목(텍스트 추론, 음성 등)을 설명하는 [공개 capability 모델](/ko/plugins/architecture#public-capability-model)과는 다릅니다. -- 번들된 `codex` 제공자는 번들된 Codex 에이전트 하니스와 함께 연결됩니다. Codex 소유 로그인, 모델 검색, 네이티브 스레드 재개, 앱 서버 실행이 필요하면 `codex/gpt-*`를 사용하세요. 일반 `openai/gpt-*` 참조는 계속해서 OpenAI 제공자와 일반 OpenClaw 제공자 전송을 사용합니다. Codex 전용 배포에서는 `agents.defaults.embeddedHarness.fallback: "none"`으로 자동 PI 대체를 비활성화할 수 있습니다. 자세한 내용은 [Codex Harness](/ko/plugins/codex-harness)를 참조하세요. +- 폴백 런타임 규칙, 쿨다운 프로브, 세션 재정의 지속성은 [/concepts/model-failover](/ko/concepts/model-failover)에 문서화되어 있습니다. +- `models.providers.*.models[].contextWindow`는 기본 모델 메타데이터입니다. + `models.providers.*.models[].contextTokens`는 유효 런타임 상한입니다. +- 공급자 Plugin은 `registerProvider({ catalog })`를 통해 모델 카탈로그를 주입할 수 있습니다. + OpenClaw는 `models.json`을 쓰기 전에 그 출력을 `models.providers`에 병합합니다. +- 공급자 매니페스트는 `providerAuthEnvVars`와 + `providerAuthAliases`를 선언할 수 있으므로 일반적인 env 기반 인증 프로브와 공급자 변형이 + Plugin 런타임을 로드할 필요가 없습니다. 남아 있는 코어 env-var 맵은 이제 + 비-Plugin/코어 공급자와 Anthropic API-key-first 온보딩 같은 몇 가지 + 일반 우선순위 사례에만 사용됩니다. +- 공급자 Plugin은 다음을 통해 공급자 런타임 동작도 소유할 수 있습니다. + `normalizeModelId`, `normalizeTransport`, `normalizeConfig`, + `applyNativeStreamingUsageCompat`, `resolveConfigApiKey`, + `resolveSyntheticAuth`, `shouldDeferSyntheticProfileAuth`, + `resolveDynamicModel`, `prepareDynamicModel`, + `normalizeResolvedModel`, `contributeResolvedModelCompat`, + `capabilities`, `normalizeToolSchemas`, + `inspectToolSchemas`, `resolveReasoningOutputMode`, + `prepareExtraParams`, `createStreamFn`, `wrapStreamFn`, + `resolveTransportTurnState`, `resolveWebSocketSessionPolicy`, + `createEmbeddingProvider`, `formatApiKey`, `refreshOAuth`, + `buildAuthDoctorHint`, + `matchesContextOverflowError`, `classifyFailoverReason`, + `isCacheTtlEligible`, `buildMissingAuthMessage`, `suppressBuiltInModel`, + `augmentModelCatalog`, `isBinaryThinking`, `supportsXHighThinking`, + `resolveDefaultThinkingLevel`, `applyConfigDefaults`, `isModernModelRef`, + `prepareRuntimeAuth`, `resolveUsageAuth`, `fetchUsageSnapshot`, 그리고 + `onModelSelected`. +- 참고: 공급자 런타임 `capabilities`는 공유 러너 메타데이터입니다(공급자 + 계열, transcript/tooling 특이사항, transport/cache 힌트). 이것은 + Plugin이 무엇을 등록하는지 설명하는 [공개 capability 모델](/ko/plugins/architecture#public-capability-model)과는 다릅니다 + (텍스트 추론, speech 등). +- 번들된 `codex` 공급자는 번들된 Codex 에이전트 하네스와 페어링됩니다. + Codex 소유 로그인, 모델 탐색, 네이티브 + 스레드 재개, 앱 서버 실행을 원하면 `codex/gpt-*`를 사용하세요. 일반 `openai/gpt-*` 참조는 계속 + OpenAI 공급자와 일반 OpenClaw 공급자 transport를 사용합니다. + Codex 전용 배포는 자동 PI 폴백을 + `agents.defaults.embeddedHarness.fallback: "none"`으로 비활성화할 수 있습니다. 자세한 내용은 + [Codex Harness](/ko/plugins/codex-harness)를 참고하세요. -## 플러그인 소유 제공자 동작 +## Plugin 소유 공급자 동작 -이제 제공자 플러그인은 대부분의 제공자별 로직을 소유할 수 있으며, OpenClaw는 일반 추론 루프를 유지합니다. +이제 공급자 Plugin이 대부분의 공급자별 로직을 소유할 수 있으며, OpenClaw는 +일반 추론 루프를 유지합니다. 일반적인 분리는 다음과 같습니다. -- `auth[].run` / `auth[].runNonInteractive`: 제공자가 `openclaw onboard`, `openclaw models auth`, 헤드리스 설정을 위한 온보딩/로그인 흐름을 소유 -- `wizard.setup` / `wizard.modelPicker`: 제공자가 인증 선택 라벨, 레거시 별칭, 온보딩 허용 목록 힌트, 온보딩/모델 선택기에 표시되는 설정 항목을 소유 -- `catalog`: 제공자가 `models.providers`에 표시됨 -- `normalizeModelId`: 제공자가 조회 또는 정규화 전에 레거시/프리뷰 모델 ID를 정규화 -- `normalizeTransport`: 제공자가 일반 모델 조립 전에 전송 계열 `api` / `baseUrl`을 정규화합니다. OpenClaw는 먼저 일치하는 제공자를 확인한 다음, 실제로 전송을 변경하는 플러그인을 찾을 때까지 다른 훅 지원 제공자 플러그인을 확인합니다. -- `normalizeConfig`: 제공자가 런타임이 사용하기 전에 `models.providers.` 구성을 정규화합니다. OpenClaw는 먼저 일치하는 제공자를 확인한 다음, 실제로 구성을 변경하는 플러그인을 찾을 때까지 다른 훅 지원 제공자 플러그인을 확인합니다. 어떤 제공자 훅도 구성을 다시 쓰지 않으면, 번들된 Google 계열 도우미가 계속해서 지원되는 Google 제공자 항목을 정규화합니다. -- `applyNativeStreamingUsageCompat`: 제공자가 구성 제공자에 대해 엔드포인트 기반 네이티브 스트리밍 사용량 호환성 재작성을 적용 -- `resolveConfigApiKey`: 제공자가 전체 런타임 인증 로딩을 강제하지 않고도 구성 제공자에 대한 환경 변수 마커 인증을 해석합니다. `amazon-bedrock`도 여기에 내장된 AWS 환경 변수 마커 해석기를 갖고 있지만, Bedrock 런타임 인증은 AWS SDK 기본 체인을 사용합니다. -- `resolveSyntheticAuth`: 제공자가 평문 비밀을 저장하지 않고도 로컬/셀프 호스팅 또는 기타 구성 기반 인증 사용 가능 여부를 노출할 수 있음 -- `shouldDeferSyntheticProfileAuth`: 제공자가 저장된 합성 프로필 플레이스홀더를 환경 변수/구성 기반 인증보다 낮은 우선순위로 표시할 수 있음 -- `resolveDynamicModel`: 제공자가 아직 로컬 정적 카탈로그에 없는 모델 ID를 허용 -- `prepareDynamicModel`: 제공자가 동적 해석 재시도 전에 메타데이터 새로 고침이 필요함 -- `normalizeResolvedModel`: 제공자가 전송 또는 기본 URL 재작성이 필요함 -- `contributeResolvedModelCompat`: 제공자가 다른 호환 전송을 통해 도착하더라도 자사 벤더 모델에 대한 호환성 플래그를 제공 -- `capabilities`: 제공자가 전사/도구/제공자 계열 특성을 게시 -- `normalizeToolSchemas`: 제공자가 내장 러너가 보기 전에 도구 스키마를 정리 -- `inspectToolSchemas`: 제공자가 정규화 후 전송별 스키마 경고를 표시 -- `resolveReasoningOutputMode`: 제공자가 네이티브 또는 태그 지정된 추론 출력 계약을 선택 -- `prepareExtraParams`: 제공자가 모델별 요청 매개변수의 기본값을 설정하거나 정규화 -- `createStreamFn`: 제공자가 일반 스트림 경로를 완전히 사용자 정의된 전송으로 대체 -- `wrapStreamFn`: 제공자가 요청 헤더/본문/모델 호환성 래퍼를 적용 -- `resolveTransportTurnState`: 제공자가 턴별 네이티브 전송 헤더 또는 메타데이터를 제공 -- `resolveWebSocketSessionPolicy`: 제공자가 네이티브 WebSocket 세션 헤더 또는 세션 쿨다운 정책을 제공 -- `createEmbeddingProvider`: 메모리 임베딩 동작이 코어 임베딩 스위치보드가 아니라 제공자 플러그인에 속하는 경우, 제공자가 이를 소유 -- `formatApiKey`: 제공자가 저장된 인증 프로필을 전송이 기대하는 런타임 `apiKey` 문자열 형식으로 변환 -- `refreshOAuth`: 공유 `pi-ai` 새로 고침 로직만으로 충분하지 않을 때 제공자가 OAuth 새로 고침을 소유 -- `buildAuthDoctorHint`: OAuth 새로 고침이 실패할 때 제공자가 복구 안내를 추가 -- `matchesContextOverflowError`: 일반 휴리스틱이 놓치는 제공자별 컨텍스트 창 초과 오류를 제공자가 인식 -- `classifyFailoverReason`: 제공자가 제공자별 원시 전송/API 오류를 속도 제한 또는 과부하 같은 대체 사유로 매핑 -- `isCacheTtlEligible`: 제공자가 어떤 업스트림 모델 ID가 프롬프트 캐시 TTL을 지원하는지 결정 -- `buildMissingAuthMessage`: 제공자가 일반 인증 저장소 오류를 제공자별 복구 힌트로 대체 -- `suppressBuiltInModel`: 제공자가 오래된 업스트림 행을 숨기고 직접 해석 실패에 대해 벤더 소유 오류를 반환할 수 있음 -- `augmentModelCatalog`: 제공자가 검색 및 구성 병합 후 합성/최종 카탈로그 행을 추가 -- `isBinaryThinking`: 제공자가 이진 켜기/끄기 사고 UX를 소유 -- `supportsXHighThinking`: 제공자가 선택된 모델에서 `xhigh`를 활성화 -- `resolveDefaultThinkingLevel`: 제공자가 모델 계열에 대한 기본 `/think` 정책을 소유 -- `applyConfigDefaults`: 제공자가 인증 모드, 환경 변수, 모델 계열에 따라 구성 구체화 중 제공자별 전역 기본값을 적용 -- `isModernModelRef`: 제공자가 라이브/스모크 선호 모델 매칭을 소유 -- `prepareRuntimeAuth`: 제공자가 구성된 자격 증명을 짧은 수명의 런타임 토큰으로 변환 -- `resolveUsageAuth`: 제공자가 `/usage` 및 관련 상태/보고 표면을 위한 사용량/쿼터 자격 증명을 해석 -- `fetchUsageSnapshot`: 제공자가 사용량 엔드포인트 가져오기/파싱을 소유하고, 코어는 계속해서 요약 셸과 형식을 소유 -- `onModelSelected`: 제공자가 텔레메트리 또는 제공자 소유 세션 기록 관리 같은 모델 선택 후 부수 효과를 실행 +- `auth[].run` / `auth[].runNonInteractive`: 공급자가 `openclaw onboard`, `openclaw models auth`, 헤드리스 설정을 위한 온보딩/로그인 + 흐름을 소유 +- `wizard.setup` / `wizard.modelPicker`: 공급자가 인증 선택 라벨, + 레거시 별칭, 온보딩 허용 목록 힌트, 온보딩/모델 선택기의 설정 항목을 소유 +- `catalog`: 공급자가 `models.providers`에 표시됨 +- `normalizeModelId`: 공급자가 조회 또는 정규화 전에 + 레거시/프리뷰 모델 id를 정규화 +- `normalizeTransport`: 공급자가 일반 모델 조립 전에 transport 계열의 `api` / `baseUrl`를 정규화함. + OpenClaw는 먼저 일치하는 공급자를 확인한 다음, + 실제로 transport를 변경하는 항목이 나올 때까지 다른 hook 지원 공급자 Plugin을 확인합니다. +- `normalizeConfig`: 공급자가 런타임이 사용하기 전에 `models.providers.` 구성을 정규화함. + OpenClaw는 먼저 일치하는 공급자를 확인한 다음, 실제로 구성을 변경하는 항목이 나올 때까지 다른 + hook 지원 공급자 Plugin을 확인합니다. 어떤 공급자 hook도 구성을 다시 쓰지 않으면, + 번들된 Google 계열 도우미가 계속 지원되는 Google 공급자 항목을 + 정규화합니다. +- `applyNativeStreamingUsageCompat`: 공급자가 구성 공급자에 대해 엔드포인트 기반 네이티브 스트리밍 사용량 호환성 재작성을 적용 +- `resolveConfigApiKey`: 공급자가 구성 공급자에 대해 + 전체 런타임 인증 로딩을 강제하지 않고 env-marker 인증을 해결함. + `amazon-bedrock`는 Bedrock 런타임 인증이 + AWS SDK 기본 체인을 사용하더라도 여기에서 내장 AWS env-marker 해결기도 가집니다. +- `resolveSyntheticAuth`: 공급자가 평문 비밀을 저장하지 않고도 + 로컬/자체 호스팅 또는 기타 구성 기반 인증 가용성을 노출할 수 있음 +- `shouldDeferSyntheticProfileAuth`: 공급자가 저장된 synthetic profile + 플레이스홀더를 env/config 기반 인증보다 낮은 우선순위로 표시할 수 있음 +- `resolveDynamicModel`: 공급자가 아직 로컬 + 정적 카탈로그에 없는 모델 id를 허용 +- `prepareDynamicModel`: 공급자가 동적 해결을 재시도하기 전에 + 메타데이터 새로 고침이 필요함 +- `normalizeResolvedModel`: 공급자에 transport 또는 base URL 재작성이 필요함 +- `contributeResolvedModelCompat`: 공급자가 + 호환 가능한 다른 transport를 통해 들어오는 경우에도 자사 vendor 모델의 compat 플래그를 제공 +- `capabilities`: 공급자가 transcript/tooling/provider-family 특이사항을 게시 +- `normalizeToolSchemas`: 공급자가 임베디드 + 러너가 보기 전에 도구 스키마를 정리 +- `inspectToolSchemas`: 공급자가 정규화 후 + transport별 스키마 경고를 표시 +- `resolveReasoningOutputMode`: 공급자가 네이티브와 태그형 + reasoning-output 계약 중에서 선택 +- `prepareExtraParams`: 공급자가 모델별 요청 파라미터를 기본 설정하거나 정규화 +- `createStreamFn`: 공급자가 일반 스트림 경로를 완전히 + 사용자 지정된 transport로 대체 +- `wrapStreamFn`: 공급자가 요청 헤더/본문/모델 compat 래퍼를 적용 +- `resolveTransportTurnState`: 공급자가 턴별 네이티브 transport + 헤더 또는 메타데이터를 제공 +- `resolveWebSocketSessionPolicy`: 공급자가 네이티브 WebSocket 세션 + 헤더 또는 세션 쿨다운 정책을 제공 +- `createEmbeddingProvider`: 공급자가 메모리 임베딩 동작이 + 코어 임베딩 스위치보드가 아니라 공급자 Plugin에 속하는 경우 이를 소유 +- `formatApiKey`: 공급자가 저장된 인증 프로필을 transport가 기대하는 런타임 + `apiKey` 문자열 형식으로 변환 +- `refreshOAuth`: 공유 `pi-ai` + 새로 고침 도구만으로 충분하지 않을 때 공급자가 OAuth 새로 고침을 소유 +- `buildAuthDoctorHint`: OAuth 새로 고침이 + 실패할 때 공급자가 복구 가이드를 추가 +- `matchesContextOverflowError`: 공급자가 일반 휴리스틱이 놓치는 + 공급자별 컨텍스트 창 초과 오류를 인식 +- `classifyFailoverReason`: 공급자가 공급자별 원시 transport/API + 오류를 rate limit 또는 overload 같은 페일오버 사유로 매핑 +- `isCacheTtlEligible`: 공급자가 어떤 업스트림 모델 id가 프롬프트 캐시 TTL을 지원하는지 결정 +- `buildMissingAuthMessage`: 공급자가 일반 인증 저장소 오류를 + 공급자별 복구 힌트로 대체 +- `suppressBuiltInModel`: 공급자가 오래된 업스트림 행을 숨기고 + 직접 해결 실패에 대해 vendor 소유 오류를 반환할 수 있음 +- `augmentModelCatalog`: 공급자가 탐색 및 구성 병합 후 + synthetic/final 카탈로그 행을 추가 +- `isBinaryThinking`: 공급자가 이진 on/off thinking UX를 소유 +- `supportsXHighThinking`: 공급자가 선택한 모델을 `xhigh`에 옵트인 +- `resolveDefaultThinkingLevel`: 공급자가 모델 계열의 기본 `/think` 정책을 소유 +- `applyConfigDefaults`: 공급자가 인증 모드, env, 모델 계열에 따라 + 구성 구체화 중 공급자별 전역 기본값을 적용 +- `isModernModelRef`: 공급자가 live/smoke 선호 모델 매칭을 소유 +- `prepareRuntimeAuth`: 공급자가 구성된 자격 증명을 + 수명이 짧은 런타임 토큰으로 변환 +- `resolveUsageAuth`: 공급자가 `/usage` 및 관련 상태/보고 표면을 위한 + 사용량/할당량 자격 증명을 해결 +- `fetchUsageSnapshot`: 공급자가 사용량 엔드포인트 가져오기/파싱을 소유하고, + 코어는 계속 요약 셸과 포맷팅을 소유 +- `onModelSelected`: 공급자가 텔레메트리나 공급자 소유 세션 기록 관리 같은 + 선택 후 부수 효과를 실행 현재 번들된 예시: -- `anthropic`: Claude 4.6 순방향 호환 대체, 인증 복구 힌트, 사용량 엔드포인트 가져오기, cache-TTL/제공자 계열 메타데이터, 인증 인식 전역 구성 기본값 -- `amazon-bedrock`: Bedrock 전용 스로틀/준비 안 됨 오류에 대한 제공자 소유 컨텍스트 초과 일치 및 대체 사유 분류, 그리고 Anthropic 트래픽의 Claude 전용 재생 정책 가드를 위한 공유 `anthropic-by-model` 재생 계열 -- `anthropic-vertex`: Anthropic 메시지 트래픽에 대한 Claude 전용 재생 정책 가드 -- `openrouter`: 패스스루 모델 ID, 요청 래퍼, 제공자 capability 힌트, 프록시 Gemini 트래픽에서의 Gemini thought-signature 정리, `openrouter-thinking` 스트림 계열을 통한 프록시 추론 주입, 라우팅 메타데이터 전달, cache-TTL 정책 -- `github-copilot`: 온보딩/디바이스 로그인, 순방향 호환 모델 대체, Claude-thinking 전사 힌트, 런타임 토큰 교환, 사용량 엔드포인트 가져오기 -- `openai`: GPT-5.4 순방향 호환 대체, 직접 OpenAI 전송 정규화, Codex 인식 누락 인증 힌트, Spark 억제, 합성 OpenAI/Codex 카탈로그 행, thinking/라이브 모델 정책, 사용량 토큰 별칭 정규화(`input` / `output` 및 `prompt` / `completion` 계열), 네이티브 OpenAI/Codex 래퍼를 위한 공유 `openai-responses-defaults` 스트림 계열, 제공자 계열 메타데이터, `gpt-image-1`용 번들 이미지 생성 제공자 등록, `sora-2`용 번들 비디오 생성 제공자 등록 -- `google` 및 `google-gemini-cli`: Gemini 3.1 순방향 호환 대체, 네이티브 Gemini 재생 검증, 부트스트랩 재생 정리, 태그 지정된 추론 출력 모드, 최신 모델 매칭, Gemini image-preview 모델용 번들 이미지 생성 제공자 등록, Veo 모델용 번들 비디오 생성 제공자 등록; Gemini CLI OAuth는 사용량 표면을 위한 인증 프로필 토큰 형식화, 사용량 토큰 파싱, 할당량 엔드포인트 가져오기도 소유 -- `moonshot`: 공유 전송, 플러그인 소유 thinking 페이로드 정규화 -- `kilocode`: 공유 전송, 플러그인 소유 요청 헤더, 추론 페이로드 정규화, 프록시 Gemini thought-signature 정리, cache-TTL 정책 -- `zai`: GLM-5 순방향 호환 대체, `tool_stream` 기본값, cache-TTL 정책, 이진 thinking/라이브 모델 정책, 사용량 인증 + 할당량 가져오기; 알 수 없는 `glm-5*` ID는 번들된 `glm-4.7` 템플릿에서 합성됨 -- `xai`: 네이티브 Responses 전송 정규화, Grok fast 변형용 `/fast` 별칭 재작성, 기본 `tool_stream`, xAI 전용 도구 스키마 / 추론 페이로드 정리, `grok-imagine-video`용 번들 비디오 생성 제공자 등록 -- `mistral`: 플러그인 소유 capability 메타데이터 -- `opencode` 및 `opencode-go`: 플러그인 소유 capability 메타데이터와 프록시 Gemini thought-signature 정리 -- `alibaba`: `alibaba/wan2.6-t2v` 같은 직접 Wan 모델 참조를 위한 플러그인 소유 비디오 생성 카탈로그 -- `byteplus`: 플러그인 소유 카탈로그와 Seedance 텍스트-비디오/이미지-비디오 모델용 번들 비디오 생성 제공자 등록 -- `fal`: 호스팅된 서드파티 이미지 생성 모델을 위한 번들 이미지 생성 제공자 등록과 호스팅된 서드파티 비디오 모델을 위한 번들 비디오 생성 제공자 등록 -- `cloudflare-ai-gateway`, `huggingface`, `kimi`, `nvidia`, `qianfan`, `stepfun`, `synthetic`, `venice`, `vercel-ai-gateway`, `volcengine`: 플러그인 소유 카탈로그만 제공 -- `qwen`: 텍스트 모델용 플러그인 소유 카탈로그와 멀티모달 표면용 공유 media-understanding 및 비디오 생성 제공자 등록; Qwen 비디오 생성은 `wan2.6-t2v`, `wan2.7-r2v` 같은 번들 Wan 모델과 함께 Standard DashScope 비디오 엔드포인트를 사용 -- `runway`: `gen4.5` 같은 네이티브 Runway 작업 기반 모델용 플러그인 소유 비디오 생성 제공자 등록 -- `minimax`: 플러그인 소유 카탈로그, Hailuo 비디오 모델용 번들 비디오 생성 제공자 등록, `image-01`용 번들 이미지 생성 제공자 등록, 하이브리드 Anthropic/OpenAI 재생 정책 선택, 사용량 인증/스냅샷 로직 -- `together`: 플러그인 소유 카탈로그와 Wan 비디오 모델용 번들 비디오 생성 제공자 등록 -- `xiaomi`: 플러그인 소유 카탈로그와 사용량 인증/스냅샷 로직 +- `anthropic`: Claude 4.6 순방향 호환 폴백, 인증 복구 힌트, 사용량 + 엔드포인트 가져오기, cache-TTL/provider-family 메타데이터, 그리고 인증 인식 전역 + 구성 기본값 +- `amazon-bedrock`: Bedrock 전용 스로틀/준비 안 됨 오류에 대한 공급자 소유 컨텍스트 초과 매칭과 + 페일오버 사유 분류, 그리고 Anthropic 트래픽에서 Claude 전용 replay-policy + 가드를 위한 공유 `anthropic-by-model` 재생 계열 포함 +- `anthropic-vertex`: Anthropic-message + 트래픽에서 Claude 전용 replay-policy 가드 +- `openrouter`: 패스스루 모델 id, 요청 래퍼, 공급자 capability + 힌트, 프록시 Gemini 트래픽에서 Gemini thought-signature 정리, `openrouter-thinking` 스트림 계열을 통한 프록시 + reasoning 주입, + 라우팅 메타데이터 전달, 그리고 cache-TTL 정책 +- `github-copilot`: 온보딩/디바이스 로그인, 순방향 호환 모델 폴백, + Claude-thinking transcript 힌트, 런타임 토큰 교환, 그리고 사용량 엔드포인트 + 가져오기 +- `openai`: GPT-5.4 순방향 호환 폴백, 직접 OpenAI transport + 정규화, Codex 인식 누락 인증 힌트, Spark 억제, synthetic + OpenAI/Codex 카탈로그 행, thinking/live-model 정책, 사용량 토큰 별칭 + 정규화(`input` / `output` 및 `prompt` / `completion` 계열), 네이티브 OpenAI/Codex + 래퍼를 위한 공유 `openai-responses-defaults` 스트림 계열, 공급자 계열 메타데이터, + `gpt-image-1`용 번들 이미지 생성 공급자 + 등록, 그리고 `sora-2`용 번들 비디오 생성 공급자 + 등록 +- `google` 및 `google-gemini-cli`: Gemini 3.1 순방향 호환 폴백, + 네이티브 Gemini 재생 검증, bootstrap 재생 정리, 태그형 + reasoning-output 모드, modern-model 매칭, Gemini image-preview 모델용 번들 이미지 생성 + 공급자 등록, 그리고 Veo 모델용 번들 + 비디오 생성 공급자 등록; Gemini CLI OAuth는 + 사용량 표면을 위한 인증 프로필 토큰 형식화, 사용량 토큰 파싱, 할당량 엔드포인트 + 가져오기도 소유합니다 +- `moonshot`: 공유 transport, Plugin 소유 thinking payload 정규화 +- `kilocode`: 공유 transport, Plugin 소유 요청 헤더, reasoning payload + 정규화, 프록시-Gemini thought-signature 정리, 그리고 cache-TTL + 정책 +- `zai`: GLM-5 순방향 호환 폴백, `tool_stream` 기본값, cache-TTL + 정책, binary-thinking/live-model 정책, 그리고 사용량 인증 + 할당량 가져오기; + 알 수 없는 `glm-5*` id는 번들된 `glm-4.7` 템플릿에서 합성됩니다 +- `xai`: 네이티브 Responses transport 정규화, Grok fast 변형을 위한 + `/fast` 별칭 재작성, 기본 `tool_stream`, xAI 전용 tool-schema / + reasoning-payload 정리, 그리고 `grok-imagine-video`용 번들 비디오 생성 공급자 + 등록 +- `mistral`: Plugin 소유 capability 메타데이터 +- `opencode` 및 `opencode-go`: Plugin 소유 capability 메타데이터와 + 프록시-Gemini thought-signature 정리 +- `alibaba`: `alibaba/wan2.6-t2v` 같은 직접 Wan 모델 참조를 위한 + Plugin 소유 비디오 생성 카탈로그 +- `byteplus`: Plugin 소유 카탈로그와 Seedance text-to-video/image-to-video 모델용 + 번들 비디오 생성 공급자 + 등록 +- `fal`: 호스팅된 서드파티 + 비디오 모델용 번들 비디오 생성 공급자 등록과 FLUX 이미지 모델용 + 이미지 생성 공급자 등록, 그리고 호스팅된 서드파티 비디오 모델용 + 번들 비디오 생성 공급자 등록 +- `cloudflare-ai-gateway`, `huggingface`, `kimi`, `nvidia`, `qianfan`, + `stepfun`, `synthetic`, `venice`, `vercel-ai-gateway`, `volcengine`: + Plugin 소유 카탈로그만 제공 +- `qwen`: 텍스트 모델용 Plugin 소유 카탈로그와 + 멀티모달 표면을 위한 공유 media-understanding 및 비디오 생성 공급자 등록; + Qwen 비디오 생성은 `wan2.6-t2v` 및 `wan2.7-r2v` 같은 + 번들 Wan 모델과 함께 Standard DashScope 비디오 엔드포인트를 사용합니다 +- `runway`: `gen4.5` 같은 네이티브 + Runway 작업 기반 모델용 Plugin 소유 비디오 생성 공급자 등록 +- `minimax`: Plugin 소유 카탈로그, Hailuo 비디오 모델용 번들 비디오 생성 공급자 + 등록, `image-01`용 번들 이미지 생성 공급자 + 등록, 하이브리드 Anthropic/OpenAI replay-policy + 선택, 그리고 사용량 인증/스냅샷 로직 +- `together`: Plugin 소유 카탈로그와 Wan 비디오 모델용 번들 비디오 생성 공급자 + 등록 +- `xiaomi`: Plugin 소유 카탈로그와 사용량 인증/스냅샷 로직 -번들된 `openai` 플러그인은 이제 `openai`와 `openai-codex` 두 제공자 ID를 모두 소유합니다. +번들된 `openai` Plugin은 이제 두 공급자 id `openai`와 +`openai-codex`를 모두 소유합니다. -여기까지는 여전히 OpenClaw의 일반 전송에 맞는 제공자들입니다. 완전히 사용자 정의된 요청 실행기가 필요한 제공자는 별도의 더 깊은 확장 표면입니다. +여기까지는 여전히 OpenClaw의 일반 transport에 맞는 공급자들입니다. 완전히 사용자 지정된 요청 실행기가 필요한 공급자는 +별도의, 더 심층적인 확장 표면입니다. ## API 키 순환 -- 선택된 제공자에 대해 일반 제공자 순환을 지원합니다. +- 선택된 공급자에 대해 일반 공급자 키 순환을 지원합니다. - 여러 키는 다음을 통해 구성합니다: - `OPENCLAW_LIVE__KEY`(단일 라이브 재정의, 최우선) - - `_API_KEYS`(쉼표 또는 세미콜론 목록) + - `_API_KEYS`(쉼표 또는 세미콜론 구분 목록) - `_API_KEY`(기본 키) - `_API_KEY_*`(번호가 붙은 목록, 예: `_API_KEY_1`) -- Google 제공자의 경우 `GOOGLE_API_KEY`도 대체값으로 포함됩니다. -- 키 선택 순서는 우선순위를 유지하면서 값을 중복 제거합니다. -- 요청은 속도 제한 응답에서만 다음 키로 재시도됩니다(예: `429`, `rate_limit`, `quota`, `resource exhausted`, `Too many concurrent requests`, `ThrottlingException`, `concurrency limit reached`, `workers_ai ... quota limit exceeded`, 또는 주기적인 사용량 제한 메시지). -- 속도 제한이 아닌 실패는 즉시 실패하며, 키 순환은 시도되지 않습니다. +- Google 공급자의 경우 `GOOGLE_API_KEY`도 폴백으로 포함됩니다. +- 키 선택 순서는 우선순위를 유지하며 값을 중복 제거합니다. +- 요청은 rate-limit 응답에서만 다음 키로 재시도됩니다(예: + `429`, `rate_limit`, `quota`, `resource exhausted`, `Too many +concurrent requests`, `ThrottlingException`, `concurrency limit reached`, + `workers_ai ... quota limit exceeded`, 또는 주기적 사용량 제한 메시지). +- rate-limit이 아닌 실패는 즉시 실패하며, 키 순환은 시도되지 않습니다. - 모든 후보 키가 실패하면 마지막 시도의 최종 오류가 반환됩니다. -## 내장 제공자(pi-ai 카탈로그) +## 내장 공급자(pi-ai 카탈로그) -OpenClaw는 pi‑ai 카탈로그를 함께 제공합니다. 이러한 제공자는 **`models.providers` 구성 없이도** 사용할 수 있으며, 인증을 설정하고 모델만 선택하면 됩니다. +OpenClaw는 pi-ai 카탈로그와 함께 제공됩니다. 이 공급자들은 +`models.providers` 구성이 **필요 없습니다**. 인증만 설정하고 모델을 선택하면 됩니다. ### OpenAI -- 제공자: `openai` +- 공급자: `openai` - 인증: `OPENAI_API_KEY` - 선택적 순환: `OPENAI_API_KEYS`, `OPENAI_API_KEY_1`, `OPENAI_API_KEY_2`, 그리고 `OPENCLAW_LIVE_OPENAI_KEY`(단일 재정의) -- 예제 모델: `openai/gpt-5.4`, `openai/gpt-5.4-pro` +- 예시 모델: `openai/gpt-5.4`, `openai/gpt-5.4-pro` - CLI: `openclaw onboard --auth-choice openai-api-key` -- 기본 전송은 `auto`입니다(WebSocket 우선, SSE 대체) +- 기본 transport는 `auto`입니다(WebSocket 우선, SSE 폴백) - 모델별 재정의: `agents.defaults.models["openai/"].params.transport` (`"sse"`, `"websocket"`, 또는 `"auto"`) -- OpenAI Responses WebSocket 워밍업은 기본적으로 `params.openaiWsWarmup` (`true`/`false`)을 통해 활성화됩니다 +- OpenAI Responses WebSocket 워밍업은 `params.openaiWsWarmup` (`true`/`false`)을 통해 기본적으로 활성화됩니다 - OpenAI 우선 처리(priority processing)는 `agents.defaults.models["openai/"].params.serviceTier`를 통해 활성화할 수 있습니다 -- `/fast` 및 `params.fastMode`는 직접 `openai/*` Responses 요청을 `api.openai.com`의 `service_tier=priority`로 매핑합니다 -- 공유 `/fast` 토글 대신 명시적인 티어를 원하면 `params.serviceTier`를 사용하세요 -- 숨겨진 OpenClaw attribution 헤더(`originator`, `version`, `User-Agent`)는 일반 OpenAI 호환 프록시가 아니라 `api.openai.com`에 대한 네이티브 OpenAI 트래픽에만 적용됩니다 -- 네이티브 OpenAI 경로는 Responses `store`, 프롬프트 캐시 힌트, OpenAI 추론 호환 페이로드 형상도 유지하며, 프록시 경로는 그렇지 않습니다 -- `openai/gpt-5.3-codex-spark`는 실제 OpenAI API에서 거부되므로 OpenClaw에서 의도적으로 숨겨집니다. Spark는 Codex 전용으로 취급됩니다 +- `/fast`와 `params.fastMode`는 직접 `openai/*` Responses 요청을 `api.openai.com`의 `service_tier=priority`로 매핑합니다 +- 공유 `/fast` 토글 대신 명시적 티어를 원하면 `params.serviceTier`를 사용하세요 +- 숨겨진 OpenClaw attribution 헤더(`originator`, `version`, + `User-Agent`)는 일반 OpenAI 호환 프록시가 아니라 `api.openai.com`으로 가는 네이티브 OpenAI 트래픽에만 적용됩니다 +- 네이티브 OpenAI 경로는 Responses `store`, 프롬프트 캐시 힌트, 그리고 + OpenAI reasoning 호환 payload shaping도 유지합니다. 프록시 경로는 그렇지 않습니다 +- `openai/gpt-5.3-codex-spark`는 실제 OpenAI API가 이를 거부하므로 OpenClaw에서 의도적으로 숨겨집니다. Spark는 Codex 전용으로 처리됩니다 ```json5 { @@ -152,14 +277,14 @@ OpenClaw는 pi‑ai 카탈로그를 함께 제공합니다. 이러한 제공자 ### Anthropic -- 제공자: `anthropic` +- 공급자: `anthropic` - 인증: `ANTHROPIC_API_KEY` - 선택적 순환: `ANTHROPIC_API_KEYS`, `ANTHROPIC_API_KEY_1`, `ANTHROPIC_API_KEY_2`, 그리고 `OPENCLAW_LIVE_ANTHROPIC_KEY`(단일 재정의) -- 예제 모델: `anthropic/claude-opus-4-6` +- 예시 모델: `anthropic/claude-opus-4-6` - CLI: `openclaw onboard --auth-choice apiKey` -- 직접 공개 Anthropic 요청은 `api.anthropic.com`으로 전송되는 API 키 및 OAuth 인증 트래픽을 포함해 공유 `/fast` 토글과 `params.fastMode`도 지원합니다. OpenClaw는 이를 Anthropic `service_tier` (`auto` 대 `standard_only`)로 매핑합니다 -- Anthropic 참고: Anthropic 직원이 OpenClaw 스타일 Claude CLI 사용이 다시 허용된다고 알려주었으므로, Anthropic이 새로운 정책을 발표하지 않는 한 OpenClaw는 Claude CLI 재사용과 `claude -p` 사용을 이 통합에서 허용된 것으로 취급합니다. -- Anthropic setup-token은 계속 지원되는 OpenClaw 토큰 경로로 남아 있지만, OpenClaw는 이제 가능하면 Claude CLI 재사용과 `claude -p`를 우선합니다. +- 직접 공개 Anthropic 요청은 공유 `/fast` 토글과 `params.fastMode`도 지원하며, `api.anthropic.com`으로 전송되는 API 키 및 OAuth 인증 트래픽을 포함합니다. OpenClaw는 이를 Anthropic `service_tier`(`auto` 대 `standard_only`)로 매핑합니다 +- Anthropic 참고: Anthropic 직원이 OpenClaw 스타일 Claude CLI 사용이 다시 허용된다고 알려주었으므로, Anthropic이 새 정책을 발표하지 않는 한 OpenClaw는 Claude CLI 재사용과 `claude -p` 사용을 이 통합에 대해 허용된 것으로 처리합니다. +- Anthropic setup-token도 계속 지원되는 OpenClaw 토큰 경로로 제공되지만, OpenClaw는 이제 가능하면 Claude CLI 재사용과 `claude -p`를 우선합니다. ```json5 { @@ -169,17 +294,19 @@ OpenClaw는 pi‑ai 카탈로그를 함께 제공합니다. 이러한 제공자 ### OpenAI Code (Codex) -- 제공자: `openai-codex` +- 공급자: `openai-codex` - 인증: OAuth (ChatGPT) -- 예제 모델: `openai-codex/gpt-5.4` +- 예시 모델: `openai-codex/gpt-5.4` - CLI: `openclaw onboard --auth-choice openai-codex` 또는 `openclaw models auth login --provider openai-codex` -- 기본 전송은 `auto`입니다(WebSocket 우선, SSE 대체) +- 기본 transport는 `auto`입니다(WebSocket 우선, SSE 폴백) - 모델별 재정의: `agents.defaults.models["openai-codex/"].params.transport` (`"sse"`, `"websocket"`, 또는 `"auto"`) - `params.serviceTier`도 네이티브 Codex Responses 요청(`chatgpt.com/backend-api`)에서 전달됩니다 -- 숨겨진 OpenClaw attribution 헤더(`originator`, `version`, `User-Agent`)는 일반 OpenAI 호환 프록시가 아니라 `chatgpt.com/backend-api`로 향하는 네이티브 Codex 트래픽에만 첨부됩니다 +- 숨겨진 OpenClaw attribution 헤더(`originator`, `version`, + `User-Agent`)는 일반 OpenAI 호환 프록시가 아니라 + `chatgpt.com/backend-api`로 가는 네이티브 Codex 트래픽에만 첨부됩니다 - 직접 `openai/*`와 동일한 `/fast` 토글 및 `params.fastMode` 구성을 공유하며, OpenClaw는 이를 `service_tier=priority`로 매핑합니다 -- `openai-codex/gpt-5.3-codex-spark`는 Codex OAuth 카탈로그가 이를 노출할 때 계속 사용할 수 있습니다. 권한 부여 여부에 따라 달라집니다 -- `openai-codex/gpt-5.4`는 네이티브 `contextWindow = 1050000`과 기본 런타임 `contextTokens = 272000`을 유지합니다. 런타임 상한은 `models.providers.openai-codex.models[].contextTokens`로 재정의할 수 있습니다 +- `openai-codex/gpt-5.3-codex-spark`는 Codex OAuth 카탈로그가 이를 노출할 때 계속 사용할 수 있습니다. 사용 권한에 따라 달라집니다 +- `openai-codex/gpt-5.4`는 네이티브 `contextWindow = 1050000`과 기본 런타임 `contextTokens = 272000`을 유지합니다. 런타임 상한은 `models.providers.openai-codex.models[].contextTokens`로 재정의하세요 - 정책 참고: OpenAI Codex OAuth는 OpenClaw 같은 외부 도구/워크플로에 대해 명시적으로 지원됩니다. ```json5 @@ -202,16 +329,16 @@ OpenClaw는 pi‑ai 카탈로그를 함께 제공합니다. 이러한 제공자 ### 기타 구독형 호스팅 옵션 -- [Qwen Cloud](/ko/providers/qwen): Qwen Cloud 제공자 표면과 Alibaba DashScope 및 Coding Plan 엔드포인트 매핑 +- [Qwen Cloud](/ko/providers/qwen): Qwen Cloud 공급자 표면과 Alibaba DashScope 및 Coding Plan 엔드포인트 매핑 - [MiniMax](/ko/providers/minimax): MiniMax Coding Plan OAuth 또는 API 키 액세스 - [GLM Models](/ko/providers/glm): Z.AI Coding Plan 또는 일반 API 엔드포인트 ### OpenCode - 인증: `OPENCODE_API_KEY`(또는 `OPENCODE_ZEN_API_KEY`) -- Zen 런타임 제공자: `opencode` -- Go 런타임 제공자: `opencode-go` -- 예제 모델: `opencode/claude-opus-4-6`, `opencode-go/kimi-k2.5` +- Zen 런타임 공급자: `opencode` +- Go 런타임 공급자: `opencode-go` +- 예시 모델: `opencode/claude-opus-4-6`, `opencode-go/kimi-k2.5` - CLI: `openclaw onboard --auth-choice opencode-zen` 또는 `openclaw onboard --auth-choice opencode-go` ```json5 @@ -222,125 +349,149 @@ OpenClaw는 pi‑ai 카탈로그를 함께 제공합니다. 이러한 제공자 ### Google Gemini (API 키) -- 제공자: `google` +- 공급자: `google` - 인증: `GEMINI_API_KEY` -- 선택적 순환: `GEMINI_API_KEYS`, `GEMINI_API_KEY_1`, `GEMINI_API_KEY_2`, `GOOGLE_API_KEY` 대체값, 그리고 `OPENCLAW_LIVE_GEMINI_KEY`(단일 재정의) -- 예제 모델: `google/gemini-3.1-pro-preview`, `google/gemini-3-flash-preview` +- 선택적 순환: `GEMINI_API_KEYS`, `GEMINI_API_KEY_1`, `GEMINI_API_KEY_2`, `GOOGLE_API_KEY` 폴백, 그리고 `OPENCLAW_LIVE_GEMINI_KEY`(단일 재정의) +- 예시 모델: `google/gemini-3.1-pro-preview`, `google/gemini-3-flash-preview` - 호환성: `google/gemini-3.1-flash-preview`를 사용하는 레거시 OpenClaw 구성은 `google/gemini-3-flash-preview`로 정규화됩니다 - CLI: `openclaw onboard --auth-choice gemini-api-key` -- 직접 Gemini 실행도 `agents.defaults.models["google/"].params.cachedContent`(또는 레거시 `cached_content`)를 받아 제공자 네이티브 `cachedContents/...` 핸들을 전달합니다. Gemini 캐시 적중은 OpenClaw `cacheRead`로 표시됩니다 +- 직접 Gemini 실행은 `agents.defaults.models["google/"].params.cachedContent` + (또는 레거시 `cached_content`)도 받아들여 공급자 네이티브 + `cachedContents/...` 핸들을 전달합니다. Gemini 캐시 적중은 OpenClaw `cacheRead`로 표시됩니다 ### Google Vertex 및 Gemini CLI -- 제공자: `google-vertex`, `google-gemini-cli` +- 공급자: `google-vertex`, `google-gemini-cli` - 인증: Vertex는 gcloud ADC를 사용하고, Gemini CLI는 자체 OAuth 흐름을 사용합니다 -- 주의: OpenClaw의 Gemini CLI OAuth는 비공식 통합입니다. 일부 사용자는 서드파티 클라이언트 사용 후 Google 계정 제한을 경험했다고 보고했습니다. 진행하기로 했다면 Google 약관을 검토하고 중요하지 않은 계정을 사용하세요. -- Gemini CLI OAuth는 번들된 `google` 플러그인의 일부로 제공됩니다. +- 주의: OpenClaw의 Gemini CLI OAuth는 비공식 통합입니다. 일부 사용자는 서드파티 클라이언트를 사용한 뒤 Google 계정 제한을 보고했습니다. 진행하기로 선택한 경우 Google 약관을 검토하고 중요하지 않은 계정을 사용하세요. +- Gemini CLI OAuth는 번들된 `google` Plugin의 일부로 제공됩니다. - 먼저 Gemini CLI를 설치하세요: - `brew install gemini-cli` - 또는 `npm install -g @google/gemini-cli` - 활성화: `openclaw plugins enable google` - 로그인: `openclaw models auth login --provider google-gemini-cli --set-default` - 기본 모델: `google-gemini-cli/gemini-3-flash-preview` - - 참고: `openclaw.json`에 client id 또는 secret을 붙여넣지 **않습니다**. CLI 로그인 흐름은 게이트웨이 호스트의 인증 프로필에 토큰을 저장합니다. - - 로그인 후 요청이 실패하면 게이트웨이 호스트에 `GOOGLE_CLOUD_PROJECT` 또는 `GOOGLE_CLOUD_PROJECT_ID`를 설정하세요. - - Gemini CLI JSON 응답은 `response`에서 파싱되며, 사용량은 `stats`로 대체되고 `stats.cached`는 OpenClaw `cacheRead`로 정규화됩니다. + - 참고: `openclaw.json`에 client id나 secret을 붙여 넣지 **않습니다**. CLI 로그인 흐름은 + 토큰을 Gateway 호스트의 인증 프로필에 저장합니다. + - 로그인 후 요청이 실패하면 Gateway 호스트에 `GOOGLE_CLOUD_PROJECT` 또는 `GOOGLE_CLOUD_PROJECT_ID`를 설정하세요. + - Gemini CLI JSON 응답은 `response`에서 파싱되며, 사용량은 `stats`로 폴백하고, + `stats.cached`는 OpenClaw `cacheRead`로 정규화됩니다. ### Z.AI (GLM) -- 제공자: `zai` +- 공급자: `zai` - 인증: `ZAI_API_KEY` -- 예제 모델: `zai/glm-5.1` +- 예시 모델: `zai/glm-5.1` - CLI: `openclaw onboard --auth-choice zai-api-key` - 별칭: `z.ai/*` 및 `z-ai/*`는 `zai/*`로 정규화됩니다 - - `zai-api-key`는 일치하는 Z.AI 엔드포인트를 자동 감지합니다. `zai-coding-global`, `zai-coding-cn`, `zai-global`, `zai-cn`은 특정 표면을 강제합니다 + - `zai-api-key`는 일치하는 Z.AI 엔드포인트를 자동 감지하며, `zai-coding-global`, `zai-coding-cn`, `zai-global`, `zai-cn`은 특정 표면을 강제합니다 ### Vercel AI Gateway -- 제공자: `vercel-ai-gateway` +- 공급자: `vercel-ai-gateway` - 인증: `AI_GATEWAY_API_KEY` -- 예제 모델: `vercel-ai-gateway/anthropic/claude-opus-4.6` +- 예시 모델: `vercel-ai-gateway/anthropic/claude-opus-4.6` - CLI: `openclaw onboard --auth-choice ai-gateway-api-key` ### Kilo Gateway -- 제공자: `kilocode` +- 공급자: `kilocode` - 인증: `KILOCODE_API_KEY` -- 예제 모델: `kilocode/kilo/auto` +- 예시 모델: `kilocode/kilo/auto` - CLI: `openclaw onboard --auth-choice kilocode-api-key` - 기본 URL: `https://api.kilo.ai/api/gateway/` -- 정적 대체 카탈로그에는 `kilocode/kilo/auto`가 포함되며, 라이브 `https://api.kilo.ai/api/gateway/models` 검색은 런타임 카탈로그를 더 확장할 수 있습니다. -- `kilocode/kilo/auto` 뒤의 정확한 업스트림 라우팅은 OpenClaw에 하드코딩되어 있지 않고 Kilo Gateway가 소유합니다. +- 정적 폴백 카탈로그는 `kilocode/kilo/auto`를 포함하며, 라이브 + `https://api.kilo.ai/api/gateway/models` 탐색은 런타임 + 카탈로그를 더 확장할 수 있습니다. +- `kilocode/kilo/auto` 뒤의 정확한 업스트림 라우팅은 OpenClaw에 하드코딩되어 있지 않고 + Kilo Gateway가 소유합니다. -설정 세부 정보는 [/providers/kilocode](/ko/providers/kilocode)를 참조하세요. +설정 세부 정보는 [/providers/kilocode](/ko/providers/kilocode)를 참고하세요. -### 기타 번들 제공자 플러그인 +### 기타 번들 공급자 Plugin - OpenRouter: `openrouter` (`OPENROUTER_API_KEY`) -- 예제 모델: `openrouter/auto` -- OpenClaw는 요청이 실제로 `openrouter.ai`를 대상으로 할 때만 OpenRouter의 문서화된 앱 attribution 헤더를 적용합니다 -- OpenRouter 전용 Anthropic `cache_control` 마커도 임의 프록시 URL이 아니라 검증된 OpenRouter 경로에서만 적용됩니다 -- OpenRouter는 프록시 스타일 OpenAI 호환 경로에 남아 있으므로 네이티브 OpenAI 전용 요청 형상화(`serviceTier`, Responses `store`, 프롬프트 캐시 힌트, OpenAI 추론 호환 페이로드)는 전달되지 않습니다 -- Gemini 기반 OpenRouter 참조는 프록시 Gemini thought-signature 정리만 유지하며, 네이티브 Gemini 재생 검증 및 부트스트랩 재작성은 비활성 상태로 유지됩니다 +- 예시 모델: `openrouter/auto` +- OpenClaw는 요청이 실제로 `openrouter.ai`를 대상으로 할 때만 + OpenRouter 문서화된 앱 attribution 헤더를 적용합니다 +- OpenRouter 전용 Anthropic `cache_control` 마커도 + 임의의 프록시 URL이 아니라 검증된 OpenRouter 경로에만 적용됩니다 +- OpenRouter는 계속 프록시 스타일 OpenAI 호환 경로를 사용하므로, 네이티브 + OpenAI 전용 요청 shaping(`serviceTier`, Responses `store`, + 프롬프트 캐시 힌트, OpenAI reasoning 호환 payload)은 전달되지 않습니다 +- Gemini 기반 OpenRouter 참조는 프록시-Gemini thought-signature 정리만 유지하며, + 네이티브 Gemini 재생 검증과 bootstrap 재작성은 비활성 상태로 유지됩니다 - Kilo Gateway: `kilocode` (`KILOCODE_API_KEY`) -- 예제 모델: `kilocode/kilo/auto` -- Gemini 기반 Kilo 참조는 동일한 프록시 Gemini thought-signature 정리 경로를 유지합니다. `kilocode/kilo/auto` 및 기타 프록시 추론 미지원 힌트는 프록시 추론 주입을 건너뜁니다 +- 예시 모델: `kilocode/kilo/auto` +- Gemini 기반 Kilo 참조는 동일한 프록시-Gemini thought-signature + 정리 경로를 유지합니다. `kilocode/kilo/auto` 및 기타 프록시 reasoning 미지원 + 힌트는 프록시 reasoning 주입을 건너뜁니다 - MiniMax: `minimax` (API 키) 및 `minimax-portal` (OAuth) - 인증: `minimax`에는 `MINIMAX_API_KEY`, `minimax-portal`에는 `MINIMAX_OAUTH_TOKEN` 또는 `MINIMAX_API_KEY` -- 예제 모델: `minimax/MiniMax-M2.7` 또는 `minimax-portal/MiniMax-M2.7` -- MiniMax 온보딩/API 키 설정은 `input: ["text", "image"]`가 포함된 명시적 M2.7 모델 정의를 작성합니다. 번들된 제공자 카탈로그는 해당 제공자 구성이 구체화되기 전까지 채팅 참조를 텍스트 전용으로 유지합니다 +- 예시 모델: `minimax/MiniMax-M2.7` 또는 `minimax-portal/MiniMax-M2.7` +- MiniMax 온보딩/API 키 설정은 + `input: ["text", "image"]`가 포함된 명시적 M2.7 모델 정의를 씁니다. 번들 공급자 카탈로그는 + 해당 공급자 구성이 구체화될 때까지 채팅 참조를 + 텍스트 전용으로 유지합니다 - Moonshot: `moonshot` (`MOONSHOT_API_KEY`) -- 예제 모델: `moonshot/kimi-k2.5` +- 예시 모델: `moonshot/kimi-k2.5` - Kimi Coding: `kimi` (`KIMI_API_KEY` 또는 `KIMICODE_API_KEY`) -- 예제 모델: `kimi/kimi-code` +- 예시 모델: `kimi/kimi-code` - Qianfan: `qianfan` (`QIANFAN_API_KEY`) -- 예제 모델: `qianfan/deepseek-v3.2` +- 예시 모델: `qianfan/deepseek-v3.2` - Qwen Cloud: `qwen` (`QWEN_API_KEY`, `MODELSTUDIO_API_KEY`, 또는 `DASHSCOPE_API_KEY`) -- 예제 모델: `qwen/qwen3.5-plus` +- 예시 모델: `qwen/qwen3.5-plus` - NVIDIA: `nvidia` (`NVIDIA_API_KEY`) -- 예제 모델: `nvidia/nvidia/llama-3.1-nemotron-70b-instruct` +- 예시 모델: `nvidia/nvidia/llama-3.1-nemotron-70b-instruct` - StepFun: `stepfun` / `stepfun-plan` (`STEPFUN_API_KEY`) -- 예제 모델: `stepfun/step-3.5-flash`, `stepfun-plan/step-3.5-flash-2603` +- 예시 모델: `stepfun/step-3.5-flash`, `stepfun-plan/step-3.5-flash-2603` - Together: `together` (`TOGETHER_API_KEY`) -- 예제 모델: `together/moonshotai/Kimi-K2.5` +- 예시 모델: `together/moonshotai/Kimi-K2.5` - Venice: `venice` (`VENICE_API_KEY`) - Xiaomi: `xiaomi` (`XIAOMI_API_KEY`) -- 예제 모델: `xiaomi/mimo-v2-flash` +- 예시 모델: `xiaomi/mimo-v2-flash` - Vercel AI Gateway: `vercel-ai-gateway` (`AI_GATEWAY_API_KEY`) - Hugging Face Inference: `huggingface` (`HUGGINGFACE_HUB_TOKEN` 또는 `HF_TOKEN`) - Cloudflare AI Gateway: `cloudflare-ai-gateway` (`CLOUDFLARE_AI_GATEWAY_API_KEY`) - Volcengine: `volcengine` (`VOLCANO_ENGINE_API_KEY`) -- 예제 모델: `volcengine-plan/ark-code-latest` +- 예시 모델: `volcengine-plan/ark-code-latest` - BytePlus: `byteplus` (`BYTEPLUS_API_KEY`) -- 예제 모델: `byteplus-plan/ark-code-latest` +- 예시 모델: `byteplus-plan/ark-code-latest` - xAI: `xai` (`XAI_API_KEY`) - 네이티브 번들 xAI 요청은 xAI Responses 경로를 사용합니다 - - `/fast` 또는 `params.fastMode: true`는 `grok-3`, `grok-3-mini`, `grok-4`, `grok-4-0709`를 해당 `*-fast` 변형으로 다시 씁니다 - - `tool_stream`는 기본적으로 켜져 있습니다. 비활성화하려면 `agents.defaults.models["xai/"].params.tool_stream`를 `false`로 설정하세요 + - `/fast` 또는 `params.fastMode: true`는 `grok-3`, `grok-3-mini`, + `grok-4`, `grok-4-0709`를 해당 `*-fast` 변형으로 재작성합니다 + - `tool_stream`은 기본적으로 활성화됩니다. 비활성화하려면 + `agents.defaults.models["xai/"].params.tool_stream`을 `false`로 + 설정하세요 - Mistral: `mistral` (`MISTRAL_API_KEY`) -- 예제 모델: `mistral/mistral-large-latest` +- 예시 모델: `mistral/mistral-large-latest` - CLI: `openclaw onboard --auth-choice mistral-api-key` - Groq: `groq` (`GROQ_API_KEY`) - Cerebras: `cerebras` (`CEREBRAS_API_KEY`) - - Cerebras의 GLM 모델은 `zai-glm-4.7` 및 `zai-glm-4.6` ID를 사용합니다. + - Cerebras의 GLM 모델은 `zai-glm-4.7` 및 `zai-glm-4.6` id를 사용합니다. - OpenAI 호환 기본 URL: `https://api.cerebras.ai/v1`. - GitHub Copilot: `github-copilot` (`COPILOT_GITHUB_TOKEN` / `GH_TOKEN` / `GITHUB_TOKEN`) -- Hugging Face Inference 예제 모델: `huggingface/deepseek-ai/DeepSeek-R1`; CLI: `openclaw onboard --auth-choice huggingface-api-key`. [Hugging Face (Inference)](/ko/providers/huggingface)를 참조하세요. +- Hugging Face Inference 예시 모델: `huggingface/deepseek-ai/DeepSeek-R1`; CLI: `openclaw onboard --auth-choice huggingface-api-key`. 자세한 내용은 [Hugging Face (Inference)](/ko/providers/huggingface)를 참고하세요. -## `models.providers`를 통한 제공자(custom/base URL) +## `models.providers`를 통한 공급자(custom/base URL) -`models.providers`(또는 `models.json`)를 사용해 **사용자 정의** 제공자 또는 OpenAI/Anthropic 호환 프록시를 추가하세요. +**사용자 지정** 공급자 또는 OpenAI/Anthropic 호환 프록시를 추가하려면 +`models.providers`(또는 `models.json`)를 사용하세요. -아래의 많은 번들 제공자 플러그인은 이미 기본 카탈로그를 게시합니다. -기본 base URL, 헤더 또는 모델 목록을 재정의하려는 경우에만 명시적인 `models.providers.` 항목을 사용하세요. +아래의 많은 번들 공급자 Plugin은 이미 기본 카탈로그를 게시합니다. +기본 base URL, 헤더 또는 모델 목록을 재정의하려는 경우에만 +명시적인 `models.providers.` 항목을 사용하세요. ### Moonshot AI (Kimi) -Moonshot은 번들 제공자 플러그인으로 제공됩니다. 기본적으로 내장 제공자를 사용하고, base URL 또는 모델 메타데이터를 재정의해야 할 때만 명시적인 `models.providers.moonshot` 항목을 추가하세요: +Moonshot은 번들 공급자 Plugin으로 제공됩니다. 기본적으로 내장 공급자를 +사용하고, base URL 또는 모델 메타데이터를 재정의해야 할 때만 +명시적인 `models.providers.moonshot` 항목을 추가하세요: -- 제공자: `moonshot` +- 공급자: `moonshot` - 인증: `MOONSHOT_API_KEY` -- 예제 모델: `moonshot/kimi-k2.5` +- 예시 모델: `moonshot/kimi-k2.5` - CLI: `openclaw onboard --auth-choice moonshot-api-key` 또는 `openclaw onboard --auth-choice moonshot-api-key-cn` Kimi K2 모델 ID: @@ -377,9 +528,9 @@ Kimi K2 모델 ID: Kimi Coding은 Moonshot AI의 Anthropic 호환 엔드포인트를 사용합니다: -- 제공자: `kimi` +- 공급자: `kimi` - 인증: `KIMI_API_KEY` -- 예제 모델: `kimi/kimi-code` +- 예시 모델: `kimi/kimi-code` ```json5 { @@ -390,15 +541,15 @@ Kimi Coding은 Moonshot AI의 Anthropic 호환 엔드포인트를 사용합니 } ``` -레거시 `kimi/k2p5`는 호환성 모델 ID로 계속 허용됩니다. +레거시 `kimi/k2p5`도 호환성 모델 id로 계속 허용됩니다. ### Volcano Engine (Doubao) -Volcano Engine (火山引擎)은 중국에서 Doubao 및 기타 모델에 대한 액세스를 제공합니다. +Volcano Engine(화산인용, 火山引擎)은 중국에서 Doubao 및 기타 모델에 대한 액세스를 제공합니다. -- 제공자: `volcengine` (코딩: `volcengine-plan`) +- 공급자: `volcengine` (코딩: `volcengine-plan`) - 인증: `VOLCANO_ENGINE_API_KEY` -- 예제 모델: `volcengine-plan/ark-code-latest` +- 예시 모델: `volcengine-plan/ark-code-latest` - CLI: `openclaw onboard --auth-choice volcengine-api-key` ```json5 @@ -409,9 +560,12 @@ Volcano Engine (火山引擎)은 중국에서 Doubao 및 기타 모델에 대한 } ``` -온보딩은 기본적으로 코딩 표면을 사용하지만, 일반 `volcengine/*` 카탈로그도 동시에 등록됩니다. +온보딩은 기본적으로 코딩 표면을 사용하지만, 일반 `volcengine/*` +카탈로그도 동시에 등록됩니다. -온보딩/모델 구성 선택기에서 Volcengine 인증 선택은 `volcengine/*`와 `volcengine-plan/*` 행을 모두 우선합니다. 해당 모델이 아직 로드되지 않은 경우, OpenClaw는 빈 제공자 범위 선택기를 표시하는 대신 필터링되지 않은 카탈로그로 대체합니다. +온보딩/구성 모델 선택기에서 Volcengine 인증 선택은 +`volcengine/*` 및 `volcengine-plan/*` 행을 모두 우선합니다. 해당 모델이 아직 로드되지 않았다면, +OpenClaw는 빈 공급자 범위 선택기를 표시하는 대신 필터링되지 않은 카탈로그로 폴백합니다. 사용 가능한 모델: @@ -433,9 +587,9 @@ Volcano Engine (火山引擎)은 중국에서 Doubao 및 기타 모델에 대한 BytePlus ARK는 국제 사용자를 위해 Volcano Engine과 동일한 모델에 대한 액세스를 제공합니다. -- 제공자: `byteplus` (코딩: `byteplus-plan`) +- 공급자: `byteplus` (코딩: `byteplus-plan`) - 인증: `BYTEPLUS_API_KEY` -- 예제 모델: `byteplus-plan/ark-code-latest` +- 예시 모델: `byteplus-plan/ark-code-latest` - CLI: `openclaw onboard --auth-choice byteplus-api-key` ```json5 @@ -446,9 +600,12 @@ BytePlus ARK는 국제 사용자를 위해 Volcano Engine과 동일한 모델에 } ``` -온보딩은 기본적으로 코딩 표면을 사용하지만, 일반 `byteplus/*` 카탈로그도 동시에 등록됩니다. +온보딩은 기본적으로 코딩 표면을 사용하지만, 일반 `byteplus/*` +카탈로그도 동시에 등록됩니다. -온보딩/모델 구성 선택기에서 BytePlus 인증 선택은 `byteplus/*`와 `byteplus-plan/*` 행을 모두 우선합니다. 해당 모델이 아직 로드되지 않은 경우, OpenClaw는 빈 제공자 범위 선택기를 표시하는 대신 필터링되지 않은 카탈로그로 대체합니다. +온보딩/구성 모델 선택기에서 BytePlus 인증 선택은 +`byteplus/*` 및 `byteplus-plan/*` 행을 모두 우선합니다. 해당 모델이 아직 로드되지 않았다면, +OpenClaw는 빈 공급자 범위 선택기를 표시하는 대신 필터링되지 않은 카탈로그로 폴백합니다. 사용 가능한 모델: @@ -466,11 +623,11 @@ BytePlus ARK는 국제 사용자를 위해 Volcano Engine과 동일한 모델에 ### Synthetic -Synthetic는 `synthetic` 제공자 뒤에서 Anthropic 호환 모델을 제공합니다: +Synthetic는 `synthetic` 공급자 뒤에서 Anthropic 호환 모델을 제공합니다: -- 제공자: `synthetic` +- 공급자: `synthetic` - 인증: `SYNTHETIC_API_KEY` -- 예제 모델: `synthetic/hf:MiniMaxAI/MiniMax-M2.5` +- 예시 모델: `synthetic/hf:MiniMaxAI/MiniMax-M2.5` - CLI: `openclaw onboard --auth-choice synthetic-api-key` ```json5 @@ -494,36 +651,60 @@ Synthetic는 `synthetic` 제공자 뒤에서 Anthropic 호환 모델을 제공 ### MiniMax -MiniMax는 사용자 정의 엔드포인트를 사용하므로 `models.providers`를 통해 구성됩니다: +MiniMax는 사용자 지정 엔드포인트를 사용하므로 `models.providers`를 통해 구성됩니다: - MiniMax OAuth (Global): `--auth-choice minimax-global-oauth` - MiniMax OAuth (CN): `--auth-choice minimax-cn-oauth` - MiniMax API 키 (Global): `--auth-choice minimax-global-api` - MiniMax API 키 (CN): `--auth-choice minimax-cn-api` -- 인증: `minimax`에는 `MINIMAX_API_KEY`, `minimax-portal`에는 `MINIMAX_OAUTH_TOKEN` 또는 `MINIMAX_API_KEY` +- 인증: `minimax`에는 `MINIMAX_API_KEY`, `minimax-portal`에는 `MINIMAX_OAUTH_TOKEN` 또는 + `MINIMAX_API_KEY` -설정 세부 정보, 모델 옵션, 구성 스니펫은 [/providers/minimax](/ko/providers/minimax)를 참조하세요. +설정 세부 정보, 모델 옵션, 구성 스니펫은 [/providers/minimax](/ko/providers/minimax)를 참고하세요. -MiniMax의 Anthropic 호환 스트리밍 경로에서 OpenClaw는 명시적으로 설정하지 않는 한 기본적으로 thinking을 비활성화하며, `/fast on`은 `MiniMax-M2.7`을 `MiniMax-M2.7-highspeed`로 다시 씁니다. +MiniMax의 Anthropic 호환 스트리밍 경로에서 OpenClaw는 +명시적으로 설정하지 않는 한 thinking을 기본적으로 비활성화하며, `/fast on`은 +`MiniMax-M2.7`을 `MiniMax-M2.7-highspeed`로 재작성합니다. -플러그인 소유 capability 분리: +Plugin 소유 capability 분리: - 텍스트/채팅 기본값은 `minimax/MiniMax-M2.7`에 유지됩니다 - 이미지 생성은 `minimax/image-01` 또는 `minimax-portal/image-01`입니다 -- 이미지 이해는 두 MiniMax 인증 경로 모두에서 플러그인 소유 `MiniMax-VL-01`입니다 -- 웹 검색은 제공자 ID `minimax`에 유지됩니다 +- 이미지 이해는 두 MiniMax 인증 경로 모두에서 Plugin 소유 `MiniMax-VL-01`입니다 +- 웹 검색은 공급자 id `minimax`에 유지됩니다 + +### LM Studio + +LM Studio는 네이티브 API를 사용하는 번들 공급자 Plugin으로 제공됩니다: + +- 공급자: `lmstudio` +- 인증: `LM_API_TOKEN` +- 기본 추론 base URL: `http://localhost:1234/v1` + +그런 다음 모델을 설정하세요(`http://localhost:1234/api/v1/models`에서 반환된 ID 중 하나로 바꾸세요): + +```json5 +{ + agents: { + defaults: { model: { primary: "lmstudio/openai/gpt-oss-20b" } }, + }, +} +``` + +OpenClaw는 탐색 + 자동 로드를 위해 LM Studio의 네이티브 `/api/v1/models`와 `/api/v1/models/load`를 사용하며, 기본적으로 추론에는 `/v1/chat/completions`를 사용합니다. +설정 및 문제 해결은 [/providers/lmstudio](/ko/providers/lmstudio)를 참고하세요. ### Ollama -Ollama는 번들 제공자 플러그인으로 제공되며 Ollama의 네이티브 API를 사용합니다: +Ollama는 번들 공급자 Plugin으로 제공되며 Ollama의 네이티브 API를 사용합니다: -- 제공자: `ollama` +- 공급자: `ollama` - 인증: 필요 없음(로컬 서버) -- 예제 모델: `ollama/llama3.3` +- 예시 모델: `ollama/llama3.3` - 설치: [https://ollama.com/download](https://ollama.com/download) ```bash -# Ollama를 설치한 다음 모델을 가져옵니다: +# Ollama를 설치한 다음 모델을 가져오세요: ollama pull llama3.3 ``` @@ -535,23 +716,26 @@ ollama pull llama3.3 } ``` -`OLLAMA_API_KEY`로 선택적으로 활성화하면 Ollama는 로컬의 `http://127.0.0.1:11434`에서 감지되며, 번들 제공자 플러그인이 Ollama를 `openclaw onboard`와 모델 선택기에 직접 추가합니다. 온보딩, 클라우드/로컬 모드, 사용자 정의 구성은 [/providers/ollama](/ko/providers/ollama)를 참조하세요. +Ollama는 `OLLAMA_API_KEY`로 옵트인하면 로컬의 `http://127.0.0.1:11434`에서 감지되며, +번들 공급자 Plugin이 Ollama를 `openclaw onboard`와 모델 선택기에 직접 추가합니다. 온보딩, 클라우드/로컬 모드, +사용자 지정 구성은 [/providers/ollama](/ko/providers/ollama)를 참고하세요. ### vLLM -vLLM은 로컬/셀프 호스팅 OpenAI 호환 서버를 위한 번들 제공자 플러그인으로 제공됩니다: +vLLM은 로컬/자체 호스팅 OpenAI 호환 +서버를 위한 번들 공급자 Plugin으로 제공됩니다: -- 제공자: `vllm` +- 공급자: `vllm` - 인증: 선택 사항(서버에 따라 다름) - 기본 base URL: `http://127.0.0.1:8000/v1` -로컬 자동 검색에 선택적으로 참여하려면(서버가 인증을 강제하지 않는 경우 어떤 값이든 작동함): +로컬 자동 탐색에 옵트인하려면(서버가 인증을 강제하지 않으면 어떤 값이든 작동함): ```bash export VLLM_API_KEY="vllm-local" ``` -그런 다음 모델을 설정하세요(`/v1/models`가 반환하는 ID 중 하나로 교체): +그런 다음 모델을 설정하세요(`/v1/models`에서 반환된 ID 중 하나로 바꾸세요): ```json5 { @@ -561,23 +745,25 @@ export VLLM_API_KEY="vllm-local" } ``` -자세한 내용은 [/providers/vllm](/ko/providers/vllm)를 참조하세요. +자세한 내용은 [/providers/vllm](/ko/providers/vllm)를 참고하세요. ### SGLang -SGLang은 빠른 셀프 호스팅 OpenAI 호환 서버를 위한 번들 제공자 플러그인으로 제공됩니다: +SGLang은 빠른 자체 호스팅 +OpenAI 호환 서버를 위한 번들 공급자 Plugin으로 제공됩니다: -- 제공자: `sglang` +- 공급자: `sglang` - 인증: 선택 사항(서버에 따라 다름) - 기본 base URL: `http://127.0.0.1:30000/v1` -로컬 자동 검색에 선택적으로 참여하려면(서버가 인증을 강제하지 않는 경우 어떤 값이든 작동함): +로컬 자동 탐색에 옵트인하려면(서버가 인증을 +강제하지 않으면 어떤 값이든 작동함): ```bash export SGLANG_API_KEY="sglang-local" ``` -그런 다음 모델을 설정하세요(`/v1/models`가 반환하는 ID 중 하나로 교체): +그런 다음 모델을 설정하세요(`/v1/models`에서 반환된 ID 중 하나로 바꾸세요): ```json5 { @@ -587,7 +773,7 @@ export SGLANG_API_KEY="sglang-local" } ``` -자세한 내용은 [/providers/sglang](/ko/providers/sglang)를 참조하세요. +자세한 내용은 [/providers/sglang](/ko/providers/sglang)를 참고하세요. ### 로컬 프록시(LM Studio, vLLM, LiteLLM 등) @@ -598,19 +784,19 @@ export SGLANG_API_KEY="sglang-local" agents: { defaults: { model: { primary: "lmstudio/my-local-model" }, - models: { "lmstudio/my-local-model": { alias: "Local" } }, + models: { "lmstudio/my-local-model": { alias: "로컬" } }, }, }, models: { providers: { lmstudio: { baseUrl: "http://localhost:1234/v1", - apiKey: "LMSTUDIO_KEY", + apiKey: "${LM_API_TOKEN}", api: "openai-completions", models: [ { id: "my-local-model", - name: "Local Model", + name: "로컬 모델", reasoning: false, input: ["text"], cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 }, @@ -626,17 +812,20 @@ export SGLANG_API_KEY="sglang-local" 참고: -- 사용자 정의 제공자의 경우 `reasoning`, `input`, `cost`, `contextWindow`, `maxTokens`는 선택 사항입니다. - 생략하면 OpenClaw는 다음 기본값을 사용합니다: +- 사용자 지정 공급자의 경우 `reasoning`, `input`, `cost`, `contextWindow`, `maxTokens`는 선택 사항입니다. + 생략하면 OpenClaw는 기본적으로 다음 값을 사용합니다: - `reasoning: false` - `input: ["text"]` - `cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 }` - `contextWindow: 200000` - `maxTokens: 8192` -- 권장 사항: 프록시/모델 제한에 맞는 명시적 값을 설정하세요. -- 네이티브가 아닌 엔드포인트에서 `api: "openai-completions"`를 사용할 경우(`api.openai.com`이 아닌 호스트를 가진 비어 있지 않은 `baseUrl`), OpenClaw는 지원되지 않는 `developer` 역할로 인한 제공자 400 오류를 방지하기 위해 `compat.supportsDeveloperRole: false`를 강제합니다. -- 프록시 스타일 OpenAI 호환 경로는 네이티브 OpenAI 전용 요청 형상화도 건너뜁니다. 즉, `service_tier`, Responses `store`, 프롬프트 캐시 힌트, OpenAI 추론 호환 페이로드 형상, 숨겨진 OpenClaw attribution 헤더가 없습니다. -- `baseUrl`이 비어 있거나 생략되면 OpenClaw는 기본 OpenAI 동작(`api.openai.com`으로 해석됨)을 유지합니다. +- 권장: 프록시/모델 한도에 맞는 명시적 값을 설정하세요. +- 네이티브가 아닌 엔드포인트에서 `api: "openai-completions"`를 사용하는 경우(`api.openai.com`이 아닌 호스트를 가진 비어 있지 않은 `baseUrl`), OpenClaw는 지원되지 않는 `developer` 역할로 인한 공급자 400 오류를 방지하기 위해 `compat.supportsDeveloperRole: false`를 강제합니다. +- 프록시 스타일 OpenAI 호환 경로도 네이티브 OpenAI 전용 요청 + shaping을 건너뜁니다: `service_tier` 없음, Responses `store` 없음, 프롬프트 캐시 힌트 없음, + OpenAI reasoning 호환 payload shaping 없음, 숨겨진 OpenClaw attribution + 헤더 없음. +- `baseUrl`이 비어 있거나 생략되면 OpenClaw는 기본 OpenAI 동작을 유지합니다(`api.openai.com`으로 확인됨). - 안전을 위해 네이티브가 아닌 `openai-completions` 엔드포인트에서는 명시적인 `compat.supportsDeveloperRole: true`도 계속 재정의됩니다. ## CLI 예시 @@ -647,11 +836,11 @@ openclaw models set opencode/claude-opus-4-6 openclaw models list ``` -참조: 전체 구성 예시는 [/gateway/configuration](/ko/gateway/configuration)을 확인하세요. +추가로 참고하세요: 전체 구성 예시는 [/gateway/configuration](/ko/gateway/configuration)입니다. ## 관련 항목 - [모델](/ko/concepts/models) — 모델 구성 및 별칭 -- [모델 대체](/ko/concepts/model-failover) — 대체 체인 및 재시도 동작 +- [모델 Failover](/ko/concepts/model-failover) — 폴백 체인과 재시도 동작 - [구성 참조](/ko/gateway/configuration-reference#agent-defaults) — 모델 구성 키 -- [제공자](/ko/providers) — 제공자별 설정 가이드 +- [공급자](/ko/providers) — 공급자별 설정 가이드 diff --git a/docs/ko/gateway/local-models.md b/docs/ko/gateway/local-models.md index 26f53ca8c..28ce9e63f 100644 --- a/docs/ko/gateway/local-models.md +++ b/docs/ko/gateway/local-models.md @@ -1,28 +1,28 @@ --- read_when: - - 직접 보유한 GPU 장비에서 모델을 서빙하려는 경우 + - 자신의 GPU 머신에서 모델을 서빙하려는 경우 - LM Studio 또는 OpenAI 호환 프록시를 연결하는 경우 - - 가장 안전한 로컬 모델 가이드를 원하는 경우 -summary: 로컬 LLM에서 OpenClaw 실행하기(LM Studio, vLLM, LiteLLM, 사용자 지정 OpenAI 엔드포인트) + - 가장 안전한 로컬 모델 가이드가 필요한 경우 +summary: 로컬 LLM(LM Studio, vLLM, LiteLLM, 사용자 지정 OpenAI 엔드포인트)에서 OpenClaw 실행하기 title: 로컬 모델 x-i18n: - generated_at: "2026-04-08T02:14:55Z" + generated_at: "2026-04-13T08:50:33Z" model: gpt-5.4 provider: openai - source_hash: d619d72b0e06914ebacb7e9f38b746caf1b9ce8908c9c6638c3acdddbaa025e8 + source_hash: 3ecb61b3e6e34d3666f9b688cd694d92c5fb211cf8c420fa876f7ccf5789154a source_path: gateway/local-models.md workflow: 15 --- # 로컬 모델 -로컬 실행은 가능하지만, OpenClaw는 큰 컨텍스트와 프롬프트 인젝션에 대한 강력한 방어를 전제로 합니다. 작은 카드로는 컨텍스트가 잘리고 안전성이 약해집니다. 기준을 높게 잡으세요: **최대 사양 Mac Studio 2대 이상 또는 동급 GPU 장비(~$30k+)**. 단일 **24 GB** GPU는 더 가벼운 프롬프트에 더 높은 지연 시간을 감수할 때만 실용적입니다. 실행할 수 있는 범위에서 **가장 큰 / 풀사이즈 모델 변형**을 사용하세요. 과도하게 양자화된 체크포인트나 “small” 모델은 프롬프트 인젝션 위험을 높입니다([Security](/ko/gateway/security) 참고). +로컬에서도 가능하지만, OpenClaw는 **큰 컨텍스트**와 프롬프트 인젝션에 대한 **강력한 방어**를 기대합니다. 작은 GPU 카드에서는 컨텍스트가 잘리고 안전성이 약해집니다. 목표는 높게 잡으세요: **최소 2대의 풀옵션 Mac Studio 또는 그에 준하는 GPU 장비(약 $30k 이상)**. **24 GB** GPU 1대로도 가능하긴 하지만, 더 가벼운 프롬프트에서만 가능하며 지연 시간도 더 높습니다. 실행 가능한 범위에서 **가장 크고 전체 크기의 모델 변형**을 사용하세요. 과도하게 양자화된 체크포인트나 “small” 모델은 프롬프트 인젝션 위험을 높입니다([보안](/ko/gateway/security) 참고). -가장 마찰이 적은 로컬 설정을 원한다면 [Ollama](/ko/providers/ollama)와 `openclaw onboard`로 시작하세요. 이 페이지는 고급 로컬 스택과 사용자 지정 OpenAI 호환 로컬 서버를 위한 권장 가이드입니다. +가장 마찰이 적은 로컬 설정을 원한다면 [LM Studio](/ko/providers/lmstudio) 또는 [Ollama](/ko/providers/ollama)로 시작한 뒤 `openclaw onboard`를 실행하세요. 이 페이지는 더 높은 사양의 로컬 스택과 사용자 지정 OpenAI 호환 로컬 서버를 위한 의견이 반영된 가이드입니다. -## 권장: LM Studio + 대형 로컬 모델(Responses API) +## 권장: LM Studio + 대형 로컬 모델 (Responses API) -현재 기준으로 가장 좋은 로컬 스택입니다. LM Studio에 대형 모델(예: 풀사이즈 Qwen, DeepSeek 또는 Llama 빌드)을 로드하고, 로컬 서버(기본값 `http://127.0.0.1:1234`)를 활성화한 뒤, 추론을 최종 텍스트와 분리하기 위해 Responses API를 사용하세요. +현재 기준으로 가장 좋은 로컬 스택입니다. LM Studio에 대형 모델(예: 전체 크기의 Qwen, DeepSeek, 또는 Llama 빌드)을 로드하고, 로컬 서버(기본값 `http://127.0.0.1:1234`)를 활성화한 뒤, Responses API를 사용해 추론과 최종 텍스트를 분리하세요. ```json5 { @@ -62,15 +62,15 @@ x-i18n: **설정 체크리스트** - LM Studio 설치: [https://lmstudio.ai](https://lmstudio.ai) -- LM Studio에서 **가장 큰 모델 빌드**를 다운로드하고(“small”/강한 양자화 변형은 피하세요), 서버를 시작한 다음 `http://127.0.0.1:1234/v1/models`에 모델이 표시되는지 확인하세요. -- `my-local-model`을 LM Studio에 표시되는 실제 모델 ID로 바꾸세요. +- LM Studio에서 **사용 가능한 가장 큰 모델 빌드**를 다운로드하고(“small”/강한 양자화 변형은 피하세요), 서버를 시작한 다음 `http://127.0.0.1:1234/v1/models`에 해당 모델이 표시되는지 확인합니다. +- `my-local-model`을 LM Studio에 표시된 실제 모델 ID로 바꾸세요. - 모델을 계속 로드된 상태로 유지하세요. 콜드 로드는 시작 지연을 추가합니다. -- LM Studio 빌드가 다르면 `contextWindow`/`maxTokens`를 조정하세요. -- WhatsApp에서는 최종 텍스트만 전송되도록 Responses API를 유지하세요. +- LM Studio 빌드가 다르면 `contextWindow`와 `maxTokens`를 조정하세요. +- WhatsApp에서는 최종 텍스트만 전송되도록 Responses API를 사용하세요. -로컬로 실행하더라도 호스팅 모델 구성은 유지하세요. 대체 모델을 계속 사용할 수 있도록 `models.mode: "merge"`를 사용하세요. +로컬로 실행하더라도 호스팅 모델 구성은 유지하세요. `models.mode: "merge"`를 사용하면 폴백이 계속 사용 가능합니다. -### 하이브리드 구성: 호스팅 모델을 기본으로, 로컬을 대체 모델로 +### 하이브리드 구성: 호스팅 모델을 기본으로, 로컬 모델을 폴백으로 ```json5 { @@ -111,18 +111,18 @@ x-i18n: } ``` -### 로컬 우선 + 호스팅 안전망 +### 로컬 우선, 호스팅 모델을 안전망으로 사용 -기본 모델과 대체 모델 순서를 바꾸고, Sonnet 또는 Opus로 대체할 수 있도록 동일한 providers 블록과 `models.mode: "merge"`를 유지하세요. +기본 모델과 폴백 순서를 바꾸면 됩니다. 동일한 providers 블록과 `models.mode: "merge"`를 유지하면 로컬 머신이 내려갔을 때 Sonnet 또는 Opus로 폴백할 수 있습니다. -### 지역 호스팅 / 데이터 라우팅 +### 지역별 호스팅 / 데이터 라우팅 -- 호스팅형 MiniMax/Kimi/GLM 변형은 지역 고정 엔드포인트(예: 미국 호스팅)를 갖춘 OpenRouter에도 존재합니다. 선택한 관할권 안에서 트래픽을 유지하면서도 Anthropic/OpenAI 대체 모델을 계속 쓰려면 해당 지역 변형을 선택하고 `models.mode: "merge"`를 유지하세요. -- 완전한 로컬 전용 구성이 가장 강력한 프라이버시 경로입니다. 호스팅 지역 라우팅은 프로바이더 기능은 필요하지만 데이터 흐름도 통제하고 싶을 때의 중간 선택지입니다. +- 호스팅되는 MiniMax/Kimi/GLM 변형도 OpenRouter에서 지역 고정 엔드포인트(예: 미국 호스팅)로 제공됩니다. 선택한 관할 구역 내에서 트래픽을 유지하려면 해당 지역 변형을 선택하고, Anthropic/OpenAI 폴백은 계속 사용할 수 있도록 `models.mode: "merge"`를 유지하세요. +- 완전한 로컬 전용이 가장 강력한 프라이버시 경로입니다. 호스팅된 지역 라우팅은 공급자 기능이 필요하지만 데이터 흐름을 통제하고 싶을 때의 중간 지점입니다. ## 기타 OpenAI 호환 로컬 프록시 -vLLM, LiteLLM, OAI-proxy 또는 사용자 지정 게이트웨이는 OpenAI 스타일 `/v1` 엔드포인트를 노출한다면 사용할 수 있습니다. 위의 provider 블록을 해당 엔드포인트와 모델 ID로 바꾸세요. +vLLM, LiteLLM, OAI-proxy 또는 사용자 지정 게이트웨이도 OpenAI 스타일의 `/v1` 엔드포인트를 노출하면 사용할 수 있습니다. 위의 provider 블록을 여러분의 엔드포인트와 모델 ID로 바꾸세요. ```json5 { @@ -150,36 +150,25 @@ vLLM, LiteLLM, OAI-proxy 또는 사용자 지정 게이트웨이는 OpenAI 스 } ``` -호스팅 모델을 대체 모델로 계속 사용할 수 있도록 `models.mode: "merge"`를 유지하세요. +호스팅 모델을 폴백으로 계속 사용할 수 있도록 `models.mode: "merge"`를 유지하세요. -로컬/프록시 `/v1` 백엔드 동작 참고 사항: +로컬/프록시 `/v1` 백엔드의 동작 참고 사항: -- OpenClaw는 이를 네이티브 - OpenAI 엔드포인트가 아니라 프록시 스타일 OpenAI 호환 경로로 처리합니다 -- 네이티브 OpenAI 전용 요청 셰이핑은 여기에 적용되지 않습니다. 즉, - `service_tier`, Responses `store`, OpenAI 추론 호환 페이로드 셰이핑, - 프롬프트 캐시 힌트는 사용되지 않습니다 -- 숨겨진 OpenClaw attribution 헤더(`originator`, `version`, `User-Agent`)도 - 이러한 사용자 지정 프록시 URL에는 주입되지 않습니다 +- OpenClaw는 이를 네이티브 OpenAI 엔드포인트가 아니라 프록시 스타일의 OpenAI 호환 경로로 처리합니다. +- 여기에는 OpenAI 전용 요청 형태 조정이 적용되지 않습니다. 즉, `service_tier`, Responses `store`, OpenAI 추론 호환 페이로드 조정, 프롬프트 캐시 힌트가 없습니다. +- 숨겨진 OpenClaw attribution 헤더(`originator`, `version`, `User-Agent`)도 이러한 사용자 지정 프록시 URL에는 주입되지 않습니다. -더 엄격한 OpenAI 호환 백엔드에 대한 호환성 참고 사항: +더 엄격한 OpenAI 호환 백엔드를 위한 호환성 참고 사항: -- 일부 서버는 Chat Completions에서 구조화된 content-part 배열이 아니라 문자열 형태의 `messages[].content`만 허용합니다. - 이런 엔드포인트에는 - `models.providers..models[].compat.requiresStringContent: true`를 설정하세요. -- 더 작거나 더 엄격한 일부 로컬 백엔드는 OpenClaw의 전체 - 에이전트 런타임 프롬프트 형태에 불안정할 수 있으며, 특히 도구 스키마가 포함될 때 그렇습니다. 백엔드가 작은 직접 `/v1/chat/completions` 호출에는 동작하지만 일반적인 - OpenClaw 에이전트 턴에서는 실패한다면 먼저 - `models.providers..models[].compat.supportsTools: false`를 시도하세요. -- 백엔드가 여전히 더 큰 OpenClaw 실행에서만 실패한다면, 남은 문제는 보통 OpenClaw 전송 계층이 아니라 업스트림 모델/서버 용량 또는 백엔드 버그입니다. +- 일부 서버는 Chat Completions에서 구조화된 content-part 배열이 아니라 문자열 `messages[].content`만 허용합니다. 그런 엔드포인트에는 `models.providers..models[].compat.requiresStringContent: true`를 설정하세요. +- 더 작거나 더 엄격한 일부 로컬 백엔드는, 특히 도구 스키마가 포함될 때 OpenClaw의 전체 에이전트 런타임 프롬프트 형태에서 불안정할 수 있습니다. 백엔드가 작은 직접 `/v1/chat/completions` 호출에서는 동작하지만 일반적인 OpenClaw 에이전트 턴에서는 실패한다면, 먼저 `models.providers..models[].compat.supportsTools: false`를 시도하세요. +- 백엔드가 더 큰 OpenClaw 실행에서만 계속 실패한다면, 남은 문제는 보통 OpenClaw의 전송 계층이 아니라 업스트림 모델/서버 용량 또는 백엔드 버그입니다. ## 문제 해결 -- 게이트웨이가 프록시에 도달할 수 있나요? `curl http://127.0.0.1:1234/v1/models`. -- LM Studio 모델이 언로드되었나요? 다시 로드하세요. 콜드 스타트는 흔한 “멈춤” 원인입니다. -- 컨텍스트 오류가 있나요? `contextWindow`를 낮추거나 서버 한도를 높이세요. -- OpenAI 호환 서버가 `messages[].content ... expected a string`을 반환하나요? - 해당 모델 항목에 `compat.requiresStringContent: true`를 추가하세요. -- 직접적인 작은 `/v1/chat/completions` 호출은 동작하지만 `openclaw infer model run`이 Gemma 또는 다른 로컬 모델에서 실패하나요? 먼저 - `compat.supportsTools: false`로 도구 스키마를 비활성화한 다음 다시 테스트하세요. 서버가 여전히 더 큰 OpenClaw 프롬프트에서만 크래시한다면, 업스트림 서버/모델 제한으로 간주하세요. -- 안전: 로컬 모델은 프로바이더 측 필터를 건너뜁니다. 프롬프트 인젝션 영향 범위를 제한하려면 에이전트 범위를 좁게 유지하고 compaction을 켜두세요. +- Gateway가 프록시에 연결 가능한가요? `curl http://127.0.0.1:1234/v1/models`. +- LM Studio 모델이 언로드되었나요? 다시 로드하세요. 콜드 스타트는 “멈춘 것처럼 보이는” 흔한 원인입니다. +- 컨텍스트 오류가 나나요? `contextWindow`를 낮추거나 서버 제한을 올리세요. +- OpenAI 호환 서버가 `messages[].content ... expected a string`을 반환하나요? 해당 모델 항목에 `compat.requiresStringContent: true`를 추가하세요. +- 작은 직접 `/v1/chat/completions` 호출은 동작하지만 `openclaw infer model run`이 Gemma 또는 다른 로컬 모델에서 실패하나요? 먼저 `compat.supportsTools: false`로 도구 스키마를 비활성화한 뒤 다시 테스트하세요. 서버가 더 큰 OpenClaw 프롬프트에서만 계속 충돌한다면, 이를 업스트림 서버/모델 제한으로 취급하세요. +- 안전성: 로컬 모델은 공급자 측 필터를 건너뜁니다. 프롬프트 인젝션의 영향 범위를 제한하려면 에이전트 범위를 좁게 유지하고 Compaction을 켜 두세요. diff --git a/docs/ko/providers/index.md b/docs/ko/providers/index.md index 40d089a38..c3aa46dcf 100644 --- a/docs/ko/providers/index.md +++ b/docs/ko/providers/index.md @@ -1,28 +1,28 @@ --- read_when: - - 모델 제공자를 선택하고 싶을 때 - - 지원되는 LLM 백엔드의 빠른 개요가 필요할 때 -summary: OpenClaw가 지원하는 모델 제공자(LLM) + - 모델 제공자를 선택하려고 합니다 + - 지원되는 LLM 백엔드를 빠르게 개요로 확인해야 합니다 +summary: OpenClaw에서 지원하는 모델 제공자(LLM) title: 제공자 디렉터리 x-i18n: - generated_at: "2026-04-08T02:17:34Z" + generated_at: "2026-04-13T08:50:34Z" model: gpt-5.4 provider: openai - source_hash: e7bee5528b7fc9a982b3d0eaa4930cb77f7bded19a47aec00572b6fcbd823a70 + source_hash: 3bc682d008119719826f71f74959ab32bedf14214459f5e6ac9cb70371d3c540 source_path: providers/index.md workflow: 15 --- # 모델 제공자 -OpenClaw는 많은 LLM 제공자를 사용할 수 있습니다. 제공자를 선택하고 인증한 다음, -기본 모델을 `provider/model`로 설정하세요. +OpenClaw은 많은 LLM 제공자를 사용할 수 있습니다. 제공자를 선택하고 인증한 다음, +기본 모델을 `provider/model` 형식으로 설정하세요. 채팅 채널 문서(WhatsApp/Telegram/Discord/Slack/Mattermost (plugin)/기타)를 찾고 있나요? [채널](/ko/channels)을 참조하세요. ## 빠른 시작 -1. 제공자로 인증합니다(보통 `openclaw onboard` 사용). +1. 제공자에서 인증합니다(보통 `openclaw onboard`를 통해 수행). 2. 기본 모델을 설정합니다: ```json5 @@ -36,7 +36,7 @@ OpenClaw는 많은 LLM 제공자를 사용할 수 있습니다. 제공자를 선 - [Alibaba Model Studio](/ko/providers/alibaba) - [Amazon Bedrock](/ko/providers/bedrock) - [Anthropic (API + Claude CLI)](/ko/providers/anthropic) -- [Arcee AI (Trinity 모델)](/ko/providers/arcee) +- [Arcee AI (Trinity models)](/ko/providers/arcee) - [BytePlus (International)](/ko/concepts/model-providers#byteplus-international) - [Chutes](/ko/providers/chutes) - [ComfyUI](/ko/providers/comfy) @@ -51,7 +51,8 @@ OpenClaw는 많은 LLM 제공자를 사용할 수 있습니다. 제공자를 선 - [Hugging Face (추론)](/ko/providers/huggingface) - [inferrs (로컬 모델)](/ko/providers/inferrs) - [Kilocode](/ko/providers/kilocode) -- [LiteLLM (통합 gateway)](/ko/providers/litellm) +- [LiteLLM (통합 게이트웨이)](/ko/providers/litellm) +- [LM Studio (로컬 모델)](/ko/providers/lmstudio) - [MiniMax](/ko/providers/minimax) - [Mistral](/ko/providers/mistral) - [Moonshot AI (Kimi + Kimi Coding)](/ko/providers/moonshot) @@ -81,9 +82,9 @@ OpenClaw는 많은 LLM 제공자를 사용할 수 있습니다. 제공자를 선 ## 공통 개요 페이지 - [추가 번들 변형](/ko/providers/models#additional-bundled-provider-variants) - Anthropic Vertex, Copilot Proxy, Gemini CLI OAuth -- [이미지 생성](/ko/tools/image-generation) - 공통 `image_generate` 도구, 제공자 선택, 장애 조치 -- [음악 생성](/ko/tools/music-generation) - 공통 `music_generate` 도구, 제공자 선택, 장애 조치 -- [비디오 생성](/ko/tools/video-generation) - 공통 `video_generate` 도구, 제공자 선택, 장애 조치 +- [이미지 생성](/ko/tools/image-generation) - 공통 `image_generate` 도구, 제공자 선택 및 장애 조치 +- [음악 생성](/ko/tools/music-generation) - 공통 `music_generate` 도구, 제공자 선택 및 장애 조치 +- [비디오 생성](/ko/tools/video-generation) - 공통 `video_generate` 도구, 제공자 선택 및 장애 조치 ## 전사 제공자 @@ -91,7 +92,7 @@ OpenClaw는 많은 LLM 제공자를 사용할 수 있습니다. 제공자를 선 ## 커뮤니티 도구 -- [Claude Max API Proxy](/ko/providers/claude-max-api-proxy) - Claude 구독 자격 증명을 위한 커뮤니티 프록시(사용 전 Anthropic 정책/약관을 확인하세요) +- [Claude Max API Proxy](/ko/providers/claude-max-api-proxy) - Claude 구독 자격 증명을 위한 커뮤니티 프록시(사용 전에 Anthropic 정책/약관을 확인하세요) -전체 제공자 카탈로그(xAI, Groq, Mistral 등)와 고급 설정은 +전체 제공자 카탈로그(xAI, Groq, Mistral 등)와 고급 구성은 [모델 제공자](/ko/concepts/model-providers)를 참조하세요. diff --git a/docs/ko/providers/lmstudio.md b/docs/ko/providers/lmstudio.md new file mode 100644 index 000000000..8be3222e3 --- /dev/null +++ b/docs/ko/providers/lmstudio.md @@ -0,0 +1,163 @@ +--- +read_when: + - LM Studio를 통해 오픈 소스 모델로 OpenClaw를 실행하려고 합니다. + - LM Studio를 설정하고 구성하려고 합니다. +summary: LM Studio로 OpenClaw 실행하기 +title: LM Studio +x-i18n: + generated_at: "2026-04-13T08:50:38Z" + model: gpt-5.4 + provider: openai + source_hash: 11264584e8277260d4215feb7c751329ce04f59e9228da1c58e147c21cd9ac2c + source_path: providers/lmstudio.md + workflow: 15 +--- + +# LM Studio + +LM Studio는 자체 하드웨어에서 오픈 웨이트 모델을 실행할 수 있게 해주는 친숙하면서도 강력한 앱입니다. llama.cpp (GGUF) 또는 MLX 모델(Apple Silicon)을 실행할 수 있습니다. GUI 패키지 또는 헤드리스 데몬(`llmster`)으로 제공됩니다. 제품 및 설정 문서는 [lmstudio.ai](https://lmstudio.ai/)를 참고하세요. + +## 빠른 시작 + +1. LM Studio(데스크톱) 또는 `llmster`(헤드리스)를 설치한 다음, 로컬 서버를 시작합니다. + +```bash +curl -fsSL https://lmstudio.ai/install.sh | bash +``` + +2. 서버 시작 + +데스크톱 앱을 시작했거나 아래 명령으로 데몬을 실행했는지 확인하세요. + +```bash +lms daemon up +``` + +```bash +lms server start --port 1234 +``` + +앱을 사용하는 경우, 원활한 사용을 위해 JIT가 활성화되어 있는지 확인하세요. 자세한 내용은 [LM Studio JIT and TTL guide](https://lmstudio.ai/docs/developer/core/ttl-and-auto-evict)를 참고하세요. + +3. OpenClaw는 LM Studio 토큰 값이 필요합니다. `LM_API_TOKEN`을 설정하세요. + +```bash +export LM_API_TOKEN="your-lm-studio-api-token" +``` + +LM Studio 인증이 비활성화된 경우, 비어 있지 않은 아무 토큰 값이나 사용하세요. + +```bash +export LM_API_TOKEN="placeholder-key" +``` + +LM Studio 인증 설정에 대한 자세한 내용은 [LM Studio Authentication](https://lmstudio.ai/docs/developer/core/authentication)을 참고하세요. + +4. 온보딩을 실행하고 `LM Studio`를 선택합니다. + +```bash +openclaw onboard +``` + +5. 온보딩에서 `Default model` 프롬프트를 사용해 LM Studio 모델을 선택합니다. + +나중에 설정하거나 변경할 수도 있습니다. + +```bash +openclaw models set lmstudio/qwen/qwen3.5-9b +``` + +LM Studio 모델 키는 `author/model-name` 형식을 따릅니다(예: `qwen/qwen3.5-9b`). OpenClaw 모델 참조는 공급자 이름이 앞에 붙습니다: `lmstudio/qwen/qwen3.5-9b`. 정확한 모델 키는 `curl http://localhost:1234/api/v1/models`를 실행한 뒤 `key` 필드를 확인하면 찾을 수 있습니다. + +## 비대화형 온보딩 + +설정을 스크립트로 처리하려는 경우(CI, 프로비저닝, 원격 부트스트랩) 비대화형 온보딩을 사용하세요. + +```bash +openclaw onboard \ + --non-interactive \ + --accept-risk \ + --auth-choice lmstudio +``` + +또는 API 키와 함께 base URL 또는 모델을 지정할 수 있습니다. + +```bash +openclaw onboard \ + --non-interactive \ + --accept-risk \ + --auth-choice lmstudio \ + --custom-base-url http://localhost:1234/v1 \ + --lmstudio-api-key "$LM_API_TOKEN" \ + --custom-model-id qwen/qwen3.5-9b +``` + +`--custom-model-id`는 `lmstudio/` 공급자 접두사 없이, LM Studio가 반환한 모델 키(예: `qwen/qwen3.5-9b`)를 받습니다. + +비대화형 온보딩에는 `--lmstudio-api-key`(또는 환경 변수의 `LM_API_TOKEN`)가 필요합니다. +인증되지 않은 LM Studio 서버의 경우, 비어 있지 않은 아무 토큰 값이나 사용할 수 있습니다. + +호환성을 위해 `--custom-api-key`도 계속 지원되지만, LM Studio에는 `--lmstudio-api-key` 사용을 권장합니다. + +이 과정은 `models.providers.lmstudio`를 기록하고, 기본 모델을 +`lmstudio/`로 설정하며, `lmstudio:default` 인증 프로필을 기록합니다. + +대화형 설정에서는 선택 사항인 선호 로드 컨텍스트 길이를 물어볼 수 있으며, 저장되는 감지된 LM Studio 모델 전반에 걸쳐 이를 config에 적용합니다. + +## 구성 + +### 명시적 구성 + +```json5 +{ + models: { + providers: { + lmstudio: { + baseUrl: "http://localhost:1234/v1", + apiKey: "${LM_API_TOKEN}", + api: "openai-completions", + models: [ + { + id: "qwen/qwen3-coder-next", + name: "Qwen 3 Coder Next", + reasoning: false, + input: ["text"], + cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 }, + contextWindow: 128000, + maxTokens: 8192, + }, + ], + }, + }, + }, +} +``` + +## 문제 해결 + +### LM Studio가 감지되지 않음 + +LM Studio가 실행 중인지, 그리고 `LM_API_TOKEN`을 설정했는지 확인하세요(인증되지 않은 서버의 경우, 비어 있지 않은 아무 토큰 값이나 사용할 수 있습니다). + +```bash +# 데스크톱 앱으로 시작하거나, 헤드리스로 시작: +lms server start --port 1234 +``` + +API에 접근할 수 있는지 확인하세요. + +```bash +curl http://localhost:1234/api/v1/models +``` + +### 인증 오류 (HTTP 401) + +설정 중 HTTP 401이 보고되면 API 키를 확인하세요. + +- `LM_API_TOKEN`이 LM Studio에 구성된 키와 일치하는지 확인하세요. +- LM Studio 인증 설정에 대한 자세한 내용은 [LM Studio Authentication](https://lmstudio.ai/docs/developer/core/authentication)을 참고하세요. +- 서버에 인증이 필요하지 않은 경우, `LM_API_TOKEN`에 비어 있지 않은 아무 토큰 값이나 사용하세요. + +### 적시 모델 로딩 + +LM Studio는 첫 요청 시 모델을 로드하는 적시(JIT) 모델 로딩을 지원합니다. `'Model not loaded'` 오류를 방지하려면 이 기능이 활성화되어 있는지 확인하세요. diff --git a/docs/ko/reference/api-usage-costs.md b/docs/ko/reference/api-usage-costs.md index 7a443b924..c41bba867 100644 --- a/docs/ko/reference/api-usage-costs.md +++ b/docs/ko/reference/api-usage-costs.md @@ -1,96 +1,85 @@ --- read_when: - - 어떤 기능이 유료 API를 호출할 수 있는지 이해하려고 합니다 - - 키, 비용, 사용량 가시성을 점검해야 합니다 - - /status 또는 /usage 비용 보고를 설명하고 있습니다 -summary: 어떤 기능이 비용을 발생시킬 수 있는지, 어떤 키가 사용되는지, 그리고 사용량을 확인하는 방법을 점검합니다 + - 유료 API를 호출할 수 있는 기능이 무엇인지 파악하고 싶습니다 + - 키, 비용, 그리고 사용량 가시성을 감사해야 합니다 + - '`/status` 또는 `/usage` 비용 보고를 설명하고 있습니다' +summary: 무엇이 비용을 발생시킬 수 있는지, 어떤 키가 사용되는지, 그리고 사용량을 확인하는 방법을 감사하세요 title: API 사용량 및 비용 x-i18n: - generated_at: "2026-04-07T06:00:59Z" + generated_at: "2026-04-13T08:50:33Z" model: gpt-5.4 provider: openai - source_hash: ab6eefcde9ac014df6cdda7aaa77ef48f16936ab12eaa883d9fe69425a31a2dd + source_hash: f5077e74d38ef781ac7a72603e9f9e3829a628b95c5a9967915ab0f321565429 source_path: reference/api-usage-costs.md workflow: 15 --- # API 사용량 및 비용 -이 문서는 **API 키를 호출할 수 있는 기능**과 해당 비용이 어디에 표시되는지 나열합니다. 이 문서는 -provider 사용량 또는 유료 API 호출을 생성할 수 있는 OpenClaw 기능에 중점을 둡니다. +이 문서는 **API 키를 호출할 수 있는 기능**과 해당 비용이 어디에 표시되는지를 정리합니다. 이 문서는 +provider 사용량이나 유료 API 호출을 발생시킬 수 있는 OpenClaw 기능에 초점을 맞춥니다. -## 비용이 표시되는 위치(채팅 + CLI) +## 비용이 표시되는 위치 (채팅 + CLI) **세션별 비용 스냅샷** - `/status`는 현재 세션 모델, 컨텍스트 사용량, 마지막 응답 토큰을 표시합니다. -- 모델이 **API 키 인증**을 사용하는 경우 `/status`는 마지막 응답의 **예상 비용**도 표시합니다. -- 라이브 세션 메타데이터가 부족한 경우 `/status`는 최신 transcript 사용량 항목에서 토큰/캐시 - 카운터와 활성 런타임 모델 라벨을 복구할 수 있습니다. 기존의 0이 아닌 라이브 값이 여전히 우선하며, - 저장된 총계가 없거나 더 작은 경우 프롬프트 크기의 transcript 총계가 우선될 수 있습니다. +- 모델이 **API 키 인증**을 사용하는 경우 `/status`는 마지막 응답에 대한 **추정 비용**도 표시합니다. +- 라이브 세션 메타데이터가 충분하지 않으면 `/status`는 최신 transcript usage + 항목에서 토큰/캐시 카운터와 활성 runtime 모델 레이블을 복구할 수 있습니다. 기존의 0이 아닌 라이브 값이 여전히 우선하며, 저장된 총계가 없거나 더 작을 때는 prompt 크기의 transcript 총계가 우선될 수 있습니다. -**메시지별 비용 바닥글** +**메시지별 비용 푸터** -- `/usage full`은 모든 응답에 사용량 바닥글을 추가하며, 여기에 **예상 비용**이 포함됩니다(API 키 전용). -- `/usage tokens`는 토큰만 표시합니다. 구독형 OAuth/토큰 및 CLI 흐름은 달러 비용을 숨깁니다. -- Gemini CLI 참고: CLI가 JSON 출력을 반환하면 OpenClaw는 `stats`에서 사용량을 읽고, - `stats.cached`를 `cacheRead`로 정규화하며, 필요할 때 - `stats.input_tokens - stats.cached`에서 입력 토큰을 계산합니다. +- `/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`에 표시할 수 있는 메시지별 달러 예상치를 노출하지 않습니다. +Anthropic 참고: Anthropic 직원이 OpenClaw 스타일 Claude CLI 사용이 다시 허용된다고 알려왔으므로, Anthropic이 새 정책을 발표하지 않는 한 OpenClaw는 Claude CLI 재사용 및 `claude -p` 사용을 이 통합에서 허용된 것으로 취급합니다. +Anthropic은 여전히 OpenClaw가 `/usage full`에 표시할 수 있는 메시지별 달러 추정치를 제공하지 않습니다. -**CLI 사용량 창(provider 할당량)** +**CLI 사용량 기간(provider 할당량)** -- `openclaw status --usage`와 `openclaw channels list`는 provider **사용량 창** +- `openclaw status --usage`와 `openclaw channels list`는 provider **사용량 기간** (메시지별 비용이 아닌 할당량 스냅샷)을 표시합니다. -- 사람이 읽는 출력은 provider 전반에서 `X% 남음` 형식으로 정규화됩니다. -- 현재 사용량 창 provider: Anthropic, GitHub Copilot, Gemini CLI, +- 사람이 읽는 출력은 provider 전반에 걸쳐 `X% 남음` 형식으로 정규화됩니다. +- 현재 사용량 기간 provider: Anthropic, GitHub Copilot, Gemini CLI, OpenAI Codex, MiniMax, Xiaomi, z.ai. -- MiniMax 참고: 원시 `usage_percent` / `usagePercent` 필드는 남은 - 할당량을 의미하므로 OpenClaw는 표시 전에 이를 반전합니다. 개수 기반 필드가 있으면 여전히 그것이 우선합니다. - provider가 `model_remains`를 반환하면 OpenClaw는 채팅 모델 항목을 우선하며, - 필요할 때 타임스탬프에서 창 라벨을 계산하고, 플랜 라벨에 모델 이름을 포함합니다. -- 이러한 할당량 창의 사용량 인증은 가능할 때 provider별 훅에서 가져오며, - 그렇지 않으면 OpenClaw는 auth profile, env 또는 config에서 일치하는 OAuth/API 키 - 자격 증명으로 대체합니다. +- 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`). +- **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..apiKey`) - 스킬 프로세스 env로 키를 내보낼 수 있습니다. +- **Skills** (`skills.entries..apiKey`) — 키를 skill 프로세스 env로 내보낼 수 있습니다. ## 키 비용이 발생할 수 있는 기능 -### 1) 코어 모델 응답(채팅 + 도구) +### 1) 코어 모델 응답 (채팅 + 도구) 모든 응답 또는 도구 호출은 **현재 모델 provider**(OpenAI, Anthropic 등)를 사용합니다. 이것이 사용량과 비용의 주요 원인입니다. -여기에는 OpenClaw의 로컬 UI 밖에서 여전히 비용이 청구되는 구독형 호스팅 provider도 포함됩니다. -예: **OpenAI Codex**, **Alibaba Cloud Model Studio -Coding Plan**, **MiniMax Coding Plan**, **Z.AI / GLM Coding Plan**, -그리고 **Extra Usage**가 활성화된 Anthropic의 OpenClaw Claude 로그인 경로. +여기에는 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 경로가 있습니다. -가격 config는 [모델](/ko/providers/models)을, 표시 방식은 [토큰 사용량 및 비용](/ko/reference/token-use)을 참조하세요. +표시 방식은 [Models](/ko/providers/models)의 가격 설정과 [토큰 사용량 및 비용](/ko/reference/token-use)을 참조하세요. -### 2) 미디어 이해(오디오/이미지/비디오) +### 2) 미디어 이해 (오디오/이미지/비디오) -수신된 미디어는 응답 실행 전에 요약되거나 전사될 수 있습니다. 이 과정은 모델/provider API를 사용합니다. +수신된 미디어는 응답이 실행되기 전에 요약/전사될 수 있습니다. 이 과정에서 모델/provider API를 사용합니다. -- 오디오: OpenAI / Groq / Deepgram / Google / Mistral -- 이미지: OpenAI / OpenRouter / Anthropic / Google / MiniMax / Moonshot / Qwen / Z.AI -- 비디오: Google / Qwen / Moonshot +- 오디오: OpenAI / Groq / Deepgram / Google / Mistral. +- 이미지: OpenAI / OpenRouter / Anthropic / Google / MiniMax / Moonshot / Qwen / Z.AI. +- 비디오: Google / Qwen / Moonshot. [미디어 이해](/ko/nodes/media-understanding)를 참조하세요. @@ -101,67 +90,67 @@ Coding Plan**, **MiniMax Coding Plan**, **Z.AI / GLM Coding Plan**, - 이미지 생성: OpenAI / Google / fal / MiniMax - 비디오 생성: Qwen -이미지 생성은 -`agents.defaults.imageGenerationModel`이 설정되지 않은 경우 인증 기반 provider 기본값을 추론할 수 있습니다. 현재 비디오 생성은 +`agents.defaults.imageGenerationModel`이 설정되지 않은 경우 +이미지 생성은 auth 기반 provider 기본값을 추론할 수 있습니다. 현재 비디오 생성은 `qwen/wan2.6-t2v`와 같은 명시적인 `agents.defaults.videoGenerationModel`이 필요합니다. [이미지 생성](/ko/tools/image-generation), [Qwen Cloud](/ko/providers/qwen), -[모델](/ko/concepts/models)을 참조하세요. +[Models](/ko/concepts/models)를 참조하세요. ### 4) 메모리 임베딩 + 시맨틱 검색 -시맨틱 메모리 검색은 원격 provider용으로 구성된 경우 **임베딩 API**를 사용합니다. +시맨틱 메모리 검색은 원격 provider로 구성된 경우 **임베딩 API**를 사용합니다. - `memorySearch.provider = "openai"` → OpenAI 임베딩 - `memorySearch.provider = "gemini"` → Gemini 임베딩 - `memorySearch.provider = "voyage"` → Voyage 임베딩 - `memorySearch.provider = "mistral"` → Mistral 임베딩 -- `memorySearch.provider = "ollama"` → Ollama 임베딩(로컬/자체 호스팅, 일반적으로 호스팅 API 과금 없음) -- 로컬 임베딩 실패 시 원격 provider로 선택적 대체 가능 +- `memorySearch.provider = "lmstudio"` → LM Studio 임베딩 (로컬/셀프 호스팅) +- `memorySearch.provider = "ollama"` → Ollama 임베딩 (로컬/셀프 호스팅, 일반적으로 hosted API 과금 없음) +- 로컬 임베딩이 실패할 경우 선택적으로 원격 provider로 대체 가능 -`memorySearch.provider = "local"`로 유지하면 로컬에서만 동작합니다(API 사용 없음). +`memorySearch.provider = "local"`로 설정하면 로컬로 유지할 수 있습니다(API 사용 없음). -[메모리](/ko/concepts/memory)를 참조하세요. +[Memory](/ko/concepts/memory)를 참조하세요. ### 5) 웹 검색 도구 -`web_search`는 provider에 따라 사용량 요금이 발생할 수 있습니다. +`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 인증도 재사용할 수 있습니다. -- **Perplexity Search API**: `PERPLEXITY_API_KEY`, `OPENROUTER_API_KEY` 또는 `plugins.entries.perplexity.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`(키 없음/자체 호스팅, 호스팅 API 과금 없음) +- **SearXNG**: `SEARXNG_BASE_URL` 또는 `plugins.entries.searxng.config.webSearch.baseUrl` (키 없음/셀프 호스팅, hosted API 과금 없음) -레거시 `tools.web.search.*` provider 경로는 여전히 임시 호환성 shim을 통해 로드되지만, 더 이상 권장되는 config 표면은 아닙니다. +레거시 `tools.web.search.*` provider 경로도 임시 호환성 shim을 통해 여전히 로드되지만, 더 이상 권장되는 config 표면은 아닙니다. **Brave Search 무료 크레딧:** 각 Brave 요금제에는 매월 갱신되는 -\$5/월 무료 크레딧이 포함됩니다. Search 요금제는 요청 1,000건당 \$5이므로, 이 크레딧으로 -월 1,000건 요청을 무료로 처리할 수 있습니다. 예기치 않은 요금을 방지하려면 Brave 대시보드에서 -사용량 한도를 설정하세요. +\$5의 무료 크레딧이 포함됩니다. Search 요금제 비용은 요청 1,000건당 \$5이므로, 이 크레딧으로 +매월 1,000건의 요청을 무료로 처리할 수 있습니다. 예상치 못한 과금을 방지하려면 Brave 대시보드에서 사용 한도를 설정하세요. [웹 도구](/ko/tools/web)를 참조하세요. -### 5) 웹 가져오기 도구(Firecrawl) +### 5) 웹 가져오기 도구 (Firecrawl) `web_fetch`는 API 키가 있으면 **Firecrawl**을 호출할 수 있습니다. - `FIRECRAWL_API_KEY` 또는 `plugins.entries.firecrawl.config.webFetch.apiKey` -Firecrawl이 구성되지 않은 경우 이 도구는 직접 fetch + readability로 대체됩니다(유료 API 없음). +Firecrawl이 구성되지 않았으면 이 도구는 직접 fetch + readability로 대체됩니다(유료 API 없음). [웹 도구](/ko/tools/web)를 참조하세요. -### 6) provider 사용량 스냅샷(status/health) +### 6) Provider 사용량 스냅샷 (상태/헬스) -일부 상태 명령은 할당량 창 또는 인증 상태를 표시하기 위해 **provider 사용량 엔드포인트**를 호출합니다. +일부 상태 명령은 할당량 기간이나 인증 상태를 표시하기 위해 **provider 사용량 엔드포인트**를 호출합니다. 이들은 일반적으로 호출량이 적지만 여전히 provider API를 호출합니다. - `openclaw status --usage` @@ -169,12 +158,12 @@ Firecrawl이 구성되지 않은 경우 이 도구는 직접 fetch + readability [Models CLI](/cli/models)를 참조하세요. -### 7) 압축 보호 요약 +### 7) Compaction 안전장치 요약 -압축 보호 기능은 **현재 모델**을 사용해 세션 기록을 요약할 수 있으며, -실행될 때 provider API를 호출합니다. +Compaction 안전장치는 세션 기록을 **현재 모델**로 요약할 수 있으며, +실행 시 provider API를 호출합니다. -[세션 관리 + 압축](/ko/reference/session-management-compaction)을 참조하세요. +[세션 관리 + Compaction](/ko/reference/session-management-compaction)을 참조하세요. ### 8) 모델 스캔 / 프로브 @@ -183,17 +172,17 @@ Firecrawl이 구성되지 않은 경우 이 도구는 직접 fetch + readability [Models CLI](/cli/models)를 참조하세요. -### 9) Talk(음성) +### 9) Talk (음성) Talk 모드는 구성된 경우 **ElevenLabs**를 호출할 수 있습니다. - `ELEVENLABS_API_KEY` 또는 `talk.providers.elevenlabs.apiKey` -[Talk 모드](/ko/nodes/talk)를 참조하세요. +[Talk mode](/ko/nodes/talk)를 참조하세요. -### 10) Skills(서드파티 API) +### 10) Skills (서드파티 API) -Skills는 `skills.entries..apiKey`에 `apiKey`를 저장할 수 있습니다. 스킬이 이 키를 외부 -API에 사용하면 해당 스킬 provider의 정책에 따라 비용이 발생할 수 있습니다. +Skills는 `skills.entries..apiKey`에 `apiKey`를 저장할 수 있습니다. skill이 해당 키를 외부 +API에 사용하면, 그 skill의 provider에 따라 비용이 발생할 수 있습니다. [Skills](/ko/tools/skills)를 참조하세요.