Khắc Phục Sự Cố

Sửa nhanh các vấn đề phổ biến. Hầu hết các vấn đề giải quyết trong vòng dưới 5 phút.

Quick Diagnosis

Loại vấn đề?

• Cài đặt thất bại → Vấn Đề Cài Đặt
• Lệnh không tìm thấy hoặc lỗi → Lỗi Lệnh
• Agent không hoạt động → Vấn Đề Agent
• Lỗi API key → Thiết Lập API Key
• Chậm hoặc treo → Vấn Đề Hiệu Suất

Installation

Vấn đề: ck: command not found

Sửa:

# Xác minh cài đặt
npm list -g claudekit-cli

# Cài đặt lại nếu cần
npm install -g claudekit-cli

# Xác minh
ck --version

Xem thêm cách sửa cài đặt →

Commands

Vấn đề: /command không hoạt động

Sửa:

1. Kiểm tra .claude/commands/ tồn tại
2. Xác minh file lệnh tồn tại
3. Kiểm tra frontmatter hợp lệ

# Liệt kê các lệnh có sẵn
ls .claude/commands/**/*.md

# Kiểm tra lệnh cụ thể
cat .claude/commands/core/cook.md

Xem thêm cách sửa lệnh →

Agents

Vấn đề: Agent không kích hoạt

Sửa:

1. Xác minh .claude/agents/ tồn tại
2. Kiểm tra định dạng file agent
3. Xác nhận Claude Code đang chạy

# Liệt kê agents
ls .claude/agents/*.md

# Xác minh file agent
cat .claude/agents/planner.md

Xem thêm cách sửa agent →

API Keys

Vấn đề: “API key not found”

Sửa:

# Thêm vào .env
echo 'GEMINI_API_KEY=your-key' >> .env
echo 'SEARCH_API_KEY=your-key' >> .env

# Hoặc export cho session
export GEMINI_API_KEY=your-key

Hướng dẫn API key đầy đủ →

Performance

Vấn đề: Lệnh mất quá lâu

Sửa:

1. Kiểm tra kết nối internet
2. Xác minh API keys đã được thiết lập
3. Sử dụng --verbose để xem gì chậm

# Chạy với verbose logging
/cook add feature --verbose

Xem thêm cách sửa hiệu suất →

Common Quick Fixes

Reset ClaudeKit

# Backup trước
cp -r .claude .claude.backup

# Cập nhật lên phiên bản mới nhất
ck init --kit engineer

# Khôi phục files tùy chỉnh
cp .claude.backup/commands/my-custom.md .claude/commands/

Clear Cache

# Xóa Node modules
rm -rf node_modules
npm install

# Xóa ClaudeKit cache
rm -rf ~/.claudekit/cache

Verify Setup

# Kiểm tra CLI
ck --version

# Kiểm tra Claude Code
claude --version

# Kiểm tra cấu trúc thư mục
tree .claude -L 2

Still Stuck?

Get Help

1. Chạy diagnostics:

   ck diagnose --verbose

2. Kiểm tra logs:

   # Bật verbose mode
   export CLAUDEKIT_VERBOSE=1
   
   # Chạy lệnh
   /cook add feature
   
   # Kiểm tra output
   cat claudekit-debug.log

3. Báo cáo vấn đề:

   • GitHub: https://github.com/claudekit/claudekit-engineer/issues
   • Bao gồm: OS, CLI version, error message, steps to reproduce

Community

• Discord: Tham gia ClaudeKit Discord
• GitHub Discussions: Chia sẻ giải pháp, đặt câu hỏi

Prevention Tips

✅ Nên:

• Giữ ClaudeKit cập nhật (ck init)
• Sử dụng --verbose khi debug
• Backup trước khi thay đổi lớn
• Đọc kỹ thông báo lỗi

❌ Không nên:

• Sửa đổi trực tiếp các files core .claude/
• Bỏ qua API rate limits
• Bỏ qua cập nhật phiên bản
• Xóa thư mục .claude/

95% các vấn đề giải quyết trong vòng dưới 5 phút với các hướng dẫn này. Đi sâu vào các phần cụ thể để biết cách sửa chi tiết.