Chọn một cách cài: Homebrew hoặc .pkg. Cả hai cài cùng app đã ký vào ~/Library/Input Methods/VietTelex.app; không cài song song vì hai bộ quản lý sẽ cùng ghi/xoá một app. Khi đổi từ Homebrew sang .pkg, chạy brew uninstall --cask viettelex trước. Khi đổi từ .pkg sang Homebrew, chuyển sang ABC, thoát VietTelex, xoá app ở đường dẫn trên rồi mới chạy lệnh Homebrew.

1. Nếu chọn .pkg, tải VietTelex-x.y.z.pkg ở trang tải hoặc Releases (đã ký + notarized).
2. Double-click → làm theo hướng dẫn (tự cài vào thư mục user, đăng ký bộ gõ, mở sẵn System Settings → Keyboard).
3. Input Sources → Edit… / ＋ → Vietnamese → ViệtTelex → Add.

① Input Sources → Edit…	② ＋ → Vietnamese → ViệtTelex → Add

Để gõ trong Terminal, iTerm, Chrome/Edge/Brave: cấp quyền cho VietTelex trong Privacy & Security → Accessibility (macOS 26 trở về trước) / Device Control and Data Access (macOS 27). Chuyển Việt/Anh bằng phím 🌐 hoặc ⌃Space (macOS nhớ theo từng app).

Nếu chữ bị gạch chân, có thể VietTelex chưa được cấp quyền. Mở Cài đặt hệ thống (System Settings) → Quyền riêng tư & Bảo mật (Privacy & Security) → Trợ năng (Accessibility, macOS 26 trở về trước) / Điều khiển thiết bị và truy cập dữ liệu (Device Control and Data Access, macOS 27), rồi bật VietTelex. Lưu ý: mục "Trợ năng" ở thanh bên trên macOS 27 là cài đặt hỗ trợ nhìn/nghe, không phải chỗ cấp quyền. Nếu đã bật mà vẫn lỗi, hãy chọn VietTelex, bấm − để xoá rồi bấm + thêm lại (từ ~/Library/Input Methods). Có thể cần khởi động lại máy để quyền có hiệu lực.

Nếu đã bật quyền mà VietTelex vẫn báo thiếu, hãy kiểm tra bản đang chạy. Bản Debug trong Xcode có định danh riêng và không dùng quyền của bản cài trong ~/Library/Input Methods; thoát bản Debug rồi mở lại bản đã cài. Nếu bản đã cài vẫn báo thiếu, xoá mục VietTelex khỏi Accessibility rồi thêm lại ứng dụng trong ~/Library/Input Methods.

Hiếm gặp, thường do quyền còn "kẹt" với bản cài cũ. Cập nhật lên bản mới nhất trước (từ 1.8.32 VietTelex tự nhận quyền vừa bật, không cần khởi động lại). Nếu vẫn báo thiếu:

1. Trong Điều khiển thiết bị và truy cập dữ liệu (macOS 27) / Trợ năng (macOS 26 trở về trước), chọn VietTelex rồi bấm − để xoá hẳn (không chỉ tắt).
2. Mở Terminal, chạy:

   tccutil reset Accessibility com.viettelex.inputmethod.telex
   

3. Chuyển sang bộ gõ khác rồi chuyển lại VietTelex (hoặc đăng xuất/đăng nhập). Khi VietTelex hỏi quyền, bấm cho phép và bật lại.

Đăng xuất/đăng nhập lại một lần rồi thêm lại.

Menu bộ gõ → Cài đặt… → tab Ứng dụng → chọn ứng dụng vừa dùng hoặc nhập mã ứng dụng, rồi thử cách gõ phù hợp. Nếu chưa biết nên chọn gì, hãy để Tự động. Khi đã tìm được cách gõ đúng, báo lại trên GitHub để mọi người cùng dùng được.

Có, trên mọi nền tảng. Trên macOS: Cài đặt… → tab Gõ phím → chọn VNI.

VietTelex tự tắt trong secure field — đúng hành vi bảo mật, không phải lỗi.

Không riêng VietTelex: mọi bộ gõ bên thứ ba đều bị. 1Password giữ Secure Input của macOS sau khi ngủ (ô khoá vault vẫn “focus” dù bạn đang ở app khác) — macOS lúc đó vô hiệu mọi bộ gõ bên thứ ba.

Gỡ nhanh: bấm vào cửa sổ 1Password rồi bấm ra, hoặc Quit 1Password. Icon Vᵀ⃠ trên menu bar (khi đang bị chặn) sẽ chỉ đúng hướng đó. Bộ gõ có sẵn của Apple (Simple Telex) thường vẫn dùng được vì không bị disable theo lớp IME bên thứ ba.

Chi tiết: ghi chú kỹ thuật.

Bấm một dấu cách trước khi ấn Enter là đủ chữ. Hoặc dùng Chrome cho TikTok.

Lý do: ô comment của TikTok chỉ ghi nhận từ đang gõ khi có một phím thật đi sau nó — Enter thì không đủ. Bộ gõ đã thử sáu cách xử lý hộ và không cách nào giữ được từ cuối (chi tiết trong ghi chú kỹ thuật), nên đây là giới hạn đã biết chứ không phải lỗi chưa sửa.

Gỡ khỏi Input Sources chỉ tắt bộ gõ, chưa xoá app. Gỡ hẳn: xoá ~/Library/Input Methods/VietTelex.app (Finder → Go → Go to Folder…) rồi đăng xuất/đăng nhập. Muốn xoá luôn cài đặt cá nhân (gõ tắt, tuỳ chỉnh): xoá thêm ~/Library/Preferences/com.viettelex.settings.plist. Cài bằng Homebrew thì chỉ cần brew uninstall --cask viettelex.

Khi cả hai máy đều cài VietTelex, bộ gõ local và bộ gõ remote cùng sửa một chuỗi phím — dấu Backspace của tap đua với Telex bên kia, con trỏ nhảy loạn.

Cách đúng: để VietTelex bật trên máy đang bị điều khiển (máy remote). Máy đang ngồi gõ tự tắt IME trong phiên remote (cùng cách với Windows App / Screen Sharing). Tab remotedesktop.google.com được nhận ra theo URL; các app RDP native đã passthrough sẵn.

Muốn gõ tiếng Việt vào ô tên máy / PIN trên trang Chrome Remote Desktop: chuyển sang ABC, hoặc gõ không dấu.

Cần quyền Trợ năng (macOS 27: Điều khiển thiết bị và truy cập dữ liệu) để bộ gõ đọc được URL tab (Chrome vốn đã cần quyền này).

Lỗi của framework Qt (Flameshot, OBS, VLC… dùng): shortcut trong overlay bị nuốt khi có bất kỳ bộ gõ nào đang active — bộ gõ Simple Telex có sẵn của Apple cũng dính y hệt, không riêng VietTelex (chi tiết). Khắc phục: System Settings → Keyboard → bật "Automatically switch to a document's input source", rồi một lần chuyển sang ABC khi đang ở app đó — macOS sẽ tự nhớ, các app khác vẫn gõ tiếng Việt bình thường.