Providers
Hugging Face (استنتاج)
ارائهدهندگان استنتاج Hugging Face یک مسیریاب تکمیل گفتوگوی سازگار با OpenAI را برای مدلهای میزبانیشدهٔ متعدد (DeepSeek، Llama و مدلهای دیگر) با یک توکن ارائه میکند. OpenClaw فقط با نقطهٔ پایانی تکمیل گفتوگو ارتباط برقرار میکند؛ برای تبدیل متن به تصویر، تعبیهسازی یا گفتار، مستقیماً از کلاینتهای استنتاج HF استفاده کنید.
| ویژگی | مقدار |
|---|---|
| شناسهٔ ارائهدهنده | huggingface |
| Plugin | همراه محصول (بهطور پیشفرض فعال است و نیازی به نصب ندارد) |
| متغیر محیطی احراز هویت | HUGGINGFACE_HUB_TOKEN یا HF_TOKEN (توکن با دسترسی ریزدانه) |
| API | سازگار با OpenAI (https://router.huggingface.co/v1) |
| صورتحساب | یک توکن HF؛ قیمتگذاری بر اساس تعرفههای ارائهدهنده و همراه با سطح رایگان است |
شروع به کار
Create a fine-grained token
به توکنهای تنظیمات Hugging Face بروید و یک توکن ریزدانهٔ جدید ایجاد کنید.
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 را بهعنوان مدل پیشفرض تنظیم میکند.
شناسههای مدل
ارجاعهای مدل از قالب huggingface/<org>/<model> استفاده میکنند (شناسههایی به سبک Hub). کاتالوگ داخلی 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، همین درخواست برای تازهسازی کاتالوگ تکرار میشود. مدلهای شناساییشده با کاتالوگ داخلی بالا ادغام میشوند؛ این کاتالوگ برای فرادادههایی مانند پنجرهٔ زمینه و هزینه، در صورت تطابق شناسه، استفاده میشود. اگر درخواست ناموفق باشد، دادهای برنگرداند یا هیچ کلیدی تنظیم نشده باشد، OpenClaw فقط به کاتالوگ داخلی بازمیگردد.
برای غیرفعالکردن شناسایی بدون حذف ارائهدهنده:
openclaw config set plugins.entries.huggingface.config.discovery.enabled falseModel names, aliases, and policy suffixes
- نام دریافتی از API: مدلهای شناساییشده در صورت وجود از
name،titleیاdisplay_nameدر API استفاده میکنند؛ در غیر این صورت OpenClaw نامی را از شناسهٔ مدل استخراج میکند (برای مثال،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 آنها را بازنویسی نمیکند: پسوند عیناً بهعنوان بخشی از شناسهٔ مدل ارسال میشود و مسیریاب 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" }, }, }, },}