Daemon và runtime

Trong UniAI, agent không chạy trên máy chủ của chúng tôi — chúng chạy trên máy của bạn, được điều khiển bởi một chương trình nhỏ gọi là daemon chuyên gọi các công cụ lập trình AI cài trên máy. UniAI server chỉ điều phối: lưu issue, xếp hàng task và điều phối chúng tới đúng runtime (runtime = daemon × một công cụ lập trình AI).

Cấu trúc này là khác biệt lớn nhất giữa UniAI với Linear / Jira: API key, bộ công cụ và thư mục mã nguồn ở lại trên máy của bạn — UniAI server không bao giờ nhìn thấy chúng. Vì thế "agent của tôi không chạy" gần như luôn là vấn đề cục bộ — daemon chưa chạy, công cụ AI chưa cài, key hết hạn. Kiểm tra trên máy trước; xem Khắc phục sự cố.

Khởi động daemon

Daemon là một phần của UniAI CLI. Sau khi cài UniAI CLI, chạy trên máy của bạn:

uniai daemon start

Khi khởi động, nó làm bốn việc:

1. Đọc thông tin đăng nhập đã lưu khi bạn đăng nhập
2. Phát hiện các công cụ lập trình AI trên PATH (14 công cụ có sẵn: Antigravity, Claude Code, CodeBuddy, Codex, Cursor, Copilot, Hermes, Kimi, Kiro CLI, OpenCode, OpenClaw, Pi, Qoder, Trae CLI)
3. Đăng ký chính nó với server, kèm một runtime cho mỗi công cụ phát hiện được
4. Poll mỗi 3 giây để nhận task, và gửi heartbeat mỗi 15 giây

Các lệnh thường dùng:

Tham chiếu CLI đầy đủ tại Lệnh CLI.

Vì sao một máy có nhiều runtime

Runtime không phải server, cũng không phải container — nó là tổ hợp "daemon × một công cụ lập trình AI". Ví dụ: bạn khởi động daemon trên một chiếc MacBook cài cả Claude Code lẫn Codex, và bạn là thành viên của hai không gian làm việc. UniAI sẽ đăng ký 4 runtime:

Điểm chính:

• Một daemon có thể ứng với nhiều runtime — mỗi runtime cho một tổ hợp công cụ đã cài × không gian làm việc bạn tham gia
• Cùng daemon, không gian làm việc và công cụ thì chỉ có đúng một runtime — khởi động lại daemon không bao giờ tạo bản ghi trùng
• Trang Runtime trong giao diện UniAI liệt kê các dòng này

Runtime profile tùy chỉnh

Cơ chế phát hiện provider có sẵn đã phủ các công cụ phổ biến, nhưng đội của bạn cũng có thể định nghĩa runtime profile tùy chỉnh cho các AI CLI dùng một trong các họ giao thức UniAI hỗ trợ và cần lệnh khởi chạy riêng theo không gian làm việc. Profile được quản lý từ giao diện Runtime hoặc CLI:

uniai runtime profile list
uniai runtime profile create --display-name "Composer" --protocol-family codex --command-name agent
uniai runtime profile update <profile-id> --command-name agent
uniai runtime profile delete <profile-id>

Lệnh được định nghĩa theo dạng argv, không phải một chuỗi shell. UniAI lưu tên file thực thi cùng các đối số cố định, rồi daemon khởi chạy trực tiếp bằng exec.Command(command_name, fixed_args...). Hỗ trợ đối số thường, dấu nháy và escape bằng backslash; không hỗ trợ pipe, redirect, &&, ;, backtick và mở rộng $VAR / $(...). Khi runtime cần hành vi shell, hãy dùng một script bọc ngoài. Hiện việc phân tích lệnh và đối số do giao diện Runtime đảm nhận; các lệnh profile của CLI quản lý bản ghi profile và ghi đè đường dẫn cục bộ.

Nếu daemon không tìm thấy một lệnh vốn chạy được trong terminal của bạn, ghim đường dẫn tuyệt đối trên máy đó:

uniai runtime profile set-path <profile-id> --path /abs/path/to/agent
uniai runtime profile unset-path <profile-id>

Sửa lệnh hoặc đối số của profile chỉ áp dụng cho task nhận mới sau khi daemon đăng ký lại. Task đang chạy giữ nguyên đối số khởi chạy ban đầu. Với triển khai hỗn hợp, hãy nâng cấp server trước khi triển khai daemon phiên bản mới: giao diện Runtime phía server lưu fixed_args, và server là nơi hiển thị báo cáo đăng ký failed_profiles. Các thành phần cũ có thể lặng lẽ bỏ qua trường chúng không hiểu thay vì báo lỗi rõ ràng, nên nâng cấp server trước sẽ giúp bạn luôn theo dõi được đợt rollout.

Khi runtime bị đánh dấu offline

UniAI dùng heartbeat để quyết định runtime có online hay không. Ba con số then chốt:

Missing không phải vĩnh viễn — daemon gửi heartbeat tiếp theo là nó trở lại online, và bản ghi runtime được giữ nguyên. Khởi động lại daemon không làm mất runtime.

Bao nhiêu task chạy song song được

UniAI giới hạn đồng thời ở hai tầng:

• Tầng daemon: mặc định 20 task đồng thời (chỉnh bằng biến môi trường MULTICA_DAEMON_MAX_CONCURRENT_TASKS)
• Tầng agent: mặc định 6 task đồng thời mỗi agent (cấu hình theo từng agent)

Giới hạn nào chặt hơn sẽ được áp dụng. Nếu daemon đã chạy 20 task, task mới phải chờ dù agent vẫn còn chỗ.

Nếu bạn thấy task kẹt ở queued không sang dispatched, thường là một trong hai giới hạn này đã chạm trần.

Task đang chạy ra sao sau khi daemon sập

Khi daemon sập hoặc bị kill, các task nó đã nhận bị bỏ lại ở dispatched hoặc running. Ở lần khởi động kế tiếp, daemon báo server: "các task này không còn của tôi, hãy đánh dấu failed." Server chuyển chúng sang failed với lý do runtime_recovery — với các nguồn cho phép thử lại, task được tự xếp hàng lại.

Kể cả khi bước này thất bại do lỗi mạng, phía server còn một lượt quét mỗi 30 giây làm lưới an toàn: runtime nào không có heartbeat quá 45 giây bị đánh dấu missing, và các task của nó được thu hồi theo.

Chẩn đoán agent không hoạt động

Khi gặp vấn đề "agent của tôi không chạy", làm checklist ba bước này trước:

1. Chạy uniai daemon status — xác nhận daemon đang chạy và online
2. Chạy uniai daemon logs -f — kiểm tra lỗi
3. Mở trang Runtime trong giao diện UniAI — xác nhận runtime của bạn hiện "online"

Thêm tình huống khác tại Khắc phục sự cố.

Tiếp theo

• Task — vòng đời đầy đủ của task sau khi daemon nhận
• Ma trận provider — khác biệt năng lực giữa 14 công cụ lập trình AI