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；價格依供應商費率計算，含免費方案。

快速開始

1. 在 Hugging Face → Settings → Tokens 建立精細 token，並勾選 Make calls to Inference Providers 權限。
2. 執行新手引導，在供應商下拉選單中選擇 Hugging Face，然後依提示輸入 API 金鑰：

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

3. 在預設 Hugging Face 模型下拉選單中，選擇你要使用的模型（若 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 設定）。

模型探索與新手引導下拉選單

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 金鑰後（透過新手引導、HUGGINGFACE_HUB_TOKEN 或 HF_TOKEN），OpenClaw 會用這個 GET 請求探索可用的聊天完成模型。在互動式新手引導中，輸入 token 後會看到預設 Hugging Face 模型下拉選單，內容來自該清單（若請求失敗則使用內建目錄）。在執行階段（如 Gateway 啟動時），有金鑰時 OpenClaw 會再次呼叫 GET https://router.huggingface.co/v1/models 以重新整理目錄。清單會與內建目錄合併（用於上下文視窗和成本等中繼資料）。若請求失敗或未設定金鑰，則僅使用內建目錄。

模型名稱與可編輯選項

• 來自 API 的名稱： 模型顯示名稱從 GET /v1/models 取得，API 回傳 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)" },
      },
    },
  },
}

• 供應商/策略選擇： 在模型 ID 後加上後綴來選擇路由器如何挑選後端：

  • :fastest — 最高吞吐量（路由器選擇；供應商選擇被鎖定 — 不會出現互動式後端選取）。
  • :cheapest — 每輸出 token 最低成本（路由器選擇；供應商選擇被鎖定）。
  • :provider — 強制使用特定後端（例如 :sambanova、:together）。

  當你選擇 :cheapest 或 :fastest（例如在新手引導模型下拉選單中），供應商會被鎖定：路由器依成本或速度決定，不會顯示「偏好特定後端」的選項。你可以在 models.providers.huggingface.models 中加入這些作為獨立項目，或在 model.primary 中使用帶後綴的格式。你也可以在 Inference Provider 設定 中設定預設順序（不加後綴 = 使用該順序）。

• 設定合併： 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 設定 中設定預設順序；詳見 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" },
      },
    },
  },
}