🖋 Hướng dẫn sử dụng Zen Content

Tài liệu này hướng dẫn cài đặt, cấu hình API, và sử dụng đầy đủ tính năng của Zen Content — công cụ viết bài chuẩn Semantic SEO, tự động nghiên cứu SERP thật, tạo ảnh minh hoạ, và đăng thẳng lên WordPress.

1. Cài đặt

Zen Content chạy được trên macOS, Windows và Linux. Tải bản mới nhất tại trang GitHub Release của dự án.

macOS

Tải file .dmg tương ứng: aarch64.dmg cho máy Apple Silicon (M1/M2/M3/M4...), x64.dmg cho máy Intel.
Mở file .dmg, kéo biểu tượng Zen Content vào thư mục Applications.
Mở app từ Launchpad. Nếu macOS báo "không xác định được nhà phát triển", vào System Settings → Privacy & Security, cuộn xuống và bấm Open Anyway.

Windows

Tải file x64-setup.exe (khuyến nghị) hoặc x64_en-US.msi.
Chạy file cài đặt và làm theo hướng dẫn trên màn hình.
Mở Zen Content từ Start Menu.

⚠ Windows chặn "Smart App Control blocked an app that may be unsafe" Do file cài đặt chưa có chứng chỉ ký số (code-signing certificate), Windows Smart App Control có thể chặn không cho chạy. Để cài được:

Mở Settings → Privacy & security → Windows Security → App & browser control → Smart App Control
Chuyển sang Off
Chạy lại file cài đặt

Lưu ý: trên nhiều bản Windows 11, sau khi tắt Smart App Control sẽ không bật lại được trừ khi cài lại Windows.

Linux

Debian/Ubuntu: tải file .deb, cài bằng sudo dpkg -i ten-file.deb
Fedora/RHEL: tải file .rpm, cài bằng sudo rpm -i ten-file.rpm
Chạy trực tiếp không cần cài: tải file .AppImage, cấp quyền thực thi (chmod +x) rồi chạy

2. Kích hoạt license

Mở app lần đầu, màn hình "🔒 Kích hoạt Zen Content" sẽ hiện ra.

Nhập license key theo định dạng SEOST-XXXXX-XXXXX-XXXXX-XXXXX
Bấm Kích hoạt

Mỗi license chỉ dùng được trên 1 máy License sẽ tự khoá vào máy đầu tiên kích hoạt nó. Nếu bạn cài lại máy hoặc đổi sang máy khác, liên hệ người quản lý license để gỡ khoá máy cũ trước khi kích hoạt trên máy mới.

App sẽ tự kiểm tra lại license mỗi 30 phút. Nếu tạm thời mất mạng, app vẫn dùng được bình thường trong thời gian ngắn (grace period) dựa trên lần kiểm tra gần nhất, không bị khoá đột ngột.

3. Cấu hình API Keys

Vào tab ⚙ Settings để nhập các API key. Mọi key được lưu trong OS Keychain (Keychain trên macOS, Credential Manager trên Windows) — không lưu dạng chữ thường trên đĩa.

Claude API Key Bắt buộc

Dùng cho toàn bộ pipeline viết bài khi chọn Claude làm nhà cung cấp AI (mặc định).

Lấy key tại console.anthropic.com/settings/keys, dán vào ô Claude API Key.

Serper API Key Bắt buộc

Dùng để lấy dữ liệu SERP (kết quả tìm kiếm Google thật), tìm ảnh minh hoạ, và kiểm chứng số liệu (fact-check).

Lấy key tại serper.dev, dán vào ô Serper API Key.

OpenAI API Key Tuỳ chọn

Chỉ cần nếu muốn tạo ảnh minh hoạ bằng GPT Image (xem mục Tạo ảnh minh hoạ bên dưới). Nếu bỏ trống, app vẫn dùng được, chỉ không tạo ảnh AI mà tìm ảnh qua Serper thay thế.

Lấy key tại platform.openai.com/api-keys.

Gemini API Key Tuỳ chọn

Chỉ cần nếu chọn Gemini làm nhà cung cấp AI thay cho Claude (mục kế tiếp).

Lấy key tại aistudio.google.com/apikey.

Chọn nhà cung cấp AI

Trong mục "Nhà cung cấp AI", chọn 1 trong 2:

Nhà cung cấp	Ghi chú
Claude (Anthropic)	Mặc định, đã test kỹ nhất cho toàn bộ pipeline
Gemini (Google)	Thay thế Claude cho toàn bộ pipeline — cần nhập Gemini API Key ở trên trước

Thị trường & ngôn ngữ viết bài

Mục "Ngôn ngữ & Thị trường viết bài" quyết định dữ liệu SERP (Google) lấy theo quốc gia/ngôn ngữ nào — đổi mục này khi viết bài tiếng Anh, Nhật, Thái... thay vì tiếng Việt.

Thị trường	Mã (gl / hl)
Việt Nam (Tiếng Việt)	vn / vi
Mỹ (English)	us / en
Anh (English)	gb / en
Nhật Bản (日本語)	jp / ja
Thái Lan (ไทย)	th / th
Singapore (English)	sg / en

Chọn preset có sẵn trong dropdown, hoặc nhập tay mã quốc gia/ngôn ngữ khác nếu thị trường bạn cần không có trong danh sách.

Model & hiệu năng

Model Claude: Sonnet 5 / Opus 4.8 / Haiku 4.5 — Opus chất lượng cao nhất nhưng chậm và đắt hơn, Haiku nhanh/rẻ nhất.
Model Gemini: 2.5 Pro / 2.5 Flash / 2.5 Flash Lite — tương tự, đánh đổi giữa chất lượng và tốc độ/chi phí.
Max tokens mỗi lượt gọi: giới hạn độ dài phản hồi AI mỗi lần gọi API (4.000–64.000).
Số keyword chạy song song: 1 / 5 / 10 — chạy nhiều keyword cùng lúc nhanh hơn nhưng tốn API quota nhanh hơn.
Extended Thinking (chỉ Claude, không hỗ trợ Haiku): bật để AI suy luận kỹ hơn trước khi trả lời, tăng chất lượng nhưng chậm hơn.

4. Kết nối site WordPress

Vào tab 🌐 Sites để thêm site WordPress — cần thiết nếu muốn đăng bài tự động và dùng Topical Map theo site.

Trên WordPress, vào Users → Profile → Application Passwords, tạo 1 Application Password mới (không dùng mật khẩu đăng nhập chính).
Trong Zen Content, điền: Tên site (tự đặt để nhận diện), URL site (https://example.com), Username WordPress, và Application Password vừa tạo.
Nếu site có WooCommerce và muốn đăng được sản phẩm kèm giá, bật "Site có WooCommerce", điền thêm Consumer Key/Secret (lấy tại WooCommerce → Settings → Advanced → REST API).
Bấm + Thêm site.

Chạm vào 1 site trong danh sách để chọn làm "site đang hoạt động" — site này sẽ được dùng cho Topical Map, đăng bài, và liên kết nội bộ (internal linking) tự động.

Tên/URL/username lưu trong database local trên máy bạn, mọi mật khẩu/key lưu riêng trong OS Keychain — không đi qua server nào khác.

5. Topical Map (Bản đồ chủ đề)

Đây là bước nên làm trước khi viết bài hàng loạt cho 1 site — AI sẽ phân cụm danh sách từ khoá thành chủ đề trung tâm → trụ cột → vệ tinh, giúp bài viết sau này bám đúng cấu trúc topical authority thay vì viết rời rạc.

Vào tab 🗺 Topical Map, chọn site áp dụng (hoặc để trống nếu chưa gắn site cụ thể).
Dán danh sách từ khoá/chủ đề của site, mỗi dòng 1 từ khoá (tối thiểu 2 từ khoá).
Bấm ▶ Tạo Topical Map.

Sau khi có bản đồ, mỗi cụm hiển thị chủ đề trụ cột và các từ khoá vệ tinh. Bấm ▶ Viết ngay cạnh 1 từ khoá để đưa nó sang tab Chạy và viết luôn. Từ khoá đã có bài viết sẽ hiện nhãn ✓ Đã viết.

Khi viết bài ở tab Chạy với cùng site đang chọn ở Topical Map, nếu từ khoá khớp với 1 mục trong bản đồ, ngữ cảnh trụ cột/vệ tinh sẽ tự động được thêm vào prompt tạo tiêu đề + dàn ý, không cần làm gì thêm.

6. Viết bài (tab Chạy)

Vào tab ▶ Chạy, dán danh sách từ khoá vào ô Keywords, mỗi dòng 1 từ khoá.
(Tuỳ chọn) Bật "Dùng tiêu đề riêng cho từng keyword" nếu muốn tự đặt tiêu đề thay vì để AI tự tạo — dán danh sách tiêu đề tương ứng theo đúng thứ tự từ khoá.
(Tuỳ chọn) Thêm Dữ liệu Training — xem mục bên dưới.
Bấm ▶ Chạy Quy trình.

Dữ liệu Training

Giúp AI dùng đúng số liệu/thông tin bạn cung cấp thay vì kiến thức cũ có thể lỗi thời. Có 3 cách thêm nguồn:

Kéo thả file .txt vào khung, hoặc bấm để chọn file.
Dán URL trang tham khảo — app tự tải nội dung trang đó về làm nguồn.
Dán trực tiếp văn bản vào ô bên dưới.

Dữ liệu Training chỉ lưu tạm trong phiên làm việc hiện tại — tắt app là mất, cần thêm lại lần sau nếu muốn dùng tiếp cho lần chạy khác.

Chạy / Tạm dừng / Dừng

Khi đang chạy, có 2 nút điều khiển:

⏸ Tạm dừng / ▶️ Tiếp tục: pipeline dừng lại ở điểm kiểm tra gần nhất (không huỷ ngang lượt gọi API đang chạy dở), bấm Tiếp tục để chạy tiếp.
⏹ Dừng: huỷ hẳn — từ khoá đang chạy dở và các từ khoá chưa tới lượt sẽ chuyển trạng thái "Đã dừng".

Mỗi từ khoá chạy độc lập — nếu 1 từ khoá lỗi (vd hết quota API), các từ khoá còn lại vẫn tiếp tục chạy bình thường.

Sau khi hoàn tất, mỗi kết quả hiện trong 1 thẻ riêng gồm: tiêu đề, nội dung bài viết, kết quả tự phê bình/tự sửa (self-critique), nút chấm điểm nội dung, và nút đăng lên WordPress.

7. Tạo ảnh minh hoạ

Vào tab 🖼 Ảnh để cấu hình cách tạo ảnh minh hoạ cho bài viết.

Chế độ tạo ảnh

Chế độ	Mô tả
GPT Image trước, Serper dự phòng	Ưu tiên chất lượng, tự chuyển sang tìm ảnh Serper nếu GPT Image lỗi
Chỉ dùng GPT Image	Không tìm ảnh Serper dự phòng khi GPT thất bại
Chỉ tìm ảnh Serper	Không tốn phí tạo ảnh AI, chỉ lấy ảnh có sẵn trên web

Model GPT Image: chọn giữa gpt-image-2, gpt-image-1.5, gpt-image-1, gpt-image-1-mini.

Số lượng ảnh mỗi bài: 3 ảnh ngẫu nhiên / tất cả H3 (nội dung chính) / tất cả H2+H3.

Ảnh thương hiệu tham chiếu

Kéo thả hoặc chọn ảnh (jpg/png/webp) làm mẫu — GPT Image sẽ tham khảo phong cách/màu sắc/logo từ các ảnh này khi tạo ảnh mới cho bài viết (dùng chế độ "edits" thay vì tạo mới hoàn toàn).

8. Đăng bài lên WordPress

Ở mỗi kết quả bài viết (tab Chạy hoặc Lịch sử), cuộn xuống phần đăng bài:

Chọn site đích trong dropdown.
Chọn loại: Bài viết hoặc Sản phẩm (chỉ hiện nếu site đã cấu hình WooCommerce).
Chọn trạng thái đăng: Công khai / Chờ duyệt / Nháp.
Chọn chuyên mục (nếu có).
Nếu đăng sản phẩm: nhập thêm giá bán (bắt buộc), giá khuyến mãi và SKU (tuỳ chọn).
Bấm 📤 Đăng bài/sản phẩm lên "Tên site".

Sau khi đăng thành công, có nút 🔗 Xem bài viết để mở link ngay. Nếu bài ở trạng thái Nháp/Chờ duyệt, link xem trước cần đăng nhập WordPress mới truy cập được.

Tự động tối ưu dung lượng Sau khi đăng thành công, ảnh minh hoạ (vốn lưu tạm dạng dữ liệu nặng trong lúc soạn bài) sẽ tự động được thay bằng link ảnh thật trên WordPress trong bản lưu cục bộ — giúp lịch sử bài viết trên máy bạn không bị phình dung lượng.

9. Chấm điểm nội dung so với đối thủ

Ở mỗi bài viết, bấm 📊 Chấm điểm nội dung vs đối thủ để:

App tìm top kết quả Google thật cho từ khoá đó.
Crawl nội dung đầy đủ của các đối thủ (không chỉ đoạn snippet).
AI phân tích và chấm điểm coverage nội dung của bài bạn so với đối thủ.

Kết quả gồm: điểm số /100, danh sách chủ đề đã bao phủ tốt, chủ đề còn thiếu (kèm số đối thủ đã đề cập), và gợi ý cải thiện cụ thể.

10. Lịch sử bài viết

Cuối tab Chạy có mục "Lịch sử bài viết đã lưu" — lưu mọi bài đã viết, kể cả sau khi đóng app.

Bấm vào 1 bài để xem nội dung, chấm điểm, hoặc đăng lên WordPress lại.
Bấm ☑ Chọn nhiều để xoá để bật chế độ chọn hàng loạt, tick chọn các bài cần xoá, bấm nút xoá 2 lần để xác nhận (tự huỷ xác nhận sau 3 giây nếu không bấm lần 2 kịp).

11. Câu hỏi thường gặp

Vì sao nút "Chạy Quy trình" bị mờ, không bấm được?

Cần đủ 3 điều kiện: (1) đã nhập ít nhất 1 từ khoá, (2) đã nhập API Key của nhà cung cấp AI đang chọn (Claude hoặc Gemini), (3) đã nhập Serper API Key. App sẽ hiện cảnh báo màu vàng cho biết đang thiếu điều kiện nào.

License báo "đã kích hoạt trên máy khác"?

Mỗi license chỉ dùng được trên 1 máy — máy đầu tiên kích hoạt sẽ giữ license đó. Liên hệ hỗ trợ để được gỡ khoá máy cũ nếu bạn cần chuyển sang máy mới.

Windows chặn không cho cài đặt?

Xem hướng dẫn tắt Smart App Control ở mục Cài đặt trên Windows.

Mất mạng khi đang dùng app có bị khoá ngay không?

Không. App có "grace period" — nếu không kết nối được server kiểm tra license, app vẫn cho dùng tạm dựa trên lần kiểm tra hợp lệ gần nhất, chỉ khoá khi server phản hồi rõ ràng là license không hợp lệ/hết hạn.

Dữ liệu bài viết, site, API key của tôi lưu ở đâu?

Toàn bộ lưu cục bộ trên máy bạn: nội dung bài viết + danh sách site trong database SQLite local, mọi API key/mật khẩu trong OS Keychain (Keychain macOS / Credential Manager Windows). App chỉ gửi dữ liệu ra ngoài khi gọi API của Claude/Gemini/Serper/OpenAI/WordPress mà bạn đã cấu hình — không có server trung gian nào lưu lại nội dung bài viết của bạn.

12. Liên hệ hỗ trợ

Gặp vấn đề khi cài đặt, cấu hình, hoặc cần gia hạn/gỡ khoá license — liên hệ qua Telegram:

💬 @thichlamseo