Tích hợp với Coding Agents

Claude Code

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.

Bắt đầu nhanh

Hướng dẫn này sẽ giúp người dùng chạy Claude Code trên nền Trạm AI chỉ trong vài phút.

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

macOS, Linux, WSL:

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

Windows PowerShell:

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

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.staging.tram.ai.vn làm base url
  2. Cung cấp Trạm AI API key làm auth token
  3. Quan trọng: Để trống tường minh Anthropic API key nhằm tránh xung đột

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

$# 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.staging.tram.ai.vn"
$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

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).

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
> /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.

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
$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
> /status
Auth token: ANTHROPIC_AUTH_TOKEN
Anthropic base URL: https://api.staging.tram.ai.vn

Người dùng cũng có thể mở Trạm AI Activity Dashboard để 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.staging.tram.ai.vn, 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
$export ANTHROPIC_DEFAULT_OPUS_MODEL="~anthropic/claude-opus-latest"
$export ANTHROPIC_DEFAULT_SONNET_MODEL="~anthropic/claude-sonnet-latest"
$export ANTHROPIC_DEFAULT_HAIKU_MODEL="~anthropic/claude-haiku-latest"
$export CLAUDE_CODE_SUBAGENT_MODEL="~anthropic/claude-opus-latest"
BiếnMô tả
ANTHROPIC_DEFAULT_OPUS_MODELModel được dùng cho các tác vụ cấp Opus (ví dụ reasoning phức tạp)
ANTHROPIC_DEFAULT_SONNET_MODELModel đượ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_MODELModel được dùng cho các tác vụ cấp Haiku (ví dụ completion nhanh)
CLAUDE_CODE_SUBAGENT_MODELModel đượ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 anthropic/claude-opus-4.8, anthropic/claude-opus-4.7, hoặc anthropic/claude-opus-4.6 — Trạm AI sẽ route lại request đến model *-fast tương ứng (ví dụ, anthropic/claude-opus-4.6 → anthropic/claude-opus-4.6-fast).
  2. Gọi trực tiếp model *-fast — anthropic/claude-opus-4.8-fast, anthropic/claude-opus-4.7-fast, hoặc anthropic/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
$export CLAUDE_CODE_SKIP_FAST_MODE_ORG_CHECK=1

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 để 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.

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 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 chính thức. Để điều chỉnh workflow ví dụ 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.staging.tram.ai.vn
lines
1- name: Run Claude Code
2  uses: anthropics/claude-code-action@v1
3  with:
4    anthropic_api_key: ${{ secrets.TRAM_AI_API_KEY }}
5  env:
6    ANTHROPIC_BASE_URL: https://api.staging.tram.ai.vn

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

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
1{
2  "statusLine": {
3    "type": "command",
4    "command": "/path/to/statusline.sh"
5  }
6}

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.staging.tram.ai.vn.
  • 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ư của Trạm AI để biết chi tiết.