Claude Code từ zero đến thành thạo · Phần 22 — Troubleshooting, glossary và Agent SDK

Phần cuối của series gồm ba thứ bạn sẽ quay lại nhiều nhất: bảng tra khi có sự cố, glossary toàn bộ thuật ngữ, và ranh giới giữa CLI và Agent SDK.

Bắt đầu ở đâu khi có sự cố

Trước khi đọc bảng dưới: chạy /doctor trong Claude Code để nó tự kiểm cài đặt, settings, extension và mức dùng context — nó đề xuất cách sửa và áp dụng sau khi bạn xác nhận. Nếu claude không khởi động được thì chạy claude doctor từ shell. Chạy /mcp để kiểm trạng thái MCP server.

Triệu chứng	Đi tới
command not found, cài fail, vấn đề PATH, EACCES, lỗi TLS	Trang troubleshoot-install
Vòng lặp đăng nhập, lỗi OAuth, 403 Forbidden, “organization disabled”, credential của Bedrock/Agent Platform/Foundry	troubleshoot-install, mục login
Settings không áp dụng, hook không kích hoạt, MCP server không nạp	Trang debug-your-config
Phiên khởi động ở auto mode, hoặc Claude sửa file và chạy lệnh mà không hỏi	Phần 7 — phiên khởi động ở mode nào
API Error: 5xx, 529 Overloaded, 429, lỗi validate request	Trang errors
model not found hoặc you may not have access to it	errors, mục về model được chọn
VS Code extension không kết nối hoặc không phát hiện Claude	Trang vs-code
Plugin JetBrains hoặc IDE không được phát hiện	Trang jetbrains
CPU hoặc bộ nhớ cao, phản hồi chậm, treo, tìm kiếm không ra file	Mục dưới đây

---

Hiệu năng và ổn định

CPU hoặc bộ nhớ cao

Bốn bước, theo thứ tự:

1. Dùng /compact thường xuyên để giảm kích thước context. Nếu nó trả về Not enough messages to compact. thì hội thoại có quá ít lượt để tóm tắt — việc này xảy ra được cả khi context đã đầy, nếu một lần dán lớn duy nhất làm đầy nó.
2. Đóng và khởi động lại Claude Code giữa các task lớn.
3. Thêm các thư mục build lớn vào .gitignore.
4. Khởi động lại với claude --safe-mode để kiểm xem nguồn gốc có phải là một plugin, MCP server, hay hook. Nó tắt mọi tuỳ biến cho phiên đó; nếu mức dùng giảm thì nguyên nhân nằm trong cấu hình của bạn.

Nếu bộ nhớ vẫn cao sau các bước trên, chạy /heapdump. Nó ghi hai file vào ~/Desktop: một heap snapshot <session-id>.heapsnapshot và một bản phân rã bộ nhớ <session-id>-diagnostics.json. Lệnh này không hiện trong menu lệnh — phải gõ đầy đủ.

File .heapsnapshot chứa mọi chuỗi trong tiến trình, gồm toàn bộ hội thoại và credential của bạn. Đừng đính nó vào issue công khai và đừng chia sẻ nó.

Khi báo lỗi, chỉ đính file -diagnostics.json — nó mang các thống kê phía sau bản tóm tắt và không có nội dung hội thoại hay credential nào.

Bản tóm tắt in ra trong hội thoại cho biết phần lớn bộ nhớ nằm ở JS heap — thứ snapshot bắt được — hay ở native memory, thứ nó không bắt được. Nếu là JS heap thì bạn tự điều tra được: mở file .heapsnapshot trong Chrome DevTools ở Memory → Load và sắp theo retained size.

Auto-compaction dừng với lỗi thrashing

Thấy Autocompact is thrashing: the context refilled to the limit... nghĩa là compaction tự động đã thành công nhưng một file hoặc output tool lập tức làm đầy lại context window vài lần liên tiếp. Claude Code dừng thử lại để không tiêu API call vào một vòng lặp không tiến triển.

Bốn cách phục hồi, theo thứ tự nên thử:

1. Bảo Claude đọc file quá lớn theo từng phần nhỏ — một dải dòng cụ thể hoặc một hàm — thay vì cả file
2. Chạy /compact kèm trọng tâm loại bỏ output lớn, ví dụ /compact keep only the plan and the diff
3. Chuyển việc với file lớn sang một subagent để nó chạy trong context window riêng (phần 16)
4. Chạy /clear nếu phần hội thoại trước không còn cần

Lệnh treo hoặc đóng băng

Bấm Ctrl+C để thử huỷ thao tác hiện tại. Nếu vẫn không phản hồi thì đóng terminal và khởi động lại.

Khởi động lại không làm mất hội thoại. Chạy claude --resume trong cùng thư mục để lấy lại phiên.

Chữ bị méo hoặc hỏng trong terminal tích hợp của editor

Nếu ký tự hiện thành ô vuông, vết nhoè, hoặc glyph sai khi chạy Claude Code trong terminal tích hợp của VS Code, Cursor hay Devin Desktop, nguyên nhân thường là GPU renderer của terminal. Chạy /terminal-setup trong Claude Code để đặt terminal.integrated.gpuAcceleration thành "off", rồi reload cửa sổ.

Bảng lớn bị cắt trong terminal

Một bảng Markdown hơn 200 dòng render 200 dòng đầu rồi một dòng … N more rows not shown. Chỉ phần hiển thị bị chặn: bảng đầy đủ vẫn nằm trong hội thoại, và /copy copy mọi dòng. Với bảng quá lớn để đọc trong terminal thì bảo Claude ghi nó ra file.

Tìm kiếm không ra file

Nếu tool Search, @file mention, custom agent hay custom skill không tìm thấy file, binary ripgrep đi kèm có thể không chạy được trên hệ của bạn. Cài package ripgrep của platform rồi bảo Claude Code dùng nó:

brew install ripgrep        # macOS
sudo apt install ripgrep    # Ubuntu/Debian
apk add ripgrep             # Alpine
pacman -S ripgrep           # Arch

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

Xác nhận bằng claude doctor — dòng Search phải hiện đường dẫn ripgrep hệ thống của bạn thay vì OK (bundled).

Tìm kiếm chậm hoặc thiếu kết quả trên WSL

Chi phí đọc đĩa khi làm việc xuyên filesystem trên WSL có thể cho ít kết quả khớp hơn mong đợi. Tìm kiếm vẫn hoạt động, chỉ trả về ít kết quả hơn so với filesystem gốc.

claude doctor báo Search là OK trong trường hợp này — nên nó không giúp bạn phát hiện vấn đề.

Ba cách: gửi truy vấn tìm kiếm cụ thể hơn (nêu thư mục hoặc loại file); chuyển project sang filesystem Linux (/home/ thay vì /mnt/c/); hoặc chạy Claude Code native trên Windows thay vì qua WSL.

Xin thêm trợ giúp

Chạy /doctor và /mcp; dùng /feedback để báo vấn đề trực tiếp cho Anthropic; kiểm GitHub repository xem có issue đã biết; và hỏi thẳng Claude về năng lực và tính năng của nó — nó có sẵn quyền truy cập tài liệu của mình.

---

Glossary

Bảng thuật ngữ đầy đủ, kèm số phần trong series để bạn tra ngược.

Thuật ngữ	Nghĩa
Agentic coding	Workflow mà AI đọc file, chạy lệnh và thay đổi một cách tự chủ trong lúc bạn xem, lái, hoặc rời đi — khác với trợ lý dạng chat chỉ trả lời bằng text mà bạn phải tự áp dụng. (Phần 2)
Agentic harness	Bộ tool, việc quản lý context, và môi trường thực thi biến một language model thành một coding agent có năng lực. Claude Code là harness; Claude là model bên trong nó. (Phần 2)
Agentic loop	Vòng lặp Claude đi qua ở mọi task: gather context → take action → verify results, lặp tới khi xong. (Phần 2)
Agent teams	Nhiều phiên Claude Code độc lập do một team lead điều phối, có task list dùng chung và nhắn tin ngang hàng. Thử nghiệm, tắt mặc định. (Phần 17)
Artifact	Một trang web tương tác Claude Code xuất bản từ phiên của bạn ra một URL riêng tư trên claude.ai.
Auto memory	Ghi chú Claude tự viết cho mình, lưu theo git repository. 200 dòng hoặc 25 KB đầu của MEMORY.md nạp ở đầu mọi phiên. Đây là bản đối ứng do Claude viết của CLAUDE.md do bạn viết. (Phần 4)
Auto mode	Permission mode nơi một classifier model riêng duyệt hành động thay bạn. Classifier không bao giờ thấy kết quả tool, nên chỉ dẫn bị inject không ảnh hưởng được quyết định của nó. (Phần 7)
Bare mode	Với --bare, Claude Code khởi động không nạp hook, skill, plugin, MCP server, auto memory hay CLAUDE.md. Khuyến nghị cho CI và script. (Phần 19)
Bundled skills	Playbook dạng prompt đi kèm Claude Code như /batch, /code-review, /debug, /loop. Khác built-in command vốn thực thi logic cố định, bundled skill đưa Claude một prompt chi tiết và để nó tự điều phối. (Phần 6, 12)
Channel	Một MCP server đẩy sự kiện vào phiên đang chạy để Claude phản ứng với thứ xảy ra khi bạn rời terminal. Có thể hai chiều.
Checkpoint	Điểm phục hồi tạo ở mỗi prompt bạn gửi. Tách biệt với git và không theo dõi thay đổi qua tool Bash. (Phần 8)
.claude directory	Nơi Claude Code đọc cấu hình theo project: settings, hook, skill, subagent, rule, auto memory. (Phần 4)
CLAUDE.md	File markdown chứa chỉ dẫn bền vững bạn viết, nạp ở đầu mọi phiên như một tin nhắn user sau system prompt. CLAUDE.md ở gốc project sống sót qua compaction và được đọc lại tươi từ đĩa. (Phần 4)
Command	Chỉ dẫn tái dùng bạn gọi bằng /name. Hai nghĩa khác không liên quan: subcommand của CLI claude như claude mcp add, và trường command của một stdio MCP server entry. (Phần 6)
Compaction	Tự tóm tắt hội thoại khi context window gần giới hạn. Output tool cũ được dọn trước, rồi hội thoại mới bị tóm tắt. (Phần 3)
Connector	Một MCP server thêm vào tài khoản claude.ai của bạn thay vì cấu hình trong Claude Code. (Phần 14)
Context window	Bộ nhớ làm việc của một phiên. (Phần 3)
Dispatch	Bộ định tuyến task khởi từ điện thoại, sinh một phiên Claude Code trong Desktop app.
Effort level	Điều khiển Claude dùng bao nhiêu ngân sách thinking của adaptive reasoning ở mỗi lượt. (Phần 21)
Extended thinking	Phần suy luận từng bước hiện ra mà model thực hiện trước khi trả lời. (Phần 21)
Hook	Handler do bạn định nghĩa, thực thi tự động ở một điểm cụ thể trong vòng đời Claude Code. Hook là tất định: chúng kích hoạt ở các mốc cố định chứ không theo ý model. Ba cấp cấu hình: hook event, matcher, hook handler. (Phần 13)
Managed settings	Settings do IT/DevOps cưỡng chế toàn tổ chức. User và project settings không ghi đè được. (Phần 21)
MCP	Chuẩn mở để nối AI tool tới nguồn dữ liệu và dịch vụ bên ngoài. (Phần 14)
MCP server	Một program cấp cho Claude tool, prompt, hoặc resource qua MCP. (Phần 14)
MCP Tool Search	Cơ chế tiết kiệm context bằng cách hoãn schema của MCP tool tới khi cần. Chỉ tên tool nạp lúc khởi động. (Phần 14)
Non-interactive mode	Chạy một prompt rồi thoát, gọi bằng -p hoặc --print. Tên cũ là headless mode. (Phần 19)
Output style	Cấu hình sửa system prompt để đổi hành vi, giọng, hoặc định dạng phản hồi. Nó tắt các phần chỉ dành cho software engineering của system prompt mặc định, khác CLAUDE.md vốn được đưa vào như một tin nhắn user. (Phần 21)
Permission mode	Hành vi phê duyệt nền của phiên. Sáu mode: default, acceptEdits, plan, auto, dontAsk, bypassPermissions. (Phần 7)
Permission rule	Một entry settings cho phép, hỏi, hoặc từ chối một lời gọi tool. Xét theo deny → ask → allow, khớp đầu tiên thắng. (Phần 7)
Plan mode	Permission mode nơi Claude nghiên cứu và đề xuất thay đổi mà không sửa file source. (Phần 7)
Plugin	Một bundle gồm skill, hook, subagent và MCP server, đóng thành một đơn vị cài đặt được. (Phần 15)
Project trust	Hộp thoại chấp nhận một thư mục trước khi Claude Code nạp cấu hình của nó.
Prompt injection	Chỉ dẫn thù địch nhúng trong một file, trang web, hoặc kết quả tool, cố lái Claude sang hành động bạn không bao giờ yêu cầu.
Remote Control	Cách tiếp tục một phiên local từ điện thoại hoặc trình duyệt qua claude.ai. Code và file vẫn ở máy bạn; chỉ giao diện là ở xa. Khác Claude Code on the web, vốn chạy trong sandbox cloud. (Phần 1)
Rules	File chỉ dẫn dạng module trong .claude/rules/, nạp cùng CLAUDE.md. Gắn được vào path bằng frontmatter paths:. (Phần 4)
Sandboxing	Cô lập filesystem và network ở mức hệ điều hành cho tool Bash. Là một tầng riêng so với permission rule. (Phần 7)
Session	Một hội thoại gắn với thư mục hiện tại, có context window độc lập riêng. (Phần 8)
Settings layers	Thứ tự Claude Code đọc cấu hình, từ cao xuống thấp: managed policy → tham số dòng lệnh → local → project → user. Array gộp giữa các tầng; scalar ở tầng cao ghi đè tầng thấp. (Phần 21)
Skill	Một file SKILL.md chứa chỉ dẫn, kiến thức, hoặc một workflow mà Claude thêm vào bộ đồ nghề. Skill là bản kế nhiệm được khuyến nghị của custom command. (Phần 12)
Subagent	Trợ lý chuyên biệt chạy trong context window riêng với system prompt riêng, quyền truy cập tool riêng, và permission độc lập. Khác agent team, nơi mỗi agent là một phiên độc lập đầy đủ bạn nói chuyện trực tiếp được. (Phần 16)
Surface	Bất kỳ chỗ bạn truy cập Claude Code: CLI, VS Code, JetBrains, Desktop, claude.ai. Mọi surface dùng chung một engine. (Phần 1)
Teleport	Lệnh /teleport kéo một phiên Claude Code cloud về terminal local. Chiều ngược lại là --cloud. (Phần 1)
Tool	Một hành động Claude thực hiện được. Tool là thứ làm Claude Code trở thành agentic — không có chúng, Claude chỉ trả lời bằng text. (Phần 2)
Turn	Một phản hồi hoàn chỉnh của Claude trong một phiên. Bắt đầu khi bạn gửi tin nhắn và kết thúc khi Claude trả lời xong, với bao nhiêu tool call ở giữa cũng được. Stop hook kích hoạt ở cuối mỗi lượt. (Phần 13)
Verification loop	Cách một phiên biết công việc thực sự xong chứ không chỉ trông có vẻ hợp lý. Bạn cho Claude một thứ nó chạy kiểm được, và nó lặp tới khi kiểm tra pass. Đây là điều kiện tiên quyết của /goal, của các lượt chạy không người trông, và của dynamic workflow — không có nó thì thứ duy nhất quyết định agent đã xong chính là agent. (Phần 10, 19)
Worktree isolation	Chế độ cô lập chạy Claude trong một git worktree riêng dưới .claude/worktrees/. (Phần 17)

Ba thuật ngữ đã đổi tên

Tên cũ	Bây giờ gọi là	Ghi chú
Headless mode	Non-interactive mode	Cùng cờ -p, cùng hành vi
Custom commands	Skills	File .claude/commands/ vẫn chạy
Slash commands	Commands	Bỏ chữ “slash” khỏi cách gọi của sản phẩm

---

Agent SDK: khi nào vượt khỏi CLI

Một agent là một ứng dụng hoàn thành một task bằng cách tự lập các bước của mình và gọi tool để đọc file, chạy lệnh, hoặc sửa code. Agent SDK cho bạn đúng bộ tool, agent loop và việc quản lý context đang vận hành Claude Code, lập trình được bằng Python và TypeScript.

Nếu bạn đang…	Dùng	Vì sao
Xây một agent mà không phải tự hiện thực tool loop	Agent SDK	Một library chạy agent loop trong tiến trình của bạn, bằng Python hoặc TypeScript
Phát triển tương tác hoặc chạy task một lần từ terminal	Claude Code CLI	Giao diện terminal, xây cho việc dùng tương tác hằng ngày
Gọi API trực tiếp và tự hiện thực tool loop	Client SDK	Truy cập trực tiếp Anthropic API chứ không phải Claude Code
Chạy agent dài hoặc bất đồng bộ mà không tự quản sandbox hay hạ tầng phiên	Managed Agents	REST API được host; Anthropic chạy cả agent và sandbox

SDK chỉ có dưới dạng library cho Python và TypeScript. Muốn điều khiển cùng agent loop đó từ ngôn ngữ khác thì chạy CLI như một subprocess với cờ -p và --output-format json (phần 19).

Mọi thứ làm Claude Code mạnh đều có trong SDK: bộ tool built-in; hook; subagent; MCP; permission; session (giữ ngữ cảnh qua các lượt, resume hoặc fork sau); skill, command và memory — nạp tự động từ .claude/ của project và từ ~/.claude/, y như Claude Code; và plugin.

Nghĩa là ranh giới rất rõ: nếu bạn đang xây một sản phẩm có agent bên trong, dùng SDK. Nếu bạn đang làm việc, dùng CLI. Và cấu hình bạn đã đầu tư suốt 21 phần trước — CLAUDE.md, skill, hook, MCP server — đi theo bạn sang SDK mà không phải viết lại.

Một lưu ý về giấy phép: Anthropic không cho phép nhà phát triển thứ ba cung cấp login claude.ai hay rate limit của claude.ai cho sản phẩm của họ, kể cả agent xây trên Claude Agent SDK, trừ khi được duyệt trước. Hãy dùng xác thực bằng API key.

---

Khép lại phần lõi của series

Hai mươi hai phần lõi, năm chặng:

• Nền tảng (1–4) — Claude Code là gì và chạy ở đâu, agent loop và bộ tool, context window và prompt caching, CLAUDE.md và bộ nhớ.
• Vận hành hằng ngày (5–10) — bàn phím và CLI, slash command, permission, session và checkpoint, workflow thường gặp, best practices.
• Mở rộng năng lực (11–15) — chọn cơ chế nào, skill, hook, MCP, plugin.
• Nhiều agent (16–18) — subagent và agent view, agent team và worktree, dynamic workflow.
• Tự động hoá, cấu hình và tra cứu (19–22) — headless và lịch chạy, review/security/CI, cấu hình, và bài này.

Nếu bạn phải chọn ba thứ để mang đi từ cả series, tôi đề nghị ba thứ này:

1. Context window là ràng buộc chi phối mọi thứ khác. Gần như mọi best practice đều là hệ quả của nó (phần 3, 10).
2. CLAUDE.md và skill là lời đề nghị; hook và permission rule là cưỡng chế. Chọn sai loại nghĩa là bạn tin một luật đang được thi hành trong khi nó chỉ là gợi ý (phần 11, 13).
3. Cho Claude một thứ nó tự kiểm được. Không có nó thì “trông có vẻ xong” là tín hiệu duy nhất nó có, và bạn trở thành vòng kiểm chứng (phần 10, 19).

Đọc tiếp: làm việc với model mới

Hai mươi hai phần trên nói về công cụ. Còn model chạy bên dưới thì đổi theo từng thế hệ, và mỗi lần đổi, cách giao việc cũng đổi theo. Phần 23 mở chặng này bằng Opus 5.5: nói rõ thế nào là xong, bỏ “think hard”, viết luật dừng vào CLAUDE.md, chia việc cho subagent, và đọc phần cần bạn quyết trước khi đọc phần còn lại.

Nguồn

• Troubleshooting
• Glossary
• Agent SDK overview

Docs gốc cập nhật thường xuyên; khi có mâu thuẫn, tin bản tiếng Anh.