HuggingFace Inference Provider

HuggingFace Inference Providers 通过单一路由 API 提供 OpenAI 兼容的 chat completions，一个 token 可访问 DeepSeek、Llama 等众多模型。

属性	值
Provider ID	huggingface
认证	HUGGINGFACE_HUB_TOKEN 或 HF_TOKEN
API	OpenAI 兼容（https://router.huggingface.co/v1）

注意：仅支持 chat completions；文字转图片、embeddings、语音需直接使用 HF inference clients。

快速开始

1. 在 HuggingFace 创建细粒度 token，需开启 Make calls to Inference Providers 权限
2. 运行 onboarding：

openclaw onboard --auth-choice huggingface-api-key
# 非交互式
openclaw onboard --non-interactive --mode local \
  --auth-choice huggingface-api-key \
  --huggingface-api-key "$HF_TOKEN"

模型 ID 格式

模型 ref 格式：huggingface/<org>/<model>

模型	Ref
DeepSeek R1	huggingface/deepseek-ai/DeepSeek-R1
Qwen3 8B	huggingface/Qwen/Qwen3-8B
Llama 3.3 70B	huggingface/meta-llama/Llama-3.3-70B-Instruct
GLM 4.7	huggingface/zai-org/GLM-4.7
Kimi K2.5	huggingface/moonshotai/Kimi-K2.5

可在模型 ID 后追加 :fastest 或 :cheapest 选择路由策略。

配置示例

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

模型发现

OpenClaw 通过 GET https://router.huggingface.co/v1/models 动态发现可用模型。有 token 时返回完整列表，无 token 时使用内置目录。

两个环境变量均可用，HUGGINGFACE_HUB_TOKEN 优先级更高。

相关链接

• provider-together — 另一个开源模型聚合提供商
• provider-nvidia — NVIDIA NIM 推理
• providers — 所有 provider 总览