快速开始
Hugging Face（推理）
Hugging Face Inference Providers 在许多托管模型（DeepSeek、Llama 等）前提供一个兼容 OpenAI 的聊天补全路由器，并使用同一个 token。OpenClaw 仅使用聊天补全端点；如需文本生成图像、嵌入或语音，请直接使用 HF inference clients。
| 属性 | 值 |
|---|---|
| 提供商 id | huggingface |
| 插件 | 内置（默认启用，无需安装步骤） |
| 凭证环境变量 | HUGGINGFACE_HUB_TOKEN 或 HF_TOKEN（精细粒度 token） |
| API | 兼容 OpenAI（https://router.huggingface.co/v1） |
| 计费 | 单个 HF token；定价 按提供商费率执行，并提供免费套餐 |
入门指南
Create a fine-grained token
前往 Hugging Face Settings Tokens，创建一个新的精细粒度 token。
Run onboarding
在提供商下拉菜单中选择 Hugging Face，然后在提示时输入你的 API key：
openclaw onboard --auth-choice huggingface-api-keySelect a default model
在 Default Hugging Face model 下拉菜单中选择一个模型。当你的 token 有效时，该列表会从 Inference API 加载；否则 OpenClaw 会显示下面的内置目录。你的选择会保存为 agents.defaults.model.primary：
{ agents: { defaults: { model: { primary: "huggingface/deepseek-ai/DeepSeek-R1" }, }, },}Verify the model is available
openclaw models list --provider huggingface非交互式设置
openclaw onboard --non-interactive \ --mode local \ --auth-choice huggingface-api-key \ --huggingface-api-key "$HF_TOKEN"将 huggingface/deepseek-ai/DeepSeek-R1 设为默认模型。
模型 ID
模型 ref 使用 huggingface/<org>/<model> 形式（Hub 风格 ID）。OpenClaw 的内置目录：
| 模型 | Ref（前缀为 huggingface/） |
|---|---|
| DeepSeek R1 | deepseek-ai/DeepSeek-R1 |
| DeepSeek V3.1 | deepseek-ai/DeepSeek-V3.1 |
| GPT-OSS 120B | openai/gpt-oss-120b |
| Llama 3.3 70B Instruct Turbo | meta-llama/Llama-3.3-70B-Instruct-Turbo |
高级配置
Model discovery and onboarding dropdown
OpenClaw 使用以下方式发现模型：
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", ... }, ... ] }。
配置了 key（新手引导、HUGGINGFACE_HUB_TOKEN 或 HF_TOKEN）后，交互式设置期间的 Default Hugging Face model 下拉菜单会由该端点填充。Gateway 网关启动时会重复同一个调用来刷新目录。发现的模型会与上面的内置目录合并（当 id 匹配时，用于上下文窗口和成本等元数据）。如果请求失败、未返回数据，或未设置 key，OpenClaw 只会回退到内置目录。
在不移除提供商的情况下禁用发现：
openclaw config set plugins.entries.huggingface.config.discovery.enabled falseModel names, aliases, and policy suffixes
- 来自 API 的名称： 发现的模型在存在时会使用 API 的
name、title或display_name；否则 OpenClaw 会从模型 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)" }, }, }, },}- 策略后缀：
:fastest和:cheapest是 HF 路由器约定，而不是 OpenClaw 会改写的内容：该后缀会作为模型 id 的一部分原样发送，HF 的路由器会选择匹配的推理提供商。如果你希望每个后缀都有不同别名，请将每个变体作为自己的条目添加到models.providers.huggingface.models下（或添加到model.primary中）。 - 配置合并：
models.providers.huggingface.models中已有的条目（例如在models.json中）会在配置合并时保留，因此你在那里设置的任何自定义name、alias或模型选项都会在重启后继续保留。
Environment and daemon setup
如果 Gateway 网关作为守护进程运行（launchd/systemd），请确保 HUGGINGFACE_HUB_TOKEN 或 HF_TOKEN 可供该进程使用（例如放在 ~/.openclaw/.env 中，或通过 env.shellEnv 提供）。
Config: DeepSeek R1 with fallback
{ 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" }, }, }, },}Config: DeepSeek with cheapest and fastest variants
{ 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)" }, }, }, },}Config: DeepSeek + Llama + GPT-OSS with aliases
{ agents: { defaults: { model: { primary: "huggingface/deepseek-ai/DeepSeek-V3.1", fallbacks: [ "huggingface/meta-llama/Llama-3.3-70B-Instruct-Turbo", "huggingface/openai/gpt-oss-120b", ], }, models: { "huggingface/deepseek-ai/DeepSeek-V3.1": { alias: "DeepSeek V3.1" }, "huggingface/meta-llama/Llama-3.3-70B-Instruct-Turbo": { alias: "Llama 3.3 70B Turbo" }, "huggingface/openai/gpt-oss-120b": { alias: "GPT-OSS 120B" }, }, }, },}