Tài liệu hướng dẫn chi tiết từ A-Z để cài đặt, xác thực và cấu hình Claude Code — công cụ dòng lệnh chính thức của Anthropic dành cho lập trình viên.
| Hệ điều hành | Phiên bản tối thiểu | Ghi chú |
|---|---|---|
| macOS | 12 (Monterey) trở lên | Hỗ trợ cả Intel và Apple Silicon |
| Ubuntu/Debian | 20.04 trở lên | Khuyến nghị Ubuntu 22.04+ |
| Windows | Windows 10/11 | Chạy qua WSL2 (bắt buộc) |
| Các bản Linux khác | Kernel 5.x+ | Fedora, Arch, RHEL đều được hỗ trợ |
Node.js (bắt buộc):
Kiểm tra phiên bản Node.js hiện tại:
node --version
Nếu chưa cài Node.js, cài qua nvm (khuyến nghị):
# Cài đặt nvm
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.1/install.sh | bash
# Khởi động lại terminal, sau đó cài Node.js LTS
nvm install --lts
nvm use --lts
Hoặc cài trực tiếp trên Ubuntu/Debian:
curl -fsSL https://deb.nodesource.com/setup_20.x | sudo -E bash -
sudo apt-get install -y nodejs
npm (đi kèm Node.js):
npm --version
Git (cần thiết để tích hợp với dự án):
git --version
# Nếu chưa có, cài đặt:
# Ubuntu/Debian
sudo apt-get install -y git
# macOS
xcode-select --install
npm install -g @anthropic-ai/claude-code
Kiểm tra cài đặt thành công:
claude --version
Cập nhật lên phiên bản mới nhất:
npm update -g @anthropic-ai/claude-code
npx @anthropic-ai/claude-code
Phương pháp này phù hợp khi bạn muốn thử nghiệm nhanh mà không cài đặt cố định vào hệ thống.
brew install claude-code
Lỗi quyền truy cập (EACCES):
# Cách 1: Thay đổi thư mục global của npm
mkdir -p ~/.npm-global
npm config set prefix '~/.npm-global'
echo 'export PATH=~/.npm-global/bin:$PATH' >> ~/.bashrc
source ~/.bashrc
# Sau đó cài lại
npm install -g @anthropic-ai/claude-code
# Cách 2: Dùng nvm (khuyến nghị — tránh dùng sudo với npm)
nvm install --lts
npm install -g @anthropic-ai/claude-code
Lỗi phiên bản Node.js quá cũ:
# Cập nhật Node.js qua nvm
nvm install 20
nvm alias default 20
Kiểm tra cài đặt hoàn chỉnh:
# Xác minh Claude Code đã sẵn sàng
claude --version
claude --help
Khi chạy Claude Code lần đầu, công cụ sẽ hướng dẫn bạn đăng nhập:
claude
Bạn sẽ được chuyển đến trình duyệt để xác thực qua tài khoản Anthropic (hoặc tài khoản Max plan).
Lấy API Key tại: https://console.anthropic.com/settings/keys
Thiết lập biến môi trường (tạm thời trong phiên terminal hiện tại):
export ANTHROPIC_API_KEY="sk-ant-api03-xxxxxxxxxxxxx"
Thiết lập vĩnh viễn (thêm vào file cấu hình shell):
# Cho Bash
echo 'export ANTHROPIC_API_KEY="sk-ant-api03-xxxxxxxxxxxxx"' >> ~/.bashrc
source ~/.bashrc
# Cho Zsh
echo 'export ANTHROPIC_API_KEY="sk-ant-api03-xxxxxxxxxxxxx"' >> ~/.zshrc
source ~/.zshrc
Sử dụng file .env trong dự án (cho nhóm phát triển):
# Tạo file .env ở thư mục gốc dự án
echo 'ANTHROPIC_API_KEY=sk-ant-api03-xxxxxxxxxxxxx' > .env
Quan trọng: Luôn thêm
.envvào.gitignoređể tránh lộ API Key:echo '.env' >> .gitignore
Claude Code hỗ trợ kết nối qua các dịch vụ proxy hoặc các nhà cung cấp tương thích:
# Sử dụng với Amazon Bedrock
export CLAUDE_CODE_USE_BEDROCK=1
export AWS_REGION="us-east-1"
export AWS_ACCESS_KEY_ID="your-access-key"
export AWS_SECRET_ACCESS_KEY="your-secret-key"
# Sử dụng với Google Vertex AI
export CLAUDE_CODE_USE_VERTEX=1
export CLOUD_ML_REGION="us-east5"
export ANTHROPIC_VERTEX_PROJECT_ID="your-project-id"
# Kiểm tra xem đã xác thực thành công chưa
claude "Xin chào, hãy cho tôi biết bạn là model nào"
| Biến môi trường | Mô tả |
|---|---|
ANTHROPIC_API_KEY |
API Key của Anthropic |
CLAUDE_CODE_USE_BEDROCK |
Bật chế độ Amazon Bedrock |
CLAUDE_CODE_USE_VERTEX |
Bật chế độ Google Vertex AI |
CLAUDE_MODEL |
Chỉ định model cụ thể (vd: claude-sonnet-4-20250514) |
CLAUDE_CODE_MAX_OUTPUT_TOKENS |
Giới hạn số token đầu ra |
HTTP_PROXY / HTTPS_PROXY |
Cấu hình proxy mạng |
~/.claude/Sau khi cài đặt và chạy lần đầu, Claude Code tạo thư mục cấu hình tại ~/.claude/:
~/.claude/
├── CLAUDE.md # Hướng dẫn toàn cục cho mọi dự án
├── settings.json # Cấu hình chung (quyền, MCP servers, v.v.)
├── credentials.json # Thông tin xác thực (tự động tạo)
└── projects/ # Bộ nhớ theo dự án
└── <hash>/
└── CLAUDE.md # Ghi chú cá nhân cho từng dự án
File ~/.claude/CLAUDE.md chứa các hướng dẫn áp dụng cho tất cả dự án. Claude sẽ đọc file này mỗi khi khởi động.
# Tạo hoặc chỉnh sửa file CLAUDE.md toàn cục
nano ~/.claude/CLAUDE.md
Ví dụ nội dung:
# Quy tắc chung
## Ngôn ngữ
- Giao tiếp bằng tiếng Việt
- Viết commit message bằng tiếng Việt
- Biến và hàm đặt tên bằng tiếng Anh
## Phong cách code
- Dùng 2 spaces cho indent
- Luôn thêm comment giải thích cho logic phức tạp
- Ưu tiên sự đơn giản, tránh over-engineering
## Phong cách commit
- feat: thêm chức năng mới
- fix: sửa lỗi
- docs: cập nhật tài liệu
- refactor: tái cấu trúc code
File ~/.claude/settings.json điều khiển hành vi và quyền hạn của Claude Code:
# Mở file cấu hình
nano ~/.claude/settings.json
Ví dụ cấu hình cơ bản:
{
"permissions": {
"allow": [
"Bash(npm run *)",
"Bash(git *)",
"Bash(node *)",
"Read",
"Write",
"Edit"
],
"deny": [
"Bash(rm -rf *)",
"Bash(sudo *)",
"Bash(curl * | bash)",
"Bash(wget * | bash)"
]
}
}
Claude Code có 3 chế độ chính để kiểm soát quyền thực thi:
1. Chế độ mặc định (Ask — Hỏi trước mỗi hành động):
# Chạy bình thường, Claude sẽ hỏi xác nhận mỗi khi cần chạy lệnh
claude
2. Chế độ tự động chấp nhận (Auto-accept):
# Tự động chấp nhận mọi hành động (dùng khi tin tưởng hoàn toàn)
claude --dangerously-skip-permissions
Cảnh báo: Chế độ này bỏ qua mọi xác nhận. Chỉ dùng trong môi trường an toàn (sandbox, CI/CD).
3. Chế độ chỉ cho phép một số lệnh cụ thể:
Cấu hình trong settings.json để tự động cho phép các lệnh an toàn và từ chối các lệnh nguy hiểm. Các lệnh không nằm trong danh sách sẽ được hỏi xác nhận:
{
"permissions": {
"allow": [
"Bash(npm test)",
"Bash(npm run lint)",
"Bash(npm run build)",
"Bash(git status)",
"Bash(git diff *)",
"Bash(git log *)"
],
"deny": [
"Bash(rm -rf /)",
"Bash(sudo *)"
]
}
}
.claude/settings.jsonNgoài cấu hình toàn cục, mỗi dự án có thể có file cấu hình riêng tại .claude/settings.json trong thư mục gốc dự án:
# Tạo thư mục cấu hình cho dự án
mkdir -p .claude
# Tạo file cấu hình dự án
nano .claude/settings.json
{
"permissions": {
"allow": [
"Bash(make *)",
"Bash(go test ./...)",
"Bash(go build ./...)"
]
}
}
File cấu hình dự án
.claude/settings.jsonnên được commit vào git để cả nhóm dùng chung.
File CLAUDE.md đặt ở thư mục gốc dự án là cách chính để hướng dẫn Claude hiểu bối cảnh dự án. Claude sẽ tự động đọc file này khi bạn chạy claude trong thư mục đó.
# Tạo file CLAUDE.md tại thư mục gốc dự án
touch CLAUDE.md
Bạn cũng có thể dùng lệnh init để Claude tự phân tích dự án và tạo file CLAUDE.md:
claude /init
# Hướng dẫn dự án
## Tổng quan
Đây là ứng dụng API backend viết bằng Node.js + TypeScript + Express.
Database: PostgreSQL với Prisma ORM.
## Cấu trúc thư mục
- src/routes/ — Định nghĩa các API endpoint
- src/services/ — Logic nghiệp vụ
- src/models/ — Prisma schema và models
- src/middleware/ — Middleware (auth, validation, error handling)
- src/utils/ — Hàm tiện ích
- tests/ — Unit test và integration test
## Quy ước code
- Dùng TypeScript strict mode
- Dùng async/await, không dùng callback
- Mỗi service method phải có try-catch
- Dùng zod để validate request body
- Đặt tên biến và hàm bằng tiếng Anh, camelCase
## Lệnh thường dùng
- `npm run dev` — Chạy development server
- `npm run build` — Build production
- `npm test` — Chạy test
- `npm run lint` — Kiểm tra linting
- `npx prisma migrate dev` — Chạy database migration
- `npx prisma generate` — Generate Prisma client
## Quy tắc quan trọng
- KHÔNG bao giờ commit file .env
- Luôn viết test cho service mới
- Dùng transaction cho các thao tác database liên quan đến nhau
# Hướng dẫn dự án
## Tổng quan
Microservice viết bằng Go, dùng Gin framework.
Database: PostgreSQL. Cache: Redis.
## Cấu trúc thư mục
- cmd/ — Entry point của ứng dụng
- internal/handler/ — HTTP handlers
- internal/service/ — Logic nghiệp vụ
- internal/repository/ — Tầng truy cập database
- internal/model/ — Định nghĩa struct/model
- pkg/ — Thư viện dùng chung
- migrations/ — SQL migration files
## Quy ước code
- Tuân thủ Go conventions (gofmt, golint)
- Dùng interface cho dependency injection
- Xử lý error rõ ràng, không dùng panic trong production code
- Viết table-driven test
## Lệnh thường dùng
- `go run cmd/server/main.go` — Chạy server
- `go test ./...` — Chạy tất cả test
- `go build -o bin/server cmd/server/main.go` — Build binary
- `golangci-lint run` — Kiểm tra linting
- `make migrate-up` — Chạy database migration
## Ghi chú
- Dùng context.Context cho mọi hàm có I/O
- Tất cả config đọc từ biến môi trường
- Log dùng structured logging với zerolog
# Hướng dẫn dự án
## Tổng quan
Ứng dụng web fullstack dùng Next.js 15 (App Router).
UI: Tailwind CSS + shadcn/ui. Database: Supabase.
## Cấu trúc thư mục
- app/ — App Router pages và layouts
- app/api/ — API routes
- components/ — React components
- components/ui/ — shadcn/ui components (không chỉnh sửa trực tiếp)
- lib/ — Utilities, Supabase client, helpers
- hooks/ — Custom React hooks
- types/ — TypeScript type definitions
- public/ — Static assets
## Quy ước code
- Dùng Server Components mặc định, chỉ dùng "use client" khi cần
- Dùng Tailwind CSS cho styling, tránh inline styles
- Component nào có state/effect thì tách riêng thành Client Component
- Fetch data ở Server Component, truyền xuống qua props
## Lệnh thường dùng
- `npm run dev` — Chạy development server (port 3000)
- `npm run build` — Build production
- `npm run lint` — Kiểm tra ESLint
- `npx shadcn@latest add <component>` — Thêm component shadcn/ui
## Quy tắc quan trọng
- Không import trực tiếp từ @supabase/supabase-js, dùng lib/supabase.ts
- Dùng next/image thay cho <img>
- Dùng next/link thay cho <a> cho navigation nội bộ
- Metadata SEO đặt trong mỗi page.tsx qua export metadata
Tương tự .gitignore, file .claudeignore cho Claude Code biết những file/thư mục nào không cần quan tâm:
# Tạo file .claudeignore tại thư mục gốc dự án
nano .claudeignore
Ví dụ nội dung .claudeignore:
# Thư mục dependencies
node_modules/
vendor/
.venv/
# Thư mục build
dist/
build/
.next/
out/
# File dữ liệu lớn
*.sql
*.dump
*.sqlite
# File nhị phân và media
*.png
*.jpg
*.gif
*.mp4
*.zip
*.tar.gz
# File tạm
*.log
*.tmp
.DS_Store
# File secrets
.env*
*.pem
*.key
credentials.json
Trong phiên làm việc, bạn có thể chuyển đổi giữa các model:
/model
# Hoặc chỉ định model cụ thể
/model claude-sonnet-4-20250514
/model claude-opus-4-0-20250514
Đặt model mặc định qua biến môi trường:
# Dùng Sonnet cho công việc nhẹ, tiết kiệm chi phí
export CLAUDE_MODEL="claude-sonnet-4-20250514"
# Dùng Opus cho công việc phức tạp
export CLAUDE_MODEL="claude-opus-4-0-20250514"
Các lệnh slash sẵn có trong phiên Claude Code:
| Lệnh | Mô tả |
|---|---|
/help |
Hiển thị trợ giúp |
/model |
Chuyển đổi model AI |
/compact |
Nén lịch sử hội thoại để tiết kiệm context |
/clear |
Xóa lịch sử hội thoại |
/init |
Phân tích dự án và tạo file CLAUDE.md |
/cost |
Hiển thị chi phí sử dụng phiên hiện tại |
/memory |
Chỉnh sửa file CLAUDE.md của dự án |
/permissions |
Xem và chỉnh sửa quyền hạn |
/config |
Mở cấu hình |
Esc |
Hủy hành động đang chạy |
Ctrl+C |
Thoát phiên làm việc |
MCP (Model Context Protocol) cho phép mở rộng khả năng của Claude Code bằng cách kết nối với các server bên ngoài.
Cấu hình MCP trong ~/.claude/settings.json (toàn cục):
{
"mcpServers": {
"filesystem": {
"command": "npx",
"args": [
"-y",
"@anthropic-ai/mcp-server-filesystem",
"/home/dev/projects"
]
},
"github": {
"command": "npx",
"args": ["-y", "@anthropic-ai/mcp-server-github"],
"env": {
"GITHUB_TOKEN": "ghp_xxxxxxxxxxxxx"
}
},
"memory": {
"command": "npx",
"args": ["-y", "@anthropic-ai/mcp-server-memory"]
}
}
}
Cấu hình MCP cho từng dự án (.claude/settings.json):
{
"mcpServers": {
"postgres": {
"command": "npx",
"args": [
"-y",
"@anthropic-ai/mcp-server-postgres",
"postgresql://localhost:5432/mydb"
]
}
}
}
Thêm MCP Server qua lệnh:
# Thêm MCP server bằng dòng lệnh
claude mcp add github --env GITHUB_TOKEN=ghp_xxxxxxxxxxxxx -- npx -y @anthropic-ai/mcp-server-github
# Liệt kê các MCP server đang cấu hình
claude mcp list
# Xóa MCP server
claude mcp remove github
Hooks cho phép chạy các script tùy chỉnh tại các thời điểm khác nhau trong vòng đời của Claude Code.
Cấu hình hooks trong .claude/settings.json:
{
"hooks": {
"PreToolUse": [
{
"matcher": "Bash",
"hooks": [
{
"type": "command",
"command": "echo 'Sắp chạy lệnh Bash...'"
}
]
}
],
"PostToolUse": [
{
"matcher": "Write",
"hooks": [
{
"type": "command",
"command": "npm run lint --fix 2>/dev/null || true"
}
]
}
],
"Notification": [
{
"matcher": "",
"hooks": [
{
"type": "command",
"command": "notify-send 'Claude Code' '$CLAUDE_NOTIFICATION_MESSAGE'"
}
]
}
]
}
}
Các sự kiện hook có sẵn:
| Sự kiện | Mô tả |
|---|---|
PreToolUse |
Chạy trước khi Claude thực thi một tool |
PostToolUse |
Chạy sau khi tool thực thi xong |
Notification |
Chạy khi Claude gửi thông báo |
Stop |
Chạy khi Claude dừng sinh phản hồi |
Claude Code lưu trữ ghi chú về dự án trong file CLAUDE.md. Bạn có thể quản lý bộ nhớ này:
# Mở và chỉnh sửa bộ nhớ dự án trong phiên Claude
/memory
Cấu trúc bộ nhớ theo mức ưu tiên (từ cao đến thấp):
<thư-mục-dự-án>/CLAUDE.md — Toàn bộ nhóm dùng chung (commit vào git)<thư-mục-dự-án>/.claude/CLAUDE.md — Cá nhân, không commit~/.claude/CLAUDE.md — Áp dụng mọi dự ánChạy Claude Code trong pipeline CI/CD hoặc script tự động:
# Chạy một lệnh đơn và thoát (dùng flag -p)
claude -p "Phân tích file main.go và tìm lỗi tiềm ẩn"
# Đọc từ stdin với pipe
cat error.log | claude -p "Phân tích log lỗi này và đề xuất cách sửa"
# Kết hợp với các lệnh khác
git diff HEAD~1 | claude -p "Review các thay đổi trong commit này"
Ví dụ dùng trong GitHub Actions:
- name: Claude Code Review
run: |
npm install -g @anthropic-ai/claude-code
git diff $..$ | \
claude -p "Review code changes, tìm bug và đề xuất cải thiện" \
--output-format json > review.json
env:
ANTHROPIC_API_KEY: $
Cài đặt:
Hoặc cài qua dòng lệnh:
code --install-extension anthropic.claude-code
Sử dụng trong VS Code:
Ctrl+Shift+P > gõ “Claude Code”Ctrl+Esc (có thể tùy chỉnh)Cấu hình trong VS Code (settings.json):
{
"claude-code.terminalProfile": "default",
"claude-code.autoOpenOnStartup": false
}
Cài đặt:
Sử dụng:
Claude Code hoạt động tốt nhất khi tích hợp sẵn trong terminal. Một số mẹo cấu hình:
Cấu hình cho iTerm2 (macOS):
Claude Code tự động nhận diện iTerm2 và hỗ trợ thông báo khi hoàn thành task.
Cấu hình cho tmux:
# Thêm vào ~/.tmux.conf để hỗ trợ passthrough
set -g allow-passthrough on
Alias tiện ích (thêm vào ~/.bashrc hoặc ~/.zshrc):
# Alias chạy Claude Code nhanh
alias c="claude"
# Chạy Claude với prompt cụ thể
alias cr="claude -p"
# Chạy Claude để review git diff
alias creview='git diff | claude -p "Review code changes này"'
# Chạy Claude để giải thích lỗi
alias cexplain='claude -p "Giải thích lỗi sau và cách sửa:"'
# Tiếp tục phiên làm việc gần nhất
alias cc="claude --continue"
alias cr="claude --resume"
Áp dụng alias:
source ~/.bashrc
# hoặc
source ~/.zshrc
Cấu hình theme màu sắc:
# Claude Code tự động phát hiện theme terminal
# Có thể ép buộc theme nếu cần
claude config set theme dark
claude config set theme light
Sau khi hoàn tất các bước trên, bạn đã sẵn sàng sử dụng Claude Code. Quy trình tóm tắt:
# 1. Cài đặt
npm install -g @anthropic-ai/claude-code
# 2. Xác thực
export ANTHROPIC_API_KEY="sk-ant-api03-xxxxxxxxxxxxx"
# 3. Vào thư mục dự án
cd ~/projects/my-project
# 4. Tạo file hướng dẫn cho dự án (tuỳ chọn)
claude /init
# 5. Bắt đầu làm việc
claude
Để tìm hiểu thêm, tham khảo tài liệu chính thức tại: https://docs.anthropic.com/en/docs/claude-code