Hugging Face（推論）

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 來探索可用的聊天補全模型。在互動式設定期間，輸入權杖後，你會看到一個預設 Hugging Face 模型下拉選單，內容來自該清單（或在請求失敗時使用內建目錄）。執行階段（例如 Gateway 啟動）若存在金鑰，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)" },
      },
    },
  },
}

• 策略尾碼： OpenClaw 內附的 Hugging Face 文件和輔助工具目前將這兩個尾碼視為內建策略變體：

  • :fastest — 最高吞吐量。
  • :cheapest — 每個輸出權杖的最低成本。

  你可以將這些新增為 models.providers.huggingface.models 中的獨立項目，或使用帶有尾碼的 model.primary。你也可以在 Inference Provider 設定中設定預設提供者順序（無尾碼 = 使用該順序）。

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

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

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

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

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

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