Hugging Face（Inference）

Hugging Face Inference Providers 通过统一路由 API 提供 OpenAI 兼容的对话补全服务，一个 Token 即可访问 DeepSeek、Llama 等众多模型。OpenClaw 使用其 OpenAI 兼容端点（仅对话补全）；文生图、Embedding 或语音服务请直接使用 HF inference clients。

• 提供商标识：huggingface
• 认证方式：HUGGINGFACE_HUB_TOKEN 或 HF_TOKEN（需要"Make calls to Inference Providers"权限）
• API：OpenAI 兼容（https://router.huggingface.co/v1）
• 计费：统一 HF Token，定价按提供商费率，含免费额度

快速开始

1. 在 Hugging Face → Settings → Tokens 创建细粒度 Token，勾选 Make calls to Inference Providers 权限。

2. 运行 onboarding，选择 Hugging Face 并输入 Token：

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

3. 在模型下拉菜单中选择默认模型（列表从 Inference API 实时加载，无 Token 时显示内置列表），选择结果自动保存为默认模型。

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 配置）。

模型发现与 onboarding 下拉列表

OpenClaw 通过调用 Inference 端点发现可用模型：

GET https://router.huggingface.co/v1/models

（可选：携带 Authorization: Bearer $HUGGINGFACE_HUB_TOKEN 获取完整列表；不带 Token 时部分端点只返回子集。）响应格式为 OpenAI 风格：{ "object": "list", "data": [ { "id": "Qwen/Qwen3-8B", "owned_by": "Qwen", ... }, ... ] }。

配置 Hugging Face API Key 后，OpenClaw 会用此 GET 请求发现可用的对话补全模型。交互式配置时，输入 Token 后会弹出从该列表填充的默认模型下拉菜单（请求失败则使用内置目录）。运行时（如 Gateway 启动），有 Key 的情况下 OpenClaw 会再次调用 GET https://router.huggingface.co/v1/models 刷新目录，并与内置目录合并（补充上下文窗口、费用等元数据）。若请求失败或未设置 Key，仅使用内置目录。

模型名称与可编辑选项

• API 返回的显示名称：优先使用 GET /v1/models 返回的 name、title 或 display_name；否则从模型 ID 派生（例如 deepseek-ai/DeepSeek-R1 → "DeepSeek R1"）。
• 覆盖显示名称：可在配置中为每个模型设置自定义标签：

{
  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，实际目录可能更多：

模型	引用（加上 huggingface/ 前缀）
DeepSeek R1	deepseek-ai/DeepSeek-R1
DeepSeek V3.2	deepseek-ai/DeepSeek-V3.2
Qwen3 8B	Qwen/Qwen3-8B
Qwen2.5 7B Instruct	Qwen/Qwen2.5-7B-Instruct
Qwen3 32B	Qwen/Qwen3-32B
Llama 3.3 70B Instruct	meta-llama/Llama-3.3-70B-Instruct
Llama 3.1 8B Instruct	meta-llama/Llama-3.1-8B-Instruct
GPT-OSS 120B	openai/gpt-oss-120b
GLM 4.7	zai-org/GLM-4.7
Kimi K2.5	moonshotai/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" },
      },
    },
  },
}

强制指定 Together 后端：

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

一个 HF Token 让你的龙虾同时拥有几十种模型可选，性价比相当高。