Cài Đặt Omnigent Trên VPS Tự Host AI Agent Chuẩn Kỹ Thuật Từ A-Z

Cài đặt Omnigent trên VPS là giải pháp tối ưu giúp bạn vận hành một lớp điều phối đa tác nhân AI (meta-harness) tập trung, hoạt động bền bỉ 24/7 mà không phụ thuộc vào tài nguyên máy tính cá nhân. Khi nhu cầu tích hợp Claude Code, Codex, Cursor hay các trợ lý mã nguồn mở ngày càng tăng, việc thiết bị cục bộ bị treo hoặc ngắt kết nối giữa chừng trở thành rào cản lớn. Một hệ thống máy chủ ảo ổn định từ ThueVPSGiaRe.vn sẽ mang đến nền tảng thực thi độc lập, cho phép bạn quản lý, cộng tác và giám sát tác vụ AI từ bất kỳ đâu.

Omnigent là gì? Tổng quan về nền tảng Meta-Harness cho AI Agent

Omnigent là một framework mã nguồn mở đóng vai trò lớp điều phối chung (meta-harness) cho toàn bộ các trợ lý AI lập trình hiện nay. Nền tảng này cho phép người dùng gom các agent độc lập như Claude Code, Codex, Cursor, OpenCode trên máy chủ, Hermes Agent hay Pi vào chung một quy trình làm việc duy nhất mà không cần viết lại mã nguồn.

• Đồng bộ phiên làm việc đa nền tảng: Bạn có thể bắt đầu phiên tương tác từ giao diện dòng lệnh (CLI), tiếp tục theo dõi trên trình duyệt máy tính hoặc kiểm tra tiến độ ngay trên điện thoại thông minh thông qua Web UI đáp ứng chuẩn di động.
• Giám sát và kết hợp đa tác nhân: Hỗ trợ điều phối nhiều agent cùng xử lý một vấn đề; ví dụ một agent phụ trách viết code và một agent từ nhà cung cấp khác thực hiện phản biện (code review).
• Hỗ trợ kết nối sandbox linh hoạt: Khả năng tích hợp mạnh mẽ với các môi trường cô lập trên đám mây như Modal, Daytona, E2B, cụm container Kubernetes hoặc OpenShell để kiểm thử mã nguồn an toàn.
• Hợp tác thời gian thực: Chia sẻ link phiên làm việc trực tiếp để đồng nghiệp cùng tham gia gõ lệnh (co-drive) hoặc rẽ nhánh (fork) thảo luận độc lập.

Yêu cầu hệ thống và chuẩn bị khi cài Omnigent trên VPS

Trước khi tiến hành cài đặt Omnigent trên VPS, máy chủ của bạn cần đáp ứng đầy đủ các gói thư viện cơ sở. Việc chuẩn bị đúng cấu hình môi trường giúp tiến trình dựng agent diễn ra suôn sẻ và tránh gặp lỗi cô lập tiến trình.

• Hệ điều hành: Khuyến nghị sử dụng các bản phân phối Linux như Ubuntu 22.04 LTS hoặc Ubuntu 24.04 LTS với đầy đủ quyền hạn root trên hệ thống để cấu hình sandbox.
• Python: Omnigent yêu cầu Python 3.12 trở lên làm nền tảng cốt lõi. Bên cạnh đó, bộ cài đặt chính thức liệt kê các công cụ cần thiết như sau — bạn nên kiểm tra từng mục trước khi bắt đầu:
• uv (bắt buộc): trình cài đặt sẽ tự đề nghị thiết lập cho bạn nếu chưa có.
• git (bắt buộc): cần cho việc tải mã nguồn và các thao tác build.
• Node.js 22 LTS trở lên kèm npm (dùng cho các coding-harness CLI mà omnigent run cài đặt) và pnpm (dùng cho web UI). Bạn có thể cài cả hai từ một bản Node duy nhất; pnpm có sẵn qua corepack enable hoặc npm install -g pnpm. Nếu chưa quen, hãy tham khảo cách cài Node.js 22 kèm npm trên Ubuntu trước khi tiến hành.
• tmux: cần cho các terminal wrapper native như omnigent claude, omnigent codex, omnigent cursor, omnigent devin, omnigent hermes, omnigent kiro, omnigent pi (cài bằng apt install tmux; installer cũng đề nghị cài hộ bạn).
• bubblewrap (bwrap) — chỉ dành cho Linux: các terminal wrapper native và harness pi bọc terminal của agent trong sandbox bwrap; trên Linux sự cô lập này là bắt buộc, thiếu binary bwrap sẽ khiến terminal không khởi động được (apt install bubblewrap; installer đề nghị cài hộ). macOS dùng sandbox seatbelt có sẵn nên không cần thêm gì.
• Tùy chọn — Devin CLI: dùng cho lệnh omnigent devin, cài bằng curl -fsSL https://cli.devin.ai/install.sh | bash rồi đăng nhập devin auth login.
• Tùy chọn — Kiro CLI: dùng cho lệnh omnigent kiro, cài bằng curl -fsSL https://cli.kiro.dev/install | bash rồi đăng nhập Kiro.
• Tùy chọn — Databricks: nếu muốn dùng workspace Databricks làm model provider, cài Omnigent kèm extra databricks; đăng nhập workspace cũng dùng Databricks CLI.

Về hạ tầng, bạn chỉ cần một máy chủ Linux ổn định và đăng nhập được bằng SSH vào VPS Linux là đủ bắt đầu. Vì hệ sinh thái Omnigent xoay quanh Python 3.12, nhiều người chọn sẵn một VPS chạy Python để đảm bảo môi trường deploy script và bot về sau cũng dùng chung một máy.

sudo apt update && sudo apt install -y git tmux bubblewrap curl

Hướng dẫn cài đặt Omnigent trên VPS chi tiết

Omnigent cung cấp kịch bản cài đặt tự động giúp thiết lập toàn bộ công cụ nền tảng một cách nhanh chóng chỉ với một câu lệnh đơn giản.

Kiểm tra hệ điều hành và Python

Chạy lệnh:

cat /etc/os-release
python3 --version

Cách 1: Sử dụng Script cài đặt Omnigent tự động (Khuyến nghị)

Chạy lệnh sau trên terminal của VPS để tải và khởi chạy script chính thức:

curl -fsSL https://raw.githubusercontent.com/omnigent-ai/omnigent/main/scripts/install_oss.sh | sh

Nếu bạn cần cài đặt thêm các tiện ích mở rộng (extras) tùy chọn như kết nối sandbox (Modal, E2B) hoặc nhà cung cấp đám mây, hãy truyền tham số --extra vào kịch bản:

curl -fsSL https://raw.githubusercontent.com/omnigent-ai/omnigent/main/scripts/install_oss.sh | sh -s -- --extra modal,e2b

Cách 2: Cài đặt thủ công bằng uv hoặc pip

Trong trường hợp bạn muốn kiểm soát chi tiết môi trường Python hoặc tự biên dịch từ repository, sử dụng công cụ uv:

# Cài đặt qua uv tool
uv tool install omnigent

# Hoặc cài đặt kèm extras tùy chọn
uv tool install "omnigent[databricks,modal]"

# Cài đặt trực tiếp từ kho mã nguồn Git
uv tool install -q --python 3.12 git+https://github.com/omnigent-ai/omnigent.git

Sau khi hoàn tất cài đặt, hai lệnh thực thi là omnigent và omni sẽ được thêm vào biến môi trường PATH. Bạn có thể sử dụng linh hoạt cả hai tên lệnh này.

Cập nhật và gỡ Omnigent

Khi có bản phát hành mới trên PyPI, Omnigent hiển thị thông báo một dòng và bạn có thể cập nhật bằng:

omni upgrade chờ các phiên agent đang chạy hoàn tất trước khi dừng local server (thêm --force để dừng ngay); lệnh omni tiếp theo sẽ đưa server trở lại trên phiên bản mới. Bản checkout từ mã nguồn thì cập nhật bằng git pull. Muốn tắt thông báo, đặt biến OMNIGENT_NO_UPDATE_CHECK=1.

Để gỡ, trước tiên xem trước phần dọn dẹp sẽ chạy mặc định với omnigent uninstall, hoặc gỡ CLI và PATH do installer quản lý nhưng giữ lại lịch sử, credentials và dự án:

Muốn xóa cả trạng thái Omnigent trong ~/.omnigent, thêm --purge (dữ liệu được backup ra ngoài trước khi xóa); workspace ~/omnigent vẫn được giữ trừ khi bạn thêm --purge-workspace:

Nếu wheel đã cài bị hỏng hoặc omnigent không còn trên PATH, hãy chạy script độc lập:

Khởi động agent AI đầu tiên trên Omnigent

Lệnh omnigent sẽ cùng bạn chọn model rồi mở một phiên ngay trong terminal. Đồng thời nó khởi chạy web UI cục bộ tại http://localhost:6767 hiển thị cùng phiên đó trên trình duyệt, hoặc trên điện thoại trong cùng mạng. Ứng dụng desktop bọc chính UI này trong cửa sổ native, thêm thông báo hệ điều hành và dock badge — có bản tải về cho macOS.

Quá trình cài đặt đặt hai tên cho cùng một CLI trên PATH: omnigent và omni ngắn gọn hơn — hai cái dùng thay thế cho nhau. Lần chạy đầu, Omnigent sẽ nhận diện credentials đã có sẵn trong môi trường (một ANTHROPIC_API_KEY/OPENAI_API_KEY, hoặc CLI claude/codex đã đăng nhập) và đề xuất một cái làm mặc định:

Hoặc bạn có thể khởi động một runtime agent cụ thể:

Lưu ý omnigent agy yêu cầu agy 1.1.13 trở lên; khi biến GEMINI_API_KEY được đặt, xác thực Gemini API trực tiếp sẽ được ưu tiên hơn đăng nhập OAuth đã lưu của agy. Với OpenCode — một trong các harness được hỗ trợ — nếu bạn muốn hiểu kỹ công cụ này trên môi trường Ubuntu, có thể đọc thêm bài cài đặt OpenCode trên Ubuntu để nắm cấu hình API key nền tảng.

Tương tự, Hermes Agent trên Ubuntu cũng đã có hướng dẫn riêng nếu bạn định chạy harness omnigent hermes lâu dài.

Đối với các công cụ như OpenClaw, bạn có thể xem thêm hướng dẫn cài đặt OpenClaw trên Ubuntu để kết nối phiên Gateway trực tiếp qua giao thức ACP. Đối với Grok Build (xAI) và Devin (Cognition), bạn cài đặt CLI của từng hãng, đăng nhập xác thực rồi chạy lệnh omnigent run --harness grok hoặc omnigent run --harness devin.

Grok Build và Devin: hai harness tích hợp sẵn

Hai coding agent này được tích hợp sẵn nhưng không có launcher omnigent <name> riêng, vì mỗi cái có CLI tự quản lý đăng nhập. Bạn cài CLI của vendor, đăng nhập bằng CLI đó, rồi gọi harness:

Cả hai nói giao thức Agent Client Protocol (ACP) qua stdio, và Omnigent không lưu credential nào cho chúng — mỗi CLI tự đọc lại thông tin đăng nhập đã ghi ra đĩa. Vì vậy --model sẽ bị từ chối thay vì âm thầm bỏ qua: cả hai chạy model mặc định của tài khoản.

Muốn chốt model, hãy cấu hình một agent acp: mà command truyền flag model của riêng vendor. Tài liệu cũng khuyến nghị dùng đăng nhập vendor thay vì API key; nếu bắt buộc dùng key, truyền tường minh bằng OMNIGENT_RUNNER_ENV_PASSTHROUGH=XAI_API_KEY hoặc khai báo passthrough trong agent acp:.

Polly, Debby và Deep Research: các agent ví dụ

Repo có sẵn hai agent ví dụ rất hợp cho phiên đầu tiên:

Polly là một multi-agent coding orchestrator — cô ấy không tự viết code mà đóng vai tech lead: lập kế hoạch, giao việc cho các coding sub-agent (Claude Code, Codex hoặc Pi) chạy song song trong các git worktree, rồi chuyển từng diff cho một reviewer của nhà cung cấp khác với người viết. Bạn là người merge.

Debby là đối tác brainstorm hai “cái đầu” — một Claude và một GPT; mỗi câu hỏi của bạn được gửi cho cả hai và hai câu trả lời đặt cạnh nhau; gõ /debate để hai đầu phê bình lẫn nhau vài vòng rồi hội tụ (cô ấy cần đồng thời credential Claude và OpenAI).

Deep Research là một agent duy nhất trả lời câu hỏi bằng báo cáo trích dẫn, đối chiếu chéo — lập kế hoạch sub-query, tìm kiếm web trực tiếp qua MCP search server và xác minh từng luận điểm trên các nguồn độc lập; đây cũng là ví dụ đơn giản nhất để sao chép.

Chạy server cục bộ và kiểm soát trạng thái

Nếu thích dùng trình duyệt, một lệnh khởi động server cục bộ và đăng ký máy hiện tại làm host:

Mở URL server in ra, bấm New Chat, chọn máy của bạn và bắt đầu. Kiểm tra trạng thái bằng omnigent server status; dừng toàn bộ bằng omnigent stop. Muốn chặn tab trình duyệt tự mở, dùng omni host --no-open hoặc đặt OMNIGENT_HOST_NO_OPEN=1 trong shell.

Một phiên cũng có thể tự khởi chạy: trang Automations chạy agent theo lịch định kỳ — định dạng lịch, REST API và giới hạn hiện tại nằm trong automations guide của dự án.

Chọn và chuyển đổi model AI cho Omnigent

Để thêm credential, đặt model mặc định hoặc gỡ bỏ — nhóm theo từng agent — chạy lệnh:

Omnigent làm việc với bốn loại credentials:

Mặc định là theo từng agent, nên một default cho Claude và một default cho Codex có thể tồn tại song song. Trong lúc làm việc, bạn vẫn chuyển model giữa phiên bằng lệnh /model.

Base URL cho Gateway (OpenRouter, Ollama)

Khi thêm credential loại Gateway, omnigent setup sẽ hỏi base URL và key. Base URL phụ thuộc agent bạn trỏ tới:

Thiết lập xác thực và quản lý Model Provider

Omnigent mang đến sự linh hoạt tối đa khi hỗ trợ 4 nhóm thông tin xác thực mô hình AI khác nhau. Để cấu hình tài khoản, hãy thực thi lệnh:

omnigent setup

Lưu ý cấu hình Base URL cho cổng Gateway:

• OpenRouter dùng cho Claude Code: Điền endpoint https://openrouter.ai/api (chú ý không dùng đuôi /api/v1).
• OpenRouter dùng cho Codex / OpenAI agents: Sử dụng endpoint https://openrouter.ai/api/v1.
• Ollama chạy local trên máy chủ: Sử dụng endpoint http://localhost:11434/v1 (Key có thể nhập giá trị bất kỳ).

Triển khai Omnigent Server chạy nền và làm việc nhóm

Để biến VPS thành một trạm điều phối AI luôn luôn sẵn sàng phục vụ làm việc nhóm, bạn nên khởi chạy Omnigent dưới dạng máy chủ dịch vụ chạy nền.

Bật chế độ xác thực đa người dùng (Multi-User)

Kích hoạt biến môi trường xác thực và khởi chạy server chạy ngầm:

OMNIGENT_AUTH_ENABLED=1 omnigent server --background

Trong lần khởi động đầu tiên, hệ thống sẽ sinh ra mật khẩu cho tài khoản admin và lưu trữ cục bộ. Bạn có thể kiểm tra trạng thái bằng omnigent server status hoặc tắt dịch vụ bằng omnigent stop.

Nếu muốn vận hành độc lập trong container, bạn có thể triển khai thông qua việc cài đặt Docker Compose trên Ubuntu để quản lý tài nguyên linh hoạt hơn.

Mở cổng Firewall cho Web UI

Giao diện Web UI mặc định lắng nghe trên cổng 6767. Để truy cập từ bên ngoài, bạn cần đảm bảo tường lửa đã cho phép lưu lượng truy cập. Bạn có thể xem thêm hướng dẫn mở port với tường lửa UFW và thực hiện lệnh:

sudo ufw allow 6767/tcp
sudo ufw reload

Cộng tác và chia sẻ phiên làm việc

• Mời thành viên: Truy cập Web UI dưới quyền admin, vào Admin → Members → Invite để tạo link mời dùng một lần.
• Cùng điều khiển (Co-drive): Đồng nghiệp có thể kết nối vào phiên đang chạy của bạn bằng câu lệnh:

  omnigent attach <session_id>

• Rẽ nhánh (Fork): Tạo một bản sao độc lập của cuộc trò chuyện để thử nghiệm hướng giải quyết khác:

  omnigent run --fork <session_id>

Thiết lập quản trị an toàn bằng Policy và viết Custom Agent

Một điểm mạnh nổi bật của Omnigent là cơ chế quản trị hành vi tác nhân (Policies). Hệ thống cho phép bạn chặn đứng các hành động rủi ro, giới hạn ngân sách tiêu thụ và kiểm soát việc gọi công cụ hệ thống.

Cấu hình Policy kiểm soát an toàn

Chính sách kiểm soát có thể khai báo tại tệp cấu hình server hoặc trực tiếp trong file cấu hình YAML của từng agent:

policies:
  approve_shell:
    type: function
    handler: omnigent.policies.builtins.safety.ask_on_os_tools   # Hỏi ý kiến người dùng trước khi thực thi shell/ghi file
  cap_calls:
    type: function
    handler: omnigent.policies.builtins.safety.max_tool_calls_per_session
    factory_params:
      limit: 50                    # Giới hạn số lần gọi tool tối đa trong 1 session
  budget:
    type: function
    handler: omnigent.policies.builtins.cost.cost_budget
    factory_params:
      max_cost_usd: 5.00           # Giới hạn trần chi phí 5 USD cho mỗi session
      ask_thresholds_usd: [3.00]   # Cảnh báo mềm khi đạt ngưỡng 3 USD

Tự định nghĩa Agent tùy chỉnh bằng file YAML

Bạn có thể định nghĩa một agent độc lập chỉ với một tệp YAML cấu hình đơn giản chứa vai trò, runtime thực thi và danh mục công cụ (Python hàm nội bộ, giao thức MCP hoặc Sub-agent):

name: my_agent
prompt: You are a helpful data analyst.

executor:
  harness: claude-sdk          # Tùy chọn: claude-native, codex, cursor, hermes, opencode, pi...

tools:
  # Gọi một hàm Python nội bộ
  word_count:
    type: function
    callable: mypackage.mymodule.word_count

  # Kết nối công cụ từ máy chủ MCP
  docs:
    type: mcp
    url: https://example.com/mcp

  # Tác nhân phụ ủy quyền
  researcher:
    type: agent
    prompt: Search for relevant information and summarize it.
    tools:
      word_count: inherit

Sau khi định nghĩa xong file my_agent.yaml, khởi chạy tác nhân bằng lệnh:

omnigent run path/to/my_agent.yaml

Để các tác vụ tự động chạy theo lịch biểu định kỳ mà không cần can thiệp thủ công, bạn có thể tham khảo phương pháp thiết lập Cronjob trên VPS kết hợp với giao thức API của Omnigent. Ngoài ra, việc chủ động sao lưu dữ liệu máy chủ tự động định kỳ cho thư mục ~/.omnigent cũng giúp bảo vệ toàn vẹn lịch sử phiên và khóa API quan trọng.

Câu hỏi thường gặp khi cài Omnigent trên VPS

Omnigent có mất phí không?

Omnigent là dự án mã nguồn mở công khai trên GitHub, bản thân phần mềm không thu phí. Chi phí thực tế của bạn nằm ở phần model (API key, subscription hay gateway) và hạ tầng VPS/cloud sandbox chạy agent.

VPS cần đáp ứng yêu cầu gì tối thiểu?

Theo tài liệu chính thức, yêu cầu cứng là Python 3.12+, kèm uv, git, Node.js 22 LTS với npm/pnpm, tmux và bubblewrap trên Linux. Bạn nên chọn hệ điều hành phổ biến như Ubuntu để mọi lệnh trong bài chạy đúng, đồng thời cân đối RAM/CPU đủ cho số agent chạy song song theo nhu cầu thực tế của mình.

Làm sao cập nhật Omnigent lên phiên bản mới?

Chạy omni upgrade — lệnh này tự nhận diện cách bạn đã cài, chờ các phiên agent đang chạy xong rồi dừng local server và nâng cấp. Muốn chỉ kiểm tra, dùng omni upgrade --check. Bản cài từ mã nguồn thì cập nhật bằng git pull.

Omnigent chạy tốt trên Windows không?

Chạy được nhưng ở chế độ “degraded”: omnigent server, web UI và các harness SDK hoạt động bình thường, còn terminal wrapper native (tmux/PTY) và sandbox bwrap/seatbelt không khả dụng. Với trải nghiệm đầy đủ — nhất là khi chạy server cho nhóm — hãy dùng Linux, macOS hoặc WSL.

Tôi có thể chạy nhiều agent của nhiều nhà cung cấp trong một phiên?

Có. Đây chính là điểm mạnh của meta-harness: bạn trộn Claude Code, Codex, Cursor, OpenCode, Hermes, Pi và agent tùy chỉnh bằng YAML trong cùng một phiên, nhờ một agent review công việc của agent khác, hoặc chia task cho agent giỏi từng mảng riêng.

Nội dung bài viết mang tính chất hướng dẫn kỹ thuật tham khảo. Các câu lệnh, tham số cài đặt và giao diện phần mềm có thể thay đổi tùy theo các bản phát hành mới của Omnigent cũng như môi trường hệ điều hành thực tế. Bạn nên kiểm thử trong môi trường an toàn trước khi áp dụng chính thức cho các dự án quan trọng.