Triển khai · Trợ lý giọng nói TÔM

TÔM Voice ⇄ Lark,
nói một câu là máy làm việc

Bấm micro nói vào một nhóm Lark riêng — trợ lý nghe, hiểu, làm việc trên máy bạn rồi trả lời lại bằng giọng nói. Không thuê máy chủ, không fork repo.

Bạn tự tay 2 việc — cài 5 công cụ nền và tạo app Lark. Điền các ô bên dưới, trang tự ghép sẵn khối lệnh để bạn dán vào Claude Code làm nốt phần còn lại.

  1. Cài 5 công cụNode · Python · ffmpeg · lark-cli · claude
  2. Tạo app Larktay · ~10 phút · một lần
  3. Điền & chép khối lệnhClaude Code cài hộ
  4. Bật lên, nói thửtay bạn bật — có lý do
01

Hiểu trước: TÔM sống trên máy bạn

Khác hẳn các hệ thống tự động chạy trên mây mà bạn từng dựng. Ở đây máy tính của bạn chính là máy chủ — repo tải về máy, cấu hình nằm trong file scripts/.env trên máy, và khi bạn tắt máy thì TÔM ngủ theo. Không có ai chạy thay bạn.

Chạy ở đâuNgay trên máy bạn. Không cần thuê máy chủ, không cần fork repo, không cần nạp Secrets lên GitHub.
Cấu hình nằm đâuFile scripts/.env trên máy — sửa trực tiếp, không phải vào web nào cả.
Tắt máy thì saoTÔM ngừng, chờ bạn bật lại. Muốn chạy liên tục thì xem mục 08.
Ra lệnh bằng cách nàoNói hoặc gõ chữ vào nhóm Lark điều khiển mà bạn tạo riêng.
Ai ra lệnh đượcChỉ mình bạn, và chỉ trong nhóm đó. Người lạ nhắn vào, TÔM không phản hồi.
Trả lời kiểu gìBạn nói bằng giọng → nghe trả lời bằng giọng. Bạn gõ chữ → đọc trả lời bằng chữ.
Đọc kỹ trước khi cài — đây là đánh đổi thật

Gói này mặc định cho TÔM toàn quyền chạy lệnh trên máy, không hỏi bạn từng bước.

Cấu hình mặc định là PERMISSION_MODE=bypassPermissions. Nghĩa là trong phạm vi thư mục BRAIN_ROOT bạn chỉ định, TÔM đọc — sửa — xoá file và gọi lệnh hệ thống mà không dừng lại xin phép. Đổi lại sự tiện lợi đó, bạn đang trao chìa khoá.

Vì vậy: chỉ cài trên máy riêng của bạn — đừng cài lên máy chung hay máy công ty. Và BRAIN_ROOT chỉ nên trỏ vào đúng thư mục bạn thật sự chấp nhận cho AI toàn quyền sửa, không trỏ vào cả ổ đĩa.

02

Cài 5 công cụ nền — một lần cho mãi mãi

Mở PowerShell, gõ từng lệnh ở cột giữa để kiểm. Cái nào báo lỗi "không tìm thấy" thì cài theo cột phải.

Cần cóKiểm bằngChưa có thì cài
Node.js ≥ 18node -vTải bản LTS ở nodejs.org
Python 3.10–3.12uv --version
hoặc python --version		Gọn nhất là cài uv — nó tự lo luôn Python:
powershell -c "irm https://astral.sh/uv/install.ps1 | iex"
ffmpegffmpeg -versionwinget install Gyan.FFmpeg
rồi mở cửa sổ PowerShell mới và kiểm lại
lark-clilark-cli --versionnpm i -g @larksuite/cli
Claude Codeclaude --versionCài Claude Code CLI rồi đăng nhập trên máy này
Windows báo không có python? Rất hay gặp — cái python bạn gõ ra thường chỉ là bản rỗng của Microsoft Store, không dùng được. Đừng mất thời gian sửa nó: cứ cài uv ở trên, trình cài đặt của gói sẽ ưu tiên dùng uv và tự tạo môi trường Python riêng.
Không cần biết máy có card đồ hoạ NVIDIA hay không. Khối lệnh ở mục 05 đã giao cho Claude Code tự kiểm rồi tự chọn mức nghe phù hợp — có card thì dùng bản nghe chuẩn hơn, không có thì dùng bản nhẹ. Nó sẽ báo lại kết quả cho bạn.
03

Việc tay — tạo app Lark và nhóm điều khiển

Khoảng 10 phút, làm một lần duy nhất. Phần này Claude Code không làm hộ được vì nó nằm trong tài khoản Lark của bạn.

  1. open.larksuite.com → Developer Console → Create Custom App

    Tạo xong, vào Add features → bật Bot. (Dùng bản Trung Quốc thì vào open.feishu.cn.)

  2. Tab Permissions & Scopes → bật đủ 3 quyền

    im:message (nhận tin) · im:message:send_as_bot (gửi tin) · im:resource (tải và gửi file, ảnh, âm thanh).

    Thiếu im:resource là hỏng phần giọng nói — nhắn chữ vẫn chạy bình thường nên rất dễ tưởng đã xong, nhưng nói thì không nghe được mà trả lời cũng không phát ra tiếng.

  3. Tab Events & Callbacks → chọn Long Connection → đăng ký event im.message.receive_v1

    Chọn Long Connection để khỏi phải có địa chỉ web công khai hay cài thêm ngrok.

  4. PUBLISH phiên bản — chỗ hỏng nhiều nhất

    Version Management & Release → Create version → Publish. Chưa publish thì mọi quyền và event bạn vừa bật chưa có hiệu lực — bạn nhắn vào nhóm mà máy im lặng hoàn toàn, không báo lỗi gì cả, gần như không thể tự đoán ra nguyên nhân.

  5. Lấy App ID và App Secret ở mục Credentials & Basic Info

    App ID có dạng cli_… — lát nữa điền vào ô ở mục 04. App Secret chỉ dùng để đăng nhập lark-cli, không ghi vào repo, không ghi vào .env.

  6. Tạo nhóm Lark riêng rồi thêm Bot vào nhóm

    Một nhóm chỉ có mình bạn cũng được — đây là nhóm duy nhất TÔM lắng nghe. Vào Add members thêm Bot của app vừa tạo. Quên bước này là mọi thứ khác đúng hết mà vẫn không chạy.

  7. Đăng nhập lark-cli bằng chính app này

    Chọn brand lark nếu dùng larksuite.com, feishu nếu dùng bản .cn. Kiểm lại bằng lark-cli profile list — phải thấy app của bạn với "active": true.

Đổi sang app Lark khác về sau? Nhớ rằng mỗi app cấp một mã định danh riêng cho cùng một con người. Đổi app là phải chạy lại whoami.mjs để lấy mã mới — giá trị cũ trong .env thành vô dụng.
04

Điền thông tin — một lần, đủ mọi giá trị

Điền tới đâu khối lệnh ở mục 05 tự cập nhật tới đó.

Lấy ở Credentials & Basic Info. Luôn bắt đầu bằng cli_.
Khuyên để trống. Nó chỉ dùng lúc đăng nhập lark-cli — tự tay dán khi được hỏi là an toàn nhất. Khối lệnh đã viết sẵn theo hướng đó.
Thư mục bạn cho TÔM toàn quyền thao tác. Để trống = thư mục cha của repo. Chỉ trỏ vào nơi bạn thật sự chấp nhận cho AI sửa file.
Giọng Microsoft, miễn phí. Đổi lúc nào cũng được ở dòng VOICE_CODE trong .env.
Bộ não trả lời bạn qua Lark. Đổi sau trong .env, không phải cài lại gì.

Đã làm xong 2 việc tay ở mục 03 chưa?

Chưa tích ô nào thì khối lệnh sẽ tự yêu cầu Claude Code dẫn bạn làm nốt phần đó trước khi cài tiếp.

Ba thứ cố tình không hỏi bạn, vì máy tự lấy được: mã định danh của bạn và mã nhóm điều khiển (chạy whoami.mjs rồi nhắn một tin bất kỳ là nó in ra sẵn), và chuyện máy có card NVIDIA hay không (Claude Code tự kiểm). Khối lệnh đã bao trọn cả ba.
05

Khối lệnh — chép rồi dán vào Claude Code

Mở Claude Code ở thư mục bất kỳ rồi dán khối này vào — bước đầu tiên đã bảo nó tự tải repo về. Chỗ nào còn màu đỏ là bạn chưa điền.

Khối lệnh triển khai TÔM Voice 

    


    

      Khối lệnh cố tình không cho Claude tự bấm nút khởi động. Lệnh đó mở ra một tiến trình thường trú có toàn quyền chạy lệnh trên máy bạn — thứ đó phải do chính tay bạn bật, sau khi hai lệnh kiểm tra ở mục 07 đã xanh hết. Để Claude tự bật giúp thì bạn mất mất khoảnh khắc nhìn thấy nó đang chạy bằng quyền gì.
    

  


  

    

      06
      
Một câu nói của bạn đi qua những đâu

    


    

      
1 · Bạn nóibấm micro nói vào nhóm điều khiển trên Lark

      
2 · lark-clikéo tin nhắn về máy bạn qua kết nối thường trực — không cần địa chỉ web công khai

      
3 · Tải audio + ffmpegchính là chỗ cần quyền im:resource

      
4 · Máy nghe (Whisper)server thường trú chuyển tiếng nói thành chữ; card đồ hoạ lỗi thì tự lùi về chạy bằng CPU

      
5 · Claude Codechạy ngầm trong thư mục BRAIN_ROOT, làm việc rồi soạn câu trả lời

      
6 · Đọc thành tiếngtrả lời được gắn thẳng vào đúng tin nhắn bạn vừa gửi

    


    
Nhắn bằng chữ thì đi cùng đường này nhưng bỏ qua bước 3–4 và bước đọc — trả lời lại bằng chữ.


    

      

        
Tệp trong repoNhiệm vụ

        
          
scripts/lark-voice-bridge.mjsTrái tim của hệ thống — nghe Lark, điều phối nghe/nghĩ/nói, nhớ được bối cảnh qua các lần khởi động lại

          
scripts/whisper-server.pyServer nghe thường trú, có bước khởi động thử để nếu card đồ hoạ lỗi thì lùi về CPU thay vì chết hẳn

          
scripts/text_to_mp3.pyĐọc câu trả lời thành tiếng (miễn phí)

          
scripts/whoami.mjsIn ra mã định danh của bạn + mã nhóm điều khiển khi bạn nhắn thử

          
scripts/check-setup.mjsCổng chốt môi trường — 10 mắt xích phải xanh hết

          
scripts/start.ps1Nút bật. Nội dung thuần ASCII — thêm dấu tiếng Việt vào là cửa sổ tắt phụt

          
scripts/watchdog.mjsTuỳ chọn chạy 24/7 — kiểm 3 phút một lần, thấy chết hoặc treo thì tự bật lại

        
      

    

  


  

    

      07
      
Cổng chốt — hai lệnh phải xanh hết

    


    

      
Chạy ở thư mục gốc repo

      
node check-itto.mjs           # gói đã đủ mảnh chưa
node scripts/check-setup.mjs  # môi trường + Lark + .env đã sẵn sàng chưa

    


    
Lệnh thứ hai soát đúng 10 mắt xích — còn một dòng đỏ là chưa được bật:


    

      

        
1. Có file .env2. Đã điền mã định danh của bạn

        
3. Đã điền mã nhóm điều khiển4. Node ≥ 18

        
5. Môi trường Python đúng đường dẫn6. Đủ các gói Python cần thiết

        
7. ffmpeg có trên PATH8. lark-cli đã cài

        
9. lark-cli có profile active: true10. claude đã cài

      

    


    

      Cổng chốt không kiểm được 2 việc phía Lark: app đã Publish chưa, và bot đã vào nhóm chưa. Phép thử thật là chạy node scripts/whoami.mjs rồi nhắn một tin vào nhóm — im lặng không in gì ra tức là một trong hai việc đó chưa xong, quay lại mục 03.
    

  


  

    

      08
      
Bật lên, nói thử, và chuyện chạy 24/7

    


    

      

        
Bật — bằng chính tay bạn

        
Chạy powershell -ExecutionPolicy Bypass -File scripts/start.ps1 rồi chờ cho tới khi cửa sổ hiện đủ cả hai dòng báo sẵn sàng (một cho phần điều phối, một cho phần nghe). Lần đầu máy phải tải mô hình nghe về — mất từ vài chục giây tới 1–2 phút. Đừng nói gì trước khi thấy dòng thứ hai.

      

      

        
Nói thử một câu

        
Vào nhóm điều khiển, bấm micro nói — hoặc gõ chữ cũng được. Câu trả lời sẽ gắn thẳng vào tin nhắn của bạn. Vài lệnh nhanh gõ ngay trong nhóm: /ping (còn sống không) · /voice on|off · /reset (bắt đầu phiên mới) · /forget (xoá nhớ đệm) · /help.

      

      

        
Tạo lối tắt ngoài Desktop — nhớ dùng đường ổ C:

        
Lối tắt trỏ vào đường mạng dạng \\máy\thư-mục\… sẽ bị Windows chặn ngầm: bấm đúp không mở gì, cũng không báo lỗi, rất dễ tưởng hỏng file. Hãy trỏ vào đường nội bộ trong ổ C:.

      

    


    

      Chạy ngầm 24/7 — cân nhắc kỹ
      
Có thể đăng ký watchdog.mjs vào Scheduled Task để nó tự bật lại khi chết.

      
Cứ 3 phút kiểm một lần; điền LARK_WEBHOOK vào .env để mỗi lần khởi động lại nó báo về Lark cho bạn biết.

      
Nhưng hãy hiểu rõ: 24/7 cộng với chế độ toàn quyền ở mục 01 nghĩa là có một AI được chạy lệnh tự do trên máy bạn không ai giám sát, kể cả lúc bạn đang ngủ. Chỉ bật khi bạn thật sự cần và chấp nhận đánh đổi đó.

    


    

      Muốn thử mà không tốn tiền token: đặt DRY_RUN=true trong .env — hệ thống vẫn nhận tin, vẫn nghe, vẫn đọc trả lời, chỉ không gọi Claude thật. Dùng để dò luồng Lark và kiểm giọng nói.
    

  


  

    

      09
      
Bẫy thường gặp — soi đây trước khi hỏi ai

    


    

      

        
Hiện tượngNguyên nhân thật & cách sửa

        
          

            Nhắn/nói xong không thấy trả lời gì
            Ba khả năng, theo thứ tự hay gặp: (1) app chưa Publish phiên bản hoặc chưa bật event; (2) bot chưa được thêm vào nhóm; (3) sai mã nhóm / mã định danh trong .env. Nhìn cửa sổ đang chạy xem có dòng log nào không.
          

          

            whoami.mjs không in gì khi bạn nhắn
            Đúng nhóm nguyên nhân ở trên — app chưa Publish, chưa bật event, hoặc bot chưa vào nhóm. Quay lại mục 03.
          

          

            Bấm đúp start.ps1 → cửa sổ tắt phụt
            File .ps1 có ký tự tiếng Việt. PowerShell 5.1 đọc file .ps1 theo bảng mã cũ nên vỡ cú pháp. Bản trong gói đã thuần ASCII — nếu bạn tự sửa file thì giữ nguyên ASCII.
          

          

            Lối tắt Desktop bấm không lên
            Lối tắt trỏ vào đường mạng (\\…) — Windows chặn ngầm. Trỏ lại vào đường nội bộ ổ C:.
          

          

            Nói câu nào cũng bị báo nghe không rõ
            Máy có card NVIDIA nhưng thiếu 2 thư viện đi kèm — phần nghe nạp lên được nhưng chạy lỗi ngầm, không báo gì rõ ràng. Chạy lại install.ps1, hoặc cài thủ công nvidia-cublas-cu12 và nvidia-cudnn-cu12 vào môi trường Python của gói. Đây là sự cố tốn thời gian nhất.
          

          

            Nghe sai chữ nhiều
            Đang dùng mức nghe nhẹ, chưa chuẩn với tiếng Việt. Máy có card đồ hoạ thì nâng WHISPER_MODEL lên mức cao hơn trong .env.
          

          

            Trả lời bằng chữ thay vì giọng
            Phần đọc lỗi mạng tạm thời, hoặc thiếu ffmpeg — hệ thống tự rớt về chữ cho khỏi đứt mạch. Kiểm ffmpeg -version rồi thử lại.
          

          

            Nghe được nhưng không gửi được tiếng
            Gần như chắc chắn thiếu quyền im:resource. Bật thêm ở mục 03 rồi Publish lại.
          

          

            check-setup.mjs báo thiếu Python / thiếu gói
            Chưa chạy install.ps1, hoặc PYTHON_BIN trong .env trỏ sai chỗ. Chạy lại install.ps1.
          

          

            lark-cli báo lỗi đăng nhập
            Đăng nhập lại bằng đúng app của bạn. lark-cli profile list phải hiện active: true.
          

          

            TÔM tự nhắn tin khi bạn không hỏi
            Trong mã nguồn, chế độ chủ động nhắn mặc định là BẬT khi để trống. Muốn tắt phải ghi rõ CARE_MODE=false trong .env.