Hugging Face(Inference)

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).

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