메인 콘텐츠로 건너뛰기

Documentation Index

Fetch the complete documentation index at: https://docs.openclaw.ai/llms.txt

Use this file to discover all available pages before exploring further.

Hugging Face Inference Providers는 단일 router API를 통해 OpenAI 호환 chat completions를 제공합니다. 하나의 토큰으로 많은 모델(DeepSeek, Llama 등)에 접근할 수 있습니다. OpenClaw는 OpenAI 호환 엔드포인트(chat completions 전용)를 사용합니다. text-to-image, embeddings, speech의 경우 HF inference clients를 직접 사용하세요.
  • Provider: huggingface
  • Auth: HUGGINGFACE_HUB_TOKEN 또는 HF_TOKEN (Make calls to Inference Providers 권한이 있는 세분화 토큰)
  • API: OpenAI 호환 (https://router.huggingface.co/v1)
  • 청구: 단일 HF 토큰 사용; 요금은 provider 요율을 따르며 무료 등급이 있습니다.

​
시작하기

1

세분화 토큰 생성

Hugging Face Settings Tokens로 이동해 새 세분화 토큰을 생성하세요.
토큰에는 반드시 Make calls to Inference Providers 권한이 활성화되어 있어야 합니다. 그렇지 않으면 API 요청이 거부됩니다.
2

온보딩 실행

provider 드롭다운에서 Hugging Face를 선택한 다음, 프롬프트가 표시되면 API 키를 입력하세요.
openclaw onboard --auth-choice huggingface-api-key
3

기본 모델 선택

Default Hugging Face model 드롭다운에서 원하는 모델을 선택하세요. 유효한 토큰이 있으면 목록이 Inference API에서 로드되고, 없으면 내장 목록이 표시됩니다. 선택한 값은 기본 모델로 저장됩니다.나중에 config에서 기본 모델을 설정하거나 변경할 수도 있습니다.
{
  agents: {
    defaults: {
      model: { primary: "huggingface/deepseek-ai/DeepSeek-R1" },
    },
  },
}
4

모델이 사용 가능한지 확인

openclaw models list --provider huggingface

​
비대화형 설정

openclaw onboard --non-interactive \
  --mode local \
  --auth-choice huggingface-api-key \
  --huggingface-api-key "$HF_TOKEN"
이렇게 하면 huggingface/deepseek-ai/DeepSeek-R1이 기본 모델로 설정됩니다.

​
모델 ID

모델 ref는 huggingface/<org>/<model> 형식(Hub 스타일 ID)을 사용합니다. 아래 목록은 GET https://router.huggingface.co/v1/models의 결과이며, 카탈로그에는 더 많은 모델이 포함될 수 있습니다.
ModelRef (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를 붙일 수 있습니다. 기본 순서는 Inference Provider settings에서 설정하세요. 전체 목록은 Inference Providers 및 GET https://router.huggingface.co/v1/models를 참조하세요.

​
고급 구성

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을 사용해 사용 가능한 chat-completion 모델을 검색합니다. 대화형 설정 중에는 토큰을 입력한 후 이 목록(또는 요청 실패 시 내장 카탈로그)으로 채워진 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에서 원하는 방식으로 보이도록 config에서 모델별 사용자 지정 레이블을 설정할 수 있습니다.
{
  agents: {
    defaults: {
      models: {
        "huggingface/deepseek-ai/DeepSeek-R1": { alias: "DeepSeek R1 (fast)" },
        "huggingface/deepseek-ai/DeepSeek-R1:cheapest": { alias: "DeepSeek R1 (cheap)" },
      },
    },
  },
}
  • 정책 접미사: OpenClaw의 번들 Hugging Face 문서와 도우미는 현재 다음 두 접미사를 내장 정책 변형으로 취급합니다.
    • :fastest — 가장 높은 처리량
    • :cheapest — 출력 토큰당 가장 낮은 비용
    이를 models.providers.huggingface.models의 별도 엔트리로 추가하거나, 접미사를 포함한 값으로 model.primary를 설정할 수 있습니다. 기본 provider 순서는 Inference Provider settings에서 설정할 수도 있습니다(접미사 없음 = 해당 순서 사용).
  • Config 병합: models.providers.huggingface.models의 기존 엔트리(예: models.json)는 config 병합 시 유지됩니다. 따라서 여기에 설정한 사용자 지정 name, alias, 모델 옵션은 보존됩니다.
Gateway가 데몬(launchd/systemd)으로 실행된다면, 해당 프로세스에서 HUGGINGFACE_HUB_TOKEN 또는 HF_TOKEN을 사용할 수 있어야 합니다(예: ~/.openclaw/.env 또는 env.shellEnv).
OpenClaw는 HUGGINGFACE_HUB_TOKEN과 HF_TOKEN을 모두 env var 별칭으로 허용합니다. 둘 중 어느 것이든 동작하며, 둘 다 설정되어 있으면 HUGGINGFACE_HUB_TOKEN이 우선합니다.
{
  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" },
      },
    },
  },
}

{
  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)" },
      },
    },
  },
}

{
  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" },
      },
    },
  },
}

{
  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" },
      },
    },
  },
}

​
관련 항목

모델 선택

모든 provider, 모델 ref, failover 동작 개요.

모델 선택

모델을 선택하고 구성하는 방법.

Inference Providers 문서

공식 Hugging Face Inference Providers 문서.

구성

전체 config 참조.