> For the complete documentation index, see [llms.txt](https://docs.avis.net/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.avis.net/vi/tich-hop/coding/claude-code.md). # Claude Code ## Hướng dẫn tích hợp Claude Code Hướng dẫn này trình bày cách kết nối [Claude Code](https://claude.com/product/claude-code), agent lập trình chính thức của Anthropic chạy trên terminal, với API tương thích Anthropic của AVIS. ### Claude Code là gì Claude Code là agent lập trình dạng CLI chạy trên terminal, có thể đọc và sửa tệp cũng như thực thi lệnh shell trong vòng lặp agent. Công cụ dùng Messages API gốc của Anthropic, nên có thể kết nối với AVIS qua giao diện tương thích Anthropic mà không cần sửa mã nguồn; bạn chỉ cần đặt base URL và thông tin xác thực. ### 1) Cài đặt Claude Code ```bash # macOS / Linux / WSL curl -fsSL https://claude.ai/install.sh | bash # Windows PowerShell irm https://claude.ai/install.ps1 | iex # Homebrew brew install --cask claude-code ``` Nếu trình cài đặt gốc bị treo hoặc không bao giờ hoàn tất (thường gặp trên các mạng giới hạn/chặn truy cập trực tiếp tới `claude.ai` — đã gặp thực tế trên ít nhất một mạng doanh nghiệp), hãy cài đặt qua npm, cách này tải từ npm registry thay vì CDN của Anthropic: ```bash node -v # requires Node 18+ npm install -g @anthropic-ai/claude-code ``` Kiểm tra: ```bash claude --version ``` ### 2) Lấy AVIS API key Đăng nhập tại [avis.net](https://avis.net), mở **Settings → API Keys** và tạo key. Xem thêm phần Xác thực. ### 3) Trỏ Claude Code tới AVIS Claude Code đọc ba biến môi trường cho một nhà cung cấp tùy chỉnh tương thích Anthropic: | Biến | Giá trị | | ---------------------- | ------------------------------------------- | | `ANTHROPIC_BASE_URL` | `https://api.avis.net/api/anthropic` | | `ANTHROPIC_AUTH_TOKEN` | AVIS API key của bạn | | `ANTHROPIC_API_KEY` | `""` (phải để trống — xem ghi chú bên dưới) | `ANTHROPIC_AUTH_TOKEN` được gửi dưới dạng `Authorization: Bearer `, mà AVIS chấp nhận như một cách thay thế cho `x-api-key` (xem phần Xác thực). Nếu `ANTHROPIC_API_KEY` cũng được đặt (ví dụ còn sót lại từ một tài khoản Anthropic thật), Claude Code sẽ gửi `x-api-key` bằng giá trị đó thay vì token AVIS của bạn — để biến này không rỗng là nguyên nhân phổ biến nhất khiến AVIS trả về `401` dù `ANTHROPIC_AUTH_TOKEN` trông có vẻ đúng. #### Cách A — Shell profile (áp dụng cho mọi dự án) Thêm vào `~/.zshrc` / `~/.bashrc` / `~/.config/fish/config.fish`: ```bash export AVIS_API_KEY="" export ANTHROPIC_BASE_URL="https://api.avis.net/api/anthropic" export ANTHROPIC_AUTH_TOKEN="$AVIS_API_KEY" export ANTHROPIC_API_KEY="" ``` `ANTHROPIC_AUTH_TOKEN` phải được khai báo **sau** `AVIS_API_KEY` trong tệp — nếu tham chiếu được phân giải trước khi biến mà nó trỏ tới được đặt, nó sẽ âm thầm trở thành token rỗng và mọi request đều bị lỗi 401. Mở lại terminal (hoặc chạy `source` tệp đó) sau khi chỉnh sửa. #### Cách B — Cấp dự án, `.claude/settings.local.json` ```json { "env": { "ANTHROPIC_BASE_URL": "https://api.avis.net/api/anthropic", "ANTHROPIC_AUTH_TOKEN": "", "ANTHROPIC_API_KEY": "" } } ``` Chỉ áp dụng cho dự án hiện tại — dùng cách này nếu bạn chỉ muốn bật AVIS cho một repo cụ thể thay vì mọi phiên `claude`. > Trình cài đặt gốc **không** đọc tệp `.env` — hãy dùng một trong hai cách trên, không dùng `.env` của dự án. #### Xóa phiên đăng nhập Anthropic đã lưu trước Nếu máy này đã từng chạy `claude login` (tài khoản Anthropic/Claude Pro hoặc Max thật), phiên OAuth đã lưu đó sẽ được ưu tiên hơn các biến môi trường ở trên. Hãy chạy `/logout` trong một phiên `claude` một lần trước khi chuyển sang AVIS, nếu không request sẽ tiếp tục đi tới Anthropic API thật và âm thầm bỏ qua cấu hình AVIS của bạn. ### 4) Chọn mô hình Truy vấn danh mục trực tiếp để lấy chính xác các ID hiện tại: ```bash curl https://api.avis.net/api/anthropic/v1/models \ -H "x-api-key: $AVIS_API_KEY" | jq '.data[].id' ``` Menu `/model` của Claude Code và định tuyến tác vụ nền có thể được trỏ tới các model ID của AVIS qua: ```bash export ANTHROPIC_MODEL="anthropic/claude-sonnet-5" export ANTHROPIC_SMALL_FAST_MODEL="anthropic/claude-haiku-4-5" export ANTHROPIC_DEFAULT_OPUS_MODEL="anthropic/claude-opus-5" export ANTHROPIC_DEFAULT_SONNET_MODEL="anthropic/claude-sonnet-5" export ANTHROPIC_DEFAULT_HAIKU_MODEL="anthropic/claude-haiku-4-5" ``` `ANTHROPIC_SMALL_FAST_MODEL` và `ANTHROPIC_DEFAULT_*` quyết định mô hình nào đứng sau các bậc Opus/Sonnet/Haiku tích hợp sẵn của Claude Code và các lệnh gọi subagent chạy nền — nếu không có chúng, việc chọn một bậc theo tên trong cấu hình nhà cung cấp tùy chỉnh sẽ không phân giải được tới mô hình hợp lệ nào. ### 5) Chạy Claude Code ```bash cd your-project claude ``` Trong phiên làm việc, hãy xác nhận AVIS đã thực sự được kết nối: ``` /status ``` Lệnh này mở một bảng với các trường **Config**, bao gồm: ``` Auth token: ANTHROPIC_AUTH_TOKEN Anthropic base URL: https://api.avis.net/api/anthropic Model: Default () ``` ### 6) Khắc phục sự cố * Trình cài đặt gốc (`curl claude.ai/install.sh | bash`) bị treo vô thời hạn, hoặc chỉ riêng `curl` hiển thị `speed: 0 bytes/s` mà không báo lỗi * Mạng đang âm thầm chặn lưu lượng tới `claude.ai` (không có thông báo từ chối kết nối/hết thời gian chờ, chỉ là không có dữ liệu) — xác nhận bằng cách kiểm tra `curl -o /dev/null -w "%{speed_download}\n" https://registry.npmjs.org` trả về tốc độ bình thường trong khi lệnh tương tự với `claude.ai` trả về `0`. * Hãy cài đặt qua npm (§1) — cách này dùng npm registry, không dùng CDN của Anthropic, và không bị ảnh hưởng bởi cùng kiểu chặn. * `401 Unauthorized` * `ANTHROPIC_API_KEY` không rỗng và đang che mất `ANTHROPIC_AUTH_TOKEN` (xem §3). * `ANTHROPIC_AUTH_TOKEN` tham chiếu `AVIS_API_KEY` trước khi biến này được khai báo trong shell profile. * Một phiên `claude login` đã lưu vẫn còn hoạt động — chạy `/logout` (xem §3). * AVIS key không hợp lệ hoặc đã bị thu hồi — kiểm tra bằng `curl` trực tiếp tới `/api/anthropic/v1/models`. * `403` với key hợp lệ * Số dư tài khoản đã hết — xem phần Lỗi. * `404` / không tìm thấy mô hình * Model ID không khớp với danh mục của AVIS — kiểm tra lại với `GET /api/anthropic/v1/models` (§4), không dùng ví dụ cố định. * Request vẫn đi tới Anthropic API thật thay vì AVIS * `/status` (§5) sẽ cho thấy điều này ngay lập tức — thường do phiên `claude login` còn sót lại (xem §3) hoặc biến môi trường được đặt trong một shell profile không phải là profile đang thực sự được nạp (ví dụ sửa `.bashrc` nhưng đang chạy `zsh`). * Thay đổi trong tệp `.env` không có tác dụng * Trình cài đặt gốc không đọc `.env` — hãy dùng export trong shell profile hoặc `.claude/settings.local.json` (§3). ### 7) Danh sách kiểm tra tối thiểu từ đầu đến cuối 1. Đã tạo AVIS API key (§2). 2. Đã đặt `ANTHROPIC_BASE_URL` / `ANTHROPIC_AUTH_TOKEN` / `ANTHROPIC_API_KEY=""` qua shell profile hoặc `.claude/settings.local.json` (§3). 3. Không còn phiên `claude login` cũ (đã chạy `/logout` nếu có). 4. Đã xác nhận model ID với `GET /api/anthropic/v1/models` (§4). 5. `claude` khởi động, `/status` hiển thị base URL của AVIS, và một tin nhắn trả về kết quả từ mô hình. --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation by asking a question. Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters: ``` GET https://docs.avis.net/vi/tich-hop/coding/claude-code.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.