Tổng Quan Về Cấu Hình Môi Trường

Bản hướng dẫn này tập trung vào việc triển khai Claude Code với sự hỗ trợ từ mô hình trí tuệ nhân tạo không chính thức của nền tảng thứ ba, cụ thể là GLM-4.6 từ ZhiPuAI. Lưu ý rằng các tính năng sau đây được điều chỉnh để tương thích với kiến trúc giao tiếp của bên thứ ba, thay vì sử dụng API gốc của Anthropic.

Cài Đặt CLI

Để bắt đầu làm việc, hãy cài đặt tiện ích dòng lệnh thông qua quản lý gói NPM:

npm install -g @anthropic-ai/claude-code

Sau khi cài đặt, bạn có thể sử dụng các phím tắt hệ thống như Cmd+Esc để khởi chạy nhanh hoặc Ctrl+Alt+K để tham chiếu đến các dòng mã cụ thể trong đầu vào của mình.

Thiết Lập Xác Thực Môi Trường

Việc định cấu hình biến môi trường là bước bắt buộc để Claude Code giao tiếp đúng địa chỉ endpoint và xác thực token.

Trên Windows

Để thiết lập tạm thời cho phiên làm việc hiện tại:

$env:ANTHROPIC_BASE_URL = "https://open.bigmodel.cn/api/anthropic"
$env:ANTHROPIC_AUTH_TOKEN = "[Điền API Key Của Bạn]"

Đối với cài đặt vĩnh viễn, mở công cụ System Properties (sysdm.cpl) và điều hướng tới tab Advanced > Environment Variables. Thêm hai mục mới:

• ANTHROPIC_BASE_URL: Gán giá trị https://open.bigmodel.cn/api/anthropic
• ANTHROPIC_AUTH_TOKEN: Gán giá trị API Key đã cấp quyền

Chuyển Đổi Mô Hình Backend

Claude Code mặc định sử dụng các biến môi trường để ánh xạ giữa các phiên bản Anthropic sang các mô hình GLM tương đương. Cấu hình mặc định thường được thiết lập như sau:

• ANTHROPIC_DEFAULT_OPUS_MODEL → GLM-4.6
• ANTHROPIC_DEFAULT_SONNET_MODEL → GLM-4.6
• ANTHROPIC_DEFAULT_HAIKU_MODEL → GLM-4.5-Air

Nếu cần tùy chỉnh thủ công, sửa đổi file cấu hình tại vị trí ~/.claude/settings.json:

{
  "env": {
    "ANTHROPIC_DEFAULT_HAIKU_MODEL": "glm-4.5-air",
    "ANTHROPIC_DEFAULT_SONNET_MODEL": "glm-4.6",
    "ANTHROPIC_DEFAULT_OPUS_MODEL": "glm-4.6"
  }
}

Nhập Văn Bản Nhiều Dòng

Trong phiên hội thoại claude code, hãy sử dụng lệnh /terminal-setup để kích hoạt khả năng xuống dòng bằng tổ hợp phím Shift + Enter. Ngoài ra, cú pháp \ + Enter cũng là một lựa chọn khả thi.

Làm Việc Với Các Chế Độ

Giao diện hội thoại hỗ trợ chuyển đổi các chế độ tác vụ khác nhau thông qua nút Shift + Tab:

1. Auto-accept Edits: Tự động phê duyệt các thay đổi mã nguồn đã được xác nhận trước đó mà không cần nhắc lại.
2. Plan Mode: Tập trung hoàn toàn vào việc lên kế hoạch và thiết kế kiến trúc, hạn chế việc viết code trực tiếp.

Quản Lý Phép Quyền Chỉnh Sửa

Mặc định, công cụ sẽ yêu cầu xác nhận trước mỗi thao tác ghi dữ liệu. Để đơn giản hóa quy trình cho các dự án cá nhân uy tín, bạn có thể bỏ qua kiểm tra bằng cờ --dangerously-skip-permissions.

claude --dangerously-skip-permissions

Cách tiếp cận bền vững hơn là cập nhật file .claude/settings.json để thiết lập trạng thái mặc định:

{
  "env": {
    "ANTHROPIC_MODEL": "glm-4.5",
    "ANTHROPIC_SMALL_FAST_MODEL": "glm-4.5-air"
  },
  "permissions": {
    "defaultMode": "bypassPermissions"
  }
}

Loại Bỏ Chữ Ký Git Mặc Định

Theo mặc định, các commit git được tạo bởi Claude Code sẽ chứa chú thích đồng tác giả. Để xóa phần này, thêm thuộc tính includeCoAuthoredBy trong cấu hình project:

{
  "statusLine": { ... },
  "includeCoAuthoredBy": false
}

Xây Dựng Lệnh Tùy Chỉnh

Công cụ hỗ trợ định nghĩa các lệnh nhanh dưới dạng file Markdown (Command aliases). Hệ thống phân loại các lệnh này thành phạm vi dự án hoặc người dùng.

Cấu Trúc Lưu Trữ

• Project Scope: Lưu tại .claude/commands/ (cần commit lên git).
• User Scope: Lưu tại ~/.claude/commands/ (áp dụng toàn hệ thống).

Ví dụ: Tạo Commit Thông Minh

File git-commit.md có thể tự động hóa quy trình đóng góp mã nguồn:

---
name: git-commit
description: Đóng gói công việc hiện tại với mô tả tự động
parameters:
  - name: tasknumber
    type: string
    required: false
---
# Thực hiện git commit với mô tả tự động sinh ra
1. Phân tích diff để chọn type (feat/fix...).
2. Generate message.
3. git add . && git commit "-m '...'".

Sử dụng bằng cách gõ /git-commit [task_id].

Kể Lại Lịch Sử Hội Thoại

Claude Code duy trì cache ngữ cảnh cục bộ trong thư mục .claude của root folder. Để khôi phục:

• Non-interactive: Chạy claude --continue (-c) để tải lại phiên cũ nhất hoặc claude --resume (-r) để chọn từ danh sách.
• Interactive: Trong cửa sổ hội thoại đang chạy, nhập lệnh /resume.

Điều kiện tiên quyết: Không di chuyển thư mục dự án và không xóa thư mục cache .claude.

Sub Agent (Tác Nhân Phụ)

Mô hình Sub Agent tách biệt ngữ cảnh xử lý để chuyên môn hóa nhiệm vụ. Mỗi agent có kho ngữ cảnh riêng và quyền truy cập tool giới hạn.

Ưu Điểm Chính

1. Tách biệt Ngữ Cảnh: Ngăn chặn nhiễu thông tin giữa tác vụ lớn và chi tiết nhỏ.
2. Chuyên Môn Hóa: Fine-tune prompt cho từng lĩnh vực (Code Review, Debugging...).
3. An Toàn: Giới hạn quyền truy cập file hệ thống cho từng agent.

Triển Khai

Dùng lệnh /agents để liệt kê hoặc tạo mới. Có thể chọn lưu trữ ở mức dự án (.claude/agents/) hoặc toàn máy (~/.claude/agents). Tên dự án luôn ưu tiên hơn tên toàn máy nếu trùng lặp.

Cấu Hình MCP (Model Context Protocol)

Thư viện MCP cho phép kết nối Claude Code với các công cụ bên ngoài (Database, Filesystem...). Hỗ trợ cả cài đặt cục bộ (project-scoped) và toàn cục.

Thêm Server Database (MySQL)

Do các vấn đề về version, khuyến nghị cài đặt giảm phiên bản server MySQL:

npm i @benborla29/mcp-server-mysql@2.0.2 -g

Thêm cấu hình vào file .mcp.json trong root project để tránh lỗi dòng lệnh trên Windows:

{
  "mcpServers": {
    "mcp_server_mysql": {
      "command": "mcp-server-mysql",
      "env": {
        "MYSQL_HOST": "localhost",
        "MYSQL_USER": "root",
        "ALLOW_INSERT_OPERATION": "true"
      }
    }
  }
}

Để cài đặt qua CLI nhưng vẫn hỗ trợ flag:

claude mcp add my-server /path/to/server
# Sau đó chỉnh sửa file config để thêm args nếu cần.

Phạm Vi Cấu Hình (Scope)

• --scope user hoặc mặc định: Áp dụng cho toàn profile người dùng (~/.claude.json).
• --scope project: Chỉ áp dụng cho thư mục hiện tại (.mcp.json trong folder).

Tích Hợp Với VS Code

Phiên bản plugin 2.0 có sự thay đổi lớn trong luồng xác thực. Nếu không muốn sử dụng xác thực chính chủ của Anthropic, cần can thiệp vào file cấu hình global.

Vô Hiệu Hóa Auth Trang Web

Tạo hoặc chỉnh sửa file ~/.claude/config.json để giả mạo API Key sơ bộ:

{
    "primaryApiKey": "dummy_value"
}

Lưu ý: Điều này giúp tránh popup đăng nhập nhưng vẫn phải cấu hình manual connection trong phần Setting của Extension:

• Set ANTHROPIC_BASE_URL về endpoint tùy chỉnh.
• Set ANTHROPIC_AUTH_TOKEN đúng chuỗi khóa.

Khuyến cáo giữ phiên bản 2.0.8 trở xuống do các bản mới hơn gặp bug hiển thị.

Mechanism Quên (Ignore Rules)

Claude Code tuân thủ ba lớp quy tắc ẩn file để giảm token tiêu thụ và bảo mật:

1. .gitignore: Tự động thừa kế nội quy git. Tuy nhiên, công cụ vẫn có thể đọc nếu cần.
2. ignorePatterns: Cấu hình qua CLI claude config set ignorePatterns <pattern>.
3. .claudeignore: Chuyên biệt cho công cụ, ưu tiên cao nhất khi làm sạch vùng quét.

Nên ưu tiên dùng .claudeignore cho các file nhạy cảm liên quan đến log hoặc build tools.

Cấu Hình CLAUDE.md

Tương tự như Cursor Rule, file CLAUDE.md hướng dẫn hành vi của AI trong dự án.

Quy Trình Kế Thừa

• Project Root: File chung cho team.
• .local.md: Quy tắc cá nhân, nằm trong .gitignore.
• Monorepo: Tự động scan lên thư mục cha.
• Global User: Tại ~/.claude/claude.md cho mọi dự án.

Lệnh /init có thể tự tạo file này nhưng đôi khi chưa tối ưu ngôn ngữ hoặc ngữ cảnh. Cần thủ công thêm dòng chỉ định ngôn ngữ trả lời nếu cần tiếng Việt.

Các Vấn Đề Thường Gặp

• Ngôn ngữ: Mô hình mặc định phản hồi bằng tiếng Anh. Cần thêm quy tắc rõ ràng vào CLAUDE.md.
• Unicode trên Windows: Tham chiếu đường dẫn chứa ký tự đặc biệt (như dấu gạch chéo ngược \) đôi khi gây lỗi, cần escape đúng chuẩn.
• Layout bàn phím: Nhập liệu tiếng Việt trên plugin VS Code cũ có thể làm lệch khung cửa sổ.