快速开始
Hugging Face（推理）
Hugging Face Inference Providers 使用一个令牌，为众多托管模型（DeepSeek、Llama 等）提供兼容 OpenAI 的聊天补全路由器。OpenClaw 仅使用聊天补全端点；对于文生图、嵌入或语音，请直接使用 HF 推理客户端。
| 属性 | 值 |
|---|---|
| 提供商 ID | huggingface |
| 插件 | 内置（默认启用，无需安装） |
| 身份验证环境变量 | HUGGINGFACE_HUB_TOKEN 或 HF_TOKEN（细粒度令牌） |
| API | 兼容 OpenAI（https://router.huggingface.co/v1） |
| 计费 | 使用单个 HF 令牌；定价遵循提供商费率，并提供免费额度 |
入门指南
Create a fine-grained token
前往 Hugging Face Settings Tokens，创建一个新的细粒度令牌。
Run onboarding
在提供商下拉列表中选择 Hugging Face，然后在提示时输入你的 API 密钥：
openclaw onboard --auth-choice huggingface-api-keySelect a default model
在 默认 Hugging Face 模型下拉列表中选择一个模型。当令牌有效时，该列表会从推理 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
模型引用采用 huggingface/<org>/<model> 格式（Hub 风格的 ID）。OpenClaw 的内置目录如下：
| 模型 | 引用（添加 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", ... }, ... ] }。
配置密钥后（通过新手引导、HUGGINGFACE_HUB_TOKEN 或 HF_TOKEN），交互式设置期间的默认 Hugging Face 模型下拉列表将由此端点填充。Gateway 网关启动时会重复执行相同调用，以刷新目录。发现的模型会与上述内置目录合并（当 ID 匹配时，内置目录用于提供上下文窗口和成本等元数据）。如果请求失败、未返回数据或未设置密钥，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" }, }, }, },}