本页内容

本页内容

供应商

Hugging Face(推理)

Hugging Face 推理 Providers 在一个令牌下的许多托管模型(DeepSeek、Llama 等)前面公开了一个 OpenAI- 兼容的聊天完成路由器。 OpenClaw 仅与 聊天完成端点进行对话;对于文本到图像、嵌入或语音,请直接使用 HF 推理客户端。

属性 值
提供方 id huggingface
插件 bundled(默认启用,无需安装)
认证环境变量 HUGGINGFACE_HUB_TOKEN 或 HF_TOKEN(细粒度 token)
API OpenAI-兼容(https://router.huggingface.co/v1)
计费 单个 HF token;定价 遵循提供商费率,并提供免费层级

入门

  • 创建细粒度令牌

    Go 至 H 修改 Face 设置 Tokens 并创建新的细粒度令牌。

  • 运行入门引导培训

    在提供商下拉菜单中选择 Hugging Face,然后在提示时输入你的 API key:

    bash
    openclaw onboard --auth-choice huggingface-api-key
  • 选择默认模型

    在 默认 Hugging Face 模型 下拉菜单中选择一个模型。只要你的 token 有效,列表就会从 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 --accept-risk --skip-health \  --mode local \  --auth-choice huggingface-api-key \  --huggingface-api-key "$HF_TOKEN"

    将 huggingface/deepseek-ai/DeepSeek-R1 设置为默认模型。

    模型 ID

    模型参考使用 huggingface/<org>/<model> 形式(集线器样式 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 通过以下方式发现模型:

    http
    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 下拉列表从此端点填充。网关启动重复相同的调用来刷新目录。匹配的内置模型提供元数据,例如上下文窗口和成本。失败的发现会产生目录失败结果;成功的空响应将保持为空。如果没有密钥,静态目录仍然可用,而无需开始发现。

    如需禁用发现功能而不移除 provider:

    bash
    openclaw config set plugins.entries.huggingface.config.discovery.enabled false
    模型名称、别名和策略后缀
    • 来自 API 的名称: 发现的模型使用 API 的 name、title 或 display_name(如果存在);否则,OpenClaw 从模型 ID 中派生出一个名称(e.g. 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 router 的约定,不是 OpenClaw 会重写的内容:该后缀会作为模型 id 的一部分原样发送,HF 的 router 会选择匹配的推理 provider。如果你希望每个后缀都有不同的别名,请将每个变体作为单独条目添加到 models.providers.huggingface.models 下(或在 model.primary 中)。
    • 配置合并:models.providers.huggingface.models中的(models.json中的e.g.)中的现有条目保留在配置合并中,因此您在其中设置的任何自定义name、alias或模型选项都将持续存在重新启动。
    环境和守护进程设置

    如果 Gateway 作为守护进程运行(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" },      },    },  },}

    相关内容

    本页有帮助吗?