Hugging Face (Inference)

Hugging Face Inference Providers 通过统一的路由 API 提供 OpenAI 兼容的聊天补全。一个 token 即可访问众多模型（DeepSeek、Llama 等）。OpenClaw 使用的是 OpenAI 兼容端点（仅聊天补全）；文生图、嵌入或语音等功能请直接使用 HF inference 客户端。

• Provider：huggingface
• 认证：HUGGINGFACE_HUB_TOKEN 或 HF_TOKEN（需要 Make calls to Inference Providers 权限的细粒度 token）
• API：OpenAI 兼容（https://router.huggingface.co/v1）
• 计费：单个 HF token；定价按 provider 费率，有免费额度。

快速开始

1. 在 Hugging Face → Settings → Tokens 创建细粒度 token，勾选 Make calls to Inference Providers 权限。
2. 运行 onboarding，在 provider 下拉菜单中选择 Hugging Face，然后输入 API 密钥：

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

3. 在 Default Hugging Face model 下拉菜单中选择你要用的模型（有有效 token 时列表从 Inference API 加载；否则显示内置列表）。你的选择会保存为默认模型。
4. 之后也可以在配置中修改默认模型：

{
  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 设为默认模型。

环境说明

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

模型发现和 onboarding 下拉菜单

OpenClaw 直接调用 Inference 端点 发现模型：

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 密钥后（通过 onboarding、HUGGINGFACE_HUB_TOKEN 或 HF_TOKEN），OpenClaw 用这个 GET 请求发现可用的聊天补全模型。交互式 onboarding 中输入 token 后，你会看到从该列表（或请求失败时的内置目录）填充的 Default Hugging Face model 下拉菜单。运行时（如 Gateway 启动时），有密钥时 OpenClaw 会再次调用 GET https://router.huggingface.co/v1/models 刷新目录。结果与内置目录合并（用于上下文窗口和成本等元数据）。请求失败或未设置密钥时，仅使用内置目录。

模型名称和可编辑选项

• API 返回的名称： 模型显示名称从 GET /v1/models 的 name、title 或 display_name 字段获取；没有的话从模型 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)" },
      },
    },
  },
}

• Provider / 策略选择： 在模型 ID 后面加后缀来指定路由策略：

  • :fastest — 最高吞吐量（由路由器选择；provider 选择是锁定的——不会弹出交互式后端选择）。
  • :cheapest — 每输出 token 成本最低（由路由器选择；provider 选择是锁定的）。
  • :provider — 强制指定后端（如 :sambanova、:together）。

  选择 :cheapest 或 :fastest 时（比如在 onboarding 模型下拉菜单中），provider 是锁定的：路由器按成本或速度决定，不会显示可选的”选择特定后端”步骤。你可以把这些作为单独条目加到 models.providers.huggingface.models 中，或者带后缀设置 model.primary。也可以在 Inference Provider settings 中设置默认顺序（不加后缀 = 使用该顺序）。

• 配置合并： models.providers.huggingface.models 中的现有条目（如 models.json 中的）在配置合并时保留。所以你设置的自定义 name、alias 或模型选项不会丢失。

模型 ID 和配置示例

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

示例 ID（来自 inference 端点）：

可以在模型 ID 后面加 :fastest、:cheapest 或 :provider（如 :together、:sambanova）。在 Inference Provider settings 设置默认顺序；详见 Inference Providers 和 GET https://router.huggingface.co/v1/models 获取完整列表。

完整配置示例

DeepSeek R1 为主，Qwen 兜底：

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