> For the complete documentation index, see [llms.txt](https://docs.avis.net/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.avis.net/vi/tich-hop/assistant/openclaw.md). # OpenClaw Hướng dẫn tích hợp Hướng dẫn này trình bày cách kết nối [OpenClaw](https://openclaw.ai) với AVIS API. ### OpenClaw là gì OpenClaw là trợ lý AI cục bộ mã nguồn mở. Công cụ tương tác với bạn qua WhatsApp, Telegram và Slack, đồng thời có thể thực hiện các tác vụ như quản lý email và lịch mà vẫn giữ dữ liệu trên máy của bạn. OpenClaw định tuyến các lệnh gọi mô hình qua tiến trình `gateway`, được cấu hình trong `~/.openclaw/openclaw.json`, rồi phân phối chúng đến một hoặc nhiều `agents` sử dụng các nhà cung cấp mô hình bạn đã đăng ký. ### 1) Cài đặt OpenClaw ```bash # macOS / Linux curl -sSL https://openclaw.ai/install.sh | bash # Windows PowerShell & ([scriptblock]::Create((iwr -useb https://openclaw.ai/install.ps1))) ``` ### 2) Lấy AVIS API key Xem phần Xác thực — đăng nhập tại [avis.net](https://avis.net), vào **Settings → API Keys** và tạo một key. ### 3) Bắt đầu nhanh qua onboarding ```bash openclaw onboard ``` Trình hướng dẫn sẽ lần lượt thiết lập xác thực, mô hình, Gateway, workspace, kênh và skill. Khi được hỏi về **phương thức xác thực/nhà cung cấp**, hãy chọn API key tùy chỉnh (`custom-api-key`), không chọn các nhà cung cấp có tên. Các tùy chọn như OpenAI và Anthropic dành cho API do chính họ vận hành, không dành cho proxy tương thích như AVIS. Tiếp theo, trình hướng dẫn sẽ hỏi: | Câu hỏi | Giá trị | | ---------------------- | ------------------------------------------------- | | Base URL | `https://api.avis.net/api/anthropic` | | API Key | AVIS API key của bạn | | Compatibility | `anthropic` | | Model ID | `anthropic/claude-sonnet-4.6` | | Provider ID (tùy chọn) | `avisai-anthropic` (hoặc để trống để tự động tạo) | Thao tác này ghi một khối nhà cung cấp `avisai-anthropic` tương ứng vào `~/.openclaw/openclaw.json` — xem §4 để biết cấu trúc kết quả, hoặc để tự sửa bằng tay. #### Không tương tác (có thể viết script) Cùng thiết lập đó, không có câu hỏi, dùng các cờ bên dưới của trình hướng dẫn: ```bash openclaw onboard \ --non-interactive --accept-risk \ --auth-choice custom-api-key \ --custom-provider-id avisai-anthropic \ --custom-base-url https://api.avis.net/api/anthropic \ --custom-api-key \ --custom-compatibility anthropic \ --custom-model-id anthropic/claude-sonnet-4.6 ``` `--custom-compatibility` (chỉ là cờ onboarding) — dùng `anthropic` ở đây. Khi sửa trực tiếp `openclaw.json`, trường `api` dùng một giá trị khác cho cùng ý nghĩa đó (xem §4/§6: `anthropic-messages`, không phải `anthropic`) — đừng mặc định giá trị cờ của trình hướng dẫn khớp 1:1 với giá trị `api` trong tệp cấu hình. `--accept-risk` là bắt buộc khi dùng `--non-interactive` (đây là xác nhận tiêu chuẩn của OpenClaw rằng agent có toàn quyền truy cập hệ thống, không liên quan đến AVIS). Sau khi hoàn tất onboarding, hãy khởi động gateway nếu gateway chưa được cài đặt dưới dạng dịch vụ: ```bash openclaw daemon start ``` ### 4) Cấu hình thủ công (`~/.openclaw/openclaw.json`) #### Khối nhà cung cấp Trong `models.providers`, hãy đăng ký từng giao diện AVIS bạn muốn dùng. Ví dụ dưới đây minh họa hai nhà cung cấp cùng lúc: một dùng giao diện Anthropic, nhà cung cấp còn lại dùng giao diện OpenAI. ```json { "models": { "providers": { "avisai-anthropic": { "baseUrl": "https://api.avis.net/api/anthropic", "apiKey": "", "api": "anthropic-messages", "models": [ { "id": "anthropic/claude-sonnet-4.6", "name": "Claude Sonnet 4.6", "input": ["text", "image"], "contextWindow": 200000, "maxTokens": 64000 }, { "id": "anthropic/claude-opus-4.8", "name": "Claude Opus 4.8", "reasoning": true, "input": ["text", "image"], "contextWindow": 200000, "maxTokens": 128000 }, { "id": "anthropic/claude-haiku-4.5", "name": "Claude Haiku 4.5", "input": ["text", "image"], "contextWindow": 200000, "maxTokens": 64000 } ] }, "avisai-openai": { "baseUrl": "https://api.avis.net/api/openai/v1", "apiKey": "", "api": "openai-completions", "models": [ { "id": "gpt-4o-mini", "name": "GPT-4o mini", "input": ["text", "image"], "contextWindow": 128000, "maxTokens": 16384 }, { "id": "gpt-5-5", "name": "GPT-5.5 Codex", "reasoning": true, "input": ["text", "image"], "contextWindow": 200000, "maxTokens": 64000 } ] } } } } ``` Ghi chú: * `apiKey` hỗ trợ cú pháp `${ENV_VAR}` nếu bạn không muốn ghi key vào tệp, ví dụ `"apiKey": "${AVIS_API_KEY}"`. * `input` liệt kê các loại dữ liệu được chấp nhận (`text`, `image`, `file`, `audio`) — chỉ đặt những gì mô hình được chọn thực sự hỗ trợ. * `contextWindow`/`maxTokens` chỉ được công bố cho OpenClaw để hiển thị/trải nghiệm người dùng — **không được áp dụng thực tế**, và không được kiểm tra với AVIS. > ⚠️ **`models[].id` ở đây là metadata, không dùng để định tuyến.** Ghi một `id` vào mảng này *không* làm cho nó hợp lệ — nó chỉ xuất hiện trong menu/alias. Giá trị thực sự được gửi tới AVIS là phần `` của key bạn tham chiếu trong `agents.defaults.models` (§4 bên dưới) hoặc `model.primary`. Chuỗi đó phải khớp chính xác với những gì AVIS mong đợi cho loại `api` của giao diện — xem §6 để biết giá trị `api` nào thực sự hoạt động với AVIS. #### Khối agents Tham chiếu đến mô hình của nhà cung cấp theo định dạng `/`. Các giá trị trong `defaults` áp dụng cho mọi agent, trừ khi được ghi đè trong mục tương ứng của `list`: ```json { "agents": { "defaults": { "model": { "primary": "avisai-anthropic/anthropic/claude-sonnet-4.6", "fallbacks": ["avisai-anthropic/anthropic/claude-haiku-4.5"] }, "models": { "avisai-anthropic/anthropic/claude-opus-4.8": { "alias": "opus" }, "avisai-anthropic/anthropic/claude-sonnet-4.6": { "alias": "sonnet" }, "avisai-anthropic/anthropic/claude-haiku-4.5": { "alias": "haiku" }, "avisai-openai/gpt-4o-mini": { "alias": "gpt4o-mini" }, "avisai-openai/gpt-5-5": { "alias": "codex" } }, "thinkingDefault": "low", "timeoutSeconds": 600, "maxConcurrent": 3 }, "list": [ { "id": "main", "default": true }, { "id": "research", "model": { "primary": "avisai-anthropic/anthropic/claude-opus-4.8" } }, { "id": "quick", "model": { "primary": "avisai-anthropic/anthropic/claude-haiku-4.5" } } ] } } ``` * `fallbacks` được thử theo thứ tự nếu `primary` gặp lỗi. * Các mục `alias` cho phép bạn chuyển mô hình giữa cuộc hội thoại bằng `/model opus`, `/model codex`, v.v. * `model.primary` của từng agent chỉ ghi đè mặc định cho agent đó (ví dụ `research` luôn dùng Opus). * **`agents.defaults.models` cũng là danh sách cho phép (allowlist) của `/model`.** Một `/` không có trong danh sách này — kể cả khi khối nhà cung cấp hoàn toàn hợp lệ — sẽ bị từ chối với lỗi `model not allowed: ...` khi bạn cố chuyển sang. Xem §7. ### 5) Chạy OpenClaw Khởi động gateway như một dịch vụ chạy nền: ```bash openclaw daemon start # background service (launchd/systemd/schtasks) ``` Mở một phiên chat với gateway: ```bash openclaw chat # local terminal UI (alias for `openclaw tui --local`) ``` Kiểm tra gateway đang chạy và xem nó thực sự đã nạp cấu hình nào: ```bash openclaw daemon status ``` Kiểm tra cấu trúc của tệp cấu hình (phát hiện lỗi gõ và giá trị enum `api` không hợp lệ *trước khi* bạn khởi động lại và gặp lỗi khó hiểu lúc chạy): ```bash openclaw config validate ``` Trong phiên chat, chuyển mô hình bằng các alias đã định nghĩa trong `agents.defaults.models` ở §4: ``` /model opus /model codex /model gpt4o-mini ``` **Sau khi đổi cấu hình, cần khởi động lại gateway.** Gateway chỉ đọc `openclaw.json` khi khởi động. Nếu sửa tệp trong lúc dịch vụ đang chạy — chẳng hạn đổi `baseUrl`, thêm nhà cung cấp hoặc thêm mô hình vào allowlist — thay đổi sẽ chưa có hiệu lực cho đến khi khởi động lại: ```bash openclaw daemon restart ``` Bỏ qua bước này là nguyên nhân phổ biến gây ra lỗi `fetch failed (timeout)` khó hiểu, vẫn tiếp diễn dù cấu hình trên đĩa trông đã đúng. ### 6) Các giao diện AVIS được hỗ trợ | `api` | Base URL | Endpoint AVIS tương ứng | | -------------------- | --------------------------------------- | ------------------------------------------ | | `anthropic-messages` | `https://api.avis.net/api/anthropic/v1` | `POST /messages` | | `openai-completions` | `https://api.avis.net/api/openai/v1` | `POST /chat/completions` | | `openai-responses` | `https://api.avis.net/api/openai/v1` | `POST /responses` (kiểu Codex CLI/Desktop) | Dùng `openai-completions` cho chat thông thường với bất kỳ mô hình nào không phải Anthropic, kể cả Gemini — danh mục tương thích OpenAI của AVIS có các mô hình Gemini dưới id chuẩn riêng của chúng (ví dụ `gemini-2-5-flash`, `gemini-2-5-pro`; xem `GET /api/openai/v1/models` để có danh sách chính xác). Không cần một khối nhà cung cấp riêng cho Gemini. Chỉ dùng `openai-responses` nếu client/agent thực sự dùng cấu trúc Responses API. Cùng một `apiKey` hoạt động trên cả ba — key gắn với tài khoản AVIS của bạn, không gắn với giao diện. ### 7) Khắc phục sự cố * `401 Unauthorized` * AVIS key không hợp lệ, đã bị thu hồi hoặc bị thiếu. * Kiểm tra lại `apiKey` trong `openclaw.json` và phần Xác thực. * `auth or provider access failed for . Run /auth to refresh credentials...` * Đây là thông báo chung của OpenClaw bao bọc một lỗi xác thực từ upstream — cùng nguyên nhân gốc với `401 Unauthorized` ở trên, không phải lỗi mới. Hãy kiểm tra key trực tiếp bằng `curl` tới endpoint AVIS trước khi cho rằng cấu hình phía OpenClaw bị sai. * `model not allowed: /` * Mô hình không có trong `agents.defaults.models` (§4) — map đó là một allowlist, không chỉ là alias. Thêm một mục cho mô hình (có hoặc không có `alias`), sau đó chạy `openclaw daemon restart`. * `404` hoặc không tìm thấy mô hình * `id` trong `models[]` của nhà cung cấp không khớp với một model id thực của AVIS. * Xem `GET /api/anthropic/v1/models` / `GET /api/openai/v1/models` để có các id hợp lệ. * `baseUrl` sai so với giao thức * Mỗi loại `api` phải đi cùng base URL AVIS tương ứng (xem bảng ở §6) — kết hợp sai (ví dụ `anthropic-messages` trỏ tới base URL của OpenAI) sẽ thất bại ở tầng truyền tải. * Agent tham chiếu tới một mô hình không phân giải được * Các key `model.primary`/`fallbacks`/`models` của agent phải có dạng `/`, khớp chính xác với tên nhà cung cấp trong `models.providers`. * `403` với key hợp lệ * Số dư tài khoản đã hết — xem phần Lỗi. * Giá trị `api` không hợp lệ bị từ chối khi chạy `openclaw daemon restart` / `openclaw config validate` * Giá trị của cờ `--custom-compatibility` trong trình hướng dẫn onboarding không giống giá trị `api` trong tệp cấu hình. Dùng `anthropic-messages` / `openai-completions` (§6) khi sửa bằng tay. * `fetch failed (timeout)` trên mọi mô hình, dù `curl` trực tiếp tới `baseUrl` của AVIS vẫn hoạt động * Gateway đang chạy như dịch vụ nền và chưa nạp lại `openclaw.json` kể từ lần sửa gần nhất (xem §5). Chạy `openclaw daemon restart`. * Kiểm tra `openclaw daemon status` — so sánh "Runtime: running (pid ...)" bằng `ps -o lstart -p ` với thời điểm sửa đổi của tệp cấu hình; nếu tiến trình khởi động trước lần sửa, hãy khởi động lại. * `baseUrl` dùng `[::1]` (IPv6 loopback) với một instance AVIS cục bộ, hoặc địa chỉ bind thay đổi giữa các lần khởi động lại * Nếu biến môi trường `HOST` của AVIS là `localhost` (thay vì `0.0.0.0`), địa chỉ bind của máy chủ cục bộ phụ thuộc vào cách hệ điều hành phân giải `localhost` — có thể thay đổi giữa IPv4 và IPv6 sau mỗi lần khởi động lại. Đặt `HOST=0.0.0.0` trong `.env` của AVIS để bind IPv4 ổn định, và dùng `127.0.0.1` (không phải `localhost` hay `[::1]`) trong `baseUrl` của `openclaw.json`. ### 8) Danh sách kiểm tra tối thiểu từ đầu đến cuối 1. Đã tạo AVIS API key (§2). 2. `~/.openclaw/openclaw.json` có một khối nhà cung cấp `avisai-*` với tổ hợp `baseUrl`/`apiKey`/`api` hợp lệ — `openclaw config validate` chạy thành công. 3. Mô hình bạn muốn dùng có trong `agents.defaults.models` (allowlist) dưới dạng `/`, với `` đã được xác nhận trong danh mục `/models` thực tế của AVIS cho giao diện đó. 4. `agents.defaults.model.primary` (hoặc ghi đè theo từng agent) trỏ tới một mục hợp lệ trong khối đó. 5. Đã khởi động lại gateway sau mỗi lần sửa cấu hình (`openclaw daemon restart`, nếu đang chạy như dịch vụ). 6. `openclaw chat` mở được, và một tin nhắn qua OpenClaw trả về kết quả từ mô hình. --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation by asking a question. Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters: ``` GET https://docs.avis.net/vi/tich-hop/assistant/openclaw.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.