Hướng dẫn CG Claude: Kiểm tra, cấu hình và khôi phục an toàn môi trường Claude Code cục bộ

CG Claude là gì

CG Claude là một bảng điều khiển cấu hình và kiểm tra dành cho môi trường Claude Code cục bộ, cung cấp phiên bản máy tính Electron và phiên bản trình duyệt cục bộ. Công cụ có thể kiểm tra hệ thống, terminal, trình duyệt, proxy, TLS, cấu hình Claude và các mục ghi đè của dự án, đồng thời hỗ trợ sửa cấu hình thông qua cơ chế xem trước, sao lưu và ảnh chụp nhanh.

Công cụ bao gồm 31 mục kiểm tra môi trường và mặc định kiểm tra liên tiếp ba lần. Công cụ không suy đoán trạng thái tài khoản dựa trên kết quả môi trường; phiên tài khoản, khu vực dịch vụ, hạn mức, thanh toán, quyền riêng tư trên web và một số trạng thái mạng vẫn cần được kiểm tra thủ công.

Tính năng chính

• Kiểm tra múi giờ hệ thống và trình duyệt, TZ của terminal, proxy, DNS, IPv6, TLS, nguồn xác thực và thư mục cấu hình Claude.
• Thực hiện cấu hình qua 13 nút quy trình; mỗi nút sẽ thử lại tối đa ba lần sau lần thất bại đầu tiên, sau đó bỏ qua và tiếp tục các nút tiếp theo.
• Hiển thị bản xem trước trước khi sửa đổi và tạo bản sao lưu trước khi ghi; nút cấu hình đầu tiên cũng lưu ảnh chụp nhanh đầy đủ của cấu hình.
• Quét quyền, Hooks, MCP, proxy, TLS, khai báo thông tin xác thực và tệp khóa phụ thuộc trong dự án.
• Chỉnh sửa thiết lập kết nối cục bộ của Claude, bao gồm proxy, gateway, NO_PROXY và đường dẫn CA bổ sung.
• Lưu và khôi phục nội dung tệp, quyền, trạng thái tệp không tồn tại, tùy chọn kiểm tra cùng múi giờ và TZ đã ghi nhận.
• Cấu hình Chat Completions tương thích OpenAI hoặc Anthropic Messages, dùng các ví dụ cố định để kiểm tra dịch hai chiều Trung-Anh.
• Cung cấp giao diện tiếng Trung và tiếng Anh, giao diện sáng／bảo vệ mắt／tối, giảm chuyển động và kiểm tra phiên bản thủ công.

CG Claude chỉ phân tích tĩnh các tệp cấu hình được hỗ trợ, không thực thi script khởi động, script dự án, Hooks, MCP hoặc cài đặt phụ thuộc, đồng thời không tự động dọn dẹp keychain, phiên Claude, Skills hay Hooks.

Cài đặt phiên bản máy tính

Người dùng thông thường nên ưu tiên gói cài đặt máy tính. Gói cài đặt phiên bản 1.2.7 nằm trong tệp đính kèm Release tại release/1.2.7/; sau khi cài đặt không cần cài thêm Node.js.

• macOS Apple Silicon:CG-Claude-1.2.7-macos-arm64.dmg
• macOS Intel:CG-Claude-1.2.7-macos-x64.dmg
• Windows x64:CG-Claude-1.2.7-windows-x64-setup.exe
• Linux x64:CG-Claude-1.2.7-linux-x86_64.AppImage hoặc CG-Claude-1.2.7-linux-amd64.deb

Sau khi tải xuống, có thể dùng SHA256SUMS.txt để kiểm tra tính toàn vẹn của tệp. Lưu ý rằng bản dựng macOS chưa được ký hoặc công chứng; tương tác trên máy thật với phiên bản máy tính Windows và Linux chưa được xác minh.

Khi cửa sổ máy tính bị đóng hoặc thu nhỏ, cửa sổ thường được ẩn vào thanh menu hoặc khay hệ thống và tác vụ vẫn tiếp tục chạy. Để thực sự kết thúc dịch vụ, hãy chọn “Thoát CG Claude” từ menu khay hệ thống; chương trình sẽ chờ giao dịch kiểm tra, cấu hình hoặc khôi phục hoàn tất rồi mới giải phóng khóa dịch vụ.

Phiên bản máy tính và dịch vụ trình duyệt không thể đồng thời sử dụng cùng một thư mục bản ghi. Trước khi khởi động một phiên bản, hãy thoát phiên bản còn lại để tránh ghi đồng thời.

Khởi động từ mã nguồn

Chuẩn bị môi trường

Chạy mã nguồn yêu cầu Node.js 22.12 trở lên. Sau khi vào thư mục dự án, cài đặt các phụ thuộc đã khóa phiên bản và khởi động Electron:

npm ci
npm run desktop

Trên macOS cũng có thể nhấp đúp vào 启动工具.command; trên Windows có thể nhấp đúp vào 启动工具.cmd. Người dùng Linux nên chạy npm run desktop trong thư mục dự án.

Script chuẩn bị sẽ tải Electron theo phiên bản đã khóa và dùng lại tệp nhị phân đã cài đặt. Quá trình tải sử dụng môi trường proxy HTTP／HTTPS hiện có nhưng không thay đổi cấu hình proxy của người dùng.

Khởi động phiên bản trình duyệt

npm run build
npm start

Sau khi khởi động, truy cập http://127.0.0.1:4318. Dịch vụ chỉ lắng nghe địa chỉ loopback và có thể thoát bằng Ctrl+C. Trên Linux cũng có thể chạy:

./scripts/start.sh

Kiểm tra lần đầu: thiết lập đường cơ sở môi trường

1. Thiết lập tùy chọn kiểm tra. Chọn chế độ mạng thực tế, phương thức dịch vụ, mục tiêu múi giờ và tùy chọn quyền riêng tư. Múi giờ mặc định được đề xuất kiểm tra theo Đài Bắc, cũng có thể đổi thành lối ra hiện tại hoặc chỉ định thủ công.
2. Xác nhận kiểm tra mạng tùy chọn. Theo mặc định, kiểm tra chủ yếu đọc cấu hình cục bộ. Nếu muốn truy vấn lối ra công khai hoặc thu thập dữ liệu WebRTC, cần đánh dấu thêm; các dịch vụ bên ngoài liên quan sẽ thấy IP kết nối.
3. Bắt đầu kiểm tra. Nhấp “Bắt đầu kiểm tra”; công cụ mặc định thực hiện liên tiếp ba lượt kiểm tra để giảm kết luận sai do trạng thái nhất thời.
4. Lọc theo trạng thái. Sử dụng các mục “Kiểm tra đạt”, “Cần chú ý” hoặc “Chờ xác nhận” ở đầu trang. Mục này sẽ xóa tìm kiếm và điều kiện phân loại cũ, đồng thời mở rộng và định vị đến kết quả đầu tiên.
5. Xem bằng chứng và giới hạn. Kết quả được chia thành đạt, cần chú ý, cần xử lý, chờ xác nhận và chưa kiểm tra. Với các mục như tài khoản, khu vực, thanh toán, quyền riêng tư trên web, múi giờ điện thoại hoặc dịch vụ định vị, hãy xác nhận thủ công theo hướng dẫn.

31 mục kiểm tra bao phủ múi giờ hệ thống và trình duyệt, TZ, proxy hệ thống, giao diện ảo, DNS, IPv6, proxy của tiến trình và tệp khởi động, proxy npm và Git, địa chỉ API, thư mục cấu hình Claude, quyền riêng tư, CLI, TLS, khả năng tương thích proxy, nguồn xác thực, CA／mTLS tùy chỉnh, cùng lối ra công khai và tính nhất quán của trình duyệt nếu được bật.

Thực hiện cấu hình một lần nhấp

Sau khi kiểm tra xong, không nên ghi ngay một cách máy móc. Trước tiên hãy đọc bản xem trước thay đổi, xác nhận giá trị đích, tệp bị ảnh hưởng và các thao tác cần quyền hệ thống.

1. Nhấp “Cấu hình một lần nhấp”, lần lượt điền chế độ mạng, phương thức dịch vụ và tùy chọn quyền riêng tư. Tùy chọn dọn dẹp địa chỉ API tùy chỉnh không được đánh dấu mặc định.
2. Kiểm tra hai nút múi giờ hệ thống và TZ của terminal được đánh dấu mặc định; có thể bỏ chọn nếu không muốn sửa đổi.
3. Đọc bản xem trước ghi, xác nhận các trường, tệp và quyền sắp được sửa đổi.
4. Bắt đầu cấu hình. Công cụ thực hiện theo thứ tự 13 nút, lưu bản sao lưu trước mỗi lần ghi và lưu ảnh chụp nhanh đầy đủ ở nút đầu tiên.
5. Sau khi cấu hình kết thúc, mở trang cài đặt, sao chép lệnh hoặc khởi động terminal theo các mục còn lại được hiển thị tập trung để hoàn tất những bước không thể tự động xử lý.
6. Mở lại terminal và ứng dụng Claude rồi kiểm tra lại ba lượt. Terminal đã mở sẽ không tự động làm mới biến môi trường khi tệp thay đổi.

Công cụ có thể xử lý proxy người dùng của shell, npm và Git, địa chỉ API tùy chỉnh của shell và Claude, biến quyền riêng tư của Claude và xác thực TLS của npm; đồng thời có thể cấu hình múi giờ hệ thống và TZ của terminal trong quy trình một lần nhấp.

Các vị trí cấu hình được hỗ trợ gồm:

• .zshrc、.zprofile、.zshenv
• .bashrc、.bash_profile、.bash_login、.profile
• .npmrc、.gitconfig、.config/git/config
• .claude/settings.json

Trên macOS, việc sửa múi giờ hệ thống cần quyền quản trị; Windows sử dụng UAC; Linux phụ thuộc vào proxy polkit khả dụng. Nếu tính năng múi giờ tự động của macOS đang bật và có thể đọc được trạng thái, cấu hình một lần nhấp sẽ thử tắt tính năng này sau khi được cấp quyền rồi đọc lại kết quả.

Chỉnh sửa kết nối cục bộ của Claude

Mở “Cấu hình cục bộ” ở cuối thanh điều hướng để lần lượt chọn giữ nguyên, thiết lập hoặc xóa các tham số kết nối. Tính năng này chỉ ghi các trường sau trong ~/.claude/settings.json:

• HTTPS_PROXY
• HTTP_PROXY
• NO_PROXY
• ANTHROPIC_BASE_URL
• NODE_EXTRA_CA_CERTS

Bản xem trước sẽ được hiển thị trước khi lưu, đồng thời ghi lại ảnh chụp nhanh đầy đủ trước sửa đổi và bản sao lưu tệp gốc. Các trường khác, Hooks, quyền và thông tin xác thực được giữ nguyên; JSON cuối cùng được định dạng với thụt lề hai khoảng trắng. Việc chuẩn hóa các mục proxy chữ thường cùng tên cũng sẽ được hiển thị trong bản xem trước.

Tệp CA bổ sung phải là đường dẫn tuyệt đối cục bộ, có thể đọc và không rỗng. Công cụ không đọc nội dung chứng chỉ và không thực hiện yêu cầu kết nối để kiểm tra. Nếu phát hiện CLAUDE_CONFIG_DIR tùy chỉnh, mục chỉnh sửa kết nối sẽ bị vô hiệu hóa để tránh ghi nhầm thư mục.

Quét cấu hình dự án

Mở “Quét dự án” và chọn thư mục dự án cục bộ. Phạm vi quét bao gồm cấu hình ghi đè, quyền, sandbox lệnh, Hooks, MCP, proxy, TLS, khai báo thông tin xác thực, tệp khóa phụ thuộc và commit Git cục bộ.

Quét dự án chỉ đọc các tệp cấu hình và siêu dữ liệu cố định, không thực thi script dự án, Hooks, MCP hoặc cài đặt phụ thuộc. Với tệp dotenv, công cụ chỉ kiểm tra sự tồn tại mà không đọc nội dung; các trường thông tin xác thực chỉ đưa ra cảnh báo, không hiển thị giá trị.

Quét dự án không thể thay thế việc kiểm tra lỗ hổng mã nguồn, lỗ hổng phụ thuộc hoặc tính chính xác của bản dựng. Những vấn đề này vẫn cần được xử lý bằng các công cụ bảo mật, phụ thuộc và bản dựng tương ứng.

Sao lưu và khôi phục ảnh chụp nhanh đầy đủ

Trong “Khôi phục sao lưu”, chọn ảnh chụp nhanh đầy đủ có sẵn rồi nhấp “Khôi phục ảnh chụp nhanh cấu hình trước đó”. Phạm vi khôi phục có thể bao gồm nội dung tệp, quyền ban đầu, trạng thái tệp vốn không tồn tại, tùy chọn kiểm tra cùng múi giờ hệ thống và TZ đã ghi nhận.

1. Chọn ảnh chụp nhanh đích và xem bản xem trước khôi phục.
2. Xác nhận nội dung tệp, quyền và trạng thái múi giờ vẫn nhất quán với đường cơ sở trong bản xem trước.
3. Thực hiện khôi phục. Công cụ sẽ lưu thêm trạng thái hiện tại trước, sau đó khôi phục ảnh chụp nhanh đích.
4. Mở lại terminal và ứng dụng khách, xác minh biến môi trường và cấu hình Claude.

Nếu nội dung tệp, quyền hoặc múi giờ thay đổi sau khi xem trước, thao tác khôi phục sẽ bị chặn để tránh ghi đè thay đổi mới. Ảnh chụp nhanh chỉ bao phủ mười một vị trí cấu hình người dùng được hỗ trợ, tùy chọn kiểm tra cùng múi giờ và TZ có thể đọc được; không bao gồm cấu hình dịch, toàn bộ thư mục ~/.claude, keychain hoặc các phiên lịch sử.

Cấu hình dịch hai chiều

Trong “Dịch hai chiều” ở bên trái, có thể thiết lập giao thức, địa chỉ API, tên mô hình, khóa và thời gian chờ. Hỗ trợ Chat Completions tương thích OpenAI và Anthropic Messages.

Sau khi nhấp “Kiểm tra dịch hai chiều”, công cụ sẽ thực sự gửi hai ví dụ cố định và lần lượt hiển thị kết quả Trung-Anh và Anh-Trung. Bài kiểm tra không đọc nội dung dự án hoặc phiên Claude, đồng thời không tự động thử lại các yêu cầu có thể phát sinh phí.

Khóa được mã hóa bằng AES-256-GCM; khóa chính được lưu trong thư mục bản ghi riêng tư cục bộ. Tuy nhiên, đây không phải keychain hệ thống, nên người có quyền đọc thư mục đó vẫn có thể giải mã. Khóa đã lưu sẽ không được trả về giao diện; sau khi thay đổi địa chỉ dịch vụ hoặc giao thức, cần nhập lại khóa.

Việc kiểm tra mô hình dịch thành công không có nghĩa là terminal gốc của Claude Code đã được kết nối và cũng không tự động bật chặn phiên.

Sử dụng chế độ trình diễn cô lập và CLI

Trước khi sửa cấu hình thực, có thể sử dụng chế độ trình diễn cô lập:

npm run demo
npm run desktop:demo

demo sử dụng thư mục cấu hình tạm thời chuyên dụng và cổng 4319; desktop:demo sử dụng thư mục dữ liệu Electron độc lập. Việc ghi trong chế độ trình diễn chỉ tác động đến thư mục kiểm tra; múi giờ hệ thống và TZ sử dụng mô phỏng cô lập, nhưng thông tin nền tảng và phiên bản ứng dụng khách vẫn được đọc từ máy cục bộ.

Khi cần tự động đọc kết quả kiểm tra, có thể sử dụng CLI:

npm run doctor -- --json

CLI mặc định chỉ kiểm tra và không sửa đổi cấu hình. Để bật truy vấn mạng công khai của terminal, thêm --network:

npm run doctor -- --json --network

Biến chạy thường dùng

• CG_PORT: cổng dịch vụ trình duyệt, mặc định là 4318; Electron sử dụng cổng loopback ngẫu nhiên.
• CG_HOME: thư mục gốc cấu hình người dùng, mặc định là thư mục chính của người dùng hiện tại, có thể dùng để kiểm tra cô lập.
• CG_DATA_DIR: thư mục bản ghi, mặc định nằm trong .claude-guard dưới thư mục gốc cấu hình.
• CG_DEMO=1: đánh dấu chế độ cô lập, đồng thời nên chỉ định thư mục gốc cấu hình độc lập.

Đề xuất sử dụng nâng cao

Tránh sử dụng bản xem trước đã lỗi thời

Nếu báo cáo lịch sử, tùy chọn kiểm tra hoặc đường cơ sở cấu hình đã thay đổi, hãy kiểm tra lại trước khi xem trước thao tác khắc phục. Báo cáo cũ vẫn có thể đọc, nhưng không nên直接 dùng làm căn cứ ghi mới. Công cụ cũng sẽ kiểm tra quyền tệp và trạng thái đọc, đồng thời từ chối tiếp tục sử dụng bản xem trước đã thay đổi.

Xử lý đúng các tệp cấu hình phức tạp

Tệp khởi động chỉ phân tích tĩnh các phép gán trực tiếp. Các hàm phức tạp, khối điều kiện, biểu thức nhiều dòng và heredoc sẽ không được tự động chỉnh sửa. Văn bản cấu hình phải là UTF-8 nghiêm ngặt; các tệp chứa UTF-8 không hợp lệ hoặc NUL sẽ bị loại khỏi ảnh chụp nhanh và được yêu cầu kiểm tra thủ công, thay vì phỏng đoán các bảng mã như GBK.

Hiểu ranh giới quyền riêng tư khi kiểm tra mạng công cộng

Việc kiểm tra mạng công cộng có thể truy cập https://ipinfo.io/json, https://api.ipify.org?format=json và stun:stun.l.google.com:19302. Các dịch vụ này sẽ thấy IP kết nối, nhưng không nhận cấu hình hoặc khóa của máy cục bộ. Khi xuất báo cáo, IP và tên máy chủ cũng sẽ được ẩn thêm theo mặc định.

Phân biệt ngôn ngữ trình duyệt với cấu hình múi giờ

Ngôn ngữ đích của trình duyệt mặc định là en-US; en-CN cũng là tiếng Anh nhưng khác khu vực. Việc kiểm tra này là mục mở rộng của dự án, không phải yêu cầu bắt buộc của tài liệu gốc. Cấu hình múi giờ bằng một cú nhấp không thay đổi ngôn ngữ trình duyệt bên ngoài; cần làm theo hướng dẫn Chrome, Edge, Firefox hoặc Safari trên trang để thiết lập thủ công.

Bảo vệ bản ghi cục bộ

Thư mục bản ghi mặc định là ~/.claude-guard/, nơi lưu tùy chọn kiểm tra, 30 báo cáo gần nhất, bản sao lưu, ảnh chụp nhanh, các lần rà soát thủ công và trạng thái quy trình. Bản sao lưu hoặc ảnh chụp nhanh có thể chứa thông tin xác thực ở dạng nguyên bản, vì vậy không nên tùy ý sao chép hoặc gửi thư mục này.

Trên hệ thống POSIX, quyền của thư mục bản ghi là 0700 và tệp bản ghi là 0600; Windows kế thừa ACL của thư mục người dùng. Tệp cấu hình mới sử dụng quyền 0600 trên POSIX, đồng thời cố gắng giữ nguyên quyền của cấu hình ban đầu.

Phát triển và đóng gói

Chế độ phát triển sử dụng cổng frontend 5173 và cổng backend 4318:

npm run dev

Trước khi gửi thay đổi, có thể chạy kiểm tra đầy đủ và xác minh định dạng:

npm run check
npm run format:check

Tạo thư mục ứng dụng hoặc gói cài đặt cho nền tảng hiện tại:

npm run pack
npm run dist

pack tạo thư mục ứng dụng; dist tạo dmg／zip cho macOS, NSIS／portable cho Windows hoặc AppImage／deb cho Linux tùy theo hệ thống hiện tại, đồng thời sử dụng runtime Electron tương ứng với hệ điều hành và kiến trúc CPU hiện tại.

Lời kết

CG Claude tập trung việc kiểm tra môi trường, xem trước cấu hình, sửa trường, quét dự án và khôi phục ảnh chụp nhanh vào một bàn làm việc cục bộ. Khuyến nghị làm quen với quy trình trong chế độ demo trước, sau đó thiết lập đường cơ sở cho môi trường thực; kiểm tra bản xem trước trước mỗi lần ghi, rồi mở lại terminal và kiểm tra liên tục sau khi hoàn tất. Đối với các mục như tài khoản, khu vực, thanh toán, múi giờ điện thoại và quyền riêng tư trình duyệt mà hệ thống không thể tự động phán đoán đáng tin cậy, nên giữ lại bước rà soát thủ công.

Nếu cần xem plugin cấu hình môi trường trình duyệt, hãy truy cập dự án LC-time.