OpenClaw Hugging Face 推理提供商配置指南

Hugging Face 推理提供商通过单个路由 API，提供兼容 OpenAI 的聊天补全能力。你可以使用一个令牌访问众多模型（DeepSeek、Llama 等）。OpenClaw 接入了其兼容 OpenAI 的端点（仅支持聊天补全）；如果需要文生图、嵌入或是语音能力，请直接使用 HF 推理客户端。 提供商标识：huggingface 鉴权方式：HUGGINGFACE_HUB_TOKEN 或 HF_TOKEN（细粒度令牌，需拥有 Make calls to Inference Providers 权限） API 类型：兼容 OpenAI（端点为 https://router.huggingface.co/v1） 计费说明：单个 HF 令牌即可；定价遵循各提供商的费率，同时提供免费额度。

快速开始

在 Hugging Face → 设置 → 令牌页面，创建一个细粒度令牌，确保开启 Make calls to Inference Providers 权限。 运行入职流程，在提供商下拉菜单中选择 Hugging Face，然后按提示输入你的 API 密钥：

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

在默认 Hugging Face 模型下拉菜单中，选择你想要使用的模型（当你拥有有效令牌时，列表会从推理 API 动态加载；否则会显示内置的默认列表）。你的选择会被保存为默认模型。 你也可以后续在配置中设置或修改默认模型：

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

非交互式示例

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

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

环境说明

如果网关以守护进程（launchd/systemd）的方式运行，请确保 HUGGINGFACE_HUB_TOKEN 或 HF_TOKEN 对该进程可见（例如，放在 ~/.openclaw/.env 中，或是通过 env.shellEnv 配置）。

模型发现与入职下拉选项

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 模型的下拉菜单，其内容就来自这个列表（如果请求失败，则会回退到内置目录）。 在运行时（例如网关启动时），如果存在有效密钥，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)" },

提供商 / 策略选择：你可以在模型 ID 后添加后缀，来选择路由选择后端的方式： :fastest — 最高吞吐量（由路由自动选择；提供商选择已锁定，无交互式后端选择器） :cheapest — 输出 token 最低成本（由路由自动选择；提供商选择已锁定） :provider — 强制指定特定后端（例如 :sambanova、:together） 当你选择 :cheapest 或 :fastest（比如在入职的模型下拉菜单中），提供商会被锁定：路由会根据成本或速度自动决策，不会显示可选的 “优先特定后端” 的步骤。你可以将这些作为单独的条目添加到 models.providers.huggingface.models 中，或是在 model.primary 中带上后缀。你也可以在推理提供商设置中设置默认的排序（不带后缀则使用该排序）。 配置合并：当配置合并时，models.providers.huggingface.models 中的现有条目（例如在 models.json 中）会被保留。因此你在那里设置的任何自定义名称、别名或是模型选项都会被保留。

模型 ID 与配置示例

模型引用的格式为 huggingface / <组织> / <模型>（Hub 风格的 ID）。下方列表来自 GET https://router.huggingface.co/v1/models；你的目录可能包含更多内容。 示例 ID（来自推理端点）： 模型引用（前缀 huggingface /） 对应模型 deepseek-ai/DeepSeek-R1 DeepSeek R1 deepseek-ai/DeepSeek-V3.2 DeepSeek V3.2 Qwen/Qwen3-8B Qwen3 8B Qwen/Qwen2.5-7B-Instruct Qwen2.5 7B Instruct Qwen/Qwen3-32B Qwen3 32B meta-llama/Llama-3.3-70B-Instruct Llama 3.3 70B Instruct meta-llama/Llama-3.1-8B-Instruct Llama 3.1 8B Instruct openai/gpt-oss-120b GPT-OSS 120B zai-org/GLM-4.7 GLM 4.7 moonshotai/Kimi-K2.5 Kimi K2.5

你可以在模型 ID 后追加 :fastest、:cheapest 或是 :provider（例如 :together、:sambanova）。你可以在推理提供商设置中设置默认排序；查看推理提供商以及 GET https://router.huggingface.co/v1/models 以获取完整列表。

完整配置示例

主模型为 DeepSeek R1，Qwen 作为 fallback

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

Qwen 作为默认，同时配置 :cheapest 与 :fastest 变体

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

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

强制指定特定后端，使用 :provider 后缀

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

多个 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" },
    },