CHƯƠNG 02 / 16

Cài đặt và cấu hình

Cài Claude Code, đăng nhập, chọn model và thiết lập môi trường trên các hệ điều hành.

Cập nhật 21 tháng 7, 202613 phút đọc

Chương này là bản tra cứu nhanh cho việc cài đặt và cấu hình Claude Code: setup, authentication, model config, fast mode, terminal/network config, và những env var quan trọng nhất. Mục tiêu là bạn tìm đúng lệnh hoặc đúng biến cần dùng trong vài giây.

Yêu cầu hệ thống

OS: macOS 13.0+, Windows 10 1809+ (hoặc Windows Server 2019+), Ubuntu 20.04+, Debian 10+, Alpine Linux 3.19+
Hardware: RAM 4 GB+, CPU x64 hoặc ARM64
Shell: Bash, Zsh, PowerShell, hoặc CMD
Network: cần kết nối internet (xem phần Network config)
ripgrep: thường đi kèm sẵn; nếu search lỗi, xem troubleshooting

Cài đặt

Native install (khuyến nghị)

# macOS, Linux, WSL
curl -fsSL https://claude.ai/install.sh | bash

# Windows PowerShell
irm https://claude.ai/install.ps1 | iex

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

Native install tự động update ngầm để giữ bản mới nhất.

Cài một channel hoặc version cụ thể (channel chọn lúc install trở thành default cho auto-update):

curl -fsSL https://claude.ai/install.sh | bash -s stable   # channel stable
curl -fsSL https://claude.ai/install.sh | bash -s 2.1.89    # version cụ thể

Các cách khác

Cách	Lệnh	Auto-update?
Homebrew (stable)	`brew install --cask claude-code`	Không (`brew upgrade claude-code`)
Homebrew (latest)	`brew install --cask claude-code@latest`	Không (`brew upgrade claude-code@latest`)
WinGet	`winget install Anthropic.ClaudeCode`	Không (`winget upgrade Anthropic.ClaudeCode`)
apt / dnf / apk	repo ký sẵn từ `downloads.claude.ai`	Không (dùng system upgrade)
npm	`npm install -g @anthropic-ai/claude-code`	Không (`npm install -g @anthropic-ai/claude-code@latest`)

Lưu ý:

Homebrew có 2 cask: claude-code bám channel stable (chậm ~1 tuần), claude-code@latest bám channel latest.
npm yêu cầu Node.js 22+ (as of v2.1.198). Package npm cài cùng native binary, binary claude không dùng Node lúc runtime. Không dùng sudo npm install -g.
Để nâng cấp npm, dùng @latest; tránh npm update -g (bị giới hạn semver range).

Windows: native vs WSL

Option	Cần gì	Sandboxing	Khi nào dùng
Native Windows	Không (Git for Windows tùy chọn)	Không hỗ trợ	Project và tool Windows-native
WSL 2	WSL 2 bật	Hỗ trợ	Toolchain Linux hoặc cần sandbox
WSL 1	WSL 1 bật	Không hỗ trợ	Khi WSL 2 không dùng được

Trên native Windows, cài Git for Windows để Claude Code dùng được Bash tool (Git Bash). Không có Git for Windows thì dùng PowerShell tool thay thế. Nếu không tự tìm được Git Bash, set path trong settings.json:

{
  "env": {
    "CLAUDE_CODE_GIT_BASH_PATH": "C:\\Program Files\\Git\\bin\\bash.exe"
  }
}

Alpine / musl

Cần cài thêm dependency và tắt ripgrep dựng sẵn:

apk add bash curl libgcc libstdc++ ripgrep

{ "env": { "USE_BUILTIN_RIPGREP": "0" } }

Verify

claude --version   # in ra ví dụ: 2.1.211 (Claude Code)
claude doctor      # chẩn đoán cài đặt + settings (read-only, không mở session)

Update & release channel

Native: auto-update ngầm; claude update để cập nhật ngay.
Channel (autoUpdatesChannel): "latest" (mặc định) nhận feature mới ngay, "stable" chậm ~1 tuần, bỏ qua bản có regression lớn. Đổi qua /config → Auto-update channel hoặc settings:

{ "autoUpdatesChannel": "stable" }

Pin version tối thiểu: minimumVersion chặn auto-update xuống dưới mức đó (đổi sang stable không bị downgrade). Managed settings có thêm requiredMinimumVersion / requiredMaximumVersion để buộc Claude Code từ chối khởi động ngoài khoảng version.
Tắt auto-update: đặt DISABLE_AUTOUPDATER = "1" (vẫn cho claude update), hoặc DISABLE_UPDATES = "1" để chặn cả manual update.

{ "env": { "DISABLE_AUTOUPDATER": "1" } }

Authentication

Đăng nhập

Chạy claude lần đầu sẽ mở browser để login. Cần một trong các account: Claude Pro, Max, Team, Enterprise, hoặc Claude Console (API credits). Gói Claude.ai free không có Claude Code.

Browser không mở? Nhấn c để copy URL login rồi paste vào browser.
Bị hỏi login code (thường gặp trong WSL2/SSH/container)? Paste code vào prompt trong terminal.
Trong session: /login để đổi account, /logout để đăng xuất (reset luôn trạng thái first-launch setup), /status để xem method đang active.

Ngoài ra: cloud provider (Amazon Bedrock, Google Cloud's Agent Platform, Microsoft Foundry) set env var trước khi chạy claude hoặc chọn 3rd-party platform ở prompt login; Cloud gateway (self-hosted Claude apps gateway) đăng nhập bằng SSO qua /login.

Nơi lưu credential

OS	Vị trí
macOS	macOS Keychain (mã hóa)
Linux	`~/.claude/.credentials.json` (mode `0600`)
Windows	`%USERPROFILE%\.claude\.credentials.json`

Nếu set CLAUDE_CONFIG_DIR (Linux/Windows), file .credentials.json nằm dưới thư mục đó.

Thứ tự ưu tiên credential (authentication precedence)

Khi có nhiều credential, Claude Code chọn theo thứ tự:

Cloud provider — khi CLAUDE_CODE_USE_BEDROCK, CLAUDE_CODE_USE_VERTEX, hoặc CLAUDE_CODE_USE_FOUNDRY được set
ANTHROPIC_AUTH_TOKEN — gửi dạng Authorization: Bearer (dùng cho LLM gateway/proxy)
ANTHROPIC_API_KEY — gửi dạng X-Api-Key (API access trực tiếp)
apiKeyHelper — script trả về key (credential động/xoay vòng)
CLAUDE_CODE_OAUTH_TOKEN — OAuth token dài hạn cho CI (tạo bằng claude setup-token)
Subscription OAuth từ /login — mặc định cho Pro/Max/Team/Enterprise

Bẫy thường gặp: có subscription nhưng ANTHROPIC_API_KEY cũng set trong env → API key thắng sau khi được approve, có thể gây lỗi auth nếu key thuộc org bị disable. Chạy unset ANTHROPIC_API_KEY để fallback về subscription; check bằng /status. Một signed-in Claude apps gateway session nằm ngoài list này và ưu tiên cao hơn cả cloud provider.

Token dài hạn cho CI

claude setup-token                  # mở browser, in token ra terminal (không tự lưu)
export CLAUDE_CODE_OAUTH_TOKEN=your-token

Token này gắn với subscription (cần Pro/Max/Team/Enterprise), chỉ làm được model request. apiKeyHelper gọi lại sau 5 phút hoặc khi gặp HTTP 401; đổi chu kỳ bằng CLAUDE_CODE_API_KEY_HELPER_TTL_MS.

Restrict login (enterprise)

Set forceLoginMethod và forceLoginOrgUUID trong [managed settings] để buộc developer login vào đúng một Anthropic organization; Claude Code thoát lúc startup nếu credential thuộc org khác.

Model configuration

Model alias

Alias	Hành vi
`default`	Xóa mọi override, về model khuyến nghị cho account (hoặc org default)
`best`	Fable 5 nếu org có, không thì Opus mới nhất
`fable`	Claude Fable 5 cho task khó/dài nhất
`sonnet`	Sonnet mới nhất, coding hằng ngày
`opus`	Opus mới nhất, reasoning phức tạp
`haiku`	Haiku, task đơn giản
`sonnet[1m]` / `opus[1m]`	Bản 1M token context window cho session dài
`opusplan`	Dùng `opus` trong plan mode, tự chuyển `sonnet` khi execute

Trên Anthropic API, opus → Opus 4.8, sonnet → Sonnet 5. Trên Bedrock/Vertex/Foundry, alias có thể resolve về bản cũ hơn — dùng full model name (vd claude-opus-4-8) hoặc ANTHROPIC_DEFAULT_OPUS_MODEL / ANTHROPIC_DEFAULT_SONNET_MODEL để pin.

Cách set model (theo thứ tự ưu tiên)

Trong session: /model <alias|name> (đổi ngay + lưu làm default), hoặc /model mở picker (Enter = lưu default, s = chỉ session này)
Lúc khởi động: claude --model <alias|name>
Env var: ANTHROPIC_MODEL=<alias|name>
Settings: field model trong settings file

claude --model opus

{ "model": "opus" }

--model và ANTHROPIC_MODEL chỉ áp dụng cho session bạn khởi động cùng — để chạy nhiều model song song ở nhiều terminal, launch mỗi cái với --model riêng thay vì đổi bằng /model.

Effort level

Điều khiển mức reasoning thích ứng. Level: low, medium, high, xhigh, max (tùy model), cộng ultracode (Claude Code setting, session-only). Mặc định high trên Fable 5/Sonnet 5/Opus 4.8.

/effort (mở slider), /effort <level>, /effort auto (về model default)
--effort <level> lúc launch
CLAUDE_CODE_EFFORT_LEVEL (ưu tiên cao nhất) hoặc effortLevel trong settings (max/ultracode không nhận ở đây)
Trong prompt: thêm ultrathink để yêu cầu reasoning sâu cho một turn mà không đổi setting session

Extended context (1M)

Fable 5, Sonnet 5, Opus 4.6+ và Sonnet 4.6 hỗ trợ context 1M token. Trên Anthropic API, Sonnet 5 luôn chạy 1M (không có bản 200K, không cần credits). Tắt hoàn toàn bằng CLAUDE_CODE_DISABLE_1M_CONTEXT=1. Chọn nhanh:

/model opus[1m]
/model claude-opus-4-8[1m]

Fallback model chain

Khi model chính quá tải/không sẵn sàng (không tính lỗi auth/billing/rate-limit), chuyển sang model dự phòng theo thứ tự:

claude --fallback-model sonnet,haiku

{ "fallbackModel": ["claude-sonnet-5", "claude-haiku-4-5"] }

Chain tối đa 3 model sau khi bỏ trùng; --fallback-model ưu tiên hơn fallbackModel setting.

Restrict model (enterprise)

availableModels trong managed/policy settings giới hạn model user được chọn; thêm enforceAvailableModels: true để phủ luôn tùy chọn Default.

{
  "availableModels": ["sonnet", "haiku"],
  "enforceAvailableModels": true
}

Fast mode

Cấu hình tốc độ cao cho Claude Opus (nhanh tới ~2.5x, cost/token cao hơn). Không phải model khác — vẫn là Opus với API config khác. Chỉ hỗ trợ Opus 4.8 và Opus 4.7 (Opus 4.7 sẽ bị gỡ 24/07/2026).

Bật/tắt: /fast (Tab để toggle), hoặc "fastMode": true trong user settings
Bật → tự chuyển sang Opus, hiện icon ↯; tắt → vẫn ở Opus (dùng /model nếu muốn đổi)
Pricing (input/output MTok): Opus 4.8 = $10/$50, Opus 4.7 = $30/$150 — flat trên toàn 1M context
Chỉ dùng qua Anthropic API hoặc subscription (bằng usage credits); không có trên Bedrock/Vertex/Foundry/Claude Platform on AWS. Cần bật usage credits; Team/Enterprise cần Owner enable trước.

Mẹo cost: bật fast mode ngay đầu session thay vì giữa chừng — lần bật đầu tính full fast-mode uncached input price cho toàn bộ context hiện có (càng sâu càng đắt, nhưng chỉ tính một lần/conversation).

Điều khiển liên quan:

fastModePerSessionOptIn: true → mỗi session bắt đầu với fast mode off (kiểm soát cost khi chạy nhiều session)
CLAUDE_CODE_DISABLE_FAST_MODE=1 → tắt hẳn fast mode
Sau LLM gateway/proxy chặn api.anthropic.com: check availability có thể fail → /fast báo lỗi connectivity. Dùng CLAUDE_CODE_SKIP_FAST_MODE_NETWORK_ERRORS=1 (coi check fail là available) hoặc CLAUDE_CODE_SKIP_FAST_MODE_ORG_CHECK=1 (bỏ qua check).

Terminal configuration

Claude Code chạy được ở mọi terminal không cần cấu hình. Phần này chỉ dùng khi có gì đó không đúng ý.

Multiline & Shift+Enter

Xuống dòng không submit: Ctrl+J, hoặc gõ \ rồi Enter — hoạt động ở mọi terminal.
Shift+Enter: nhiều terminal (Ghostty, Kitty, iTerm2, WezTerm, Warp, Apple Terminal, Windows Terminal) chạy sẵn. VS Code, Cursor, Alacritty, Zed cần chạy /terminal-setup một lần. gnome-terminal và JetBrains IDE không hỗ trợ — dùng Ctrl+J.

Option key trên macOS

Nhiều shortcut dùng phím Option (vd Option+Enter). macOS mặc định không gửi Option như modifier — bật "Use Option as Meta Key":

Apple Terminal: Settings → Profiles → Keyboard → "Use Option as Meta Key"
iTerm2: Settings → Profiles → Keys → General → Left/Right Option key = "Esc+"
VS Code: "terminal.integrated.macOptionIsMeta": true

Notification / bell

Mặc định Claude Code chỉ gửi desktop notification ở Ghostty, Kitty, iTerm2. Terminal khác: đặt preferredNotifChannel = "terminal_bell", hoặc cấu hình Notification hook.

{ "preferredNotifChannel": "terminal_bell" }

tmux

Trong tmux, Shift+Enter và notification bị hỏng. Thêm vào ~/.tmux.conf rồi tmux source-file ~/.tmux.conf:

set -g allow-passthrough on
set -s extended-keys on
set -as terminal-features 'xterm*:extkeys'

Fullscreen & flicker

Nếu màn hình nhấp nháy hoặc scroll nhảy, chuyển sang fullscreen rendering: /tui fullscreen (lưu preference). Hoặc set env var:

CLAUDE_CODE_NO_FLICKER=1 claude

Chỉ nhấp nháy mà terminal hỗ trợ synchronized output nhưng không auto-detect (vd Emacs eat): CLAUDE_CODE_FORCE_SYNC_OUTPUT=1.

Theme & Vim mode

Theme: /theme hoặc /config. Custom theme là JSON trong ~/.claude/themes/.
Vim keybindings cho prompt: /config → Editor mode, hoặc "editorMode": "vim".

Network configuration

Tất cả env var ở phần này cũng set được trong settings.json (block env).

Proxy

export HTTPS_PROXY=https://proxy.example.com:8080     # khuyến nghị
export HTTP_PROXY=http://proxy.example.com:8080
export NO_PROXY="localhost,192.168.1.1,.example.com"  # bypass; "*" = bypass tất cả

Basic auth nhét vào URL: http://username:password@proxy.example.com:8080. Không hỗ trợ SOCKS proxy; với NTLM/Kerberos dùng LLM gateway.

CA certificate

Mặc định tin cả bundled Mozilla CA và OS trust store. TLS-inspection proxy (CrowdStrike Falcon, Zscaler) chạy được khi root cert nằm trong OS trust store.
CLAUDE_CODE_CERT_STORE = bundled,system (mặc định); đặt bundled hoặc system để thu hẹp.
Custom CA: export NODE_EXTRA_CA_CERTS=/path/to/ca-cert.pem

mTLS

export CLAUDE_CODE_CLIENT_CERT=/path/to/client-cert.pem
export CLAUDE_CODE_CLIENT_KEY=/path/to/client-key.pem
export CLAUDE_CODE_CLIENT_KEY_PASSPHRASE="your-passphrase"   # nếu key mã hóa

Background agents

Background agent chạy trong supervisor process dùng chung, không kế thừa env của shell hiện tại một cách đáng tin cậy. Vì vậy proxy/CA/mTLS var nên đặt trong block env của ~/.claude/settings.json (hoặc managed settings), không chỉ export trong shell.

URL cần allowlist

URL	Dùng cho
`api.anthropic.com`	Claude API request
`claude.ai`	Xác thực account claude.ai
`platform.claude.com`	Xác thực account Console
`mcp-proxy.anthropic.com`	MCP connector từ claude.ai
`downloads.claude.ai`	Native installer/updater; plugin download
`storage.googleapis.com`	Metadata plugin; artifact upload
`raw.githubusercontent.com`	Changelog cho `/release-notes`

Bảng env var quan trọng

Env var	Mục đích
`ANTHROPIC_MODEL`	Model dùng (alias hoặc name); override `model` setting
`ANTHROPIC_API_KEY`	API key gửi dạng `X-Api-Key`; đè subscription khi được approve
`ANTHROPIC_AUTH_TOKEN`	Giá trị header `Authorization` (tự thêm `Bearer` )
`ANTHROPIC_BASE_URL`	Đổi endpoint API để route qua proxy/gateway (không đổi model)
`ANTHROPIC_DEFAULT_OPUS_MODEL`	Version cụ thể mà alias `opus`/Default resolve tới
`ANTHROPIC_DEFAULT_SONNET_MODEL`	Tương tự cho `sonnet`
`ANTHROPIC_DEFAULT_HAIKU_MODEL`	Tương tự cho `haiku`
`CLAUDE_CODE_OAUTH_TOKEN`	OAuth token dài hạn cho CI/SDK (tạo bằng `claude setup-token`)
`CLAUDE_CODE_USE_BEDROCK`	Dùng Amazon Bedrock
`CLAUDE_CODE_USE_VERTEX`	Dùng Google Cloud's Agent Platform
`CLAUDE_CODE_USE_FOUNDRY`	Dùng Microsoft Foundry
`CLAUDE_CODE_EFFORT_LEVEL`	Effort level (`low`…`max`, `auto`); ưu tiên cao nhất
`CLAUDE_CODE_SUBAGENT_MODEL`	Model cho subagent (`inherit` = như bỏ trống)
`CLAUDE_CONFIG_DIR`	Đổi thư mục config (mặc định `~/.claude`)
`CLAUDE_CODE_GIT_BASH_PATH`	Windows: path tới `bash.exe` của Git Bash
`API_TIMEOUT_MS`	Timeout API request (mặc định 600000 = 10 phút)
`BASH_DEFAULT_TIMEOUT_MS`	Timeout mặc định cho bash command dài (120000 = 2 phút)
`BASH_MAX_TIMEOUT_MS`	Timeout tối đa model được set cho bash (600000)
`BASH_MAX_OUTPUT_LENGTH`	Số ký tự tối đa của bash output trước khi lưu ra file
`MAX_THINKING_TOKENS`	Override budget extended thinking; `=0` tắt thinking (trừ Fable 5)
`MCP_TIMEOUT`	Timeout khởi động MCP server (mặc định 30000 = 30s)
`USE_BUILTIN_RIPGREP`	`0` = dùng `rg` hệ thống thay vì bản đi kèm
`DISABLE_AUTOUPDATER`	`1` = tắt auto-update ngầm (`claude update` vẫn chạy)
`DISABLE_UPDATES`	`1` = chặn cả manual update, mạnh hơn `DISABLE_AUTOUPDATER`
`DISABLE_TELEMETRY`	`1` = opt out telemetry
`DISABLE_ERROR_REPORTING`	`1` = opt out error reporting
`DISABLE_COST_WARNINGS`	`1` = tắt cảnh báo cost
`DISABLE_PROMPT_CACHING`	`1` = tắt prompt caching cho mọi model
`CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC`	Non-empty = tắt mọi traffic không thiết yếu (update, telemetry, error report, feedback, release notes, gateway model discovery)
`CLAUDE_CODE_ENABLE_TELEMETRY`	`1` = bật OpenTelemetry (cần trước khi cấu hình OTel exporter)
`CLAUDE_CODE_DISABLE_1M_CONTEXT`	`1` = bỏ các bản 1M context khỏi picker
`CLAUDE_CODE_DISABLE_FAST_MODE`	`1` = tắt hẳn fast mode
`CLAUDE_CODE_NO_FLICKER`	`1` = bật fullscreen rendering (chống nhấp nháy)
`HTTPS_PROXY` / `HTTP_PROXY` / `NO_PROXY`	Proxy config
`NODE_EXTRA_CA_CERTS`	Path tới custom CA cert
`CLAUDE_CODE_CLIENT_CERT` / `CLAUDE_CODE_CLIENT_KEY`	Client cert/key cho mTLS

Precedence: khi một hành vi có cả env var và settings field, env var thắng (vd ANTHROPIC_MODEL đè model). Khi cùng biến set trong shell lẫn env block của settings, giá trị trong settings file thắng. Giữa các settings file, theo settings precedence (managed > user/project).

Set env var trong settings file:

{
  "env": {
    "API_TIMEOUT_MS": "1200000",
    "BASH_DEFAULT_TIMEOUT_MS": "300000"
  }
}

Xem thêm

content/en/docs/claude-code/setup.md — cài đặt, package manager, uninstall, binary integrity
content/en/docs/claude-code/quickstart.md — session đầu tiên, lệnh thiết yếu
content/en/docs/claude-code/authentication.md — login, credential, team/enterprise auth
content/en/docs/claude-code/model-config.md — model alias, effort, fallback, restrict model
content/en/docs/claude-code/fast-mode.md — fast mode chi tiết, pricing, gateway
content/en/docs/claude-code/terminal-config.md — Shift+Enter, tmux, theme, Vim mode
content/en/docs/claude-code/network-config.md — proxy, CA, mTLS, allowlist URL
content/en/docs/claude-code/env-vars.md — reference đầy đủ toàn bộ env var