Hugging Face (Inference)

Hugging Face Inference Providers는 단일 라우터 API를 통해 OpenAI 호환 채팅 완성을 제공합니다. 하나의 토큰으로 다양한 모델(DeepSeek, Llama 등)에 접근할 수 있습니다. OpenClaw는 OpenAI 호환 엔드포인트(채팅 완성만 지원)를 사용하며, 텍스트-이미지 변환, 임베딩, 음성 처리는 HF inference 클라이언트를 직접 사용하세요.

  • 프로바이더: huggingface
  • 인증: HUGGINGFACE_HUB_TOKEN 또는 HF_TOKEN (Make calls to Inference Providers 권한이 있는 세분화된 토큰)
  • API: OpenAI 호환 (https://router.huggingface.co/v1)
  • 과금: 단일 HF 토큰; 가격은 프로바이더 요금을 따르며 무료 티어가 있습니다.

빠른 시작

  1. Hugging Face → Settings → Tokens에서 Make calls to Inference Providers 권한이 있는 세분화된 토큰을 생성합니다.
  2. 온보딩을 실행하고 프로바이더 드롭다운에서 Hugging Face를 선택한 후, 프롬프트에 따라 API 키를 입력합니다:
openclaw onboard --auth-choice huggingface-api-key
  1. Default Hugging Face model 드롭다운에서 원하는 모델을 선택합니다(유효한 토큰이 있으면 Inference API에서 목록을 불러오고, 그렇지 않으면 내장 목록이 표시됩니다). 선택한 모델이 기본 모델로 저장됩니다.
  2. 나중에 설정에서 기본 모델을 변경하거나 지정할 수도 있습니다:
{
  agents: {
    defaults: {
      model: { primary: "huggingface/deepseek-ai/DeepSeek-R1" },
    },
  },
}

비대화형 예시

openclaw onboard --non-interactive \
  --mode local \
  --auth-choice huggingface-api-key \
  --huggingface-api-key "$HF_TOKEN"

기본 모델로 huggingface/deepseek-ai/DeepSeek-R1이 설정됩니다.

환경 참고 사항

Gateway가 데몬(launchd/systemd)으로 실행되는 경우, 해당 프로세스에서 HUGGINGFACE_HUB_TOKEN 또는 HF_TOKEN을 사용할 수 있는지 확인하세요(예: ~/.openclaw/.env 또는 env.shellEnv를 통해).

모델 검색 및 온보딩 드롭다운

OpenClaw는 Inference 엔드포인트를 직접 호출하여 모델을 검색합니다:

GET https://router.huggingface.co/v1/models

(선택 사항: 전체 목록을 보려면 Authorization: Bearer $HUGGINGFACE_HUB_TOKEN 또는 $HF_TOKEN을 전송하세요. 일부 엔드포인트는 인증 없이 부분 목록만 반환합니다.) 응답은 OpenAI 스타일 { "object": "list", "data": [ { "id": "Qwen/Qwen3-8B", "owned_by": "Qwen", ... }, ... ] }입니다.

Hugging Face API 키를 설정하면(온보딩, HUGGINGFACE_HUB_TOKEN 또는 HF_TOKEN 경유) OpenClaw는 이 GET 요청으로 사용 가능한 채팅 완성 모델을 검색합니다. 대화형 온보딩 중에 토큰을 입력하면 해당 목록에서 채워진 Default Hugging Face model 드롭다운이 표시됩니다(요청 실패 시 내장 카탈로그 사용). 런타임(예: Gateway 시작 시)에 키가 있으면 OpenClaw는 다시 GET https://router.huggingface.co/v1/models를 호출하여 카탈로그를 갱신합니다. 목록은 내장 카탈로그(컨텍스트 윈도우, 비용 등의 메타데이터 포함)와 병합됩니다. 요청이 실패하거나 키가 설정되지 않은 경우 내장 카탈로그만 사용됩니다.

모델 이름 및 편집 가능한 옵션

  • API에서 가져온 이름: API가 name, title 또는 display_name을 반환하면 모델 표시 이름은 GET /v1/models에서 가져온 값이 사용되며, 그렇지 않으면 모델 ID에서 파생됩니다(예: deepseek-ai/DeepSeek-R1 → “DeepSeek R1”).
  • 표시 이름 재정의: 설정에서 모델별 커스텀 라벨을 지정하여 CLI와 UI에서 원하는 대로 표시할 수 있습니다:
{
  agents: {
    defaults: {
      models: {
        "huggingface/deepseek-ai/DeepSeek-R1": { alias: "DeepSeek R1 (fast)" },
        "huggingface/deepseek-ai/DeepSeek-R1:cheapest": { alias: "DeepSeek R1 (cheap)" },
      },
    },
  },
}

  • 프로바이더 / 정책 선택: 모델 ID에 접미사를 추가하여 라우터의 백엔드 선택 방식을 지정합니다:

    • :fastest — 최고 처리량 (라우터가 선택; 프로바이더 선택이 고정 — 대화형 백엔드 선택기 없음).
    • :cheapest — 출력 토큰당 최저 비용 (라우터가 선택; 프로바이더 선택이 고정).
    • :provider — 특정 백엔드 강제 지정 (예: :sambanova, :together).

    :cheapest 또는 :fastest를 선택하면(예: 온보딩 모델 드롭다운에서) 프로바이더가 고정됩니다: 라우터가 비용 또는 속도 기준으로 결정하며 “특정 백엔드 선호” 단계가 표시되지 않습니다. 이들을 models.providers.huggingface.models의 별도 항목으로 추가하거나 model.primary에 접미사를 붙여 설정할 수 있습니다. Inference Provider 설정에서 기본 순서를 지정할 수도 있습니다(접미사 없음 = 해당 순서 사용).

  • 설정 병합: models.providers.huggingface.models의 기존 항목(예: models.json 내)은 설정 병합 시 유지됩니다. 따라서 설정한 커스텀 name, alias 또는 모델 옵션이 보존됩니다.

모델 ID 및 설정 예시

모델 참조는 huggingface/<org>/<model> 형식(Hub 스타일 ID)을 사용합니다. 아래 목록은 GET https://router.huggingface.co/v1/models에서 가져온 것이며, 실제 카탈로그에는 더 많은 모델이 포함될 수 있습니다.

예시 ID (inference 엔드포인트에서):

모델참조 (huggingface/ 접두사 추가)
DeepSeek R1deepseek-ai/DeepSeek-R1
DeepSeek V3.2deepseek-ai/DeepSeek-V3.2
Qwen3 8BQwen/Qwen3-8B
Qwen2.5 7B InstructQwen/Qwen2.5-7B-Instruct
Qwen3 32BQwen/Qwen3-32B
Llama 3.3 70B Instructmeta-llama/Llama-3.3-70B-Instruct
Llama 3.1 8B Instructmeta-llama/Llama-3.1-8B-Instruct
GPT-OSS 120Bopenai/gpt-oss-120b
GLM 4.7zai-org/GLM-4.7
Kimi K2.5moonshotai/Kimi-K2.5

모델 ID에 :fastest, :cheapest 또는 :provider(예: :together, :sambanova)를 추가할 수 있습니다. Inference Provider 설정에서 기본 순서를 지정하세요. Inference Providers 및 GET https://router.huggingface.co/v1/models에서 전체 목록을 확인하세요.

전체 설정 예시

DeepSeek R1을 기본으로, Qwen을 폴백으로:

{
  agents: {
    defaults: {
      model: {
        primary: "huggingface/deepseek-ai/DeepSeek-R1",
        fallbacks: ["huggingface/Qwen/Qwen3-8B"],
      },
      models: {
        "huggingface/deepseek-ai/DeepSeek-R1": { alias: "DeepSeek R1" },
        "huggingface/Qwen/Qwen3-8B": { alias: "Qwen3 8B" },
      },
    },
  },
}

Qwen을 기본으로, :cheapest 및 :fastest 변형 포함:

{
  agents: {
    defaults: {
      model: { primary: "huggingface/Qwen/Qwen3-8B" },
      models: {
        "huggingface/Qwen/Qwen3-8B": { alias: "Qwen3 8B" },
        "huggingface/Qwen/Qwen3-8B:cheapest": { alias: "Qwen3 8B (cheapest)" },
        "huggingface/Qwen/Qwen3-8B:fastest": { alias: "Qwen3 8B (fastest)" },
      },
    },
  },
}

DeepSeek + Llama + GPT-OSS에 별칭 설정:

{
  agents: {
    defaults: {
      model: {
        primary: "huggingface/deepseek-ai/DeepSeek-V3.2",
        fallbacks: [
          "huggingface/meta-llama/Llama-3.3-70B-Instruct",
          "huggingface/openai/gpt-oss-120b",
        ],
      },
      models: {
        "huggingface/deepseek-ai/DeepSeek-V3.2": { alias: "DeepSeek V3.2" },
        "huggingface/meta-llama/Llama-3.3-70B-Instruct": { alias: "Llama 3.3 70B" },
        "huggingface/openai/gpt-oss-120b": { alias: "GPT-OSS 120B" },
      },
    },
  },
}

:provider로 특정 백엔드 강제 지정:

{
  agents: {
    defaults: {
      model: { primary: "huggingface/deepseek-ai/DeepSeek-R1:together" },
      models: {
        "huggingface/deepseek-ai/DeepSeek-R1:together": { alias: "DeepSeek R1 (Together)" },
      },
    },
  },
}

정책 접미사가 포함된 다중 Qwen 및 DeepSeek 모델:

{
  agents: {
    defaults: {
      model: { primary: "huggingface/Qwen/Qwen2.5-7B-Instruct:cheapest" },
      models: {
        "huggingface/Qwen/Qwen2.5-7B-Instruct": { alias: "Qwen2.5 7B" },
        "huggingface/Qwen/Qwen2.5-7B-Instruct:cheapest": { alias: "Qwen2.5 7B (cheap)" },
        "huggingface/deepseek-ai/DeepSeek-R1:fastest": { alias: "DeepSeek R1 (fast)" },
        "huggingface/meta-llama/Llama-3.1-8B-Instruct": { alias: "Llama 3.1 8B" },
      },
    },
  },
}
arrow_back
이전
Github Copilot
다음
Kilocode
arrow_forward