Hugging Face (inference)

Hugging Face Inference Providers 提供 OpenAI 兼容的聊天补全功能，通过单一路由器 API 实现。您只需一个令牌即可访问许多模型（DeepSeek、Llama 等）。OpenClaw 使用 OpenAI 兼容端点（仅限聊天补全）；如需文本生成图像、嵌入或语音功能，请直接使用 HF inference clients。

提供商：huggingface
身份验证：HUGGINGFACE_HUB_TOKEN 或 HF_TOKEN（具有 Make calls to Inference Providers 权限的细粒度令牌）
API：OpenAI 兼容 (https://router.huggingface.co/v1)
计费：单一 HF 令牌；定价遵循提供商费率，并提供免费层级。

入门指南

Create a fine-grained token
前往 Hugging Face Settings Tokens 并创建一个新的细粒度令牌。
Warning
令牌必须启用 Make calls to Inference Providers 权限，否则 API 请求将被拒绝。
Run 新手引导
在提供商下拉菜单中选择 Hugging Face，然后在提示时输入您的 API 密钥：
Terminal window
```
openclaw onboard --auth-choice huggingface-api-key
```
Select a default 模型
在 Default Hugging Face 模型 下拉菜单中，选择您想要的模型。当您拥有有效令牌时，列表会从 Inference API 加载；否则将显示内置列表。您的选择将保存为默认模型。

您也可以稍后在配置中设置或更改默认模型：
```
{
  agents: {
    defaults: {
      model: { primary: "huggingface/deepseek-ai/DeepSeek-R1" },
    },
  },
}
```

Verify the 模型 is available

openclaw models list --provider huggingface

非交互式设置

openclaw onboard --non-interactive \
  --mode local \
  --auth-choice huggingface-api-key \
  --huggingface-api-key "$HF_TOKEN"

这会将 huggingface/deepseek-ai/DeepSeek-R1 设置为默认模型。

模型 ID

模型引用采用 huggingface/<org>/<model> 的形式（Hub 风格 ID）。以下列表来自 GET https://router.huggingface.co/v1/models；您的目录中可能包含更多内容。

模型	Ref（前缀为 `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`

高级配置

Model discovery and 新手引导 dropdown

OpenClaw 通过直接调用 推理端点 来发现模型：

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 请求来发现可用的聊天补全模型。在 交互式设置 期间，输入令牌后，您会看到一个 默认 Hugging Face 模型 下拉列表，其中的内容填充自该列表（如果请求失败，则使用内置目录）。在运行时（例如 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 中按您想要的方式显示：

{
  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 — 最低的输出 token 成本。
您可以将这些作为单独的条目添加到 models.providers.huggingface.models 中，或使用后缀设置 model.primary。您也可以在 Inference Provider settings 中设置您的默认提供商顺序（无后缀 = 使用该顺序）。
配置合并： models.providers.huggingface.models 中的现有条目（例如在 models.json 中）会在合并配置时保留。因此您在那里设置的任何自定义 name、alias 或模型选项都将被保留。

环境和守护程序设置

如果 Gateway 作为守护程序运行，请确保 HUGGINGFACE_HUB_TOKEN 或 HF_TOKEN 对该进程可用（例如，在 ~/.openclaw/.env 中或通过 env.shellEnv）。

配置：带有 Qwen 回退的 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" },
      },
    },
  },
}

Config: Qwen 及最便宜且最快的变体

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

Config: 带别名的 DeepSeek + Llama + GPT-OSS

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

Config: 带策略后缀的多个 Qwen 和 DeepSeek

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