> ## Documentation Index
> Fetch the complete documentation index at: https://docs2.openclaw.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Hugging Face (suy luận)

[Các nhà cung cấp suy luận của Hugging Face](https://huggingface.co/docs/inference-providers) cung cấp một bộ định tuyến hoàn thành hội thoại tương thích với OpenAI cho nhiều mô hình được lưu trữ (DeepSeek, Llama và nhiều mô hình khác) dưới một token duy nhất. OpenClaw chỉ giao tiếp với **điểm cuối hoàn thành hội thoại**; đối với chuyển văn bản thành hình ảnh, embedding hoặc giọng nói, hãy sử dụng trực tiếp [các ứng dụng khách suy luận HF](https://huggingface.co/docs/api-inference/quicktour).

| Thuộc tính               | Giá trị                                                                                                                                         |
| ------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------- |
| ID nhà cung cấp          | `huggingface`                                                                                                                                   |
| Plugin                   | đi kèm (được bật theo mặc định, không cần bước cài đặt)                                                                                         |
| Biến môi trường xác thực | `HUGGINGFACE_HUB_TOKEN` hoặc `HF_TOKEN` (token chi tiết)                                                                                        |
| API                      | Tương thích với OpenAI (`https://router.huggingface.co/v1`)                                                                                     |
| Thanh toán               | Một token HF duy nhất; [mức giá](https://huggingface.co/docs/inference-providers/pricing) tuân theo mức phí của nhà cung cấp và có gói miễn phí |

## Bắt đầu

<Steps>
  <Step title="Tạo token chi tiết">
    Truy cập [Hugging Face Settings Tokens](https://huggingface.co/settings/tokens/new?ownUserPermissions=inference.serverless.write\&tokenType=fineGrained) và tạo một token chi tiết mới.

    <Warning>
      Token phải được bật quyền **Make calls to Inference Providers**, nếu không các yêu cầu API sẽ bị từ chối.
    </Warning>
  </Step>

  <Step title="Chạy quy trình thiết lập ban đầu">
    Chọn **Hugging Face** trong danh sách thả xuống nhà cung cấp, sau đó nhập khóa API khi được nhắc:

    ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
    openclaw onboard --auth-choice huggingface-api-key
    ```
  </Step>

  <Step title="Chọn mô hình mặc định">
    Trong danh sách thả xuống **Default Hugging Face model**, hãy chọn một mô hình. Danh sách được tải từ Inference API khi token hợp lệ; nếu không, OpenClaw sẽ hiển thị danh mục tích hợp bên dưới. Lựa chọn của bạn được lưu dưới dạng `agents.defaults.model.primary`:

    ```json5 theme={"theme":{"light":"min-light","dark":"min-dark"}}
    {
      agents: {
        defaults: {
          model: { primary: "huggingface/deepseek-ai/DeepSeek-R1" },
        },
      },
    }
    ```
  </Step>

  <Step title="Xác minh mô hình có sẵn">
    ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
    openclaw models list --provider huggingface
    ```
  </Step>
</Steps>

### Thiết lập không tương tác

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
openclaw onboard --non-interactive \
  --mode local \
  --auth-choice huggingface-api-key \
  --huggingface-api-key "$HF_TOKEN"
```

Đặt `huggingface/deepseek-ai/DeepSeek-R1` làm mô hình mặc định.

## ID mô hình

Tham chiếu mô hình có dạng `huggingface/<org>/<model>` (ID kiểu Hub). Danh mục tích hợp của OpenClaw:

| Mô hình       | Tham chiếu (thêm tiền tố `huggingface/`) |
| ------------- | ---------------------------------------- |
| DeepSeek R1   | `deepseek-ai/DeepSeek-R1`                |
| DeepSeek V3.1 | `deepseek-ai/DeepSeek-V3.1`              |
| GPT-OSS 120B  | `openai/gpt-oss-120b`                    |

<Tip>
  Khi token hợp lệ, OpenClaw cũng phát hiện mọi mô hình khác từ **GET** `https://router.huggingface.co/v1/models` trong quá trình thiết lập ban đầu và khi Gateway khởi động, vì vậy danh mục của bạn có thể bao gồm nhiều hơn đáng kể so với ba mô hình trên. Bạn có thể thêm `:fastest` hoặc `:cheapest` vào bất kỳ ID mô hình nào; bộ định tuyến của HF sẽ định tuyến đến nhà cung cấp suy luận tương ứng. Đặt thứ tự nhà cung cấp mặc định trong [cài đặt Nhà cung cấp suy luận](https://hf.co/settings/inference-providers).
</Tip>

## Cấu hình nâng cao

<AccordionGroup>
  <Accordion title="Phát hiện mô hình và danh sách thả xuống khi thiết lập ban đầu">
    OpenClaw phát hiện các mô hình bằng:

    ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
    GET https://router.huggingface.co/v1/models
    Authorization: Bearer $HUGGINGFACE_HUB_TOKEN   # hoặc $HF_TOKEN
    ```

    Phản hồi theo kiểu OpenAI: `{ "object": "list", "data": [ { "id": "Qwen/Qwen3-8B", "owned_by": "Qwen", ... }, ... ] }`.

    Khi đã cấu hình khóa (qua quy trình thiết lập ban đầu, `HUGGINGFACE_HUB_TOKEN` hoặc `HF_TOKEN`), danh sách thả xuống **Default Hugging Face model** trong quá trình thiết lập tương tác sẽ được điền từ điểm cuối này. Khi Gateway khởi động, lệnh gọi tương tự được thực hiện lại để làm mới danh mục. Các mô hình được phát hiện sẽ được hợp nhất với danh mục tích hợp ở trên (dùng cho siêu dữ liệu như cửa sổ ngữ cảnh và chi phí khi ID trùng khớp). Nếu yêu cầu thất bại, không trả về dữ liệu hoặc chưa đặt khóa, OpenClaw chỉ sử dụng danh mục tích hợp.

    Tắt tính năng phát hiện mà không xóa nhà cung cấp:

    ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
    openclaw config set plugins.entries.huggingface.config.discovery.enabled false
    ```
  </Accordion>

  <Accordion title="Tên mô hình, bí danh và hậu tố chính sách">
    * **Tên từ API:** các mô hình được phát hiện sử dụng `name`, `title` hoặc `display_name` của API khi có; nếu không, OpenClaw suy ra tên từ ID mô hình (ví dụ: `deepseek-ai/DeepSeek-R1` trở thành "DeepSeek R1").
    * **Ghi đè tên hiển thị:** đặt nhãn tùy chỉnh cho từng mô hình trong cấu hình:

    ```json5 theme={"theme":{"light":"min-light","dark":"min-dark"}}
    {
      agents: {
        defaults: {
          models: {
            "huggingface/deepseek-ai/DeepSeek-R1": { alias: "DeepSeek R1 (fast)" },
            "huggingface/deepseek-ai/DeepSeek-R1:cheapest": { alias: "DeepSeek R1 (cheap)" },
          },
        },
      },
    }
    ```

    * **Hậu tố chính sách:** `:fastest` và `:cheapest` là quy ước của bộ định tuyến HF, không phải nội dung mà OpenClaw viết lại: hậu tố được gửi nguyên văn như một phần của ID mô hình và bộ định tuyến của HF chọn nhà cung cấp suy luận tương ứng. Thêm từng biến thể dưới dạng một mục riêng trong `models.providers.huggingface.models` (hoặc trong `model.primary`) nếu bạn muốn có bí danh riêng cho từng hậu tố.
    * **Hợp nhất cấu hình:** các mục hiện có trong `models.providers.huggingface.models` (ví dụ: trong `models.json`) được giữ lại khi hợp nhất cấu hình, vì vậy mọi `name`, `alias` tùy chỉnh hoặc tùy chọn mô hình bạn đặt ở đó vẫn tồn tại sau khi khởi động lại.
  </Accordion>

  <Accordion title="Thiết lập môi trường và daemon">
    Nếu Gateway chạy dưới dạng daemon (launchd/systemd), hãy đảm bảo `HUGGINGFACE_HUB_TOKEN` hoặc `HF_TOKEN` khả dụng cho tiến trình đó (ví dụ: trong `~/.openclaw/.env` hoặc thông qua `env.shellEnv`).

    <Note>
      OpenClaw chấp nhận cả `HUGGINGFACE_HUB_TOKEN` và `HF_TOKEN`. Nếu cả hai đều được đặt, `HUGGINGFACE_HUB_TOKEN` được ưu tiên.
    </Note>
  </Accordion>

  <Accordion title="Cấu hình: DeepSeek R1 với phương án dự phòng">
    ```json5 theme={"theme":{"light":"min-light","dark":"min-dark"}}
    {
      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" },
          },
        },
      },
    }
    ```
  </Accordion>

  <Accordion title="Cấu hình: DeepSeek với các biến thể rẻ nhất và nhanh nhất">
    ```json5 theme={"theme":{"light":"min-light","dark":"min-dark"}}
    {
      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)" },
          },
        },
      },
    }
    ```
  </Accordion>

  <Accordion title="Cấu hình: DeepSeek + GPT-OSS với bí danh">
    ```json5 theme={"theme":{"light":"min-light","dark":"min-dark"}}
    {
      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" },
          },
        },
      },
    }
    ```
  </Accordion>
</AccordionGroup>

## Liên quan

<CardGroup cols={2}>
  <Card title="Lựa chọn mô hình" href="/vi/concepts/model-providers" icon="layers">
    Tổng quan về tất cả nhà cung cấp, tham chiếu mô hình và hành vi chuyển đổi dự phòng.
  </Card>

  <Card title="Lựa chọn mô hình" href="/vi/concepts/models" icon="brain">
    Cách chọn và cấu hình mô hình.
  </Card>

  <Card title="Tài liệu Nhà cung cấp suy luận" href="https://huggingface.co/docs/inference-providers" icon="book">
    Tài liệu chính thức về Nhà cung cấp suy luận của Hugging Face.
  </Card>

  <Card title="Cấu hình" href="/vi/gateway/configuration" icon="gear">
    Tài liệu tham chiếu cấu hình đầy đủ.
  </Card>
</CardGroup>