Hugging Face（inference）

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 を使って利用可能な chat-completion モデルを検出します。対話セットアップ 中では、token を入力した後に Default Hugging Face model ドロップダウンが表示され、この一覧（またはリクエスト失敗時は組み込みカタログ）から埋められます。ランタイム中（たとえば Gateway 起動時）も、キーが存在すれば OpenClaw は再び GET https://router.huggingface.co/v1/models を呼び出してカタログを更新します。この一覧は、組み込みカタログ（コンテキストウィンドウやコストなどのメタデータ用）とマージされます。リクエストが失敗した場合、またはキーが設定されていない場合は、組み込みカタログのみが使われます。

• API 由来の名前: モデル表示名は、API が name, title, display_name を返した場合、それを GET /v1/models から hydrate します。そうでない場合はモデル ID から導出されます（例: deepseek-ai/DeepSeek-R1 は「DeepSeek R1」になります）。
• 表示名を上書き: config でモデルごとにカスタムラベルを設定すると、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 ドキュメントと helper は現在、この 2 つのサフィックスを組み込みポリシーバリアントとして扱います:

  • :fastest — 最大スループット
  • :cheapest — 出力トークン単価が最安

  これらは models.providers.huggingface.models に別エントリとして追加することも、model.primary にサフィックス付きで設定することもできます。デフォルトの provider 順序は Inference Provider settings でも設定できます（サフィックスなし = その順序を使う）。

• Config merge: models.providers.huggingface.models 内の既存エントリ（例: models.json 内）は、config マージ時に保持されます。そのため、そこに設定したカスタム name, alias, またはモデルオプションは保持されます。

Gateway を daemon（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" },
      },
    },
  },
}