Hugging Face (Inference)

Hugging Face Inference Providersは、単一のルーターAPIを通じてOpenAI互換のチャット補完を提供します。1つのトークンでDeepSeek、Llamaなど多数のモデルにアクセスできます。OpenClawはOpenAI互換エンドポイント（チャット補完のみ）を使用します。画像生成、エンベディング、音声についてはHF inference clientsを直接使用してください。

  • プロバイダー：huggingface
  • 認証：HUGGINGFACE_HUB_TOKENまたはHF_TOKEN（Make calls to Inference Providers権限付きのfine-grainedトークン）
  • API：OpenAI互換（https://router.huggingface.co/v1）
  • 課金：単一のHFトークンで利用。料金表はプロバイダーのレートに準じ、無料枠あり。

クイックスタート

  1. Hugging Face → Settings → TokensでMake calls to Inference Providers権限付きのfine-grainedトークンを作成します。
  2. オンボーディングを実行し、プロバイダードロップダウンでHugging Faceを選択して、プロンプトに従いAPIキーを入力します：
openclaw onboard --auth-choice huggingface-api-key
  1. Default Hugging Face modelドロップダウンで使用したいモデルを選びます（有効なトークンがある場合、一覧はInference APIから読み込まれます。そうでなければ組み込みの一覧が表示されます）。選択したモデルがデフォルトモデルとして保存されます。
  2. 設定でデフォルトモデルを後から変更することもできます：
{
  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リクエストで利用可能なチャット補完モデルを検出します。対話型オンボーディングでは、トークン入力後にそのリストから取得されたDefault Hugging Face modelドロップダウンが表示されます（リクエスト失敗時は組み込みカタログを使用）。ランタイム時（例：Gatewayの起動時）、キーが存在するとGET https://router.huggingface.co/v1/modelsを再度呼び出してカタログを更新します。一覧は組み込みカタログ（コンテキストウィンドウやコストなどのメタデータ用）とマージされます。リクエスト失敗時やキー未設定時は組み込みカタログのみが使用されます。

モデル名と編集可能なオプション

  • APIからの名前： モデル表示名はGET /v1/modelsのレスポンスに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 — 出力トークンあたり最低コスト（ルーターが選択、プロバイダーは固定）。
    • :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エンドポイントから取得）：

モデル参照（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

モデル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" },
      },
    },
  },
}
arrow_back
前へ
Github Copilot
次へ
Kilocode
arrow_forward