Hướng dẫn từng bước để tự cài đặt, tự kiểm tra và tự giao việc cho AI agent trên dữ liệu Lark của công ty, kèm ranh giới an toàn cần vạch ra trước khi bấm nút kết nối và các lỗi thường gặp trong quá trình sử dụng.
Trước khi đi vào thao tác, cần hiểu đúng vai trò của từng mảnh ghép. Hiểu sai vai trò là nguồn gốc của phần lớn kỳ vọng sai và lỗi sử dụng về sau.
| Thành phần | Vai trò | Hình dung đơn giản |
|---|---|---|
| Lark CLI | Công cụ dòng lệnh chính thức của Lark, cho phép đọc và thao tác dữ liệu Base, Docs, IM ngay từ Terminal bằng chính tài khoản Lark của bạn. | Cánh cửa nối máy tính của bạn với dữ liệu Lark của công ty. |
| Claude Code / Codex | AI agent chạy trong Terminal, nhận yêu cầu bằng tiếng Việt tự nhiên rồi tự gọi Lark CLI để lấy dữ liệu, tổng hợp và phân tích. | Trợ lý phân tích ngồi cạnh bạn, biết tự mở cánh cửa đó khi được giao việc. |
| Skill / package nội bộ | Gói cấu hình do đội kỹ thuật chuẩn bị sẵn, chứa danh sách Base, table ID và kịch bản phân tích chuẩn để agent không phải mò mẫm. | Bản đồ chỉ đường trong kho dữ liệu, kèm quy tắc đi lại. |
Thay vì chờ nhân sự xuất báo cáo, bạn gõ một câu yêu cầu và agent tự truy vấn dữ liệu thật từ Lark Base rồi trả về kết quả tổng hợp. Một vài ví dụ điển hình gồm có: rà soát hợp đồng sắp hết hạn, tổng hợp doanh số theo tháng theo chi nhánh, soi danh sách lead chưa được chăm sóc và đối chiếu số liệu giữa hai bảng.
Điểm khác biệt quan trọng so với việc hỏi ChatGPT thông thường là agent làm việc trên dữ liệu thật, mới nhất của công ty, với đúng quyền truy cập của tài khoản bạn đang đăng nhập.
Agent chỉ đọc được những gì tài khoản Lark của bạn được share quyền. Không có phép màu nào vượt qua phân quyền của Lark; đây vừa là giới hạn vừa là lớp bảo vệ quan trọng nhất của toàn bộ hệ thống.
Nếu bạn là người trực tiếp cài đặt, hãy đọc tuần tự tab 2, 3, 4 rồi mới dùng. Nếu máy đã được đội kỹ thuật cài sẵn, bạn vẫn bắt buộc đọc tab 2 và tab 7 trước khi dùng, sau đó đi thẳng tới tab 5. Tab 6 và tab 8 là tài liệu tra cứu khi gặp lỗi hoặc khi muốn tự kiểm tra chất lượng kết quả.
Đây là bước quan trọng nhất của toàn bộ guideline và cũng là bước dễ bị bỏ qua nhất. Kết nối agent vào dữ liệu công ty mà chưa vạch ranh giới cũng giống như trao chìa khóa tổng cho một nhân viên mới chưa qua đào tạo.
Ba điều dưới đây gộp lại chỉ để xác định trước một "phân khu" ranh giới rõ ràng, trước khi kết nối, trao đổi hay giao việc cho agent. Đó là điều kiện cần, xuất phát từ nhu cầu thật của bạn chứ không phải chạy theo vì thấy hay.
Cách đơn giản nhất để vạch ranh giới là chia toàn bộ dữ liệu Lark của công ty thành ba vùng rồi quyết định trước với từng vùng.
Ranh giới hiệu quả nhất được thực thi bằng phân quyền thật trên Lark chứ không phải bằng lời dặn agent. Tài khoản dùng cho agent chỉ được share đúng những Base thuộc vùng xanh và vùng vàng đã duyệt. Đừng dựa vào việc "dặn agent đừng đọc chỗ này"; hãy làm cho agent không thể đọc được ngay từ tầng quyền.
Toàn bộ quá trình cài mất khoảng 20 đến 30 phút nếu chuẩn bị đủ các điều kiện dưới đây. Thiếu một trong số này thì gần như chắc chắn sẽ vướng lỗi giữa chừng.
| Hạng mục | Yêu cầu | Cách tự kiểm tra |
|---|---|---|
| Máy tính | macOS có kết nối internet ổn định | Mở được trang web bất kỳ trong trình duyệt |
| Terminal | Ứng dụng Terminal hoạt động bình thường | Mở Spotlight (Cmd + Space), gõ "Terminal", cửa sổ dòng lệnh hiện ra |
| Quyền cài phần mềm | Được phép cài Node.js và npm package trên máy | Máy cá nhân thường có sẵn; máy công ty cần hỏi IT |
| Tài khoản Lark | Đã được admin share quyền vào đúng các Base cần truy vấn | Mở Lark, vào từng Base trong danh sách và xem được dữ liệu |
| Claude Code hoặc Codex | Có tài khoản còn hạn sử dụng (Claude Pro/Max hoặc ChatGPT Plus trở lên) | Đăng nhập được trên trình duyệt trước khi cài bản Terminal |
Lỗi phổ biến nhất của toàn bộ quy trình không nằm ở kỹ thuật mà nằm ở quyền. Nếu tài khoản Lark của bạn chưa được share vào Base, mọi bước cài đặt phía sau đều thành công nhưng agent vẫn không đọc được dữ liệu. Hãy mở Lark trên điện thoại hoặc trình duyệt, bấm vào từng Base cần dùng và xác nhận bạn xem được dữ liệu trước khi bắt đầu cài.
Chỉ tải công cụ từ các nguồn dưới đây. Tuyệt đối không cài bản do người lạ gửi qua chat hoặc link rút gọn.
nodejs.org/en/download, chọn bản LTS cho macOS.github.com/larksuite/cli, cài qua npm với package @larksuite/cli.docs.claude.com/docs/claude-code/setup.Thay vì làm từng lệnh một, phần cài Lark CLI, đăng nhập đúng domain và xác minh quyền truy cập được gộp lại thành một prompt duy nhất. Bạn chỉ cần hoàn tất hai bước khởi động dưới đây, sau đó dán nguyên prompt vào Claude Code hoặc Codex và để agent tự làm phần còn lại, kể cả khi bàn giao máy cho người khác dùng lần đầu.
Node.js là nền chạy của mọi công cụ dòng lệnh phía sau. Vào nodejs.org/en/download, tải bản LTS cho macOS, mở file cài và bấm Next theo hướng dẫn. Sau khi cài xong, mở Terminal và kiểm tra.
node --version v22.x.x npm --version 10.x.x
Cả hai lệnh đều in ra số phiên bản. Nếu báo command not found, hãy đóng Terminal mở lại; nếu vẫn lỗi thì cài lại Node.js.
Chọn một trong hai, tùy công ty bạn đang dùng hệ nào. Đây là nơi bạn sẽ dán prompt tổng hợp ở bước kế tiếp.
# Claude Code npm install -g @anthropic-ai/claude-code claude # lần đầu chạy sẽ mở trình duyệt để đăng nhập # hoặc Codex npm install -g @openai/codex codex # đăng nhập bằng tài khoản ChatGPT
Gõ claude hoặc codex thì giao diện chat của agent hiện ra ngay trong Terminal và bạn đã đăng nhập thành công.
Sau khi giao diện chat của agent hiện ra, điền phần mô tả nhu cầu ở cuối prompt rồi dán nguyên khối bên dưới vào khung chat và gửi đi. Agent sẽ tự kiểm tra và cài Lark CLI nếu còn thiếu, hỏi lại bạn cần đăng nhập domain nào, chờ bạn đăng nhập trên trình duyệt, thử đọc thử một bảng để xác minh quyền và tóm tắt lại toàn bộ kết quả. Cách làm này phù hợp nhất khi bàn giao máy cho một CEO khác dùng lần đầu, vì họ không cần nhớ bất kỳ câu lệnh Terminal nào.
Bạn đang giúp tôi kết nối Lark CLI vào máy này để tôi tự truy vấn dữ liệu công ty bằng Claude Code hoặc Codex. Hãy làm theo trình tự dưới đây, dừng lại hỏi tôi bất cứ khi nào cần tôi xác nhận hoặc thao tác trên trình duyệt. 1. Kiểm tra máy đã có Lark CLI chưa; nếu chưa, cài bằng npm với gói @larksuite/cli phiên bản mới nhất rồi xác nhận bằng lệnh --version. 2. Hỏi tôi cần đăng nhập những domain nào trong số base, docs và im, dựa trên mô tả nhu cầu của tôi bên dưới, sau đó chạy lệnh đăng nhập cho từng domain đã chọn và chờ tôi hoàn tất đăng nhập trên trình duyệt. 3. Sau khi đăng nhập xong, thử đọc một bảng dữ liệu nhỏ mà tôi chỉ định để xác minh quyền truy cập hoạt động đúng, không tự ý mở bảng nào ngoài phạm vi tôi cho phép. 4. Tóm tắt lại những gì đã cài, những domain đã đăng nhập, những Base đã xác nhận đọc được, và Base hoặc bảng nào tôi cần xin admin Lark share thêm quyền nếu còn thiếu. Nhu cầu của tôi là [mô tả ngắn gọn nhóm việc cần agent hỗ trợ, ví dụ theo dõi doanh số theo chi nhánh và tình trạng hợp đồng]. Base tôi đã được share quyền và muốn agent đọc gồm [liệt kê tên Base, hoặc để trống nếu chưa rõ và để agent hỏi lại]. Phạm vi tôi chưa muốn agent chạm vào gồm [ví dụ bảng lương, dữ liệu HR, dữ liệu thanh toán khách hàng].
Prompt này chỉ thay thế phần thao tác Terminal, không thay thế việc bạn tự vạch ranh giới. Phần "Nhu cầu của tôi" và "Phạm vi tôi chưa muốn agent chạm vào" trong prompt chính là nơi bạn áp bản cam kết phân khu đã điền ở tab 2 vào thực tế.
Agent tự báo cáo đã cài xong Lark CLI, đã đăng nhập đúng domain và đọc thử thành công ít nhất một bảng, kèm danh sách Base nào còn thiếu quyền. Nếu agent báo lỗi ở bất kỳ bước nào, xem cách xử lý tương ứng ở tab 6.
Chất lượng kết quả phụ thuộc phần lớn vào cách giao việc. Nguyên tắc chung là giao việc như giao cho một chuyên viên phân tích mới vào công ty, rõ phạm vi, rõ nguồn số liệu và rõ định dạng đầu ra mong muốn.
Một prompt hiệu quả thường có bốn phần, gồm có: gọi đúng skill hoặc nguồn dữ liệu, nêu phạm vi thời gian và đối tượng, liệt kê các mục cần trả lời và yêu cầu ghi rõ nguồn bảng cho từng con số.
Use $ten-skill để [việc cần làm] trong [phạm vi thời gian, chi nhánh, nhóm khách]. Trả về [các mục cụ thể]. Ghi rõ lấy số từ bảng nào và nếu thiếu dữ liệu thì nói thiếu, không tự suy diễn.
Các mẫu dưới đây viết theo khung chung, bạn thay tên skill và các chỗ trong ngoặc vuông theo đúng công ty và Base của mình.
Use $ten-skill để rà soát toàn bộ hợp đồng của [chi nhánh hoặc nhóm khách hàng]: hợp đồng hết hạn, sắp hết hạn, hồ sơ chưa đạt, thiếu lịch thu tiếp.
Use $ten-skill để phân tích doanh số tháng này theo [chi nhánh hoặc kênh]: tổng tiền, số hợp đồng hoặc đơn hàng, đã thu, top nhân sự, top nguồn, điểm cần lưu ý.
Use $ten-skill để liệt kê lead trong [khoảng thời gian] chưa có người chăm sóc, nhóm theo nguồn, kèm đề xuất thứ tự ưu tiên gọi lại.
Bên cạnh việc truy vấn số liệu, agent còn dùng được để soi lại chính cách các Base đang được thiết kế, tức là kiểm tra bảng, trường dữ liệu và mối liên kết có hợp lý không, có chỗ nào trùng lặp, thiếu liên kết hoặc đặt tên không nhất quán. Đây là việc nên làm định kỳ, đặc biệt khi công ty mở rộng thêm phòng ban hoặc thêm mảng kinh doanh mới.
Use $ten-skill để rà soát toàn bộ cấu trúc các Base đang dùng cho [phòng ban hoặc nhóm việc]: liệt kê các bảng, các trường dữ liệu, mối liên kết giữa các bảng. Đánh giá luồng dữ liệu hiện tại có hợp lý không, có bảng nào trùng lặp hoặc thiếu liên kết, trường nào nên tách riêng hoặc gộp lại, và đề xuất cách tối ưu để dễ mở rộng khi công ty phát triển thêm.
Khác với các prompt truy vấn số liệu ở trên, prompt này yêu cầu agent đánh giá về mặt thiết kế, nên kết quả cần được đội vận hành dữ liệu xem lại trước khi áp dụng thay đổi thật lên Base.
Việc lập trước một bảng phân nhóm nguồn dữ liệu giúp agent không lấy nhầm nguồn khi trả lời. Bảng dưới đây là khung mẫu, thay tên Base và tên bảng theo đúng công ty bạn rồi đưa vào skill nội bộ.
| Nhóm việc | Nguồn được dùng |
|---|---|
| Sale, hợp đồng | [Tên Base của bạn] với bảng hợp đồng và CRM |
| Lead | [Tên Base của bạn] với bảng lead |
| Vận hành | [Tên Base vận hành], kết hợp bảng duyệt nếu có quy trình approval riêng |
| HR, ngày công, chấm công | Không sử dụng, trừ khi có phê duyệt riêng cho từng trường hợp |
Nguyên tắc quan trọng hơn nội dung bảng cụ thể là mỗi nhóm câu hỏi chỉ được trả lời từ đúng nguồn đã duyệt, không để agent tự chọn nguồn khi có nhiều bảng chứa dữ liệu tương tự.
Hầu hết sự cố rơi vào một trong các nhóm dưới đây. Trước khi gọi hỗ trợ kỹ thuật, hãy thử tự xử lý theo bảng; phần lớn trường hợp giải quyết được trong vài phút.
| Biểu hiện | Nguyên nhân thường gặp | Cách xử lý |
|---|---|---|
lark-cli: command not found |
Chưa cài CLI, hoặc cài xong nhưng Terminal chưa nhận đường dẫn mới | Chạy npm install -g @larksuite/cli@latest, sau đó đóng hẳn Terminal và mở lại rồi thử lark-cli --version |
node: command not found |
Chưa cài Node.js hoặc cài chưa hoàn tất | Cài lại bản LTS từ nodejs.org, mở Terminal mới sau khi cài |
Lỗi EACCES hoặc permission denied khi chạy npm install |
Tài khoản máy không có quyền ghi vào thư mục cài đặt toàn cục | Cài Node.js bằng bộ cài chính thức từ nodejs.org thay vì qua công cụ khác; nếu vẫn lỗi, nhờ IT cấp quyền, tránh tự chạy sudo khi chưa hiểu rõ |
| Cài rất chậm hoặc treo giữa chừng | Mạng công ty chặn npm hoặc dùng proxy | Thử mạng khác (phát 4G từ điện thoại); nếu chỉ chạy được trong mạng công ty thì nhờ IT cấu hình proxy cho npm |
| Biểu hiện | Nguyên nhân thường gặp | Cách xử lý |
|---|---|---|
| Permission denied khi agent đọc Base | Tài khoản Lark chưa được share quyền vào Base đó | Nhờ admin Lark share Base cho đúng tài khoản bạn đã đăng nhập, sau đó chạy lại lark-cli auth login --domain base |
| Đăng nhập xong vẫn không đọc được dữ liệu | Đăng nhập nhầm tài khoản Lark khác, ví dụ tài khoản cá nhân thay vì tài khoản công ty | Kiểm tra tài khoản đang đăng nhập trên trình duyệt mặc định, đăng xuất tài khoản sai rồi chạy lại auth login |
| Hôm trước dùng được, hôm nay báo lỗi xác thực | Token đăng nhập hết hạn | Chạy lại lark-cli auth login cho domain tương ứng; đây là hiện tượng bình thường theo chu kỳ |
| Đọc được Base này nhưng không đọc được Base kia | Quyền share theo từng Base, không phải quyền toàn hệ thống | Rà lại danh sách Base ở bản phân khu tab 2, nhờ admin share bổ sung nếu Base đó thuộc vùng được duyệt |
| Biểu hiện | Nguyên nhân thường gặp | Cách xử lý |
|---|---|---|
| Agent báo không tìm thấy skill | Skill nội bộ chưa được cài vào đúng thư mục, hoặc app chưa khởi động lại sau khi cài | Dán lại prompt cài đặt tổng hợp ở tab 4 để agent tự kiểm tra và cài lại, sau đó thoát hẳn Claude Code / Codex và mở lại |
| Agent trả lời chung chung, không đụng tới dữ liệu thật | Prompt không gọi skill hoặc không chỉ rõ nguồn Base | Bắt đầu câu lệnh bằng "Use $ten-skill to..." hoặc dán link Base cụ thể vào yêu cầu |
| Agent chạy rất lâu rồi báo lỗi giới hạn | Yêu cầu quét bảng quá lớn trong một lần | Thu hẹp phạm vi theo tháng hoặc theo chi nhánh, chạy thành nhiều lượt nhỏ rồi yêu cầu tổng hợp lại |
| Kết quả có số liệu đáng ngờ | Không phải lỗi kỹ thuật; xem tab 8 | Áp dụng quy trình kiểm chứng ở tab 8 trước khi dùng số |
Nếu đã thử đúng cách xử lý trong bảng mà lỗi vẫn còn, hãy chụp nguyên màn hình Terminal có thông báo lỗi và gửi cho đội kỹ thuật kèm ba thông tin, gồm có: lệnh vừa chạy, thời điểm chạy và việc bạn đang định làm. Đừng gửi kèm token hay nội dung file cấu hình.
Ranh giới bảo mật của hệ thống này rất rõ ràng nếu bạn nắm hai danh sách dưới đây. Vi phạm danh sách cấm là rủi ro nghiêm trọng nhất của toàn bộ mô hình, hơn mọi lỗi kỹ thuật cộng lại.
Base token và table ID chỉ là địa chỉ, giống số phòng trong một tòa nhà. Người cầm địa chỉ vẫn phải có chìa khóa, tức tài khoản Lark được share quyền, thì mới vào được. Ngược lại, app secret và access token là chính chiếc chìa khóa, lọt ra ngoài là người khác vào thẳng dữ liệu mà không cần xin phép ai.
Bình tĩnh xử lý theo thứ tự, gồm có: báo ngay cho đội kỹ thuật, thu hồi hoặc đổi key bị lộ tại nguồn cấp, kiểm tra log truy cập trong khoảng thời gian bị lộ và cuối cùng mới rút kinh nghiệm quy trình. Tốc độ thu hồi key quan trọng hơn việc tìm người có lỗi.
Phần này không nói về lỗi kỹ thuật mà nói về rủi ro tinh vi hơn, xuất hiện đúng lúc mọi thứ chạy mượt nhất.
Sau vài ngày dùng quen, bạn sẽ thấy agent tổng hợp ra nhanh, phân tích ra nhanh, góc nhìn có vẻ đầy đủ. Tự nhiên thấy việc nhẹ hẳn, đầu óc thảnh thơi, kiểu gõ vài lệnh là xong cả buổi làm. Cảm giác đó thật sự dễ nghiện.
Và chính lúc đó, người dùng dễ bị chính công cụ kéo đi lúc nào không hay. Tốc độ tạo cảm giác chính xác, trong khi hai thứ này không liên quan gì đến nhau. Một bản tổng hợp ra trong 30 giây trông thuyết phục y hệt một bản tổng hợp đúng, và khác biệt chỉ lộ ra khi có người chịu kiểm tra.
Ba câu hỏi dưới đây cần được hỏi với mọi kết quả quan trọng trước khi bạn dùng nó để ra quyết định.
1. Phần tổng hợp có chính xác và đầy đủ không, hay agent đã tự lược bớt vài chỗ mà mình không để ý?
Agent có xu hướng ưu tiên sự gọn gàng của câu trả lời hơn sự đầy đủ của dữ liệu. Cách kiểm tra là yêu cầu agent báo cáo tổng số dòng đã quét và số dòng bị loại kèm lý do, rồi đối chiếu tổng số với con số bạn thấy trên Base. Lệch tổng là dấu hiệu phải dừng lại.
2. Góc nhìn đưa ra đã đủ bối cảnh, đủ thông tin nền chưa, hay chỉ là suy diễn từ vài dòng dữ liệu ít ỏi?
Một nhận định kiểu "doanh số giảm do chi nhánh X yếu đi" nghe rất chắc chắn nhưng có thể chỉ dựa trên vài chục dòng của một tháng. Hãy hỏi lại agent nhận định này dựa trên bao nhiêu bản ghi, trong khoảng thời gian nào và còn cách giải thích nào khác không. Nhận định từ mẫu nhỏ chỉ nên coi là giả thuyết cần kiểm tra thêm.
3. Mình có đang càn thêm, thêm rác vào những gì vốn đã gọn không, khiến kết quả nhìn hoành tráng nhưng chưa chắc dùng được?
Agent làm nhanh nên rất dễ sa vào việc yêu cầu thêm bảng, thêm chiều phân tích, thêm biểu đồ cho mọi thứ. Kết quả là báo cáo dày lên nhưng quyết định không rõ hơn. Trước khi yêu cầu thêm bất kỳ phân tích nào, hãy tự trả lời phân tích đó thay đổi quyết định gì; nếu không trả lời được thì đừng thêm.
Agent giúp bạn đi nhanh hơn tới câu trả lời, nhưng trách nhiệm với quyết định vẫn nguyên vẹn là của bạn. Số liệu chưa qua kiểm chứng thì chưa đưa vào cuộc họp, chưa gửi cho đối tác và chưa dùng để đánh giá con người. Giữ được kỷ luật này thì tốc độ của agent là tài sản; mất kỷ luật này thì tốc độ chỉ giúp bạn sai nhanh hơn.