Providers
Hugging Face(추론)
Hugging Face Inference Providers는 하나의 토큰으로 여러 호스팅 모델(DeepSeek, Llama 등)을 이용할 수 있도록 OpenAI 호환 채팅 완성 라우터를 제공합니다. OpenClaw는 채팅 완성 엔드포인트만 사용합니다. 텍스트-이미지 변환, 임베딩 또는 음성 기능에는 HF 추론 클라이언트를 직접 사용하세요.
| 속성 | 값 |
|---|---|
| 제공자 ID | huggingface |
| Plugin | 번들 제공(기본적으로 활성화되며 설치 단계 없음) |
| 인증 환경 변수 | HUGGINGFACE_HUB_TOKEN 또는 HF_TOKEN(세분화된 토큰) |
| API | OpenAI 호환(https://router.huggingface.co/v1) |
| 결제 | 단일 HF 토큰을 사용하며, 요금은 무료 등급이 포함된 제공자 요율을 따름 |
시작하기
세분화된 토큰 만들기
Hugging Face Settings Tokens로 이동하여 새로운 세분화된 토큰을 만드세요.
온보딩 실행
제공자 드롭다운에서 Hugging Face를 선택한 다음, 메시지가 표시되면 API 키를 입력하세요.
openclaw onboard --auth-choice huggingface-api-key기본 모델 선택
기본 Hugging Face 모델 드롭다운에서 모델을 선택하세요. 토큰이 유효하면 추론 API에서 목록을 불러오고, 그렇지 않으면 OpenClaw가 아래의 내장 카탈로그를 표시합니다. 선택한 항목은 agents.defaults.model.primary로 저장됩니다.
{ agents: { defaults: { model: { primary: "huggingface/deepseek-ai/DeepSeek-R1" }, }, },}모델 사용 가능 여부 확인
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
모델 참조는 huggingface/<org>/<model> 형식(Hub 스타일 ID)을 사용합니다. OpenClaw의 내장 카탈로그는 다음과 같습니다.
| 모델 | 참조(huggingface/ 접두사 추가) |
|---|---|
| DeepSeek R1 | deepseek-ai/DeepSeek-R1 |
| DeepSeek V3.1 | deepseek-ai/DeepSeek-V3.1 |
| GPT-OSS 120B | openai/gpt-oss-120b |
| Llama 3.3 70B Instruct Turbo | meta-llama/Llama-3.3-70B-Instruct-Turbo |
고급 구성
모델 검색 및 온보딩 드롭다운
OpenClaw는 다음 요청으로 모델을 검색합니다.
GET https://router.huggingface.co/v1/modelsAuthorization: Bearer $HUGGINGFACE_HUB_TOKEN # 또는 $HF_TOKEN응답은 OpenAI 형식입니다. { "object": "list", "data": [ { "id": "Qwen/Qwen3-8B", "owned_by": "Qwen", ... }, ... ] }.
구성된 키(온보딩, HUGGINGFACE_HUB_TOKEN 또는 HF_TOKEN)가 있으면 대화형 설정 중 기본 Hugging Face 모델 드롭다운이 이 엔드포인트의 데이터로 채워집니다. Gateway를 시작할 때 카탈로그를 새로 고치기 위해 동일한 호출을 반복합니다. 검색된 모델은 위의 내장 카탈로그와 병합됩니다. ID가 일치하면 컨텍스트 창 및 비용과 같은 메타데이터에 내장 카탈로그가 사용됩니다. 요청이 실패하거나 데이터가 반환되지 않거나 키가 설정되지 않은 경우 OpenClaw는 내장 카탈로그만 사용합니다.
제공자를 제거하지 않고 검색을 비활성화하려면 다음을 실행하세요.
openclaw config set plugins.entries.huggingface.config.discovery.enabled false모델 이름, 별칭 및 정책 접미사
- API의 이름: 검색된 모델은 API에
name,title또는display_name이 있으면 해당 값을 사용합니다. 그렇지 않으면 OpenClaw가 모델 ID에서 이름을 생성합니다(예:deepseek-ai/DeepSeek-R1은 "DeepSeek R1"이 됨). - 표시 이름 재정의: 구성에서 모델별 사용자 지정 레이블을 설정하세요.
{ agents: { defaults: { models: { "huggingface/deepseek-ai/DeepSeek-R1": { alias: "DeepSeek R1 (fast)" }, "huggingface/deepseek-ai/DeepSeek-R1:cheapest": { alias: "DeepSeek R1 (cheap)" }, }, }, },}- 정책 접미사:
:fastest와:cheapest는 HF 라우터 규칙이며 OpenClaw가 재작성하는 값이 아닙니다. 접미사는 모델 ID의 일부로 그대로 전송되고, HF 라우터가 조건에 맞는 추론 제공자를 선택합니다. 접미사별로 서로 다른 별칭을 사용하려면 각 변형을models.providers.huggingface.models아래(또는model.primary)에 별도의 항목으로 추가하세요. - 구성 병합:
models.providers.huggingface.models의 기존 항목(예:models.json의 항목)은 구성 병합 시 유지되므로, 여기에서 설정한 사용자 지정name,alias또는 모델 옵션은 다시 시작해도 유지됩니다.
환경 및 데몬 설정
Gateway가 데몬(launchd/systemd)으로 실행되는 경우 해당 프로세스에서 HUGGINGFACE_HUB_TOKEN 또는 HF_TOKEN을 사용할 수 있는지 확인하세요(예: ~/.openclaw/.env 또는 env.shellEnv 사용).
구성: 대체 모델을 사용하는 DeepSeek R1
{ agents: { defaults: { model: { primary: "huggingface/deepseek-ai/DeepSeek-R1", fallbacks: ["huggingface/openai/gpt-oss-120b"], }, models: { "huggingface/deepseek-ai/DeepSeek-R1": { alias: "DeepSeek R1" }, "huggingface/openai/gpt-oss-120b": { alias: "GPT-OSS 120B" }, }, }, },}구성: 최저가 및 최고속 변형을 사용하는 DeepSeek
{ agents: { defaults: { model: { primary: "huggingface/deepseek-ai/DeepSeek-R1" }, models: { "huggingface/deepseek-ai/DeepSeek-R1": { alias: "DeepSeek R1" }, "huggingface/deepseek-ai/DeepSeek-R1:cheapest": { alias: "DeepSeek R1 (cheapest)" }, "huggingface/deepseek-ai/DeepSeek-R1:fastest": { alias: "DeepSeek R1 (fastest)" }, }, }, },}구성: 별칭을 사용하는 DeepSeek + Llama + GPT-OSS
{ agents: { defaults: { model: { primary: "huggingface/deepseek-ai/DeepSeek-V3.1", fallbacks: [ "huggingface/meta-llama/Llama-3.3-70B-Instruct-Turbo", "huggingface/openai/gpt-oss-120b", ], }, models: { "huggingface/deepseek-ai/DeepSeek-V3.1": { alias: "DeepSeek V3.1" }, "huggingface/meta-llama/Llama-3.3-70B-Instruct-Turbo": { alias: "Llama 3.3 70B Turbo" }, "huggingface/openai/gpt-oss-120b": { alias: "GPT-OSS 120B" }, }, }, },}