Hướng dẫn cấu hình Claude Code với OpenRouter – Giải thích rõ ràng từng bước

Bạn đã nghe mọi người ca ngợi Claude Code của Anthropic. Bạn cũng có thể đã bắt gặp cái tên OpenRouter xuất hiện ngay sau đó, thường kèm theo một loạt biến môi trường và ảnh chụp màn hình terminal. Nếu bạn mới bắt đầu, tất cả có thể khiến bạn cảm thấy như thể mọi người đã bỏ qua một bước nào đó và nhảy thẳng vào thuật ngữ chuyên môn.

Hướng dẫn này sẽ lấp đầy khoảng trống đó. Chúng ta sẽ đi chậm ở những phần quan trọng, giải thích mọi điểm gây nhầm lẫn, và đến cuối bài bạn sẽ thực sự hiểu những gì đang xảy ra thay vì chỉ copy-paste lệnh và hy vọng nó hoạt động.

Hai công cụ cần biết nhanh

Claude Code là tác nhân lập trình trong terminal của Anthropic. Nó đọc tệp, chỉnh sửa mã, chạy lệnh. Mặc định, nó kết nối trực tiếp đến máy chủ của Anthropic.

OpenRouter là một trạm trung chuyển – một “bảng điều phối” cho các mô hình AI. Thay vì mỗi ứng dụng cần có kết nối riêng đến từng nhà cung cấp AI, OpenRouter nằm ở giữa và cho phép bạn định tuyến yêu cầu đến các mô hình khác nhau thông qua một tài khoản, một bảng điều khiển, và một nơi duy nhất để theo dõi chi tiêu. (Đến cả các mô hình mã nguồn mở và miễn phí cũng có sẵn!)

Bạn có thể xem toàn bộ danh sách mô hình do OpenRouter cung cấp tại đây.

Lưu ý quan trọng: Tài liệu chính thức của OpenRouter xác nhận rằng sự kết hợp này chỉ được đảm bảo hoạt động tốt với các mô hình của Anthropic. Bạn thực chất không đang thay đổi “bộ não” của Claude, mà chủ yếu đang định tuyến lại đường truyền mà nó sử dụng để giao tiếp.

Giải thích nhanh thuật ngữ: “OpenAI Compatible”

Claude Code gửi yêu cầu theo định dạng của Anthropic. Một số máy chủ chỉ hiểu định dạng của OpenAI thay thế. Nếu bạn trỏ Claude Code nhầm vào một trong những máy chủ đó, bạn sẽ nhận được lỗi lộn xộn – như gửi thư bằng tiếng Pháp cho người chỉ đọc tiếng Tây Ban Nha vậy.

OpenRouter có một endpoint nói trực tiếp ngôn ngữ của Anthropic, do đó không cần bước dịch thuật, không cần proxy riêng biệt. Mọi thứ chạy trơn tru ngay từ đầu.

Tôi nên dùng zsh hay bash? Làm sao để biết?

Câu hỏi này khiến nhiều người mới dừng lại hơn bất kỳ điều gì khác trong hướng dẫn này, và nó hoàn toàn chính đáng. Đây là cách kiểm tra trong mười giây.

Mở terminal và gõ lệnh sau, sau đó nhấn Enter:

echo $SHELL

Bạn sẽ nhận được một trong những kết quả sau:

• Kết thúc bằng /zsh, ví dụ /bin/zsh, nghĩa là bạn đang dùng zsh. Đây là mặc định trên các phiên bản macOS hiện đại.
• Kết thúc bằng /bash, ví dụ /bin/bash, nghĩa là bạn đang dùng bash. Phổ biến trên các Mac đời cũ, nhiều cấu hình Linux, và Windows Subsystem for Linux (WSL).

Chỉ vậy thôi. Kết quả hiển thị sẽ cho bạn biết cần chỉnh sửa tệp nào sau này:

• Người dùng zsh chỉnh sửa ~/.zshrc
• Người dùng bash chỉnh sửa ~/.bashrc

Các bước cấu hình chi tiết

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

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

Bước 2: Lấy API key OpenRouter

Vào openrouter.ai, tạo tài khoản, lấy API key và nạp một ít tín dụng (credits) vào tài khoản của bạn.

Bước 3: Thêm biến môi trường vào tệp shell

Mở tệp shell tương ứng mà bạn đã xác định ở trên (zsh hoặc bash), thêm các dòng sau, rồi khởi động lại terminal:

export OPENROUTER_API_KEY="your-openrouter-api-key"
export ANTHROPIC_BASE_URL="https://openrouter.ai/api"
export ANTHROPIC_AUTH_TOKEN="$OPENROUTER_API_KEY"
export ANTHROPIC_API_KEY=""

Dòng cuối cùng là cố ý, không phải lỗi đánh máy. Một giá trị cũ tại đây có thể gây ra lỗi xác thực gây nhầm lẫn. Ngoài ra, hãy đặt các dòng này gần cuối tệp, nếu không khi OPENROUTER_API_KEY bị định nghĩa lại sau đó, token sẽ lặng lẽ trở thành chuỗi rỗng.

Tùy chọn cho mỗi dự án riêng biệt: Thay vì cấu hình global, bạn có thể dùng tệp settings cho từng dự án:

{
  "env": {
    "ANTHROPIC_BASE_URL": "https://openrouter.ai/api",
    "ANTHROPIC_AUTH_TOKEN": "<your-openrouter-api-key>",
    "ANTHROPIC_API_KEY": ""
  }
}

Bước 4: Xóa đăng nhập cũ

/logout

Sau đó khởi động lại Claude Code hoàn toàn.

Bước 5: Khởi chạy Claude Code

cd /path/to/your/project
claude

Bước 6: Xác nhận cấu hình thành công

/status

Lệnh này nên hiển thị ANTHROPIC_AUTH_TOKEN và base URL của OpenRouter. Bạn cũng có thể kiểm tra bảng điều khiển hoạt động trên OpenRouter – cảm giác xem các yêu cầu xuất hiện dần dần khá thỏa mãn.

Bạn đã sẵn sàng sử dụng! Claude Code với danh sách các mô hình đang chờ đợi lượt!

Kết luận

Cài đặt Claude Code, lấy API key từ OpenRouter, đặt bốn biến môi trường vào tệp đúng, chạy /logout, khởi động lại, và dùng /status để xác nhận. Mười phút, xong.

Lời khuyên: Hãy bắt đầu với các mô hình của Claude trước, sau đó mở rộng khám phá khi bạn đã biết “hoạt động tốt” trông như thế nào.