Hướng dẫn này giải thích các bước để bắt đầu sử dụng Tích hợp Claude. Quản trị viên GeckoFlag bật tính năng và cấp quyền cho người dùng, sau đó người dùng tạo token API và thêm tiện ích mở rộng vào ứng dụng Claude trên máy tính.
Trước khi bắt đầu
- GeckoFlag v1.11.0 trở lên — cần được công khai qua HTTPS.
- Tài khoản quản trị viên GeckoFlag — chỉ quản trị viên mới có thể thực hiện cài đặt ở BƯỚC 1 và BƯỚC 2.
- Ứng dụng Claude trên máy tính (Windows, macOS) — đăng nhập sẵn bằng tài khoản có gói Claude. Node.js cần cho tiện ích mở rộng đã có sẵn trong ứng dụng, nên bạn không cần cài đặt riêng.
- Tệp tiện ích mở rộng GeckoFlag (.mcpb) — tệp để thêm vào ứng dụng Claude trên máy tính. Tệp này có trong gói tải xuống bạn nhận được sau khi mua GeckoFlag, cùng với GeckoFlag và tài liệu hướng dẫn.
Ảnh chụp màn hình là ví dụ khi hiển thị bằng tiếng Anh (tên các mục trong GeckoFlag và Claude thay đổi theo ngôn ngữ hiển thị). Các màn hình của ứng dụng Claude trên máy tính là tại thời điểm tháng 10 năm 2026 và có thể thay đổi theo quyết định của Anthropic.
Tổng quan các bước
- Quản trị viên bật Tích hợp Claude trên màn hình cài đặt của GeckoFlag
- Quản trị viên bật “Cho phép dùng Tích hợp Claude (API)” cho từng người sẽ sử dụng
- Người dùng tạo và sao chép token API trên màn hình hồ sơ
- Người dùng cài đặt tiện ích mở rộng vào ứng dụng Claude trên máy tính
- Nhập URL GeckoFlag và token API vào tiện ích mở rộng
- Nhờ Claude kiểm tra xem đã kết nối được chưa
BƯỚC 1: Bật Tích hợp Claude (quản trị viên)
- Đăng nhập GeckoFlag bằng tài khoản quản trị viên và mở “Cài đặt” (Settings) ở menu bên trái.
- Nhấn “Sửa” (Edit) trên thẻ “Tích hợp Claude” (Claude Integration).
- Đánh dấu “Bật tích hợp Claude” (Enable Claude integration). Mặc định là tắt.
- Nếu muốn Claude cũng tạo, cập nhật vấn đề và đăng bình luận, hãy đánh dấu thêm “Cho phép ghi” (Allow writing), rồi lưu.
- Khi không cho phép ghi — mọi token đều chỉ có quyền đọc. Kể cả token được tạo với quyền “Đọc và ghi” cũng chỉ dùng được để tìm kiếm và xem.
- Kiểm tra tình trạng sử dụng — trên cùng màn hình, bạn có thể xem số người dùng được cho phép và số token API đã được tạo.
BƯỚC 2: Cấp quyền cho người dùng (quản trị viên)
Chỉ những người dùng được quản trị viên cho phép mới có thể dùng Tích hợp Claude (quản trị viên cũng cần được cấp).
- Mở “Người dùng” (Users) ở menu bên trái và nhấn “Sửa” ở người dùng cần cấp.
- Đánh dấu “Cho phép dùng Tích hợp Claude (API)” (Allow Claude integration (API)) rồi nhấn “Cập nhật” (Update).
- Thiết lập riêng, khác với “Tạo bằng AI” — ô “Cho phép đăng ký với sự hỗ trợ của AI” (Allow AI-assisted registration) ngay phía trên là quyền dùng Tạo bằng AI. Nếu chỉ dùng Tích hợp Claude, bạn không cần bật ô này.
- Khi gỡ quyền — mọi token API của người dùng đó sẽ bị xóa và không thể dùng từ Claude nữa.
BƯỚC 3: Tạo token API
Từ bước này, mỗi người dùng Tích hợp Claude tự thực hiện.
- Mở “Hồ sơ” (Profile) ở menu bên trái và tìm đến phần “Token API (Tích hợp Claude)” (API Tokens).
- Ghi lại “URL nhập vào tiện ích mở rộng” (URL to enter in the extension). Bạn sẽ dùng nó ở BƯỚC 5.
- Ở “Tên token” (Token name), nhập tên cho biết token dùng trên máy tính nào (ví dụ: Claude trên máy tính công ty).
- Chọn “Hết hạn sau” (Expires in) trong 30 ngày, 90 ngày, 365 ngày hoặc không giới hạn (mặc định là 90 ngày).
- Chọn “Quyền” (Permission) rồi nhấn “Tạo token” (Create token).
- Cách chọn quyền — chọn “Chỉ đọc” (Read only) nếu chỉ tìm kiếm và xem, hoặc “Đọc và ghi” (Read and write) nếu muốn Claude cũng tạo, cập nhật vấn đề và đăng bình luận. Chỉ chọn quyền ghi khi thật sự cần.
- Token chỉ hiển thị một lần ngay sau khi tạo. Hãy sao chép ngay lúc đó. Bảo quản token như mật khẩu, không để người khác biết.
- Số lượng có thể tạo — mỗi người tạo được tối đa 5 token. Token không dùng nữa có thể xóa bất cứ lúc nào trên cùng màn hình.
- Khi đổi mật khẩu — mọi token của người đó sẽ bị xóa. Hãy tạo lại và nhập lại vào tiện ích mở rộng.
BƯỚC 4: Cài đặt tiện ích mở rộng vào Claude
- Mở ứng dụng Claude trên máy tính, nhấn vào tên tài khoản ở góc dưới bên trái và mở “Cài đặt” (Settings).
- Mở “Tiện ích mở rộng” (Extensions) ở menu bên trái.
- Kéo thả tệp tiện ích mở rộng GeckoFlag (.mcpb) vào màn hình này. Bạn cũng có thể cài đặt bằng cách chọn tệp từ “Cài đặt tiện ích mở rộng” trong “Cài đặt nâng cao” (Advanced settings), hoặc nhấp đúp vào tệp.
- Khi phần mô tả tiện ích mở rộng GeckoFlag hiện ra, hãy kiểm tra nội dung rồi nhấn “Cài đặt” (Install).
Màn hình cài đặt hiển thị các lưu ý tiêu chuẩn của Claude như “tiện ích mở rộng được phép truy cập máy tính của bạn” và “thông tin nhà phát triển chưa được Anthropic xác minh”. Tiện ích mở rộng GeckoFlag chỉ giao tiếp với URL GeckoFlag bạn đã nhập, và chỉ lưu tệp khi xuất biểu đồ Gantt ra Excel.
BƯỚC 5: Cấu hình địa chỉ kết nối và token
- Sau khi cài đặt, màn hình cấu hình (Configure) sẽ mở ra. Nhập các mục sau rồi nhấn “Lưu” (Save).
| Mục | Nội dung cần nhập |
|---|---|
| GeckoFlag URL (bắt buộc) | “URL nhập vào tiện ích mở rộng” đã ghi lại ở BƯỚC 3 (ví dụ: https://pm.example.com). URL phải bắt đầu bằng https://. |
| API token (bắt buộc) | Token API đã sao chép ở BƯỚC 3 (chuỗi bắt đầu bằng gfk_). Token được lưu dưới dạng che. |
| Export folder (tùy chọn) | Nơi lưu tệp Excel biểu đồ Gantt. Nếu để trống, tệp được lưu vào thư mục “Tải xuống”. |
- Khi “GeckoFlag” xuất hiện trong danh sách “Tiện ích mở rộng”, việc cài đặt đã hoàn tất. Hãy kiểm tra tiện ích mở rộng đang được bật. Khi muốn đổi cấu hình, bạn có thể mở lại từ “Cấu hình” (Configure).
- Muốn xác nhận trước khi ghi (khuyên dùng) — trên cùng màn hình, mở tiện ích mở rộng GeckoFlag và đặt các thao tác ghi như tạo, cập nhật vấn đề thành “luôn hỏi”, Claude sẽ luôn hỏi xác nhận trước khi thực hiện.
BƯỚC 6: Kiểm tra kết nối
- Mở cuộc trò chuyện mới trong Claude và nhờ: “Kiểm tra xem đã kết nối được với GeckoFlag chưa”.
- Nếu Claude trả lời tên người sở hữu token, phiên bản GeckoFlag và việc có thể ghi hay không, quá trình thiết lập đã hoàn tất.
Giờ bạn chỉ cần nhờ bằng lời nói thường ngày, như “Cho tôi xem các vấn đề tôi phụ trách có hạn chót trong tuần này”. Xem thêm ví dụ cách nhờ trên trang Tích hợp Claude.
Khi gặp sự cố
Trong nhiều trường hợp, Claude sẽ giải thích nguyên nhân và cách xử lý ngay trong cuộc trò chuyện. Sau đây là các trường hợp thường gặp.
- Claude không dùng GeckoFlag — tiện ích mở rộng đang bị tắt hoặc chưa được cài đặt. Hãy bật GeckoFlag trong “Tiện ích mở rộng” của phần cài đặt rồi mở lại cuộc trò chuyện.
- Không tìm thấy API (404) — Tích hợp Claude đang bị tắt, phiên bản GeckoFlag đã cũ hoặc URL bị sai. Hãy kiểm tra cài đặt của quản trị viên, phiên bản GeckoFlag và URL đã nhập.
- Token bị từ chối (401) — token có thể bị sai, đã hết hạn hoặc đã bị xóa (đổi mật khẩu cũng xóa token). Hãy tạo lại trên màn hình hồ sơ và nhập lại vào tiện ích mở rộng.
- Chưa được cho phép sử dụng — quản trị viên cần bật “Cho phép dùng Tích hợp Claude (API)” trên màn hình sửa người dùng.
- Không ghi được (403) — bạn đang dùng token “Chỉ đọc”, hoặc thiết lập “Cho phép ghi” của trang đang tắt. Hãy tạo token “Đọc và ghi” hoặc nhờ quản trị viên cho phép.
- Không tìm thấy vấn đề hoặc dự án — mã bị sai, hoặc bạn không phải thành viên của dự án đó. Hãy kiểm tra lại mã hoặc nhờ chủ sở hữu thêm bạn vào làm thành viên.
- Bị chuyển hướng — có sự khác biệt giữa http và https, có hay không có www… Hãy nhập URL cuối cùng hiển thị khi mở bằng trình duyệt.
- Bị trang từ chối — hạn chế truy cập theo địa chỉ IP của GeckoFlag đang áp dụng cho API. Hãy dùng từ địa điểm được phép, hoặc nhờ quản trị viên xem lại phạm vi cho phép.
- Giới hạn số lần (429) — tối đa 60 lần mỗi phút cho mỗi token. Nếu đã dùng token sai liên tiếp, hãy chờ tối đa khoảng 15 phút rồi thử lại.
- Không có phản hồi — máy chủ có thể đang chậm hoặc đã dừng. Với thao tác ghi, dữ liệu có thể đã được lưu, nên hãy kiểm tra trên màn hình GeckoFlag trước khi thử lại.
- Lỗi 401 liên tục trên máy chủ Apache — thông thường lỗi này được tự động khắc phục. Nếu vẫn tiếp diễn, hãy kiểm tra tệp webroot/.htaccess của GeckoFlag đã là bản mới nhất chưa.