Skip to content
OpenClaw Docs

Hugging Face (Inference)

Hugging Face (Inference)

Section titled “Hugging Face (Inference)”

Hugging Face Inference Providers 透過單一路由器 API 提供 OpenAI 相容的聊天完成功能。您可以使用一個 Token 存取多種模型（DeepSeek、Llama 等）。OpenClaw 使用 OpenAI 相容端點（僅限聊天完成）；若需文字轉圖片、嵌入或語音功能，請直接使用 HF inference clients。

  • 提供者： huggingface
  • 驗證： HUGGINGFACE_HUB_TOKEN 或 HF_TOKEN （具備 Make calls to Inference Providers 權限的細粒度 Token）
  • API：OpenAI 相容 (https://router.huggingface.co/v1)
  • 計費：單一 HF Token；定價 依提供者費率並附有免費層級。

快速開始

Section titled “快速開始”
  1. 請前往 Hugging Face → Settings → Tokens 建立具備 Make calls to Inference Providers 權限的細粒度 Token。
  2. 執行設定精靈，在提供者下拉選單中選擇 Hugging Face，然後在提示時輸入您的 API 金鑰：
Terminal window
openclaw onboard --auth-choice huggingface-api-key
  1. 在 Default Hugging Face model 下拉選單中，選擇您想要的模型（當您擁有有效的 Token 時，清單會從 Inference API 載入；否則會顯示內建清單）。您的選擇將會被儲存為預設模型。
  2. 您也可以稍後在設定中設定或變更預設模型：
{
  agents: {
    defaults: {
      model: { primary: "huggingface/deepseek-ai/DeepSeek-R1" },
    },
  },
}

非互動式範例

Section titled “非互動式範例”
Terminal window
openclaw onboard --non-interactive \
  --mode local \
  --auth-choice huggingface-api-key \
  --huggingface-api-key "$HF_TOKEN"

這會將 huggingface/deepseek-ai/DeepSeek-R1 設定為預設模型。

環境注意事項

Section titled “環境注意事項”

如果 Gateway 以守護程序 (launchd/systemd) 執行，請確保 HUGGINGFACE_HUB_TOKEN 或 HF_TOKEN 對該程序可用（例如，在 ~/.openclaw/.env 中或透過 env.shellEnv）。

模型探索與設定精靈下拉選單

Section titled “模型探索與設定精靈下拉選單”

OpenClaw 透過直接呼叫 Inference endpoint 來探索模型：

Terminal window
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 來重新整理目錄。該清單會與內建目錄合併（用於上下文視窗和成本等元資料）。如果請求失敗或未設定金鑰，則僅使用內建目錄。

模型名稱和可編輯選項

Section titled “模型名稱和可編輯選項”
  • 來自 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 — 每個輸出權杖的最低成本（由路由器選擇；提供者選擇已鎖定）。
    • :provider — 強制使用特定後端（例如 :sambanova、:together）。

    當您選擇 :cheapest 或 :fastest（例如在入門引導模型下拉選單中）時，提供者會被鎖定：路由器會根據成本或速度進行決定，並且不會顯示可選的「優先選擇特定後端」步驟。您可以將它們作為單獨的條目新增到 models.providers.huggingface.models 或設定 model.primary 並帶有後綴。您也可以在 推論提供者設定 中設定您的預設順序（無後綴 = 使用該順序）。

  • 設定合併： 當合併設定時，會保留 models.providers.huggingface.models 中的現有條目（例如在 models.json 中）。因此，您在那裡設定的任何自訂 name、alias 或模型選項都會被保留。

模型 ID 與設定範例

Section titled “模型 ID 與設定範例”

模型參照使用 huggingface/<org>/<model> 的形式（Hub 風格的 ID）。以下列表來自 GET https://router.huggingface.co/v1/models；您的目錄可能包含更多內容。

範例 ID（來自推論端點）：

模型參照（加上 huggingface/ 前綴）
DeepSeek R1deepseek-ai/DeepSeek-R1
DeepSeek V3.2deepseek-ai/DeepSeek-V3.2
Qwen3 8BQwen/Qwen3-8B
Qwen2.5 7B InstructQwen/Qwen2.5-7B-Instruct
Qwen3 32BQwen/Qwen3-32B
Llama 3.3 70B Instructmeta-llama/Llama-3.3-70B-Instruct
Llama 3.1 8B Instructmeta-llama/Llama-3.1-8B-Instruct
GPT-OSS 120Bopenai/gpt-oss-120b
GLM 4.7zai-org/GLM-4.7
Kimi K2.5moonshotai/Kimi-K2.5

您可以將 :fastest、:cheapest 或 :provider（例如 :together、:sambanova）附加到模型 ID。在 推論提供者設定 中設定您的預設順序；請參閱 推論提供者 和 GET https://router.huggingface.co/v1/models 以取得完整列表。

完整設定範例

Section titled “完整設定範例”

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