> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.tramlabs.io/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.tramlabs.io/_mcp/server.

# Claude Code

> Sử dụng Claude Code với Trạm AI

> **Warning**
>
> Claude Code chạy qua Trạm AI chỉ được đảm bảo hoạt động với provider chính chủ của Anthropic. Để có độ tương thích tối đa, khi dùng Claude Code người dùng nên đặt Anthropic 1P làm provider ưu tiên hàng đầu.

## Vì sao nên dùng Trạm AI với Claude Code?

Trạm AI bổ sung một lớp độ tin cậy và quản lý giữa Claude Code và API của Anthropic, mang lại nhiều lợi ích đáng kể.

### Provider Failover để đảm bảo tính sẵn sàng cao

API của Anthropic thỉnh thoảng gặp gián đoạn hoặc chạm rate limit. Khi người dùng route Claude Code qua Trạm AI, request sẽ tự động failover giữa nhiều provider Anthropic. Nếu một provider không khả dụng hoặc chạm rate limit, Trạm AI sẽ route liền mạch sang provider khác, giúp phiên lập trình không bị gián đoạn.

### Kiểm soát budget ở cấp tổ chức

Trạm AI cung cấp khả năng quản lý budget tập trung cho nhóm và tổ chức. Người dùng có thể đặt giới hạn chi tiêu, phân bổ credit cho từng thành viên trong nhóm và ngăn chặn những khoản vượt chi ngoài dự kiến. Điều này đặc biệt hữu ích khi nhiều developer trong tổ chức cùng sử dụng Claude Code.

### Khả năng theo dõi mức sử dụng và phân tích

Trạm AI cho phép theo dõi toàn diện cách Claude Code đang được dùng trong toàn nhóm. Người dùng có thể theo dõi thói quen sử dụng, giám sát chi phí theo thời gian thực và biết được dự án hay thành viên nào đang tiêu thụ nhiều tài nguyên nhất. Toàn bộ dữ liệu này đều có sẵn trong [Trạm AI Activity Dashboard](https://console.tramlabs.io/settings/logs).

## Bắt đầu nhanh

Hướng dẫn này sẽ giúp người dùng chạy [Claude Code](https://code.claude.com/docs/en/overview) trên nền Trạm AI chỉ trong vài phút.

### Bước 1: Cài đặt Claude Code

#### Cài đặt gốc (Khuyến nghị)

**macOS, Linux, WSL:**

**`lines`**

```bash lines
curl -fsSL https://claude.ai/install.sh | bash
```

**Windows PowerShell:**

**`lines`**

```powershell lines
irm https://claude.ai/install.ps1 | iex
```

#### npm

Yêu cầu [Node.js 18 trở lên](https://nodejs.org/en/download/).

**`lines`**

```bash lines
npm install -g @anthropic-ai/claude-code
```

### Bước 2: Kết nối Claude với Trạm AI

Thay vì đăng nhập trực tiếp bằng Anthropic, hãy kết nối Claude Code với Trạm AI.\
Người dùng chỉ cần thiết lập một vài biến môi trường.

Yêu cầu:

1. Dùng `https://api.tramlabs.io` làm base url
2. Cung cấp [Trạm AI API key](https://console.tramlabs.io/keys) làm auth token
3. **Quan trọng:** Để trống tường minh Anthropic API key nhằm tránh xung đột

#### Shell Profile

Thêm các biến môi trường này vào shell profile:

```bash
# Open your shell profile in nano
nano ~/.zshrc  # or ~/.bashrc for Bash users

# Add these lines to the file:
export TRAM_AI_API_KEY="<your-tram-ai-api-key>"
export ANTHROPIC_BASE_URL="https://api.tramlabs.io"
export ANTHROPIC_AUTH_TOKEN="$TRAM_AI_API_KEY"
export ANTHROPIC_API_KEY="" # Important: Must be explicitly empty

# After saving, restart your terminal for changes to take effect
```

> **Note**
>
> **Tính bền vững:** Chúng tôi khuyến nghị thêm các dòng này vào shell profile (`~/.bashrc`, `~/.zshrc`, hoặc `~/.config/fish/config.fish`).

#### File cài đặt dự án

Ngoài ra, bạn có thể cấu hình Claude Code bằng một file cài đặt ở cấp dự án, đặt tại `.claude/settings.local.json` trong thư mục gốc của dự án:

**`lines`**

```json lines
{
  "env": {
    "ANTHROPIC_BASE_URL": "https://api.tramlabs.io",
    "ANTHROPIC_AUTH_TOKEN": "<your-tram-ai-api-key>",
    "ANTHROPIC_API_KEY": ""
  }
}
```

Thay `<your-tram-ai-api-key>` bằng Trạm AI API key thực tế của bạn.

> **Note**
>
> **Lưu ý:** Cách này giữ cấu hình của bạn trong phạm vi dự án, giúp dễ dàng chia sẻ cài đặt Trạm AI với cả nhóm qua hệ thống quản lý phiên bản (chỉ cần lưu ý đừng commit API key của bạn).

> **Warning**
>
> **Vị trí biến:** Đừng đặt những biến này trong file `.env` ở cấp dự án. Bản cài đặt gốc của Claude Code không đọc file `.env` tiêu chuẩn.

### Bước 3: Xóa mọi phiên đăng nhập Anthropic được cache

Nếu trước đây người dùng đã đăng nhập vào Claude Code bằng tài khoản Anthropic, cần chạy `/logout` một lần để xóa phiên đã được cache. Claude Code sẽ cảnh báo xung đột xác thực khi tồn tại đồng thời cả phiên đăng nhập được cache lẫn `ANTHROPIC_AUTH_TOKEN`, và xung đột này có thể gây ra hành vi ngoài ý muốn khi khởi động — thường biểu hiện dưới dạng lỗi model-not-found khó hiểu (ví dụ với `tram/auto`, `tram/pareto-code`, hoặc bất kỳ model nào chỉ có trên Trạm AI).

**`lines`**

```text lines
> /logout
```

Sau đó thoát và khởi chạy lại `claude` để nó nhận các biến môi trường mới.

> **Note**
>
> Nếu người dùng chưa bao giờ đăng nhập vào Claude Code bằng Anthropic có thể bỏ qua bước này.

### Bước 4: Bắt đầu phiên làm việc

Di chuyển đến thư mục dự án và khởi động Claude Code:

**`lines`**

```bash lines
cd /path/to/your/project
claude
```

Đã kết nối thành công. Mọi prompt đã gửi đều sẽ được route qua Trạm AI.

### Bước 5: Xác minh

Người dùng có thể xác nhận kết nối của mình bằng cách chạy lệnh `/status` bên trong Claude Code.

**`lines`**

```text lines
> /status
Auth token: ANTHROPIC_AUTH_TOKEN
Anthropic base URL: https://api.tramlabs.io
```

Người dùng cũng có thể mở [Trạm AI Activity Dashboard](https://console.tramlabs.io/settings/logs) để thấy request của mình xuất hiện theo thời gian thực.

## Cách hoạt động

Trạm AI cung cấp một input tương thích với Anthropic Messages API.

1. **Kết nối trực tiếp:** Khi người dùng đặt `ANTHROPIC_BASE_URL` thành `https://api.tramlabs.io`, Claude Code sẽ giao tiếp trực tiếp với Trạm AI bằng giao thức gốc của nó. Không cần máy chủ proxy cục bộ.
2. **Anthropic Skin:** "Anthropic Skin" của Trạm AI hoạt động giống hệt Anthropic API. Nó đảm nhận việc ánh xạ model và truyền qua các tính năng nâng cao như khối "Thinking" và tool use gốc.
3. **Thanh toán:** Người dùng được tính phí bằng credit Trạm AI của mình. Mức sử dụng (bao gồm cả reasoning token) đều hiển thị trong dashboard Trạm AI.

## Cấu hình các model

Claude Code dùng một số biến môi trường để xác định model nào được dùng cho từng loại tác vụ. Người dùng có thể ghi đè các biến này để route từng vai trò qua một model cụ thể:

**`lines`**

```bash lines
export ANTHROPIC_DEFAULT_OPUS_MODEL="claude-opus-4.8"
export ANTHROPIC_DEFAULT_SONNET_MODEL="claude-sonnet-4.6"
export ANTHROPIC_DEFAULT_HAIKU_MODEL="Claude Haiku 4.5"
export CLAUDE_CODE_SUBAGENT_MODEL="claude-opus-4.8"
```

| Biến                             | Mô tả                                                                 |
| -------------------------------- | --------------------------------------------------------------------- |
| `ANTHROPIC_DEFAULT_OPUS_MODEL`   | Model được dùng cho các tác vụ cấp Opus (ví dụ reasoning phức tạp)    |
| `ANTHROPIC_DEFAULT_SONNET_MODEL` | Model được dùng cho các tác vụ cấp Sonnet (ví dụ lập trình tổng quát) |
| `ANTHROPIC_DEFAULT_HAIKU_MODEL`  | Model được dùng cho các tác vụ cấp Haiku (ví dụ completion nhanh)     |
| `CLAUDE_CODE_SUBAGENT_MODEL`     | Model được dùng cho các tác vụ sub-agent do Claude Code sinh ra       |

Hãy thêm các biến này vào cùng shell profile hoặc file cài đặt dự án nơi đã đặt `ANTHROPIC_BASE_URL` và `ANTHROPIC_AUTH_TOKEN`.

Claude Code được tối ưu cho model của Anthropic và có thể không hoạt động đúng với các provider khác.

## Fast Mode

Fast mode của Anthropic cho output nhanh hơn tới 2.5 lần, đổi lại mức giá cao cấp hơn. **Fast mode chỉ khả dụng trên Claude Opus 4.6, Claude Opus 4.7 và Claude Opus 4.8** — không model Anthropic nào khác hỗ trợ.

Với mỗi phiên bản Opus được hỗ trợ, có hai cách tương đương để yêu cầu fast mode trên Trạm AI:

1. Gửi `speed: "fast"` với `Claude Opus 4.8`, `Claude Opus 4.7`, hoặc `Claude Opus 4.6` — Trạm AI sẽ route lại request đến model `*-fast` tương ứng (ví dụ, `Claude Opus 4.6` → `Claude Opus 4.6-fast`).
2. Gọi trực tiếp model `*-fast` — `Claude Opus 4.8-fast`, `Claude Opus 4.7-fast`, hoặc `Claude Opus 4.6-fast`.

Cả hai cách đều route qua provider chính chủ của Anthropic, và beta header bắt buộc sẽ được chèn tự động.

### Sử dụng `/fast` trong Claude Code

Claude Code có sẵn lệnh `/fast` để bật/tắt fast mode. Khi được bật, Claude Code sẽ gửi `speed: "fast"` trong request của nó cùng với model Opus đã cấu hình. Trạm AI hỗ trợ đầy đủ tham số này — bạn chỉ cần đặt biến môi trường sau:

**`lines`**

```bash lines
export CLAUDE_CODE_SKIP_FAST_MODE_ORG_CHECK=1
```

> **Note**
>
> Yêu cầu Claude Code v2.1.96 trở lên.

### Giá

Fast mode được tính phí cao hơn so với mức giá token tiêu chuẩn của model Claude Opus tương ứng. Xem [giá fast mode của Anthropic](https://platform.claude.com/docs/en/build-with-claude/fast-mode#pricing) để biết mức giá hiện tại. Khi fast mode đang hoạt động, đối tượng `usage` trong response sẽ kèm theo `"speed": "fast"` để xác nhận request đã được xử lý ở bậc tốc độ cao hơn.

> **Note**
>
> Nếu `speed: "fast"` được gửi đến một model không hỗ trợ fast mode, Trạm AI sẽ âm thầm bỏ qua tham số đó và request vẫn chạy ở tốc độ tiêu chuẩn với mức giá tiêu chuẩn.

### Cơ chế định tuyến

Fast mode chỉ được phục vụ bởi provider chính chủ của Anthropic, vì các provider khác (ví dụ Amazon Bedrock, Google Vertex) đều không hỗ trợ.

## Agent SDK

[Anthropic Agent SDK](https://platform.claude.com/docs/en/agent-sdk/overview) cho phép lập trình xây dựng các AI agent bằng Python hoặc TypeScript. Vì Agent SDK dùng Claude Code làm runtime, người dùng có thể kết nối nó với Trạm AI bằng chính các biến môi trường đã mô tả ở trên.

Để biết hướng dẫn thiết lập đầy đủ và ví dụ mã, hãy xem hướng dẫn tích hợp Anthropic Agent SDK của chúng tôi.

## GitHub Action

Người dùng có thể dùng Trạm AI với [Claude Code GitHub Action](https://github.com/anthropics/claude-code-action) chính thức. Để điều chỉnh [workflow ví dụ](https://github.com/anthropics/claude-code-action/blob/main/examples/claude.yml) cho Trạm AI, chỉ cần thực hiện hai thay đổi ở bước action:

1. Truyền Trạm AI API key qua `anthropic_api_key` (lưu nó dưới dạng một GitHub secret tên là `TRAM_AI_API_KEY`)
2. Đặt biến môi trường `ANTHROPIC_BASE_URL` thành `https://api.tramlabs.io`

**`lines`**

```yaml lines
- name: Run Claude Code
  uses: anthropics/claude-code-action@v1
  with:
    anthropic_api_key: ${{ secrets.TRAM_AI_API_KEY }}
  env:
    ANTHROPIC_BASE_URL: https://api.tramlabs.io
```

## Statusline theo dõi chi phí

Người dùng có thể thêm một statusline tùy chỉnh vào Claude Code để theo dõi chi phí Trạm AI API theo thời gian thực. Statusline hiển thị provider, model, chi phí tích lũy và các khoản giảm giá cache cho phiên làm việc của bạn.

![Statusline của Claude Code hiển thị theo dõi chi phí Trạm AI](/_fern-img/5bc3af530c4a0111317cbdcee893be444718c676f3f80bf0860141cffcb5ee1b.webp)

Hãy tải các script statusline từ repository Trạm AI-examples, cấp quyền thực thi cho chúng, rồi thêm nội dung sau vào `~/.claude/settings.json`:

**`lines`**

```json lines
{
  "statusLine": {
    "type": "command",
    "command": "/path/to/statusline.sh"
  }
}
```

Script này dùng biến môi trường `ANTHROPIC_AUTH_TOKEN` — biến mà lẽ ra đã được đặt thành Trạm AI API key nếu người dùng làm theo phần thiết lập ở trên.

## Khắc phục sự cố

* **Lỗi model-not-found với các model Trạm AI** (ví dụ `tram/auto`, `tram/pareto-code`): Thường do xung đột thông tin xác thực, biểu hiện dưới dạng cảnh báo xung đột xác thực khi khởi động. Có hai tình huống riêng biệt. (1) Nếu có phiên OAuth Anthropic được cache từ trước khi chuyển sang Trạm AI, hãy chạy `/logout` bên trong Claude Code, rồi thoát và khởi chạy lại `claude` để xóa phiên đã được cache. (2) Nếu shell profile vẫn đặt một `ANTHROPIC_API_KEY` thực (ví dụ một key console Anthropic cũ), `/logout` sẽ không có tác dụng — nó chỉ xóa phiên OAuth được cache chứ không xóa biến môi trường của shell. Trường hợp này, hãy đảm bảo `ANTHROPIC_API_KEY=""` đã được đặt trong shell profile theo Bước 2, sau đó khởi động lại terminal. Dùng `/status` để xác minh auth token là `ANTHROPIC_AUTH_TOKEN` và base URL là `https://api.tramlabs.io`.
* **Lỗi xác thực:** Hãy đảm bảo `ANTHROPIC_API_KEY` được đặt thành một chuỗi rỗng (`""`). Nếu nó không được đặt (null), Claude Code có thể quay về hành vi mặc định và cố xác thực với máy chủ của Anthropic. Nếu sau khi đặt mà vẫn gặp lỗi xác thực, hãy chạy `/logout` (xem ở trên).
* **Lỗi độ dài context:** Nếu chạm giới hạn context, hãy cân nhắc chia tác vụ thành các phần nhỏ hơn hoặc bắt đầu một phiên mới.
* **Quyền riêng tư:** Trạm AI không ghi log các prompt mã nguồn của người dùng, trừ khi người dùng chủ động opt-in cho việc ghi log prompt trong phần cài đặt tài khoản. Xem [Chính sách quyền riêng tư](https://tramlabs.io/privacy) của Trạm AI để biết chi tiết.