Giới thiệu
Việc tích hợp OpenClaw, một framework tự động hóa crawler và Agent, với các mô hình lớn được triển khai cục bộ thông qua Ollama, chủ yếu dựa vào khả năng cung cấp API tương thích OpenAI của Ollama. Vì OpenClaw thường được thiết kế để hỗ trợ giao thức OpenAI, nên bạn chỉ cần cấu hình nó để trỏ đến dịch vụ Ollama cục bộ là được.
Giai đoạn 1: Chuẩn bị Môi trường Ollama (Máy chủ)
Trước khi cấu hình OpenClaw, bạn cần đảm bảo dịch vụ Ollama đã sẵn sàng và mô hình phù hợp cho các tác vụ Agent.
1. Khởi động Dịch vụ Ollama
Đảm bảo Ollama đang chạy.
ollama serve*Địa chỉ mặc định: `http://127.0.0.1:11434`*
2. Lựa chọn và Tối ưu hóa Mô hình (Bước quan trọng)
OpenClaw, với vai trò là một Agent, đòi hỏi mô hình phải có khả năng tuân thủ chỉ thị mạnh mẽ và khả năng gọi hàm (Function Calling).
- Mô hình được đề xuất: `phi3.5:7b` (tốt cho tiếng Việt), `mistral-nemo:latest` (mạnh mẽ và phổ biến), `gemma2:9b`.
- Tải về mô hình:
ollama pull phi3.5:7b
3. Tạo Mô hình chuyên dụng với ngữ cảnh dài (Tùy chọn nhưng được khuyến nghị)
Các tác vụ crawler thường liên quan đến nội dung trang web dài, cửa sổ ngữ cảnh (Context Window) mặc định của mô hình có thể không đủ (thường là 4k hoặc 8k). Bạn nên tạo một phiên bản với ngữ cảnh 32k:
- Tạo một tệp mới `Modelfile`:
FROM phi3.5:7b PARAMETER num_ctx 32768 SYSTEM "Bạn là một trợ lý crawler web hữu ích. Luôn xuất ra JSON hợp lệ khi được yêu cầu." - Xây dựng mô hình mới:
ollama create phi-agent -f Modelfile*Hãy ghi nhớ tên mô hình này `phi-agent`, bạn sẽ cần nó cho bước cấu hình sau.*
Giai đoạn 2: Cấu hình OpenClaw (Máy khách)
Cách thức cấu hình OpenClaw phụ thuộc vào phiên bản của nó (CLI tương tác hoặc tệp cấu hình). Dưới đây là hai phương pháp phổ biến.
Phương pháp A: Cấu hình qua Biến môi trường (Phổ biến nhất, khuyến nghị cho Docker/mã script)
OpenClaw thường đọc các biến môi trường tiêu chuẩn để kết nối với nhà cung cấp LLM.
- Cài đặt biến môi trường:
Trước khi chạy OpenClaw, xuất các biến sau:
# Chỉ định loại nhà cung cấp là openai (vì Ollama tương thích với giao thức OpenAI) export AGENT_LLM_PROVIDER=openai # URL cơ sở trỏ đến giao diện v1 của Ollama (lưu ý có /v1 ở cuối) export AGENT_LLM_BASE_URL=http://127.0.0.1:11434/v1 # Khóa API (Ollama cục bộ không cần khóa thực, điền bất kỳ chuỗi không rỗng nào, ví dụ 'ollama-local') export AGENT_LLM_API_KEY=ollama-local # Chỉ định tên mô hình cần sử dụng (phải khớp với tên trong ollama list) export AGENT_LLM_MODEL=phi-agent - Khởi động OpenClaw:
openclaw execute
Phương pháp B: Sửa tệp cấu hình (`config.json` hoặc `.env`)
Nếu bạn sử dụng tệp cấu hình, hãy tìm thư mục cấu hình của OpenClaw (thường là `~/.openclaw/config.json` hoặc trong thư mục gốc của dự án).
Ví dụ cấu hình (`config.json`):
{
"llm": {
"provider": "openai",
"base_url": "http://127.0.0.1:11434/v1",
"api_key": "ollama-local-key",
"model": "phi-agent",
"parameters": {
"temperature": 0.7,
"max_tokens": 4096,
"stream": true
}
},
"features": {
"enable_function_calling": true,
"enable_rag": true
}
}*Lưu ý: `enable_function_calling` rất quan trọng đối với OpenClaw để trích xuất dữ liệu có cấu trúc, hãy đảm bảo mô hình Ollama của bạn hỗ trợ tính năng này (Phi 3.5 và Mistral Nemo đều hỗ trợ).*
Giai đoạn 3: Xác minh Tích hợp
Trước khi chạy tác vụ crawler, hãy thực hiện kiểm tra kết nối.
1. Kiểm tra Kết nối API
Sử dụng `curl` để xác nhận OpenClaw có thể truy cập Ollama:
curl http://127.0.0.1:11434/v1/models*Nếu trả về danh sách JSON chứa mô hình của bạn, nghĩa là kết nối mạng ổn.*
2. Chạy Tác vụ OpenClaw đơn giản
Tạo một tác vụ kiểm tra đơn giản (ví dụ: trích xuất tiêu đề tin tức), và quan sát nhật ký:
openclaw execute --url "https://news.example.com" --task "Trích xuất tiêu đề chính và ngày đăng."Điểm cần quan sát:
- Không có lỗi: Không xuất hiện `Connection refused` hoặc `401 Unauthorized`.
- Tốc độ phản hồi: Mô hình cục bộ tạo ký tự đầu tiên (TTFT) nên trong khoảng giây.
- Chất lượng đầu ra: Kiểm tra xem có trích xuất dữ liệu chính xác không. Nếu mô hình "nói胡话", có thể là do ngữ cảnh không đủ (quay lại Giai đoạn 1 để điều chỉnh `num_ctx`) hoặc tham số nhiệt độ quá cao.
Giai đoạn 4: Kịch bản Nâng cao và Khắc phục sự cố
Kịch bản 1: Triển khai trên nhiều máy (OpenClaw trong Docker kết nối với Ollama trên Host)
Nếu OpenClaw chạy trong container Docker, trong khi Ollama chạy trên host:
- Cấu hình Host: Đặt `OLLAMA_HOST=0.0.0.0:11434` và khởi động lại Ollama.
- Tường lửa: Đảm bảo tường lửa trên host cho phép cổng 11434.
- Cấu hình Container:
- Linux: Đặt `base_url` thành `http://host.docker.internal:11434/v1` hoặc IP của host.
- Mac/Win: Đặt `base_url` thành `http://host.docker.internal:11434/v1`.
Lỗi phổ biến và Giải pháp
| Lỗi | Có thể do | Giải pháp |
|---|---|---|
| `Connection refused` | Địa chỉ sai hoặc Ollama chưa khởi động | Kiểm tra URL có chứa `/v1` không; xác nhận `ollama serve` đang chạy. |
| `401 Unauthorized` | Khóa API rỗng | Điền bất kỳ chuỗi nào vào `api_key` trong cấu hình (ví dụ `ollama-local`). |
| `Context length exceeded` | Nội dung trang web quá dài, vượt giới hạn mô hình | Tăng `num_ctx` trong Modelfile và chạy lại `ollama create`. |
| `Model not found` | Tên mô hình không khớp | Chạy `ollama list` để đối chiếu tên, đảm bảo trường `model` trong cấu hình khớp chính xác. |
| Đầu ra định dạng sai (lỗi phân tích JSON) | Khả năng tuân thủ chỉ thị của mô hình yếu | Thay đổi sang mô hình mạnh hơn (ví dụ Phi 3.5-14B); Trong System Prompt, nhấn mạnh "Chỉ xuất ra JSON". |
Tóm tắt quy trình
+-----------------------+
| Bắt đầu quy trình |
+----------+------------+
|
v
+-----------------------+
| 1. Chuẩn bị Ollama |
| - Cài đặt và khởi động |
| - Lệnh: ollama serve |
+----------+------------+
|
v
+-----------------------+
| 2. Lấy mô hình |
| - Lệnh: ollama pull |
| (đề xuất: phi3.5:7b)|
+----------+------------+
|
+------> [Cần ngữ cảnh dài?] ------+
| |
(Không) (Có)
| |
| +-----------------------------+
| | Tạo Modelfile tùy chỉnh |
| | - Đặt PARAMETER num_ctx |
| | - Lệnh: ollama create |
| +--------------+--------------+
| |
+<--------------------------------+
|
v
+-----------------------+
| 3. Cấu hình OpenClaw |
| --------------------- |
| Provider: openai |
| Base URL: |
| http://...:11434/v1 |
| API Key: ollama-local |
| Model: <tên_mô_hình> |
+----------+------------+
|
v
+-----------------------+
| 4. Xác minh kết nối |
| - curl kiểm tra /v1/models|
| - Kiểm tra danh sách mô hình|
+----------+------------+
|
v
+-----------------------+
| 5. Chạy tác vụ OpenClaw|
| - Thực thi lệnh crawler|
| - Quan sát đầu ra |
+----------+------------+
|
v
+-----------------------+
| Tích hợp thành công! |
+-----------------------+