Appearance
想在 OpenClaw 中使用 Hugging Face Inference Providers，只需一个带有 "Make calls to Inference Providers" 权限的 Hugging Face Token。通过 openclaw onboard --auth-choice huggingface-api-key 交互式向导或 --non-interactive 模式配置后，即可在对话中选择 DeepSeek R1、Qwen3、Llama 3.3 等模型，且支持 :fastest（最高吞吐量）和 :cheapest（最低成本）策略后缀。若 Gateway 以守护进程运行，请确保 HUGGINGFACE_HUB_TOKEN 或 HF_TOKEN 环境变量对进程可见。
OpenClaw 接入 Hugging Face Inference 配置
Hugging Face Inference Providers 通过统一路由 API 提供 OpenAI 兼容的对话补全服务。一个 Token 即可访问 DeepSeek、Llama、Qwen 等众多模型。OpenClaw 使用其 OpenAI 兼容端点（仅对话补全）；文生图、Embedding 或语音服务请直接使用 HF inference clients。
- 提供商标识：
huggingface - 认证方式：
HUGGINGFACE_HUB_TOKEN或HF_TOKEN（需要 "Make calls to Inference Providers" 权限） - API 端点：
https://router.huggingface.co/v1（OpenAI 兼容） - 计费：统一 HF Token；定价详情 按提供商费率，含免费额度
快速接入步骤
1. 创建细粒度 Token
在 Hugging Face 的 Settings → Tokens 创建一个新 Token，选择 Fine-grained 类型，并确保勾选 Make calls to Inference Providers 权限。缺少该权限时 API 请求会被拒绝。
2. 运行 onboarding 向导
在终端执行以下命令，在 provider 下拉菜单中选择 Hugging Face，然后输入你的 Token：
bash
openclaw onboard --auth-choice huggingface-api-key交互式向导输入 Token 后，会弹出一个 Default Hugging Face model 下拉菜单，列表从 Hugging Face Inference API 实时加载（若 Token 无效或请求失败，则显示内置的备选列表）。选中的模型自动保存为默认模型。
3. 非交互式快速设置
如需静默配置，可使用以下命令：
bash
openclaw onboard --non-interactive \
--mode local \
--auth-choice huggingface-api-key \
--huggingface-api-key "$HF_TOKEN"执行后默认模型为 huggingface/deepseek-ai/DeepSeek-R1。
4. 验证模型是否可用
bash
openclaw models list --provider huggingface环境变量与守护进程配置
如果 Gateway 以后台守护进程（launchd/systemd）方式运行，必须确保 HUGGINGFACE_HUB_TOKEN 或 HF_TOKEN 对该进程可见。建议将 Token 写入 ~/.openclaw/.env 文件，或通过 env.shellEnv 配置注入。
注意：OpenClaw 同时接受
HUGGINGFACE_HUB_TOKEN和HF_TOKEN。两者同时设置时，HUGGINGFACE_HUB_TOKEN优先级更高。
模型发现与 onboarding 下拉列表
OpenClaw 通过调用 Inference API 的端点发现可用的对话模型：
GET https://router.huggingface.co/v1/models可选：在请求头中携带 Authorization: Bearer $HUGGINGFACE_HUB_TOKEN 或 $HF_TOKEN 可获取完整模型列表（无 Token 时部分端点只返回子集）。返回格式为 OpenAI 风格的 { "object": "list", "data": [ { "id": "Qwen/Qwen3-8B", ... } ] }。
配置 Hugging Face API Key 后（通过 onboarding 或环境变量），OpenClaw 启动时（如 Gateway 启动）会调用此 GET 请求刷新目录，并与内置目录合并（内置目录提供上下文窗口、成本等元数据）。若请求失败或未设置 Key，仅使用内置目录。
模型名称与自定义别名
- 默认显示名称：OpenClaw 优先使用 GET
/v1/models返回的name、title或display_name。若无这些字段，则从模型 ID 派生（例如deepseek-ai/DeepSeek-R1→ "DeepSeek R1"）。 - 自定义别名：可在配置中为每个模型设置
alias，使其在 CLI 和 UI 中显示为自定义名称：
json5
{
agents: {
defaults: {
models: {
"huggingface/deepseek-ai/DeepSeek-R1": { alias: "DeepSeek R1 (fast)" },
"huggingface/deepseek-ai/DeepSeek-R1:cheapest": { alias: "DeepSeek R1 (cheap)" },
},
},
},
}策略后缀：:fastest 和 :cheapest
在模型 ID 后追加后缀，可控制路由策略：
:fastest— 路由到吞吐量最高的后端（锁定，不提供手动选择）。:cheapest— 路由到每输出 token 成本最低的后端（锁定，不提供手动选择）。
你可以在 models.providers.huggingface.models 中添加带后缀的独立条目，或直接在 model.primary 中设置带后缀的 ID。若未使用后缀，路由行为由 Inference Provider 设置 中的默认排序决定。
配置合并时，models.providers.huggingface.models 中的现有条目（如从 models.json 加载的）会被保留，自定义的 name、alias 等选项不会被覆盖。
支持模型列表与 ID 格式
模型引用格式：huggingface/<org>/<model>（Hub 风格 ID）。以下是来自 GET https://router.huggingface.co/v1/models 的常见模型（实际列表可能更多）：
| 模型 | 引用（加上 huggingface/ 前缀） |
|---|---|
| DeepSeek R1 | deepseek-ai/DeepSeek-R1 |
| DeepSeek V3.2 | deepseek-ai/DeepSeek-V3.2 |
| Qwen3 8B | Qwen/Qwen3-8B |
| Qwen2.5 7B Instruct | Qwen/Qwen2.5-7B-Instruct |
| Qwen3 32B | Qwen/Qwen3-32B |
| Llama 3.3 70B Instruct | meta-llama/Llama-3.3-70B-Instruct |
| Llama 3.1 8B Instruct | meta-llama/Llama-3.1-8B-Instruct |
| GPT-OSS 120B | openai/gpt-oss-120b |
| GLM 4.7 | zai-org/GLM-4.7 |
| Kimi K2.5 | moonshotai/Kimi-K2.5 |
提示：可以在任何模型 ID 后追加
:fastest或:cheapest（例如huggingface/Qwen/Qwen3-8B:cheapest）。在 Inference Provider 设置 中可调整默认顺序；完整列表请参见 Inference Providers 文档 或 GET 端点。
高级配置示例
示例 1：DeepSeek R1 为主，Qwen 作为 fallback
json5
{
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" },
},
},
},
}示例 2：Qwen 为默认，带 cheapest 和 fastest 变体
json5
{
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)" },
},
},
},
}示例 3：DeepSeek V3.2 + Llama 3.3 + GPT-OSS 带别名
json5
{
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" },
},
},
},
}示例 4：多个 Qwen 和 DeepSeek 混合策略
json5
{
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" },
},
},
},
}相关文档
常见问题
为什么我创建了 Hugging Face Token，但 OpenClaw 提示认证失败？
最常见的原因是 Token 没有启用 Make calls to Inference Providers 权限。请在 Hugging Face Token 设置页面 检查并确认该权限已勾选。如果 Token 已更新，请确保环境变量 HUGGINGFACE_HUB_TOKEN 或 HF_TOKEN 正确设置，并重新启动 Gateway 进程。
如何在 OpenClaw 中设置模型 fallback？
在 agents.defaults.model 配置中，使用 primary 指定主模型，fallbacks 数组指定备选模型（按优先级排列）。例如：primary: "huggingface/deepseek-ai/DeepSeek-R1", fallbacks: ["huggingface/Qwen/Qwen3-8B"]。当主模型不可用时，OpenClaw 会依次尝试 fallback 列表。
模型 ID 格式有误，OpenClaw 无法识别我选中的模型？
模型 ID 必须使用 Hugging Face Hub 风格，格式为 huggingface/<org>/<model>，例如 huggingface/deepseek-ai/DeepSeek-R1。不要在 /v1/models 返回的 ID 基础上加额外前缀，直接复制 API 返回的 id 字段（如 deepseek-ai/DeepSeek-R1）并在前面添加 huggingface/。