Sử dụng OpenClaw với Ollama: Xây dựng một hệ thống phân tích dữ liệu cục bộ

Các quy trình AI hiện đại thường dựa vào API đám mây. Nhưng nếu bạn muốn một hệ thống chạy hoàn toàn trên máy tính của mình, giữ dữ liệu riêng tư và vẫn hỗ trợ các quy trình multi-step agent thì sao?

Với các tích hợp kênh của OpenClaw, cùng một hệ thống cục bộ cũng có thể được mở rộng sang những giao diện như WhatsApp hoặc Slack, cho phép truy cập an toàn vào các quy trình của bạn từ những môi trường quen thuộc.

Hướng dẫn sử dụng OpenClaw Ollama: Xây dựng một nhà phân tích dữ liệu cục bộ

Bước 1: Cài đặt OpenClaw

Trước khi xây dựng quy trình làm việc phân tích dữ liệu cục bộ, chúng ta cần OpenClaw Gateway chạy trên máy tính của bạn. Hãy coi OpenClaw như lớp thực thi trong dự án này, nhận yêu cầu từ giao diện người dùng web, load workspace skill, chạy các công cụ cục bộ (như lệnh shell và script Python) và điều phối toàn bộ quy trình làm việc từ đầu đến cuối.

curl -fsSL https://openclaw.ai/install.sh | bash
openclaw onboard --install-daemon

Lệnh này cài đặt CLI của OpenClaw, chạy trình hướng dẫn thiết lập để cấu hình môi trường cục bộ và thiết lập daemon gateway để có thể dễ dàng khởi động và dừng. Mặc dù chúng ta sẽ chạy gateway ở foreground cho bản demo này, việc cài đặt daemon đảm bảo thiết lập chuẩn và giúp việc khắc phục sự cố dễ dàng hơn.

Bây giờ, hãy xác nhận mọi thứ đang hoạt động:

openclaw doctor
openclaw gateway status

OpenClaw doctor báo cáo rằng OpenClaw đã được cài đặt chính xác. Trạng thái OpenClaw gateway cho bạn biết gateway hiện có đang chạy hay không. Ở giai đoạn này, có thể hiển thị “không chạy”, nhưng không sao. Điểm quan trọng là lệnh hoạt động và quá trình cài đặt được nhận diện.

Nếu bạn muốn hướng dẫn chi tiết từng tùy chọn cài đặt (kênh, xác thực, skill, bảo mật cổng), bạn có thể tham khảo hướng dẫn của OpenClaw để có hướng dẫn từng bước đầy đủ.

Bước 2: Cài đặt Ollama

Tiếp theo, chúng ta sẽ thiết lập Ollama, đóng vai trò là máy chủ LLM cục bộ cho dự án này. OpenClaw vẫn sẽ điều phối quy trình làm việc, nhưng khi cần thông tin mô hình để tóm tắt hoặc suy luận, nó sẽ gọi các LLM thông qua Ollama.

Chạy các lệnh sau:

brew install ollama
ollama serve
ollama pull qwen3:8b

Các lệnh trên cài đặt môi trường chạy Ollama, khởi động máy chủ mô hình cục bộ mà OpenClaw sẽ giao tiếp và tải xuống mô hình qwen3:8b. Ví dụ sử dụng qwen3:8b vì nó cung cấp sự cân bằng tốt giữa hiệu năng và chất lượng cho hầu hết các laptop, nhưng bạn có thể chọn một mô hình khác dựa trên tài nguyên hệ thống của mình.

Bước 3: Cấu hình OpenClaw

Tiếp theo, chúng ta cần cấu hình OpenClaw để sử dụng phiên bản Ollama cục bộ. Điều này đảm bảo rằng tất cả quá trình suy luận, tóm tắt và phân tích đều diễn ra hoàn toàn trên máy mà không cần gọi API bên ngoài.

Tạo thư mục cấu hình cục bộ:

mkdir -p .openclaw-local

Sau đó tạo file: .openclaw-local/openclaw.json

{
  "models": {
    "providers": {
      "ollama": {
        "baseUrl": "http://127.0.0.1:11434/v1",
        "apiKey": "ollama-local",
        "api": "openai-completions",
        "models": [
          {
            "id": "qwen3:8b",
            "name": "qwen3:8b",
            "reasoning": false,
            "input": ["text"],
            "cost": { "input": 0, "output": 0, "cacheRead": 0, "cacheWrite": 0 },
            "contextWindow": 131072,
            "maxTokens": 8192
          }
        ]
      }
    }
  },
  "agents": {
    "defaults": {
      "model": { "primary": "ollama/qwen3:8b" }
    }
  },
  "tools": {
    "web": {
      "search": { "enabled": false },
      "fetch": { "enabled": true }
    }
  }
}

Cấu hình trên định nghĩa 3 thành phần chính:

• baseUrl trỏ đến điểm cuối API cục bộ được ollama serve cung cấp, trong khi cài đặt api: openai-completions cho phép giao tiếp tương thích với OpenAI. Việc đăng ký mô hình cho qwen3:8b chỉ định các khả năng của nó, bao gồm cửa sổ ngữ cảnh lớn 131K để xử lý những tập dữ liệu lớn và giới hạn token cho các phản hồi được kiểm soát. Vì mô hình chạy cục bộ, tất cả các giá trị chi phí đều được đặt thành không.
• Phần agent defaults kiểm soát mô hình mà các agent mô hình OpenClaw sử dụng để suy luận. Bằng cách đặt mô hình chính thành ollama/qwen3:8b, mọi tác vụ agent, chẳng hạn như diễn giải prompt, tạo tóm tắt hoặc suy luận trên dữ liệu, đều được tự động chuyển đến mô hình Ollama cục bộ mà không cần bất kỳ lệnh gọi API bên ngoài nào.
• Cấu hình công cụ quản lý các khả năng bên ngoài như tìm kiếm trên web, tính năng này bị vô hiệu hóa để đảm bảo quyền riêng tư và ngăn chặn những yêu cầu gửi ra ngoài. Công cụ tìm nạp vẫn được bật để truy xuất tài nguyên hạn chế khi cần thiết.

Kết hợp cùng nhau, các cài đặt này đảm bảo rằng toàn bộ quy trình làm việc chạy riêng tư trên máy của bạn, với OpenClaw xử lý việc điều phối và Ollama cung cấp trí thông minh cục bộ.

Bước 4: Định nghĩa workspace skill

Trong bước này, chúng ta định nghĩa workspace skill cho OpenClaw biết cách thực thi quy trình công việc của chúng ta. Thay vì dựa vào mô hình để lập kế hoạch sử dụng công cụ, chúng ta sử dụng chế độ điều phối lệnh, cho phép lệnh slash trực tiếp kích hoạt lệnh thực thi cục bộ, giúp quy trình công việc nhanh hơn và hoàn toàn cục bộ.

Hãy tạo file SKILL.md sau trong không gian làm việc của bạn:

---
name: local-data-analyst
description: Local Data Analyst: analyze private local data with Ollama, generate chart/report, and keep all data on-device.
user-invocable: true
command-dispatch: tool
command-tool: exec
command-arg-mode: raw
---
Invoke as /local-data-analyst <raw command>.
This skill bypasses model planning and dispatches raw command text directly to the exec tool.
Use this exact command template in this workspace:
python3 /……/main.py --docs-dir <context_dir> --data-file <data_file> --output-dir <output_dir> --prompt "<prompt>" --use-ollama --model qwen3:8b
Expected outputs under <output_dir>:
- trend_chart.png
- analysis_report.md
- tool_trace.json

Cấu hình skill này kiểm soát cách OpenClaw thực hiện phân tích:

• Phần đầu (một khối siêu dữ liệu có cấu trúc ở đầu file) định nghĩa một skill do người dùng gọi có tên là local-data-analyst, skill này sẽ khả dụng dưới dạng lệnh slash /local-data-analyst.
• Lệnh slash là cách OpenClaw kích hoạt các hành động có cấu trúc từ khung chat hoặc giao diện người dùng.
• Cài đặt `command-dispatch: tool` cho phép chế độ điều phối lệnh, trong đó OpenClaw trực tiếp chuyển lệnh đến một công cụ thay vì yêu cầu mô hình quyết định phải làm gì.
• Với `command-arg-mode: raw`, toàn bộ chuỗi lệnh được truyền nguyên vẹn đến công cụ thực thi, đảm bảo quá trình thực thi có thể dự đoán được.
• Lệnh chạy script `main.py` cục bộ, script này:
  • Load tập dữ liệu và các tài liệu ngữ cảnh tùy chọn
  • Sử dụng Ollama (qwen3:8b) để suy luận và tóm tắt
  • Tạo ra 3 thành phần, bao gồm biểu đồ, báo cáo markdown và dấu vết thực thi công cụ

Như vậy, OpenClaw xử lý việc điều phối và thực thi, trong khi Ollama cung cấp khả năng suy luận cục bộ. Trong bước tiếp theo, chúng ta sẽ kết nối skill này với giao diện web để người dùng có thể upload lên dữ liệu và kích hoạt phân tích chỉ bằng một thao tác.

Bước 5: Tạo giao diện web

Tại thời điểm này, chúng ta đã có hai thành phần cốt lõi hoạt động trên workspace skill OpenClaw và phần backend mô hình cục bộ (Ollama) cung cấp khả năng suy luận. Bây giờ, chúng ta cần một giao diện nhẹ cho phép bạn upload lên các file và kích hoạt những lần chạy mà không cần chạm vào terminal mỗi lần.

File web_assistant.py hoạt động như một máy chủ giao diện đơn giản:

• Chấp nhận upload lên file,
• Tạo một thư mục chạy riêng biệt cho mỗi lần thực thi,
• Xây dựng lệnh slash của OpenClaw trỏ đến các file trên ổ đĩa,
• Gọi agent OpenClaw cục bộ,
• Chờ kết quả đầu ra,
• Trả về các sản phẩm sẵn sàng xem trước cho trình duyệt.

Lựa chọn thiết kế quan trọng ở đây là máy chủ web không bao giờ tự chạy logic phân tích. Nó ủy thác mọi thứ cho OpenClaw, do đó giao diện người dùng vẫn đơn giản.

Bước 5.1: Xây dựng lệnh slash

Mục tiêu ở đây là tạo ra một chuỗi duy nhất mà OpenClaw có thể nhận được dưới dạng tin nhắn trò chuyện, ví dụ: /local-data-analyst python3 ... --data-file ... --output-dir …

def build_slash_command(
    data_path: Path,
    docs_dir: Path,
    output_dir: Path,
    prompt: str,
    model: str,
    x_col: str,
    y_col: str,
) -> str:
    args = [
        "python3",
        str(BASE_DIR / "src" / "main.py"),
        "--docs-dir", str(docs_dir),
        "--data-file", str(data_path),
        "--output-dir", str(output_dir),
        "--prompt", prompt,
        "--use-ollama",
        "--model", model,
    ]
    if x_col:
        args.extend(["--x-column", x_col])
    if y_col:
        args.extend(["--y-column", y_col])
    raw = " ".join(shlex.quote(a) for a in args)
    return f"/local-data-analyst {raw}"

Hàm build_slash_command() chuẩn bị hướng dẫn chính xác sẽ được gửi đến OpenClaw. Thay vì thực hiện phân tích trực tiếp, ứng dụng web xây dựng một lệnh slash có cấu trúc mà OpenClaw có thể định tuyến đến workspace skill thích hợp. Hàm này thực hiện 4 nhiệm vụ chính:

• Danh sách args xác định lệnh gọi CLI tới src/main.py. Đây là cùng một lệnh bạn có thể chạy thủ công từ terminal.
• Các flag --x-column và --y-column chỉ được thêm vào khi được cung cấp. Nếu những giá trị này bị thiếu, script phân tích có thể tự động suy ra các cột từ tập dữ liệu.
• Lệnh gọi shlex.quote() mã hóa tất cả các đối số, bao gồm cả prompt của người dùng. Điều này rất quan trọng để xử lý khoảng trắng và các ký tự đặc biệt, đồng thời ngăn ngừa rủi ro tấn công chèn lệnh khi truyền dữ liệu đầu vào của người dùng cho một lệnh shell.

Hàm trả về một chuỗi bắt đầu bằng: /local-data-analyst. Tiền tố này khớp với tên skill được định nghĩa trong SKILL.md. Khi OpenClaw nhận được lệnh slash này, nó ngay lập tức chuyển yêu cầu đến workspace skill local-data-analyst, sau đó skill này sẽ thực thi lệnh bằng công cụ exec.

Bước 5.2: Thực thi OpenClaw

Bây giờ, chúng ta đã có lệnh slash, chúng ta gửi nó đến OpenClaw bằng cách sử dụng trình chạy agent CLI. Đây là nơi ứng dụng web chuyển giao quyền thực thi.

slash_message = build_slash_command(
    data_path=data_path,
    docs_dir=docs_dir,
    output_dir=output_dir,
    prompt=prompt,
    model=model,
    x_col=x_col,
    y_col=y_col,
)
agent_cmd = [
    "openclaw", "agent",
    "--local",
    "--session-id", f"stealth-web-{run_id}",
    "--message", slash_message,
    "--timeout", "120",
]
proc = subprocess.run(agent_cmd, capture_output=True, 
                     text=True, env=openclaw_env())

Việc gọi agent OpenClaw là điểm chuyển giao nơi ứng dụng web ngừng hoạt động và thay vào đó yêu cầu OpenClaw thực thi quy trình công việc từ đầu đến cuối.

• Sử dụng tham số --local đảm bảo quá trình chạy diễn ra trên máy của bạn và agent xử lý yêu cầu thông qua cổng cục bộ và mô hình được hỗ trợ bởi Ollama thay vì bất kỳ dịch vụ được host nào.
• Tham số --session-id stealth-web-{run_id} cung cấp cho mỗi lần chạy một không gian tên phiên riêng biệt, ngăn chặn việc rò rỉ trạng thái giữa các lần chạy và giúp dễ dàng gỡ lỗi một lần thực thi cụ thể sau này.
• Tham số --message truyền chuỗi lệnh slash chính xác như thể người dùng đã nhập vào khung chat; OpenClaw nhận được nó, định tuyến nó đến skill /local-data-analyst và thực thi lệnh cơ bản thông qua công cụ exec.
• Cuối cùng, --timeout 120 hoạt động như một van an toàn để giao diện người dùng web không bị treo vĩnh viễn nếu quá trình phân tích bị đình trệ, và env=openclaw_env() buộc tiến trình con sử dụng cấu hình OpenClaw cục bộ của dự án và thư mục trạng thái để nó luôn nhắm mục tiêu vào thiết lập Ollama dự định.

Trong bước tiếp theo, chúng ta sẽ load các artifact được tạo ra, bao gồm biểu đồ, báo cáo và dấu vết công cụ, và hiển thị bản xem trước nhẹ trong trình duyệt.

Bước 5.3: Thiết lập máy chủ

Cuối cùng, web_assistant.py chạy một máy chủ HTTP cục bộ nhỏ để bạn có thể tương tác thông qua trình duyệt.

 def main() -> int:
    host = "127.0.0.1"
    port = 8765
    server = ThreadingHTTPServer((host, port), Handler)
    print(f"Local Data Analyst web UI: http://{host}:{port}")
    print("Press Ctrl+C to stop.")
    try:
        server.serve_forever()
    except KeyboardInterrupt:
        pass
    return 0

Điều này giúp việc triển khai đơn giản:

• ThreadingHTTPServer cho phép nhiều yêu cầu mà không làm chặn toàn bộ ứng dụng.
• Tất cả "công việc thực sự" diễn ra trong Trình xử lý yêu cầu, nhận các file upload lên, tạo thư mục chạy, kích hoạt OpenClaw và trả về bản xem trước.

Bước 6: Xây dựng công cụ phân tích cục bộ

Ở bước này, OpenClaw đã có thể thực thi quy trình công việc thông qua workspace skill, và giao diện người dùng web có thể kích hoạt các lần chạy thông qua lệnh slash. Phần còn lại là công cụ phân tích sẽ nhận các file bạn đã upload lên, chạy các bước của quy trình công việc và tạo ra những artifact.

File main.py trong kho lưu trữ này tập trung vào hai hàm xác định cốt lõi của quy trình, đó là load dữ liệu dạng bảng và gọi Ollama để suy luận cục bộ.

Bước 6.1: Load dữ liệu dạng bảng

Trình trợ giúp này hỗ trợ nhiều định dạng đầu vào trong khi vẫn giữ cho quy trình công việc nhất quán.

def load_tabular_data(data_path: Path, events: List[SkillEvent]) -> pd.DataFrame:
    ext = data_path.suffix.lower()
    if ext == ".csv":
        df = pd.read_csv(data_path)
    elif ext in {".tsv", ".tab"}:
        df = pd.read_csv(data_path, sep="\t")
    elif ext in {".json", ".jsonl"}:
        try:
            df = pd.read_json(data_path)
        except ValueError:
            df = pd.read_json(data_path, lines=True)
    elif ext in {".xlsx", ".xls"}:
        df = pd.read_excel(data_path)
    else:
        raise ValueError(f"Unsupported data file...")
    log_event(events, "fs", "read", f"Loaded data file: {data_path.name}")
    return df

Hàm load_tabular_data() phát hiện loại file bằng cách sử dụng data_path.suffix và chuyển hướng nó đến pandas loader chính xác. Các file CSV và TSV được xử lý bằng read_csv(), trong đó các file TSV/tab chỉ đơn giản là chuyển dấu phân cách thành \t. Đầu vào JSON được xử lý bằng read_json() trước, và nếu pandas ném ra ValueError, nó sẽ chuyển sang lines=True cho JSONL. Hỗ trợ Excel được thêm thông qua read_excel() để người dùng có thể upload lên các file .xlsx mà không cần xử lý trước.

Cuối cùng, lệnh gọi log_event() ghi lại một mục theo dõi có cấu trúc mà đường dẫn có thể sau đó tuần tự hóa thành tool_trace.json.

Bước 6.2: Tích hợp Ollama

Vì bản demo này không dựa vào SDK, nên nó gọi trực tiếp API HTTP cục bộ của Ollama.

def ollama_generate(model: str, prompt: str) -> str:
    url = "http://localhost:11434/api/generate"
    payload = json.dumps({
        "model": model, 
        "prompt": prompt, 
        "stream": False
    }).encode("utf-8")
    req = request.Request(url, data=payload, 
                         headers={"Content-Type": "application/json"})    
    with request.urlopen(req, timeout=45) as resp:
        body = json.loads(resp.read().decode("utf-8"))
    return str(body.get("response", "")).strip()

Hàm `ollama_generate()` gửi một payload JSON đến điểm cuối `/api/generate` của Ollama trên localhost. Payload này chỉ định tên mô hình (ví dụ: `qwen3:8b`), chuỗi prompt cuối cùng và vô hiệu hóa việc truyền dữ liệu để hàm trả về một phản hồi hoàn chỉnh duy nhất.

Việc sử dụng `urllib.request` giúp cho wrapper này nhẹ và dễ di chuyển, và điều kiện `timeout=45` ngăn chặn quy trình làm việc của chúng ta bị treo vô thời hạn nếu mô hình chậm hoặc máy chủ bị lỗi. Cuối cùng, hàm trích xuất đầu ra của mô hình từ trường phản hồi và trả về văn bản sạch, sau đó được sử dụng để ghi file `analysis_report.md`.

Bước 7: Xây dựng máy chủ web

Đây là một script khởi chạy nhỏ để bắt đầu giao diện người dùng web cục bộ, chấp nhận upload và kích hoạt các lần chạy OpenClaw ngầm.

set -euo pipefail
ROOT="$(cd "$(dirname "$0")" && pwd)"
cd "$ROOT/.."
python3 ../web_assistant.py

Script này thực hiện 3 việc:

• set -euo pipefail khiến script dừng lại nhanh chóng, tức là nó dừng khi gặp lỗi, coi các biến chưa được thiết lập là lỗi và tránh những lỗi âm thầm trong các pipeline.
• ROOT=... giải quyết thư mục nơi script được đặt, vì vậy nó hoạt động ngay cả khi bạn chạy nó từ một nơi khác.
• cd "$ROOT/.." di chuyển đến thư mục gốc dự án mong muốn và sau đó khởi chạy web_assistant.py, nơi chứa giao diện người dùng và xử lý toàn bộ pipeline.

Sau khi script này chạy, giao diện người dùng trình duyệt của bạn sẽ trở thành cổng chính cho bản demo.

Bước 8: Khởi động hệ thống

Đối với bước cuối cùng, chúng ta chạy hệ thống bằng cách sử dụng thiết lập hai tiến trình. Cổng OpenClaw xử lý tất cả việc thực thi tác vụ, trong khi giao diện web đóng vai trò là lớp người dùng để gửi yêu cầu và xem các kết quả được tạo ra.

Terminal 1: Gateway

Trước khi khởi chạy giao diện, trước tiên chúng ta khởi động OpenClaw gateway. Quá trình này hoạt động như lớp thực thi của hệ thống, xử lý các yêu cầu của agent, load workspace skill, gọi những công cụ cục bộ và định tuyến các cuộc gọi suy luận đến mô hình Ollama.

export OPENCLAW_CONFIG_PATH="$PWD/.openclaw-local/openclaw.json"
openclaw gateway --force

Trong terminal này, OPENCLAW_CONFIG_PATH trỏ OpenClaw đến cấu hình cục bộ của dự án, nơi chúng ta đã ghim mô hình mặc định vào ollama/qwen3:8b và tắt tìm kiếm web để bảo mật. Tiếp theo, openclaw gateway --force khởi động gateway ngay cả khi OpenClaw cho rằng một cái gì đó đã đang chạy hoặc được cấu hình một phần.

Khi gateway được thiết lập, nó sẵn sàng chấp nhận các thông báo từ agent cục bộ (bao gồm cả lệnh /local-data-analyst của chúng ta).

Terminal 2: Giao diện người dùng web

Sau khi cổng kết nối hoạt động, chúng ta khởi chạy giao diện web, giao diện này thu thập thông tin đầu vào từ người dùng, gửi từng yêu cầu đến agent OpenClaw cục bộ và hiển thị các biểu đồ, báo cáo và dấu vết thực thi được tạo ra.

./local_data_analyst/run_web.sh

Sau đó mở:

http://127.0.0.1:8765

Máy chủ web chạy trên 127.0.0.1, vì vậy nó chỉ có thể truy cập được từ máy của bạn. Khi bạn nhấp vào Run Analysis, giao diện người dùng sẽ ghi một thư mục chạy, xây dựng lệnh slash, gọi agent openclaw --local và sau đó thăm dò ổ đĩa để tìm các file đầu ra để có thể xem trước:

• trend_chart.png
• analysis_report.md
• tool_trace.json

Kết quả cuối cùng sẽ trông giống như thế này. Bạn có thể kiểm tra bản demo này bằng một số file ví dụ.