Hugging Face (inference)

Hugging Face Inference Providers 在众多托管模型（DeepSeek、Llama 等）前提供了一个兼容 OpenAI 的 chat completions 路由器，只需一个 token 即可访问所有这些模型。OpenClaw 仅与 chat completions 端点 通信；文本转图像、嵌入或语音请直接使用 HF 推理客户端。

属性	值
Provider id	`huggingface`
插件	内置（默认启用，无需安装步骤）
认证环境变量	`HUGGINGFACE_HUB_TOKEN` 或 `HF_TOKEN`（细粒度 token）
API	兼容 OpenAI（`https://router.huggingface.co/v1`）
计费	单个 HF token；定价遵循各提供方费率，并提供免费额度

快速开始¶

1. 创建细粒度 token

前往 [Hugging Face Settings Tokens](https://huggingface.co/settings/tokens/new?ownUserPermissions=inference.serverless.write&tokenType=fineGrained) 并创建一个新的细粒度 token。

Warning

该 token 必须启用 Make calls to Inference Providers 权限，否则 API 请求将被拒绝。

2. 运行 onboarding 引导

在提供方下拉菜单中选择 Hugging Face，然后按提示输入你的 API 密钥：

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

3. 选择默认模型

在 Default Hugging Face model 下拉菜单中选择一个模型。当你的 token 有效时，列表会从 Inference API 加载；否则 OpenClaw 会显示下方内置目录。你的选择将保存为 agents.defaults.model.primary：

{
  agents: {
    defaults: {
      model: { primary: "huggingface/deepseek-ai/DeepSeek-R1" },
    },
  },
}

4. 验证模型是否可用

openclaw models list --provider huggingface

非交互式设置¶

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

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

模型 ID¶

模型引用使用 huggingface/<org>/<model> 形式（Hub 风格 ID）。OpenClaw 的内置目录：

模型	引用（前缀为 `huggingface/`）
DeepSeek R1	`deepseek-ai/DeepSeek-R1`
DeepSeek V3.1	`deepseek-ai/DeepSeek-V3.1`
GPT-OSS 120B	`openai/gpt-oss-120b`

Tip

当你的 token 有效时，OpenClaw 还会在 onboarding 期间和 Gateway 启动时从 GET https://router.huggingface.co/v1/models 发现其他任何模型，因此你的目录可以包含远不止以上三个模型。你可以向任意模型 ID 追加 :fastest 或 :cheapest；HF 的路由器会路由到匹配的推理提供方。在 Inference Provider settings 中设置你的默认提供方顺序。

高级配置¶

模型发现与 onboarding 下拉列表

OpenClaw 通过以下方式发现模型：

GET https://router.huggingface.co/v1/models
Authorization: Bearer $HUGGINGFACE_HUB_TOKEN   # or $HF_TOKEN

响应采用 OpenAI 风格：{ "object": "list", "data": [ { "id": "Qwen/Qwen3-8B", "owned_by": "Qwen", ... }, ... ] }。

配置了 key（通过 onboarding 配置，或设置 HUGGINGFACE_HUB_TOKEN、HF_TOKEN）后，交互式设置过程中的 Default Hugging Face model 下拉列表将由该端点填充。Gateway 启动时会重复相同调用以刷新目录。匹配的内置模型会提供上下文窗口和成本等元数据。发现失败会产生目录失败结果；成功的空响应则保持为空。如果没有 key，则静态目录仍然可用，且不会启动发现流程。

在不移除提供方的情况下禁用发现：

openclaw config set plugins.entries.huggingface.config.discovery.enabled false

模型名称、别名与策略后缀

来自 API 的名称： 发现的模型在存在 name、title 或 display_name 时使用这些字段；否则 OpenClaw 会从模型 ID 派生出名称（例如 deepseek-ai/DeepSeek-R1 变为 “DeepSeek R1”）。
覆盖显示名称： 在配置中为每个模型设置自定义标签：

{
  agents: {
    defaults: {
      models: {
        "huggingface/deepseek-ai/DeepSeek-R1": { alias: "DeepSeek R1 (fast)" },
        "huggingface/deepseek-ai/DeepSeek-R1:cheapest": { alias: "DeepSeek R1 (cheap)" },
      },
    },
  },
}

策略后缀： :fastest 和 :cheapest 是 HF 路由器的约定，不是 OpenClaw 重写的内容；后缀会作为模型 ID 的一部分原样发送，由 HF 的路由器选择匹配的推理提供方。如果你希望每个后缀有不同别名，可将每个变体作为独立条目添加到 models.providers.huggingface.models（或 model.primary）下。
配置合并： 配置合并时会保留 models.providers.huggingface.models 中已有的条目（例如 models.json 中的条目），因此你在这里设置的任何自定义 name、alias 或模型选项都会在重启后继续存在。

环境与守护进程设置

如果 Gateway 以守护进程（launchd/systemd）方式运行，请确保该进程可以访问 `HUGGINGFACE_HUB_TOKEN` 或 `HF_TOKEN`（例如放在 `~/.openclaw/.env` 中，或通过 `env.shellEnv` 提供）。

Note

OpenClaw 同时接受 `HUGGINGFACE_HUB_TOKEN` 和 `HF_TOKEN`。如果两者都设置，`HUGGINGFACE_HUB_TOKEN` 优先。

配置：DeepSeek R1 及回退

{
  agents: {
    defaults: {
      model: {
        primary: "huggingface/deepseek-ai/DeepSeek-R1",
        fallbacks: ["huggingface/openai/gpt-oss-120b"],
      },
      models: {
        "huggingface/deepseek-ai/DeepSeek-R1": { alias: "DeepSeek R1" },
        "huggingface/openai/gpt-oss-120b": { alias: "GPT-OSS 120B" },
      },
    },
  },
}

配置：DeepSeek 的最便宜和最快变体

{
  agents: {
    defaults: {
      model: { primary: "huggingface/deepseek-ai/DeepSeek-R1" },
      models: {
        "huggingface/deepseek-ai/DeepSeek-R1": { alias: "DeepSeek R1" },
        "huggingface/deepseek-ai/DeepSeek-R1:cheapest": { alias: "DeepSeek R1 (cheapest)" },
        "huggingface/deepseek-ai/DeepSeek-R1:fastest": { alias: "DeepSeek R1 (fastest)" },
      },
    },
  },
}

配置：DeepSeek + GPT-OSS 及别名

{
  agents: {
    defaults: {
      model: {
        primary: "huggingface/deepseek-ai/DeepSeek-V3.1",
        fallbacks: ["huggingface/openai/gpt-oss-120b"],
      },
      models: {
        "huggingface/deepseek-ai/DeepSeek-V3.1": { alias: "DeepSeek V3.1" },
        "huggingface/openai/gpt-oss-120b": { alias: "GPT-OSS 120B" },
      },
    },
  },
}

模型选择

所有提供商、模型引用和故障转移行为的概述。

模型

如何选择和配置模型。

Inference Providers 文档

Hugging Face Inference Providers 官方文档。

配置

完整配置参考。

本页原文 Markdown：在 AtomGit 查看·内容源自开源项目 cl/openclaw