claude-help

Hướng dẫn cài đặt và cấu hình Claude Code CLI

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.


1. Yêu cầu hệ thống

Hệ điều hành hỗ trợ

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ợ

Phần mềm cần thiết

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

Yêu cầu phần cứng


2. Cài đặt Claude Code

Cách 1: Cài qua npm (phổ biến nhất)

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

Cách 2: Cài qua npx (chạy trực tiếp không cần cài toàn cục)

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.

Cách 3: Cài qua Homebrew (macOS)

brew install claude-code

Xử lý lỗi thường gặp khi cài đặt

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

3. Xác thực và API Key

Cách 1: Đăng nhập tương tác (khuyến nghị cho người dùng cá nhân)

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

Cách 2: Sử dụng API Key trực tiếp

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 .env vào .gitignore để tránh lộ API Key:

echo '.env' >> .gitignore

Cách 3: Dùng với các nhà cung cấp API khác

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"

Xác minh xác thực

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

Các biến môi trường quan trọng

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

4. Cấu hình cơ bản

Cấu trúc thư mục ~/.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.md toàn cục

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 settings.json

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)"
    ]
  }
}

Chế độ quyền hạn (Permission Modes)

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 *)"
    ]
  }
}

Cấu hình cấp dự án với .claude/settings.json

Ngoà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.json nên được commit vào git để cả nhóm dùng chung.


5. Cấu hình dự án

Tạo file CLAUDE.md cho dự án

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

Ví dụ CLAUDE.md cho dự án Node.js/TypeScript

# 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

Ví dụ CLAUDE.md cho dự án Go

# 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

Ví dụ CLAUDE.md cho dự án Next.js

# 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

File .claudeignore

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

6. Cấu hình nâng cao

Chọn model (lệnh /model)

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"

Phím tắt và lệnh trong phiên làm việc

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

Cấu hình MCP Servers

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

Cấu hình Hooks

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

Cấu hình bộ nhớ (Memory)

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

  1. Dự án: <thư-mục-dự-án>/CLAUDE.md — Toàn bộ nhóm dùng chung (commit vào git)
  2. Dự án cá nhân: <thư-mục-dự-án>/.claude/CLAUDE.md — Cá nhân, không commit
  3. Toàn cục: ~/.claude/CLAUDE.md — Áp dụng mọi dự án

Chế độ chạy không tương tác (Headless / CI/CD)

Chạ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: $

7. IDE Integration

VS Code Extension

Cài đặt:

  1. Mở VS Code
  2. Vào Extensions (Ctrl+Shift+X)
  3. Tìm kiếm “Claude Code”
  4. Nhấn Install

Hoặc cài qua dòng lệnh:

code --install-extension anthropic.claude-code

Sử dụng trong VS Code:

Cấu hình trong VS Code (settings.json):

{
  "claude-code.terminalProfile": "default",
  "claude-code.autoOpenOnStartup": false
}

JetBrains Plugin (IntelliJ, WebStorm, GoLand, PyCharm…)

Cài đặt:

  1. Mở IDE JetBrains
  2. Vào Settings > Plugins > Marketplace
  3. Tìm kiếm “Claude Code”
  4. Nhấn Install và khởi động lại IDE

Sử dụng:

Terminal Integration

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

Tổng kết

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