
>**核心功能**：通过 **Hugging Face Inference Providers** 统一接入数千个开源模型（DeepSeek, Llama, Qwen, GLM 等）。
**技术架构**：基于 **OpenAI 兼容路由 API** (`router.huggingface.co`)，只需一个 Token 即可调用多后端模型。
**独特优势**：支持**智能路由策略**（最快/最便宜/指定供应商），自动发现最新模型，享受免费额度与灵活计费。


----

## 🌐 一、什么是 Hugging Face Inference Providers？


Hugging Face Inference Providers 是一个强大的**路由器**，它屏蔽了底层不同推理服务商（如 Together AI, SambaNova, Replicate 等）的差异。


- **统一接口**：所有模型均通过标准的 OpenAI Chat Completions API 访问。

- **单一鉴权**：只需一个 Hugging Face Token，即可访问生态内所有支持的模型。

- **智能调度**：你可以让 HF 自动选择**最快**或**最便宜**的后端，也可以强制指定特定供应商。

- **适用范围**：主要用于**文本对话 (Chat Completions)**。>注意：图像生成、Embedding 或语音任务请直接使用 HF 专用的 Inference Clients，本指南专注于对话模型。


----

## 🔑 二、快速开始 (Quick Start)


### 1. 获取 Fine-grained Token


登录 [Hugging Face Settings](https://huggingface.co/settings/tokens)，创建一个新的 **Fine-grained Token**。


- **权限要求**：必须勾选 **`Make calls to Inference Providers`** (对应 scope: `inference.serverless.write`)。

- **保存 Token**：复制生成的 token (通常以 `hf_` 开头)。


### 2. 交互式配置 (推荐)


运行 Onboarding 命令，选择 Hugging Face 并粘贴 Token：

```
openclaw onboard --auth-choice huggingface-api-key
```

- 系统会自动调用 API 获取可用模型列表。

- 在弹出的下拉菜单中选择你的默认模型（如 `deepseek-ai/DeepSeek-R1`）。


### 3. 非交互式配置 (CI/CD 或脚本)


```
openclaw onboard --non-interactive \
  --mode local \
  --auth-choice huggingface-api-key \
  --huggingface-api-key "$HF_TOKEN"
```
默认将设置 `huggingface/deepseek-ai/DeepSeek-R1` 为初始模型。

### 4. 环境变量说明


如果 OpenClaw 作为守护进程 (systemd/launchd) 运行，请确保以下变量对进程可见：


- `HUGGINGFACE_HUB_TOKEN` 或 `HF_TOKEN`

- 建议写入 `~/.openclaw/.env` 文件。


----

## ⚙️ 三、高级路由策略 (核心特性)


Hugging Face 允许你在模型 ID 后添加**后缀**，从而控制路由器的行为。这是 HF 提供商最强大的功能。

### 1. 策略后缀详解


|后缀|行为描述|适用场景|
|:-:|:-:|:-:|
|**(无后缀)**|遵循你在 [HF Inference Provider 设置](https://hf.co/settings/inference-providers) 中定义的默认顺序。|日常开发，偏好固定。|
|`:fastest`|路由器自动选择当前**吞吐量最高/延迟最低**的后端。**锁定供应商选择**。|实时对话，对延迟敏感的任务。|
|`:cheapest`|路由器自动选择当前**每 Token 成本最低**的后端。**锁定供应商选择**。|批量处理，低成本测试，长文本生成。|
|`:<provider>`|强制指定后端供应商 (如 `:together`, `:sambanova`, `:replicate`)。|需要特定供应商的稳定性或特性时。|

### 2. 配置示例


在 `openclaw.json` 中，你可以通过定义多个条目来对比不同策略：

```
{
  "agents": {
    "defaults": {
      "model": { 
        // 默认使用 Qwen，自动选择最便宜的后端
        "primary": "huggingface/Qwen/Qwen2.5-7B-Instruct:cheapest" 
      },
      "models": {
        // 自定义显示名称，方便在 CLI 中区分
        "huggingface/Qwen/Qwen2.5-7B-Instruct": { 
          "alias": "Qwen2.5 7B (Default)" 
        },
        "huggingface/Qwen/Qwen2.5-7B-Instruct:cheapest": { 
          "alias": "Qwen2.5 7B (💰 Cheapest)" 
        },
        "huggingface/Qwen/Qwen2.5-7B-Instruct:fastest": { 
          "alias": "Qwen2.5 7B (⚡ Fastest)" 
        },
        // 强制指定 Together AI 作为后端
        "huggingface/deepseek-ai/DeepSeek-R1:together": { 
          "alias": "DeepSeek R1 (via Together)" 
        }
      }
    }
  }
}
```


----

## 📚 四、热门模型推荐


通过 `GET https://router.huggingface.co/v1/models` 可获取完整列表。以下是目前生态中表现优异的模型及其 OpenClaw 引用 ID：


|模型系列|具体型号|OpenClawModelID|特点|
|:-:|:-:|:-:|:-:|
|**DeepSeek**|DeepSeek R1|`huggingface/deepseek-ai/DeepSeek-R1`|顶级推理能力，性价比极高|
||DeepSeek V3.2|`huggingface/deepseek-ai/DeepSeek-V3.2`|全能型旗舰|
|**Qwen (通义)**|Qwen3 8B|`huggingface/Qwen/Qwen3-8B`|轻量级，速度快|
||Qwen3 32B|`huggingface/Qwen/Qwen3-32B`|中等规模，性能均衡|
||Qwen2.5 7B Instruct|`huggingface/Qwen/Qwen2.5-7B-Instruct`|经典小钢炮|
|**Llama**|Llama 3.3 70B|`huggingface/meta-llama/Llama-3.3-70B-Instruct`|开源界标杆，逻辑强|
||Llama 3.1 8B|`huggingface/meta-llama/Llama-3.1-8B-Instruct`|极速响应|
|**其他**|GLM 4.7|`huggingface/zai-org/GLM-4.7`|智谱最新模型|
||Kimi K2.5|`huggingface/moonshotai/Kimi-K2.5`|长上下文专家|
||GPT-OSS 120B|`huggingface/openai/gpt-oss-120b`|(如有) 超大参数开源模型|

>💡 **提示**：模型 ID 格式严格为 `huggingface/<org>/<model-name>`。


----

## 🔍 五、模型发现与动态更新


OpenClaw 具备**动态模型发现**能力：


1. **启动时探测**：当配置了有效的 `HF_TOKEN` 后，OpenClaw 会在启动时调用 `GET https://router.huggingface.co/v1/models`。

2. **元数据合并**：
	- 从 API 获取实时模型列表（包含 `name`, `owned_by` 等信息）。
	- 与内置目录合并（补充上下文窗口长度、预估成本等元数据）。

3. **Fallback 机制**：如果 API 调用失败或未配置 Token，系统将仅使用内置的静态模型列表。


### 自定义显示名称


如果 API 返回的名称不符合你的习惯，可以在配置中强制覆盖：

```
{
  "agents": {
    "defaults": {
      "models": {
        "huggingface/deepseek-ai/DeepSeek-R1": { 
          "alias": "我的主力推理模型" 
        }
      }
    }
  }
}
```


----

## 🛠️ 六、故障排查


|问题|可能原因|解决方案|
|:-:|:-:|:-:|
|**401 Unauthorized**|Token 无效或缺少权限|检查 Token 是否包含 `inference.serverless.write` 权限；确认未过期。|
|**Model not found**|模型 ID 错误或暂未对该用户开放|运行 `openclaw models list --provider huggingface` 查看实时列表；检查模型名拼写。|
|**Rate Limit / 429**|触发免费额度限制或后端限流|升级 HF Pro 账号；尝试切换 `:cheapest` 或 `:fastest` 策略以路由到不同后端。|
|**Provider Unavailable**|指定后端 (如 `:together`) 暂时不可用|移除 `:provider` 后缀，让 HF 自动路由；或更换其他供应商后缀。|
|**Billing Error**|账户余额不足 (超出免费额度)|登录 HF 官网绑定支付方式或充值。|


----

## 💡 七、最佳实践


1. **利用 `:cheapest` 进行开发**：在调试 Prompt 或进行大规模测试时，使用 `:cheapest` 后缀可以显著降低成本。

2. **生产环境使用 `:fastest` 或固定供应商**：为了保证延迟稳定，生产环境建议使用 `:fastest` 或在 HF 设置中固定首选供应商，避免路由波动。

3. **设置 Fallback 链**：结合 HF 的多模型优势，配置主备模型链。例如：主用 DeepSeek R1，备用 Qwen 32B。```
	"model": {
	  "primary": "huggingface/deepseek-ai/DeepSeek-R1:fastest",
	  "fallbacks": ["huggingface/Qwen/Qwen3-32B:fastest"]
	}
	```

4. **关注免费额度**：Hugging Face 提供每月的免费推理额度。定期检查用量，避免意外产生费用。

5. **定期刷新模型列表**：HF 生态更新极快，新模型经常上线。定期运行 `openclaw models list` 以发现新能力。


----

## 🔗 八、相关资源


- **Hugging Face Inference Providers 文档**: https://huggingface.co/docs/inference-providers 

- **定价详情**: https://huggingface.co/docs/inference-providers/pricing 

- **管理供应商偏好**: https://hf.co/settings/inference-providers 

- **API 参考**: `GET https://router.huggingface.co/v1/models`


通过 Hugging Face Inference Providers，OpenClaw 让你能够以最低的门槛探索整个开源大模型生态，无论是追求极致性价比还是最强推理能力，都能一键切换。🚀🤗

核心功能：通过 Hugging Face Inference Providers 统一接入数千个开源模型（DeepSeek, Llama, Qwen, GLM 等）。

OpenClaw 集成 Hugging Face Inference 完全指南

通过 Hugging Face Inference Providers 统一接入数千个开源模型（DeepSeek, Llama, Qwen, GLM 等）。

云计算

人工智能

开发工具

HuggingFaceInferenceProviders提供统一API接入DeepSeek、Llama、Qwen等数千个开源模型，支持智能路由（最快/最便宜/指定供应商）和自动发现最新模型。通过OpenAI兼容API和单一Token实现多后端调用，适合文本对话任务，提供免费额度和灵活计费方案，助力开发者高效使用AI模型。

路由器

路由

文章

问答

视频

教程

学习中心

腾讯云实验室

直播

竞赛

腾讯云代码分析专区

腾讯iOA零信任安全管理系统专区

腾讯云架构师技术同盟交流圈

腾讯云数据库专区

腾讯云智能顾问专区

腾讯云原生专区

腾讯混元专区

腾讯云TCE专区

腾讯云Lighthouse专区

腾讯云HAI专区

腾讯云Edgeone专区

腾讯云存储专区

腾讯云智能专区

腾讯轻联专区 

腾讯云开发专区

TAPD专区

腾讯轻量云游戏服专区

腾讯云最具价值专家

腾讯云架构师技术同盟

腾讯云创作之星

腾讯云开发者先锋

腾讯云代码助手

云原生构建

TAPD 敏捷项目管理

Cloud Studio

SDK中心

API中心

命令行工具

涵盖代码开发、场景应用、自动测试全流程，助你从零构建专属AI助手

一站式MCP教程库，解锁AI应用新玩法

聚焦“写作效率、视觉美观与运行性能”三方面进行全面升级，为您提供更高效、稳定的创作环境

社区富文本&Markdown编辑器全新改版上线，欢迎大家体验!

诚挚邀请您参与本次调研，分享您的真实使用感受与建议。您的反馈至关重要，感谢您的支持与参与！

社区新版编辑器体验调研

HuggingFaceInferenceProviders提供统一API接入DeepSeek、Llama、Qwen等数千个开源模型，支持智能路由（最快/最便宜/指定供应商）和自动发现最新模型。通过OpenAI兼容API和单一Token实现多后端调用，适合文本对话任务，提供免费额度和灵活计费方案，助力开发者高效使用AI模...

OpenClaw 集成 Hugging Face Inference 完全指南-腾讯云开发者社区-腾讯云

OpenClaw 集成 Hugging Face Inference 完全指南

OpenClaw 集成 Hugging Face Inference 完全指南

社区

活动

圈层

关于

腾讯云开发者

热门产品

热门推荐

更多推荐