Cài đặt OpenClaw và cấu hình OmniProxy

OpenClaw là một trợ lý AI được cài trên máy tính của bạn. Bạn có thể trò chuyện trực tiếp với nó qua Telegram, Discord, WhatsApp hoặc Feishu mà không cần luôn mở thêm một cửa sổ trò chuyện khác; các cuộc hội thoại và bản ghi sẽ được lưu trên máy tính này, đồng thời nó cũng có thể tiếp tục thực hiện các bước tiếp theo ngay trên máy.

Chuẩn bị trước khi cài đặt

OpenClaw yêu cầu Node 24.16 trở lên, hoặc có thể sử dụng Node 26.1 trở lên; nên dùng Node 26. Node là môi trường nền tảng cần thiết để OpenClaw hoạt động.

Có thể cài đặt trên macOS, Linux và Windows. Nếu máy tính chưa có phiên bản Node phù hợp, tập lệnh cài đặt sẽ tự chuẩn bị: Node 26 trên macOS và Node 24 LTS trên Linux. Bạn chỉ cần pnpm khi xây dựng OpenClaw từ mã nguồn.

Nếu máy tính đã cài một phiên bản Node cũ hơn, bạn cũng không cần vội gỡ bỏ. Trong lần kiểm thử ngày 2026-10-09, Node hệ thống trên máy này là 24.2.0, thấp hơn yêu cầu 24.16, và tập lệnh cài đặt không tương tác đã tự chuẩn bị Node 24.21.0.

Muốn có cửa sổ

Ứng dụng desktop đồng hành

Trên Windows, dùng gói cài đặt Hub
Trên macOS, dùng DMG từ GitHub
Lần đầu có thể cài Gateway cục bộ

Khuyến nghị chính thức

Tập lệnh cài đặt

macOS Linux WSL2
Trên Windows, dùng PowerShell
Có thể thêm --no-onboard

Đã có Node

Trình quản lý gói

npm pnpm hoặc bun
Sau đó chạy onboard
Xem phiên bản Node trên trang cài đặt

Nếu muốn có cửa sổ, hãy tải ứng dụng đồng hành dành cho máy tính. Nếu chỉ dùng trong terminal, hãy chạy tập lệnh cài đặt chính thức.

Cài đặt và khởi chạy lần đầu

Bạn có thể cài ứng dụng đồng hành dành cho máy tính có giao diện cửa sổ, hoặc cài trực tiếp qua terminal. Gateway là dịch vụ cục bộ chịu trách nhiệm nhận tin nhắn, gọi mô hình và gửi kết quả trở lại; bạn có thể thiết lập dịch vụ này khi mở ứng dụng đồng hành lần đầu.

Nếu muốn có cửa sổ

Windows: tải xuống và chạy OpenClawCompanion-Setup-x64.exe hoặc OpenClawCompanion-Setup-arm64.exe. Gói cài đặt có chữ ký và bao gồm phần cài đặt, trạng thái khay hệ thống, trò chuyện và chế độ node.
macOS: tải tệp .dmg của OpenClaw từ GitHub releases của OpenClaw. Ưu tiên dùng dmg; bạn cũng có thể dùng .zip. Sau khi cài đặt, hãy mở OpenClaw.app. Nếu bản phát hành này không có tệp dành cho macOS, hãy làm theo trang ứng dụng macOS.

Khi mở lần đầu, bạn có thể để OpenClaw thiết lập Gateway trên máy tính này hoặc kết nối với một Gateway từ xa đã tồn tại.

Cài đặt bằng terminal

Trên macOS, Linux và WSL2, sử dụng:

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

Trên Windows PowerShell, sử dụng:

iwr -useb https://openclaw.ai/install.ps1 | iex

Tập lệnh sẽ nhận diện hệ thống hiện tại, cài Node khi cần, sau đó cài OpenClaw và mở quy trình hướng dẫn ban đầu. Quy trình này sẽ hướng dẫn bạn hoàn tất thiết lập lần đầu.

Nếu tạm thời không muốn mở quy trình hướng dẫn, trên macOS, Linux và WSL2 hãy dùng:

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

Trên Windows, sử dụng tùy chọn -NoOnboard chính thức:

& ([scriptblock]::Create((iwr -useb https://openclaw.ai/install.ps1))) -NoOnboard

Nếu bạn tự quản lý Node, bạn cũng có thể dùng npm, pnpm hoặc bun. Với npm 12 và npm 11.16 trở lên, chạy:

npm install -g openclaw@latest --allow-scripts=openclaw
openclaw onboard --install-daemon

Với npm 11.15 trở xuống, cần bỏ --allow-scripts=openclaw. Khi dùng pnpm, cần thêm --allow-build=openclaw. Hãy tham khảo trang cài đặt để biết khác biệt cụ thể.

Sau khi cài đặt xong, lần lượt chạy ba lệnh sau:

openclaw --version
openclaw doctor
openclaw gateway status

openclaw --version dùng để xem phiên bản, openclaw doctor dùng để kiểm tra các vấn đề môi trường thường gặp, còn openclaw gateway status dùng để xem Gateway có đang chạy hay không. Chỉ khi cả ba lệnh đều trả về kết quả bình thường thì quá trình cài đặt cơ bản mới được xem là hoàn tất.

Nếu terminal báo không tìm thấy openclaw, nguyên nhân thường là thư mục bin toàn cục của npm chưa được thêm vào PATH. PATH là danh sách các vị trí mà terminal dùng để tìm chương trình. Bạn có thể đối chiếu bằng node -v, npm prefix -g và echo "$PATH", thêm thư mục bin tương ứng vào PATH, rồi mở lại terminal.

Nếu trong ~/.openclaw đã có một cấu hình đang được sử dụng, tập lệnh cài đặt mặc định sẽ dùng thư mục này. Nếu muốn cài thêm một bản riêng để tránh thay đổi cấu hình ban đầu, hãy chạy tập lệnh không tương tác và chỉ định thư mục mới:

curl -fsSL --proto '=https' --tlsv1.2 https://openclaw.ai/install-cli.sh | bash -s -- --prefix "$HOME/openclaw-omniproxy" --no-onboard

--no-onboard là hành vi mặc định của tập lệnh này. Ngày 2026-10-09, lệnh này đã được dùng để cài OpenClaw 2026.9.9. Sau khi cài đặt, bạn cần chạy openclaw trong thư mục bin của thư mục đó.

Lấy thông số kết nối từ OmniProxy

Trước tiên, hãy xác nhận OmniProxy đang chạy, sau đó mở danh sách mô hình và chuẩn bị ba mục sau:

baseUrl: https://your-omniproxy-origin.example/v1
apiKey:  <YOUR_OMNIPROXY_API_KEY>
Model ID: sao chép toàn bộ từ danh sách mô hình hiện tại của OmniProxy

baseUrl là địa chỉ mà OpenClaw dùng để gửi yêu cầu tới mô hình và phải kết thúc bằng /v1. Khi kết nối với OmniProxy, hãy đặt api thành openai-completions. Chỉ đổi sang openai-responses khi mô hình đó thực sự hoạt động qua /v1/responses.

Model ID là mã định danh đầy đủ của mô hình trong danh sách. Hãy sao chép chính xác như trong danh sách; nếu có dấu gạch chéo thì cũng phải giữ nguyên. Hai tên dưới đây chỉ dùng để đối chiếu với tài liệu của nhà cung cấp vào ngày 2026-10-09; nếu chúng không xuất hiện trong danh sách thì đừng sử dụng: claude-sonnet-5-5, gpt-6-luna.

Ngay cả khi gateway không kiểm tra khóa, bạn vẫn phải điền nội dung cho apiKey; có thể dùng một chuỗi ký tự giữ chỗ chỉ được sử dụng trên máy tính này. Không đưa khóa thật vào kho mã nguồn.

Điền cấu hình công cụ

Có thể hiểu Provider là một nhóm thiết lập kết nối mà OpenClaw dùng để tìm dịch vụ mô hình. Ở đây, Provider được đặt tên là omniproxy.

Chạy lệnh sau trong terminal, đồng thời thay địa chỉ, khóa và hai Model ID bằng thông tin của bạn:

openclaw config set models.providers.omniproxy '{"baseUrl":"https://your-omniproxy-origin.example/v1","apiKey":"<YOUR_OMNIPROXY_API_KEY>","api":"openai-completions","models":[{"id":"claude-sonnet-5-5","name":"Claude Sonnet 5.5"},{"id":"gpt-6-luna","name":"GPT-6 Luna"}]}' --strict-json --merge

Lệnh này sẽ ghi Provider và danh sách mô hình vào cấu hình. Sau khi lệnh chạy thành công, bạn không cần khởi động lại Gateway.

Tiếp theo, hãy chỉ định mô hình mặc định. Tham chiếu mô hình được tạo từ omniproxy/ và Model ID; hãy giữ nguyên tất cả dấu gạch chéo vốn có trong ID. Nếu ID trong danh sách mô hình dài hơn tên ngắn bên dưới, hãy dùng toàn bộ nội dung trong danh sách:

openclaw config set agents.defaults.model.primary '"omniproxy/claude-sonnet-5-5"' --strict-json

Bạn có thể không điền reasoning, input, cost, contextWindow và maxTokens. Khi không điền, mô hình văn bản sẽ được xử lý theo cách mặc định.

Bạn cũng có thể ghi trực tiếp cùng bộ thiết lập này vào tệp cấu hình. Provider trong cấu hình chính nằm tại models.providers. Mỗi agent cũng có thể có tệp models.json riêng; agent là phiên bản trợ lý thực sự nhận tác vụ và gọi mô hình. Tệp này nằm trong agent/models.json thuộc thư mục của agent tương ứng bên dưới ~/.openclaw/agents/.

Nếu tệp models.json này có baseUrl không rỗng, địa chỉ đó sẽ ghi đè địa chỉ trong cấu hình chính.

Kiểm tra cài đặt

Ba lệnh

openclaw --version
openclaw doctor
gateway status

Cấu hình

models.providers

baseUrl kết thúc bằng /v1
api dùng completions
Mô hình ít nhất phải có id

Chọn dùng

provider/mô hình

primary dùng tham chiếu này
Ưu tiên dùng biến môi trường cho khóa
Danh sách phải theo gateway

Trước tiên, xác nhận lệnh có thể được tìm thấy, sau đó ghi địa chỉ và mô hình. Tham chiếu mô hình phải bao gồm tên Provider.

Xác minh bằng một tác vụ thực tế

Mở một thư mục dự án thông thường và gửi một tin nhắn thật ngắn. Thay tham chiếu mô hình trong lệnh bằng Model ID đầy đủ của bạn:

openclaw agent --local --model omniproxy/claude-sonnet-5-5 --timeout 300 --message "Trả lời bằng một từ."

--local có nghĩa là chạy tác vụ agent này trên máy cục bộ, --model chỉ định mô hình được dùng cho lần này, còn --timeout 300 có nghĩa là chờ tối đa 300 giây.

Phản hồi thực tế của mô hình phải xuất hiện trong terminal. Ngày 2026-10-09, OpenClaw 2026.9.9 đã nhận được phản hồi khi dùng lệnh này. Lần gọi đầu tiên có thể mất một đến hai phút.

Nếu xuất hiện nguyên văn lỗi Request timed out before a response was generated, trước tiên hãy tăng --timeout, rồi gửi lại một lần nữa. Điều này thường có nghĩa là thời gian chờ chưa đủ, không nhất thiết là địa chỉ đã được nhập sai.

Sau khi nhận thành công phản hồi ngắn, hãy yêu cầu nó đọc một tệp cục bộ do bạn chỉ định. Tiếp theo, mở nhật ký lệnh gọi của OmniProxy và xác nhận nguồn cùng Model ID trong bản ghi. Chỉ có kết quả từ số phiên bản hoặc doctor vẫn chưa đủ để chứng minh kết nối mô hình đã được cấu hình hoàn tất.

Cài đặt

Lệnh có phản hồi

Hiển thị được số phiên bản
doctor không có lỗi chặn
Có thể đọc trạng thái Gateway

Tác vụ

Nó đã làm một việc nhỏ

Ví dụ: đọc một tệp cục bộ
Phản hồi không phải lỗi
Tham chiếu mô hình được viết đúng

Nhật ký

Có thể thấy trên gateway

Nguồn là OpenClaw
ID mô hình khớp
Khóa không xuất hiện trong kho mã

Sau khi lệnh phiên bản có kết quả, bạn vẫn cần nhận được một phản hồi thực tế.

Các lỗi thường gặp

Không tìm thấy openclaw: thêm thư mục bin toàn cục của npm vào PATH, rồi mở lại terminal. Nếu cài đặt vào một thư mục được chỉ định, hãy chạy chương trình trong thư mục bin của thư mục đó.
node -v thấp hơn 24.16: không cần gỡ phiên bản cũ trước. Hãy kiểm tra Node do tập lệnh cài đặt chuẩn bị, hoặc làm theo trang cài đặt để dùng 24.16+ hay 26.1+. Nên dùng Node 26.
Mô hình không xuất hiện: mô hình phải được ghi trong mảng models của models.providers và tối thiểu phải có cùng id. Chỉ ghi agents.defaults.models sẽ không tự đăng ký một mô hình mới.
Trả về 400 và đề cập đến vai trò developer: khi máy chủ của địa chỉ không phải api.openai.com, hãy giữ nguyên mặc định và không đặt supportsDeveloperRole thành true. Ngay cả khi đặt thành true, giá trị này vẫn sẽ bị ghi đè.
Hết thời gian chờ rất nhanh: tăng --timeout lên trên 300 giây; trước mắt đừng thay đổi địa chỉ.
Đã chọn gpt-6-luna nhưng lệnh gọi công cụ thất bại: mô hình này hỗ trợ Chat Completions; trong Chat Completions, tính năng gọi hàm chỉ được hỗ trợ khi reasoning_effort là none. Nếu ID trong danh sách khác với ID này, hãy dùng ID trong danh sách.
Không thể kết nối đến địa chỉ: xác nhận OmniProxy đang chạy, baseUrl kết thúc bằng /v1, đồng thời xác nhận địa chỉ được ghi vào cấu hình có thể truy cập được. Các địa chỉ mạng riêng khác cần được cho phép riêng.
Đã cấu hình nhưng vẫn truy cập địa chỉ khác: kiểm tra xem models.json của agent đó có điền một baseUrl khác hay không.

Tài liệu tham khảo chính thức

Xem các bước cài đặt tại OpenClaw install. Xem cách thiết lập Provider tùy chỉnh tại Custom providers và các trường cấu hình. Có thể đối chiếu các Model ID dùng trong ví dụ với tổng quan về mô hình Claude và GPT-6 Luna.

Thay thế mọi chỗ giữ chỗ bằng giá trị từ cấu hình OmniProxy của riêng bạn. Không bao giờ công bố khóa thật.

Kết quả được lưu hoặc mã HTTP 200 đơn lẻ không chứng minh khả năng tương thích đầy đủ của Agent. Hãy kiểm tra nguồn và mô hình trong bản ghi lệnh gọi của OmniProxy.

Nguồn chính thức · OpenClaw ↗