Câu hỏi thường gặp
Những câu hỏi hay gặp trước khi cài đặt hoặc giao việc đầu tiên. Đã cài rồi mà gặp lỗi thì sang Xử lý sự cố — trang đó sắp theo triệu chứng.
Cần máy như thế nào?
| Hạng mục | Dev | Production |
|---|---|---|
| RAM | 8 GB rảnh | 16 GB |
| Node.js | 22.x (better-sqlite3 cần native build) | 22.x |
| Khác | Docker Compose v2, git ≥ 2.35, npm 10+ | như dev |
Số container: 8 service nền ở DEV-LITE, 11 ở DEV FULL-STACK và production (2 Postgres, một trong đó có pgvector). Chi tiết: Cài đặt và chạy lần đầu.
Dùng được những agent CLI nào?
Hệ thống nhận copilot · claude · codex · opencode · hermes · openclaw · grok. Bạn không bị khoá vào một nhà cung cấp: mỗi task chọn agentType riêng.
CLI phải có sẵn trên PATH của máy chạy server (bản production build từ Dockerfile.agents). Không có CLI nào thì task vẫn tạo được nhưng bấm Start Agent sẽ không chạy — GET /api/agents cho biết server đang thấy những CLI nào.
Có bắt buộc phải có API key không?
Tuỳ bạn cần gì:
| Muốn dùng | Cần gì |
|---|---|
| Xem sản phẩm chạy, demo | Không cần key — bật AGENTBOARD_FAKE_AGENT=1, xem Bài 0 — Chạy thử trong 10 phút |
| Agent chạy việc thật | Đăng nhập agent CLI bạn chọn (key nằm ở chính CLI đó, không nằm trong AgentJira) |
| AI Planner sinh kế hoạch | AGENTBOARD_LLM_MODE=live + AGENTBOARD_LLM_API_KEY + AGENTBOARD_LLM_MODEL |
| Tìm kiếm ngữ nghĩa trong Wiki | Model embedding của Arkon |
AGENTBOARD_LLM_MODE mặc định là replay — Planner phát lại bản ghi có sẵn và sẽ báo
Cassette cache miss khi gặp yêu cầu mới. Đây là mặc định an toàn cho môi trường test,
không phải bug. Đổi sang live khi muốn Planner làm việc thật.
Chi phí token do ai trả?
AgentJira không đứng giữa và không bán token: bạn cắm key của chính mình. Ba nguồn tiêu tốn tách biệt nhau — agent CLI (lớn nhất), AI Planner, và model embedding của Arkon. Muốn kiểm soát: giới hạn timeoutMinutes mỗi task (1–240, mặc định 60) và giữ maxConcurrency của Group ở mức thấp.
Chạy offline hoàn toàn được không?
Bản thân hệ thống chạy được sau tường lửa — mọi thành phần đều tự host, không có dịch vụ SaaS bắt buộc. Nhưng phần thông minh thì không: agent CLI và Planner cần gọi tới nhà cung cấp model. Hoàn toàn không có mạng ra ngoài thì chỉ chạy được ở chế độ agent giả lập.
Dữ liệu nằm ở đâu?
Bốn nơi, tất cả đều trên hạ tầng của bạn:
| Kho | Chứa gì |
|---|---|
| Postgres của Board | Space, task, group, plan, activity, membership |
| Postgres pgvector của Arkon | Trang Wiki, source đã trích xuất, vector tìm kiếm |
| MinIO | File và ảnh đính kèm của Wiki |
| Repo git của bạn | Worktree agent và code agent viết ra |
Redis chỉ giữ hàng đợi xử lý, không phải nguồn dữ liệu. Backup và khôi phục: Vận hành và backup.
Agent có sửa được code trên máy tôi không?
Không, theo hai chốt tách biệt. Agent chỉ làm việc trong git worktree riêng agent/<task-key> — nhánh làm việc của bạn không bị đụng tới. Ngoài ra server chỉ nhận repoPath nằm trong danh sách thư mục cho phép; đặt ALLOWED_REPO_ROOTS để thu hẹp thêm.
Agent có tự merge vào nhánh chính không?
Không, và không có chế độ nào bật được điều đó. Agent xong việc thì task sang cột review; merge chỉ xảy ra sau khi một người bấm Approve. Service token và CI đều bị từ chối ở bước này. Vì sao thiết kế cứng như vậy: Vì sao Human Gate không bypass được.
Ai thấy được task và Wiki của Space khác?
Không ai, trừ khi được cấp quyền. Phân quyền tính theo từng Space và fail-closed: chưa được cấp thì mặc định 403. Bật AGENTBOARD_WS_TOPICS thì cả stream realtime cũng chia phòng theo Space. Ma trận quyền: Phân quyền Board.
Có thay được Jira hay Linear không?
Không, và cũng không nhắm tới. AgentJira không có sprint, burndown hay timesheet — bảng này để giao việc cho agent, không phải quản lý con người. Nhiều team chạy song song: Jira cho người, AgentJira cho agent. Ranh giới đầy đủ: AgentJira là gì.
Chạy được bao nhiêu agent cùng lúc?
Giới hạn thật là CPU/RAM của máy chủ và hạn mức của nhà cung cấp model, không phải phần mềm. Mỗi task chạy trong worktree riêng nên không tranh file nhau. Điều chỉnh bằng maxConcurrency của Task Group — đặt quá cao là cách phổ biến nhất để làm nghẽn máy chủ.
Server sập giữa lúc agent chạy thì mất việc không?
Không. Mỗi lần chạy giữ một "giấy phép" 30 giây phải gia hạn liên tục; giấy phép hết hạn thì lần khởi động sau hệ thống đưa task về idle và ghi một Activity system_recovery. Worktree vẫn nguyên, bấm chạy lại là tiếp tục.
Nâng cấp có mất dữ liệu không?
Không. Migration chạy lúc boot, và quy trình rollback là quay lại tag image trước đó — dữ liệu nằm ở volume, không nằm trong image. Quy trình đầy đủ: Vận hành và backup.
Bước tiếp theo: Bài 0 — Chạy thử trong 10 phút · AgentJira là gì · Cài đặt và chạy lần đầu · Xử lý sự cố