Cài đặt Claude Code

Các option cài đặt

Chọn option nào?

┌────────────────────────────────────────────────────────────┐
│                                                            │
│  Option 1: Homebrew (macOS)                                │
│     brew install --cask claude-code                        │
│                                                            │
│  Option 2: Install script (macOS, Linux, WSL)              │
│     curl -fsSL https://claude.ai/install.sh | bash         │
│                                                            │
│  Option 3: Windows CMD                                     │
│     curl -fsSL https://claude.ai/install.cmd -o install.cmd│
│     install.cmd && del install.cmd                         │
│                                                            │
│  Option 4 (enterprise): AWS Bedrock / GCP Vertex           │
│     → Xem docs riêng                                       │
│                                                            │
└────────────────────────────────────────────────────────────┘

Cài đặt bước-bằng-bước

macOS với Homebrew

Verify:

brew install --cask claude-code

macOS với Homebrew

macOS / Linux / WSL với install script

claude --version
# Expected: claude-code X.Y.Z (build XXXX)

macOS / Linux / WSL với install script

Script sẽ:

Sau khi xong, mở terminal mới (để PATH update) và verify:

• Detect OS + architecture
• Tải binary về ~/.claude/bin/claude
• Thêm ~/.claude/bin vào PATH (sửa .bashrc hoặc .zshrc)

curl -fsSL https://claude.ai/install.sh | bash

Cài đặt bước-bằng-bước (tiếp)

Windows (CMD)

claude --version

Windows (CMD)

curl -fsSL https://claude.ai/install.cmd -o install.cmd && install.cmd && del install.cmd

Authenticate lần đầu

Lần đầu chạy claude:

Bạn sẽ thấy menu xác thực:

Chọn option nào?

Cho khóa học này: Option 1 hoặc 2 là đủ. Option 3, 4 bạn đọc để biết tồn tại, cần xem docs riêng khi enterprise apply.

Option 1: Login với Pro/Max

Claude Code mở browser → login tài khoản Claude.ai → token được lưu local (~/.claude/auth.json). Chỉ làm 1 lần.

Nếu bạn đang có subscription Pro hoặc Max, đây là cách dễ nhất và không tính token theo request — dùng thoải mái trong giới hạn plan.

Option 2: API key

• Vào console.anthropic.com
• Tạo API key
• Trong Claude Code:

┌──────────────────────────────────────────────────────────┐
│                                                          │
│  How would you like to authenticate?                     │
│                                                          │
│   1. Log in with Claude Pro/Max subscription             │
│   2. Use Anthropic API key                               │
│   3. Use AWS Bedrock                                     │
│   4. Use Google Cloud Vertex AI                          │
│                                                          │
│  [Use arrow keys to select]                              │
│                                                          │
└──────────────────────────────────────────────────────────┘

claude

Option 2: API key

Ưu điểm: Kiểm soát chính xác token spent, có usage dashboard. Nhược: Phải theo dõi usage, tránh vượt budget.

Option 3: AWS Bedrock (enterprise)

Xem docs riêng: code.claude.com/docs/en/amazon-bedrock.

Checklist ngắn:

Option 4: GCP Vertex AI

Docs: code.claude.com/docs/en/google-vertex-ai.

Checklist:

• Key được lưu local encrypted.
• AWS account với access Bedrock
• Request model access cho Claude 3.x / 4.x trong Bedrock console
• IAM credentials có quyền bedrock:InvokeModel
• Env var: CLAUDE_CODE_USE_BEDROCK=1, AWS_REGION, AWS credentials
• GCP project có Vertex AI enabled
• Model Garden access cho Claude
• Service account với role aiplatform.user
• Env: CLAUDE_CODE_USE_VERTEX=1, ANTHROPIC_VERTEX_PROJECT_ID, CLOUD_ML_REGION

   Paste your API key: sk-ant-api03-...

Verify cài đặt đầy đủ

Test 1: Version check

Expected output: phiên bản + build number.

Test 2: Simple conversation

claude --version

Test 2: Simple conversation

Trong session:

mkdir ~/claude-test && cd ~/claude-test
claude

Verify cài đặt đầy đủ (tiếp)

Test 3: File operation

Vẫn trong ~/claude-test:

You: Hello, what can you do?

Claude: (Giải thích khả năng, list tool có sẵn)

Test 3: File operation

Check manually:

You: Tạo một file hello.txt với nội dung "Hello from Claude Code".
     Sau đó đọc lại file đó để confirm.

Claude: 
  [Write] hello.txt
  [Read] hello.txt
  Content: "Hello from Claude Code". Confirmed.

You: /exit

Verify cài đặt đầy đủ (tiếp)

Nếu cả 3 test pass → cài đặt hoàn chỉnh.

cat hello.txt
# Hello from Claude Code

Ví dụ thực chiến: Onboard dev mới trong team

Tình huống

Team 5 dev, tech lead muốn tất cả dùng Claude Code với cấu hình đồng nhất. Onboard dev thứ 6 sáng thứ Hai.

Script onboard (tech lead viết, dùng cho mọi dev mới)

Kết quả

• Dev mới productive sau 30 phút (thay vì 1–2 tiếng loay hoay)
• Config đồng nhất → output Claude đồng nhất trên cả team
• Ít câu "sao máy tao không giống máy mày" trong standup

#!/bin/bash
# onboard-claude-code.sh — chạy trên máy dev mới

set -e

echo "1. Cài Homebrew (nếu chưa)..."
which brew || /bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

echo "2. Cài Claude Code..."
brew install --cask claude-code

echo "3. Clone team config template..."
git clone git@github.com:acme/team-claude-config.git ~/.claude-team
cp ~/.claude-team/CLAUDE.md ~/.claude/CLAUDE.md
cp ~/.claude-team/settings.json ~/.claude/settings.json

echo "4. Test bằng project demo..."
cd ~/Projects && git clone git@github.com:acme/demo.git
cd demo && claude

echo "Nếu prompt xin login, login với API key @acme.com được cấp."
echo "Done! Gõ: claude trong bất kỳ project nào."

Case studies theo ngành

🏭 Enterprise SaaS — Bedrock cho compliance

Trước: Team compliance block Claude Code vì "code gửi API bên ngoài".

Sau (setup Bedrock):

🎓 EdTech — Classroom license

Trước: 80 sinh viên khóa "Advanced SE" cần tool AI coding, mỗi em tự mua Pro = khó.

Sau:

🛠️ Devtool startup — Dogfooding

Trước: Team 6 dev, mỗi người self-onboard, tốn thời gian + inconsistent.

Sau:

• Claude Code gọi model trong AWS account của công ty
• VPC peering đã sẵn, code không rời infrastructure
• Billing chung với AWS invoice
• Kết quả: approval SecOps, rollout 120 engineer trong 3 tuần
• Teacher mua API key, viết script generate sub-key rotation
• Mỗi student cài Claude Code một lần với key được cấp
• Quota per student enforced ở layer proxy
• Kết quả: 80 em dùng được Claude Code cả kỳ, tổng cost < $800
• Shared script onboarding (giống ví dụ trên)
• ~/.claude/CLAUDE.md global cho habit chung
• CI check CLAUDE.md không bị drift
• Kết quả: onboard dev mới còn 45 phút, 100% dev dùng Claude Code daily

Anti-patterns khi cài đặt

❌ Cài xong không update PATH

Biểu hiện: gõ claude → "command not found".

Fix: Tùy shell:

❌ API key commit vào git

Biểu hiện: ANTHROPIC_API_KEY=sk-ant-... trong .env rồi push lên GitHub public.

Hậu quả: Bot scan GitHub, dùng key của bạn. Bill tăng $1000 trong 1 đêm.

Fix:

❌ Dùng chung API key cho cả team

Biểu hiện: một key dán khắp Slack, mỗi dev copy.

Hậu quả: Không rotate được (sợ break teammate); không audit được ai dùng gì; vi phạm T&C Anthropic.

Fix: Mỗi dev key riêng. Hoặc dùng Claude Pro/Max team plan. Hoặc proxy server với rotate key (advanced).

❌ Cài Claude Code nhưng chưa cài Node.js

Biểu hiện: Claude Code chạy, nhưng khi thử /init trên project TS/JS, nhiều command fail (npm, npx không có).

Fix: Cài Node.js 18+ (nodejs.org hoặc brew install node) trước.

❌ Cài bản cũ, không update

Biểu hiện: bạn cài 6 tháng trước, bỏ qua thông báo update. Mới thấy feature hook được ra trong doc nhưng không có trên máy.

Fix:

• Rotate key ngay (console.anthropic.com)
• Xóa commit: git filter-repo hoặc BFG
• Add .env vào .gitignore
• Dùng secret manager thay vì file plaintext (1Password, AWS Secrets)

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

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

❌ Cài bản cũ, không update

Nguyên tắc: check version 1 lần/tháng. Claude Code ship nhanh.

# Homebrew
brew upgrade claude-code

# Script-installed
curl -fsSL https://claude.ai/install.sh | bash   # re-run = update

# Check version sau khi upgrade
claude --version

Troubleshooting 5 lỗi phổ biến

Lỗi 1: "SSL certificate verify failed"

Nguyên nhân: Corporate proxy chặn cert Anthropic.

Fix:

Hoặc liên hệ IT xin CA bundle công ty.

Lỗi 2: "Command not found: claude" sau khi cài

Fix: Xem anti-pattern "không update PATH" phía trên.

Lỗi 3: "Rate limit exceeded"

Nguyên nhân: Vượt quota plan (Pro/Max) hoặc API limit.

Fix:

Lỗi 4: "Authentication failed" ngẫu nhiên

Nguyên nhân: Token login Pro/Max hết hạn.

Fix:

• Pro/Max: đợi reset (thường daily), hoặc upgrade plan
• API: tăng rate limit trong console.anthropic.com (Tier mới cần request)

export NODE_EXTRA_CA_CERTS=/path/to/corporate-ca.crt

Lỗi 4: "Authentication failed" ngẫu nhiên

Lỗi 5: Windows — "Cannot execute binary"

Nguyên nhân: CMD version có thể incompatible một số feature mới.

Fix: Dùng WSL2 + install script thay CMD. 90% user Windows chuyển sang WSL2 đều hài lòng hơn.

claude logout
claude          # login lại

Áp dụng ngay

Bài tập 1: Cài đặt + verify (15 phút)

Bước 1: Chọn option cài phù hợp OS bạn, cài.

Bước 2: Authenticate (Pro/Max hoặc API key).

Bước 3: Chạy 3 test verify ở phần "Verify cài đặt" phía trên.

Bước 4: Ghi lại:

Bài tập 2 (optional, 10 phút): Setup global CLAUDE.md

Bước 1: Tạo ~/.claude/CLAUDE.md:

Bước 2: Edit file, thêm một vài preference cá nhân:

• Version cài được: ____
• Option authenticate đã chọn: ____
• Test 3 (file operation) hoạt động? ☐ Có ☐ Không
• Thời gian tổng: _____ phút

mkdir -p ~/.claude
touch ~/.claude/CLAUDE.md

Bài tập 2 (optional, 10 phút): Setup global CLAUDE.md

Bước 3: Verify — mở Claude Code trong bất kỳ project, hỏi:

# Global Claude preferences

## Communication
- Respond in Vietnamese when I ask questions
- Use Vietnamese for explanations, English for code/technical terms

## Code style
- TypeScript: always strict mode
- Python: type hints required for function signatures  
- Comments: only when the "why" is non-obvious

## Git
- Commit messages: Conventional Commits format
- PR descriptions: include "Context", "Changes", "Test plan"

Áp dụng ngay (tiếp)

Claude phản hồi tiếng Việt? ☐ Có ☐ Không (nếu không, check CLAUDE.md có bị override bởi project-level không)

Cho tôi review codebase này.

Tóm tắt bài học

🎯 Claude Code = CLI local + LM remote — cài CLI, auth với model endpoint.

🎯 4 authentication option — Pro/Max (dễ nhất), API key (kiểm soát cost), Bedrock/Vertex (enterprise).

🎯 Verify bằng 3 test — version, conversation, file operation.

🎯 Check update hàng tháng — tool ship nhanh, bỏ lỡ = bỏ lỡ feature lớn.

🎯 API key là secret — không commit, không share Slack, không dùng chung team.