4.4 · Cài đặt Claude Code

Mở đầu: Tại sao cài Claude Code không giống cài một CLI bình thường?

• Máy bạn cần binary Claude Code
• Máy bạn cần network đến Anthropic API (hoặc AWS Bedrock / GCP Vertex)
• Authentication đúng = bạn có quota gọi model
• Permission đúng = Claude Code không bị chặn write file

Bỏ qua một bước = gặp lỗi khó hiểu sau này. Bài này đi qua từng bước với mindset "ít phút bây giờ = tiết kiệm hàng giờ debug sau".

Các option cài đặt

┌────────────────────────────────────────────────────────────┐
│                                                            │
│  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                                       │
│                                                            │
└────────────────────────────────────────────────────────────┘

Chọn option nào?

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

macOS với Homebrew

brew install --cask claude-code

Verify:

claude --version

macOS / Linux / WSL với install script

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

Script sẽ:

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

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

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:

claude

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

┌──────────────────────────────────────────────────────────┐
│                                                          │
│  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]                              │
│                                                          │
└──────────────────────────────────────────────────────────┘

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

1. Vào console.anthropic.com
2. Tạo API key
3. Trong Claude Code:

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

1. Key được lưu local encrypted.

Ư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:

• 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

Option 4: GCP Vertex AI

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

Checklist:

• 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

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

Test 1: Version check

claude --version

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

Test 2: Simple conversation

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

Trong session:

You: Hello, what can you do?

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

Test 3: File operation

Vẫn trong ~/claude-test:

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

Check manually:

cat hello.txt

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

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)

#!/bin/bash

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."

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

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):

• 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

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:

• 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

Devtool startup — Dogfooding

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

Sau:

• 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:

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

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

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:

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

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:

brew upgrade claude-code

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

claude --version

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

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:

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

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:

• 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)

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

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

Fix:

claude logout
claude          # login lại

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.

Á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:

• 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

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

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

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

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

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"

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

Cho tôi review codebase này.

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)

---

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

Tài liệu tham khảo

• Claude Code quickstart docs
• AWS Bedrock setup
• GCP Vertex setup
• Changelog Claude Code