ccs/docs/vi/troubleshooting.vi.md

Hướng Dẫn Khắc Phục Sự Cố CCS

Cảnh báo lỗi thời của trình cài đặt gốc

Vấn đề: "Tại sao trình cài đặt curl/irm hiển thị cảnh báo lỗi thời?"

Nguyên nhân: Trình cài đặt shell gốc đã lỗi thời, ưu tiên cài đặt npm.

Giải pháp:

# Gỡ cài đặt phiên bản cũ (nếu cài qua curl/irm)
ccs-uninstall  # hoặc: curl -fsSL ccs.kaitran.ca/uninstall | bash

# Cài đặt qua npm (khuyến nghị)
npm install -g @kaitranntt/ccs

Lưu ý: Trình cài đặt cũ hiện tự động chạy npm install nếu Node.js khả dụng.

Vấn Đề Riêng Của Windows

PowerShell Execution Policy

Nếu bạn thấy "cannot be loaded because running scripts is disabled":

# Kiểm tra policy hiện tại
Get-ExecutionPolicy

# Cho phép user hiện tại chạy scripts (khuyến nghị)
Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser

# Hoặc chạy với bypass (một lần)
powershell -ExecutionPolicy Bypass -File "$env:USERPROFILE\.ccs\ccs.ps1" glm

PATH chưa được cập nhật (Windows)

Nếu lệnh ccs không tìm thấy sau khi cài đặt:

1. Khởi động lại terminal của bạn
2. Hoặc thêm thủ công vào PATH:
   • Mở "Edit environment variables for your account"
   • Thêm %USERPROFILE%\.ccs vào User PATH
   • Khởi động lại terminal

Claude CLI không tìm thấy (Windows)

# Kiểm tra Claude CLI
where.exe claude

# Nếu thiếu, cài đặt từ tài liệu Claude

Claude CLI Ở Vị Trí Không Chuẩn

Nếu Claude CLI được cài đặt trên ổ đĩa khác hoặc vị trí tùy chỉnh (phổ biến trên Windows với ổ D:):

Triệu Chứng

╔═════════════════════════════════════════════╗
║  ERROR                                      ║
╚═════════════════════════════════════════════╝

Claude CLI not found

Searched:
  - CCS_CLAUDE_PATH: (not set)
  - System PATH: not found
  - Common locations: not found

Giải Pháp: Đặt CCS_CLAUDE_PATH

Bước 1: Tìm Vị Trí Claude CLI

Windows:

# Tìm kiếm tất cả ổ đĩa
Get-ChildItem -Path C:\,D:\,E:\ -Filter claude.exe -Recurse -ErrorAction SilentlyContinue | Select-Object FullName

# Các vị trí phổ biến cần kiểm tra thủ công
D:\Program Files\Claude\claude.exe
D:\Tools\Claude\claude.exe
D:\Users\<Username>\AppData\Local\Claude\claude.exe

Unix/Linux/macOS:

# Tìm kiếm hệ thống
sudo find / -name claude 2>/dev/null

# Hoặc kiểm tra các vị trí cụ thể
ls -la /usr/local/bin/claude
ls -la ~/.local/bin/claude
ls -la /opt/homebrew/bin/claude

Bước 2: Đặt Biến Môi Trường

Windows (PowerShell) - Vĩnh viễn:

# Thay bằng đường dẫn thực tế của bạn
$ClaudePath = "D:\Program Files\Claude\claude.exe"

# Đặt cho phiên hiện tại
$env:CCS_CLAUDE_PATH = $ClaudePath

# Đặt vĩnh viễn cho user
[Environment]::SetEnvironmentVariable("CCS_CLAUDE_PATH", $ClaudePath, "User")

# Khởi động lại terminal để áp dụng

Unix (bash) - Vĩnh viễn:

# Thay bằng đường dẫn thực tế của bạn
CLAUDE_PATH="/opt/custom/location/claude"

# Thêm vào shell profile
echo "export CCS_CLAUDE_PATH=\"$CLAUDE_PATH\"" >> ~/.bashrc

# Reload profile
source ~/.bashrc

Unix (zsh) - Vĩnh viễn:

# Thay bằng đường dẫn thực tế của bạn
CLAUDE_PATH="/opt/custom/location/claude"

# Thêm vào shell profile
echo "export CCS_CLAUDE_PATH=\"$CLAUDE_PATH\"" >> ~/.zshrc

# Reload profile
source ~/.zshrc

Bước 3: Xác Minh Cấu Hình

# Kiểm tra biến môi trường đã được đặt
echo $CCS_CLAUDE_PATH        # Unix
$env:CCS_CLAUDE_PATH         # Windows

# Kiểm tra CCS có thể tìm thấy Claude
ccs --version

# Kiểm tra với profile thực tế
ccs glm --version

Các Vấn Đề Phổ Biến

Đường Dẫn Không Hợp Lệ:

Error: File not found: D:\Program Files\Claude\claude.exe

Sửa: Kiểm tra kỹ đường dẫn, đảm bảo file tồn tại:

Test-Path "D:\Program Files\Claude\claude.exe"  # Windows
ls -la "/path/to/claude"                         # Unix

Thư Mục Thay Vì File:

Error: Path is a directory: D:\Program Files\Claude

Sửa: Đường dẫn phải trỏ đến file claude.exe, không phải thư mục:

# Sai
$env:CCS_CLAUDE_PATH = "D:\Program Files\Claude"

# Đúng
$env:CCS_CLAUDE_PATH = "D:\Program Files\Claude\claude.exe"

Không Thể Thực Thi:

Error: File is not executable: /path/to/claude

Sửa (chỉ Unix):

chmod +x /path/to/claude

Cấu Hình Riêng Cho WSL

Khi sử dụng Claude trên Windows từ WSL:

# Định dạng đường dẫn mount: /mnt/d/ cho ổ D:
export CCS_CLAUDE_PATH="/mnt/d/Program Files/Claude/claude.exe"

# Thêm vào ~/.bashrc để lưu
echo 'export CCS_CLAUDE_PATH="/mnt/d/Program Files/Claude/claude.exe"' >> ~/.bashrc
source ~/.bashrc

Lưu ý: Khoảng trắng trong đường dẫn Windows hoạt động đúng từ WSL khi được quote đúng cách.

Debug Phát Hiện

Để xem CCS đã kiểm tra gì:

# Tạm thời di chuyển claude ra khỏi PATH để kiểm tra
# Sau đó chạy ccs - thông báo lỗi sẽ hiển thị những gì đã được kiểm tra

ccs --version
# Sẽ hiển thị:
#   - CCS_CLAUDE_PATH: (status)
#   - System PATH: not found
#   - Common locations: not found

Phương Án Thay Thế: Thêm Vào PATH

Nếu bạn không muốn dùng CCS_CLAUDE_PATH, thêm thư mục Claude vào PATH:

Windows (PowerShell):

# Thêm D:\Program Files\Claude vào PATH
$ClaudeDir = "D:\Program Files\Claude"
$env:Path += ";$ClaudeDir"
[Environment]::SetEnvironmentVariable("Path", $env:Path, "User")

# Khởi động lại terminal

Unix (bash):

# Thêm /opt/claude/bin vào PATH
echo 'export PATH="/opt/claude/bin:$PATH"' >> ~/.bashrc
source ~/.bashrc

Lưu ý: CCS_CLAUDE_PATH có ưu tiên cao hơn PATH, cho phép ghi đè cho từng dự án.

Vấn Đề Cài Đặt

Lỗi BASH_SOURCE unbound variable

Lỗi này xảy ra khi chạy installer trong một số shells hoặc môi trường.

Đã sửa trong phiên bản mới nhất: Installer bây giờ xử lý cả thực thi qua pipe (curl | bash) và thực thi trực tiếp (./install.sh).

Giải pháp: Nâng cấp lên phiên bản mới nhất:

curl -fsSL https://raw.githubusercontent.com/kaitranntt/ccs/main/installers/install.sh | bash

Git worktree không được phát hiện

Nếu cài từ git worktree hoặc submodule, các phiên bản cũ có thể không phát hiện repository git.

Đã sửa trong phiên bản mới nhất: Installer bây giờ phát hiện cả thư mục .git (clone chuẩn) và file .git (worktree/submodule).

Giải pháp: Nâng cấp lên phiên bản mới nhất hoặc dùng phương pháp cài đặt curl.

Vấn Đề Cấu Hình

Không tìm thấy profile

Error: Profile 'foo' not found in ~/.ccs/config.json

Fix: Thêm profile vào ~/.ccs/config.json:

{
  "profiles": {
    "foo": "~/.ccs/foo.settings.json"
  }
}

Thiếu file settings

Error: Settings file not found: ~/.ccs/foo.settings.json

Fix: Tạo file settings hoặc sửa đường dẫn trong config.

jq chưa được cài đặt

Error: jq is required but not installed

Fix: Cài đặt jq (xem hướng dẫn cài đặt).

Lưu ý: Installer tạo các mẫu cơ bản ngay cả khi không có jq, nhưng các tính năng nâng cao cần jq.

Vấn Đề Cấu Hình PATH

Cấu Hình PATH Tự Động

v2.2.0+ tự động cấu hình shell PATH. Nếu bạn thấy hướng dẫn reload sau khi cài, hãy làm theo:

Cho bash:

source ~/.bashrc

Cho zsh:

source ~/.zshrc

Cho fish:

source ~/.config/fish/config.fish

Hoặc mở cửa sổ terminal mới (PATH tự động load).

PATH Chưa Được Cấu Hình

Nếu lệnh ccs không tìm thấy sau khi cài và reload:

Xác minh PATH entry tồn tại:

# Cho bash/zsh
grep "\.local/bin" ~/.bashrc ~/.zshrc

# Cho fish
grep "\.local/bin" ~/.config/fish/config.fish

Sửa thủ công (nếu auto-config thất bại):

Bash:

echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.bashrc
source ~/.bashrc

Zsh:

echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.zshrc
source ~/.zshrc

Fish:

echo 'set -gx PATH $HOME/.local/bin $PATH' >> ~/.config/fish/config.fish
source ~/.config/fish/config.fish

Shell Profile Sai

Nếu auto-config thêm vào file sai:

Tìm profile đang active:

echo $SHELL  # Hiển thị shell hiện tại

Tình huống phổ biến:

• macOS bash dùng ~/.bash_profile (không phải ~/.bashrc)
• Shell tùy chỉnh cần config thủ công
• Tmux/screen có thể dùng shell khác

Giải pháp: Thêm PATH thủ công vào file profile đúng.

Shell Không Được Phát Hiện

Nếu installer không thể phát hiện shell:

Triệu chứng:

• Không có cảnh báo PATH hiển thị
• Lệnh ccs không tìm thấy sau khi cài

Giải pháp: Thiết lập PATH thủ công (xem ở trên).

Thiếu profile mặc định

Error: Profile 'default' not found in ~/.ccs/config.json

Fix: Thêm profile "default" hoặc luôn chỉ định tên profile:

{
  "profiles": {
    "default": "~/.claude/settings.json"
  }
}

Vấn Đề Phổ Biến

Claude CLI không tìm thấy

Error: claude command not found

Giải pháp: Cài đặt Claude CLI từ tài liệu chính thức.

Permission denied (Unix)

Error: Permission denied: ~/.local/bin/ccs

Giải pháp: Cho phép script thực thi:

chmod +x ~/.local/bin/ccs

Không tìm thấy file config

Error: Config file not found: ~/.ccs/config.json

Giải pháp: Chạy lại installer hoặc tạo config thủ công:

mkdir -p ~/.ccs
echo '{"profiles":{"default":"~/.claude/settings.json"}}' > ~/.ccs/config.json

Nhận Trợ Giúp

Nếu bạn gặp các vấn đề không được đề cập ở đây:

1. Kiểm tra GitHub Issues
2. Tạo issue mới với:
   • Hệ điều hành của bạn
   • Phiên bản CCS (ccs --version)
   • Thông báo lỗi chính xác
   • Các bước để tái tạo vấn đề

Chế Độ Debug

Bật verbose output để khắc phục sự cố:

ccs --verbose glm

Điều này sẽ hiển thị:

• File config nào đang được đọc
• Profile nào đang được chọn
• File settings nào đang được sử dụng
• Lệnh chính xác đang được thực thi

Tắt Output Có Màu

Nếu output có màu gây vấn đề trong terminal hoặc logs của bạn:

export NO_COLOR=1
ccs glm

Trường Hợp Sử Dụng:

• Môi trường CI/CD
• Tạo log file
• Terminal không hỗ trợ màu
• Tùy chọn trợ năng