# OpenClaw (/vi/docs/guides/openclaw)

Chạy trợ lý AI cá nhân OpenClaw trên các mô hình cheapaimodel qua một nhà cung cấp mô hình tùy chỉnh.



OpenClaw thêm các dịch vụ tương thích OpenAI làm nhà cung cấp tùy chỉnh trong `models.providers` của `~/.openclaw/openclaw.json`. Sau đó, các agent tham chiếu mô hình dưới dạng `cheapaimodel/<model-id>`.

|            | Cài đặt OpenClaw                            | Giá trị                                                                                                                    |
| ---------- | ------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------- |
| Base URL   | `models.providers.cheapaimodel.baseUrl`     | `https://api.cheapaimodel.ai/v1`                                                                                           |
| API key    | `models.providers.cheapaimodel.apiKey`      | `${CHEAPAIMODEL_API_KEY}`, chứa key của bạn từ trang [API key](https://console.cheapaimodel.ai/keys) trong bảng điều khiển |
| ID mô hình | `models.providers.cheapaimodel.models[].id` | `glm-5.3`, hoặc bất kỳ ID nào trong [danh mục](/vi/models)                                                                 |

## Thiết lập [#set-it-up]

<Steps>
  <Step>
    ### Lưu key [#store-the-key]

    Đặt key vào tệp env toàn cục của OpenClaw; Gateway đọc tệp này kể cả khi chạy dưới dạng dịch vụ nền:

    ```bash title="~/.openclaw/.env"
    CHEAPAIMODEL_API_KEY=sk-...
    ```

    Nếu Gateway đang chạy, khởi động lại bằng `openclaw gateway restart` để Gateway đọc tệp.
  </Step>

  <Step>
    ### Thêm nhà cung cấp [#add-the-provider]

    Gộp đoạn sau vào cấu hình của bạn:

    ```json5 title="~/.openclaw/openclaw.json"
    {
      agents: {
        defaults: {
          model: { primary: "cheapaimodel/glm-5.3" },
        },
      },
      models: {
        mode: "merge",
        providers: {
          cheapaimodel: {
            baseUrl: "https://api.cheapaimodel.ai/v1",
            apiKey: "${CHEAPAIMODEL_API_KEY}",
            api: "openai-completions",
            models: [
              {
                id: "glm-5.3",
                name: "GLM-5.3",
                compat: { supportsUsageInStreaming: true },
              },
            ],
          },
        },
      },
    }
    ```

    * `api: "openai-completions"` gửi yêu cầu tới `/v1/chat/completions`.
    * Thêm một mục vào `models` cho mỗi ID mô hình. `id` là ID trong danh mục; `name` là nhãn hiển thị, và OpenClaw bắt buộc phải có.
    * Thêm `contextWindow` và `maxTokens` vào mỗi mục theo trang của mô hình, ví dụ [trang glm-5.3](/vi/models/glm-5.3). Nếu thiếu, OpenClaw tính ngân sách ngữ cảnh bằng giá trị dự phòng riêng và để máy chủ quyết định giới hạn đầu ra.
    * `compat.supportsUsageInStreaming` khiến OpenClaw yêu cầu số liệu sử dụng token trong streaming, và cheapaimodel có trả về số liệu này (xem [Streaming](/vi/docs/concepts/streaming)). Nếu thiếu, OpenClaw sẽ ước tính mức dùng ngữ cảnh và ghi log `returned no token usage`.

    Gateway theo dõi tệp và áp dụng thay đổi mà không cần khởi động lại.
  </Step>

  <Step>
    ### Kiểm tra [#check-it]

    ```bash title="Terminal"
    openclaw models list
    ```

    Danh sách sẽ có `cheapaimodel/glm-5.3`. Muốn đổi mô hình mặc định về sau, chạy `openclaw models set cheapaimodel/<model-id>`.
  </Step>
</Steps>

Các agent của OpenClaw dựa vào khả năng gọi công cụ (tool calling) của mô hình. Nếu một mô hình xử lý công cụ chưa tốt, hãy thử mô hình khác trong danh mục.

## Lỗi thường gặp [#common-mistakes]

* **OpenClaw cảnh báo thiếu `CHEAPAIMODEL_API_KEY`.** Tiến trình Gateway không có biến này, nên `${CHEAPAIMODEL_API_KEY}` không được thay giá trị. Đặt biến vào `~/.openclaw/.env` rồi khởi động lại Gateway.
* **`401`.** Key sai, đã hết hạn hoặc đã dùng hết hạn mức chi tiêu. Kiểm tra key trong bảng điều khiển.
* **Cấu hình bị từ chối với `custom model providers must declare models`.** Nhà cung cấp tùy chỉnh cần một mảng `models`, và mỗi mục cần có cả `id` lẫn `name`.
* **`404`.** Nếu nội dung phản hồi là `fault filter abort`, `baseUrl` thiếu `/v1`; nếu là `Invalid URL (POST /v1/chat/completions/chat/completions)`, thì `baseUrl` có kèm đường dẫn endpoint. Đặt thành `https://api.cheapaimodel.ai/v1`.
* **`503` kèm `model_not_found`.** `id` phải là một ID trong danh mục, viết chính xác. Tiền tố `cheapaimodel/` chỉ là tham chiếu mô hình của OpenClaw và không được gửi đi.