Cấu hình Claude Code – Hướng dẫn thiết lập chi tiết
Các thiết lập cấu hình cần thiết và tùy chọn setup để tối ưu hóa trải nghiệm Claude Code của bạn.
Thiết lập API Key
Claude Code cần API key của Anthropic để hoạt động. Thiết lập bằng một trong những cách sau:
# Tùy chọn 1: Biến môi trường (khuyến nghị)
export ANTHROPIC_API_KEY="your-api-key-here"
# Tùy chọn 2: Thêm vào shell profile
echo 'export ANTHROPIC_API_KEY="your-api-key-here"' >> ~/.bashrc
source ~/.bashrc
Lựa chọn Model
Claude Code hỗ trợ nhiều model khác nhau. Bạn có thể chỉ định model nào sẽ sử dụng:
Claude 4 Sonnet: Hiệu suất cân bằng và tốc độ mới nhất
export ANTHROPIC_MODEL="claude-sonnet-4-20250514"
Claude 4 Opus (và opus 4.1) : Khả năng tối đa cho các tác vụ phức tạp
export ANTHROPIC_MODEL="claude-opus-4-20250514"
Claude 3.5 Haiku: Nhanh nhất và hiệu quả về chi phí
export ANTHROPIC_MODEL="claude-3-5-haiku-20241022"
⚠️ Giới hạn quan trọng: Claude 3.5 Haiku
Mặc dù Haiku tiết kiệm chi phí, nhưng nó có những hạn chế đáng kể khi sử dụng Claude Code:
❌ Những hạn chế:
- Khả năng suy luận giảm – Gặp khó khăn với kế hoạch đa bước phức tạp và quyết định kiến trúc
- Hiểu ngữ cảnh hạn chế – Ít hiệu quả khi phân tích codebase lớn và duy trì ngữ cảnh qua nhiều file
- Phân tích code đơn giản – Có thể bỏ sót các bug tinh tế, dependencies hoặc pattern phức tạp
- Chỉ refactoring cơ bản – Không phù hợp cho việc tái cấu trúc tinh vi hoặc triển khai tính năng
- Kiến thức framework hạn chế – Ít hiệu quả với các framework phức tạp hoặc pattern coding mới
✅ Trường hợp sử dụng khuyến nghị cho Haiku:
- Chỉnh sửa file đơn giản
- Sửa lỗi cú pháp cơ bản
- Câu hỏi code nhanh
- Học cơ bản Claude Code trước khi nâng cấp
💡 Khuyến nghị: Đối với công việc phát triển nghiêm túc, Claude 4 Sonnet hoặc Opus 4.1 cung cấp kết quả tốt hơn đáng kể và xứng đáng với chi phí bổ sung.
Phương pháp thay thế:
Bạn cũng có thể chỉ định model trực tiếp khi khởi động Claude Code:
claude --model claude-sonnet-4-20250514
claude --model claude-opus-4-20250514
claude --model claude-3-5-haiku-20241022
Cấu hình MCP
Model Context Protocol (MCP) cho phép Claude Code kết nối với các công cụ và dịch vụ bên ngoài. Cấu hình MCP servers để mở rộng khả năng của Claude:
Thiết lập MCP Server
Cấu hình MCP có thể được lưu trữ tại nhiều vị trí:
- Riêng cho dự án:
.claude/settings.local.json(trong thư mục dự án) - Local cho user:
~/.claude/settings.local.json - Global cho user:
~/.claude/settings.json - Claude.json chính:
~/.claude.json - File MCP riêng:
~/.claude/mcp_servers.json
Ví dụ cấu hình MCP:
// Ví dụ: ~/.claude.json (khuyến nghị cho độ tin cậy)
{
"projects": {
"/path/to/your/project": {
"mcpServers": {
"filesystem": {
"command": "npx",
"args": ["-y", "@modelcontextprotocol/server-filesystem", "/Users/username/Desktop", "/path/to/allowed/dir"]
},
"memory": {
"command": "npx",
"args": ["-y", "@modelcontextprotocol/server-memory"]
},
"fetch": {
"command": "npx",
"args": ["-y", "@modelcontextprotocol/server-fetch"]
}
}
}
}
}
📝 Lưu ý: Nếu theo ví dụ này, hãy đảm bảo cập nhật đúng cấu hình projects.
Allowed Tools (Công cụ được phép)
Thiết lập Allowed Tools
Cấu hình allowed tools có thể được lưu trữ tại nhiều vị trí:
- Riêng cho dự án:
.claude/settings.local.json(trong thư mục dự án) - Local cho user:
~/.claude/settings.local.json - Global cho user:
~/.claude/settings.json - Claude.json chính:
~/.claude.json
Ví dụ cấu hình Allowed Tools:
// Ví dụ: ~/.claude.json (khuyến nghị cho độ tin cậy)
{
"projects": {
"/path/to/your/project": {
"mcpServers": {
"filesystem": {
"command": "npx",
"args": ["-y", "@modelcontextprotocol/server-filesystem", "/Users/username/Desktop", "/path/to/allowed/dir"]
}
},
"allowedTools": [
"Task",
"Bash", // ⚠️ Nguy hiểm: cho phép tất cả lệnh hệ thống
"Bash(git log:*)", // An toàn hơn: chỉ cho phép lệnh git log
"Glob",
"Grep",
"LS",
"Read",
"Edit",
"MultiEdit",
"Write",
"WebFetch",
"WebSearch"
]
}
}
}
📝 Lưu ý: Nếu theo ví dụ này, hãy đảm bảo cập nhật đúng cấu hình projects.
Nhiều vị trí cấu hình tồn tại do tương thích legacy – bạn có thể gặp phải tên file và vị trí thư mục khác nhau.
💡 Khuyến nghị: Sử dụng ~/.claude.json cho độ tin cậy như trong các ví dụ trên.
Thư mục làm việc bổ sung
Claude Code có thể truy cập nhiều thư mục ngoài thư mục làm việc hiện tại bằng cách sử dụng CLI argument --add-dir (được thêm vào v1.0.18). Điều này cho phép bạn làm việc trên nhiều dự án hoặc tham khảo tài nguyên bên ngoài mà không cần thay đổi thư mục.
Cách sử dụng
# Thêm một thư mục bổ sung
claude --add-dir /path/to/other/project
# Kết hợp với các tùy chọn khác
claude --add-dir ~/shared/libraries
# Sử dụng với print mode cho scripting
claude --add-dir ../backend -p "Validate that API calls in the current directory match endpoints defined in ../backend"
Các trường hợp sử dụng phổ biến
🔄 Dự án Multi-Repository
# Làm việc trên frontend trong khi tham chiếu backend API
claude --add-dir ../backend-api
📚 Tài nguyên chia sẻ
# Truy cập cấu hình hoặc tài liệu chung
claude --add-dir ~/company/shared-configs
📝 Lưu ý quan trọng:
- Thư mục làm việc hiện tại luôn được bao gồm
- File CLAUDE.md dường như không được đọc tự động từ các thư mục bổ sung được thêm qua
--add-dir
Lợi ích của tính năng này
Tính năng này cải thiện đáng kể việc điều phối workflow bằng cách cho phép Claude:
✅ Những khả năng mới:
- Làm việc đồng thời trên nhiều repository – duy trì ngữ cảnh và áp dụng thay đổi nhất quán
- Tham chiếu trực tiếp code chung từ thư viện hoặc repository cấu hình
- Tạm thời expose codebase để Claude phân tích hoặc sửa đổi mà không cần thay đổi thư mục
Thay vì phải xoay xở với nhiều session hoặc copy file, bạn có thể kết hợp nhiều repository trong cùng một cấu trúc workflow – điều phối các hoạt động multi-repository phức tạp trong một session duy nhất, có nhận thức ngữ cảnh.
🎯 Phương pháp này duy trì sự tách biệt các mối quan tâm trong khi cho phép hợp tác cross-project khi cần thiết.