概述
Hugging Face Inference API（通过 router.huggingface.co）提供了一个统一的推理路由层，将 Hub 上数以千计的开源模型聚合在单一端点下，并支持自动将请求分发到 Together AI、SambaNova、Fireworks 等不同的推理后端。对于希望使用 DeepSeek、Qwen、Llama 等开源模型又不想自建推理基础设施的开发者，这是最便捷的托管方案之一，且提供免费层级。
快速开始
前往 Hugging Face Token 创建页面，创建一个细粒度 Token，并勾选 "Make calls to Inference Providers" 权限。
设置环境变量（两个名称均可识别）：
export HUGGINGFACE_HUB_TOKEN="hf_xxxxxxxxxxxx"
# 或者
export HF_TOKEN="hf_xxxxxxxxxxxx"
运行引导配置命令：
openclaw onboard --auth-choice huggingface-api-key
非交互方式：
openclaw onboard --non-interactive \
--mode local \
--auth-choice huggingface-api-key \
--huggingface-api-key "$HF_TOKEN"
配置参数
模型引用格式为 huggingface/<org>/<model-name>，并支持追加策略后缀：
{
agents: {
defaults: {
model: { primary: "huggingface/deepseek-ai/DeepSeek-R1" },
},
},
}
配置主备模型，在主模型不可用时自动切换：
{
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/deepseek-ai/DeepSeek-R1:together" },
models: {
"huggingface/deepseek-ai/DeepSeek-R1:together": { alias: "DeepSeek R1 (Together)" },
"huggingface/deepseek-ai/DeepSeek-R1:cheapest": { alias: "DeepSeek R1 (最低价)" },
"huggingface/deepseek-ai/DeepSeek-R1:fastest": { alias: "DeepSeek R1 (最快)" },
},
},
},
}
支持的模型
模型 ID 格式遵循 HuggingFace Hub 的 <org>/<model> 惯例，常用模型：
| 模型 | 引用 ID |
|---|---|
| DeepSeek R1 | deepseek-ai/DeepSeek-R1 |
| Qwen3 8B | Qwen/Qwen3-8B |
| Llama 3.3 70B | meta-llama/Llama-3.3-70B-Instruct |
| GPT-OSS 120B | openai/gpt-oss-120b |
策略后缀说明：
:fastest— 路由至当前吞吐量最高的后端:cheapest— 路由至单位 Token 成本最低的后端:sambanova/:together等 — 指定特定推理服务商
注意事项
Token 权限要求：必须使用细粒度 Token 并明确勾选推理权限，普通的写权限 Token 无法调用推理 API，请在创建时注意选择正确的权限类型。
免费层级限制：免费层级存在请求速率和并发限制，对于生产级高频调用建议升级至付费计划，计费按各后端提供商的实际价格执行。
模型目录动态更新：可用模型列表在 OpenClaw 启动时通过 API 自动拉取，无需手动维护。若认证失效，系统会回退到内置的静态模型目录。
守护进程环境：在 launchd 或 systemd 管理的进程中，HUGGINGFACE_HUB_TOKEN 或 HF_TOKEN 需写入 ~/.openclaw/.env，确保非交互式启动时凭据可用。
自定义模型条目保留：在 models.providers.huggingface.models 中手动添加的自定义模型条目，在 OpenClaw 进行配置合并更新时会被保留，不会被覆盖。