Providers

Hugging Face（推論）

Hugging Face 推論供應商透過單一權杖，為許多託管模型（DeepSeek、Llama 等）提供與 OpenAI 相容的聊天補全路由器。OpenClaw 僅使用聊天補全端點；若需文字轉圖片、嵌入或語音功能，請直接使用 HF 推論用戶端。

屬性	值
供應商 ID	`huggingface`
外掛	內建（預設啟用，無須安裝）
驗證環境變數	`HUGGINGFACE_HUB_TOKEN` 或 `HF_TOKEN`（細粒度權杖）
API	與 OpenAI 相容（`https://router.huggingface.co/v1`）
計費	單一 HF 權杖；定價依循各供應商費率，並提供免費方案

開始使用

建立細粒度權杖

前往 Hugging Face Settings Tokens，建立新的細粒度權杖。

執行初始設定

在供應商下拉式選單中選擇 Hugging Face，然後在提示出現時輸入你的 API 金鑰：

bash

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

選取預設模型

在 Default Hugging Face model 下拉式選單中選取模型。權杖有效時，清單會從 Inference API 載入；否則 OpenClaw 會顯示下方的內建目錄。你的選擇會儲存為 agents.defaults.model.primary：

json5

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

確認模型可用

bash

openclaw models list --provider huggingface

非互動式設定

bash

openclaw onboard --non-interactive \  --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`

進階設定

模型探索與初始設定下拉式選單

OpenClaw 使用以下方式探索模型：

bash

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

回應採用 OpenAI 樣式：{ "object": "list", "data": [ { "id": "Qwen/Qwen3-8B", "owned_by": "Qwen", ... }, ... ] }。

設定金鑰後（透過初始設定、HUGGINGFACE_HUB_TOKEN 或 HF_TOKEN），互動式設定期間的 Default Hugging Face model 下拉式選單會由此端點填入。閘道啟動時會重複相同呼叫以重新整理目錄。探索到的模型會與上述內建目錄合併（ID 相符時，內建目錄會用於提供內容窗口和成本等中繼資料）。如果請求失敗、未傳回資料或未設定金鑰，OpenClaw 只會退回使用內建目錄。

若要停用探索而不移除供應商：

bash

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

模型名稱、別名與原則後綴

**API 提供的名稱：**探索到的模型會在 API 的 name、title 或 display_name 存在時使用該值；否則 OpenClaw 會從模型 ID 衍生名稱（例如 deepseek-ai/DeepSeek-R1 會變成 “DeepSeek R1”）。
**覆寫顯示名稱：**在設定中為各模型設定自訂標籤：

json5

{  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 或模型選項都會在重新啟動後保留。

環境與常駐程式設定

如果閘道以常駐程式（launchd/systemd）方式執行，請確認該程序能存取 HUGGINGFACE_HUB_TOKEN 或 HF_TOKEN（例如透過 ~/.openclaw/.env 或 env.shellEnv）。

設定：使用 DeepSeek R1 並提供備援

json5

{  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 的最便宜和最快變體

json5

{  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 並設定別名

json5

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

Hugging Face（推論）

開始使用

建立細粒度權杖

執行初始設定

選取預設模型

確認模型可用

非互動式設定

模型 ID

進階設定

相關內容

On this page

Molty