Những gì bạn cần
- Một khóa API từ trang khóa. Đăng ký bằng Google hoặc email và mật khẩu, sau đó nhận tín dụng dùng thử $0,50 chỉ với một cú nhấp chuột.
- Python 3.9 trở lên, để cài đặt proxy.
- Claude Code đã được cài đặt và hoạt động trên máy của bạn.
Tại sao cần proxy? Claude Code sử dụng định dạng Messages của Anthropic, trong khi API của chúng tôi sử dụng định dạng Chat Completions của OpenAI với ID mô hình uncensored. Proxy thực hiện chuyển đổi giữa hai định dạng này. Nếu bạn muốn tìm hiểu bối cảnh trước, hãy đọc hướng dẫn khắc phục sự cố proxy. Mô hình là mô hình trọng số mở, không phải Claude, nên hãy mong đợi hành vi khác biệt trên các tác vụ nhiều bước phức tạp.
Bước 1: cài đặt proxy
Hãy sử dụng môi trường ảo để các phụ thuộc của proxy được tách biệt với các dự án của bạn:
python3 -m venv ~/litellm-env
source ~/litellm-env/bin/activate
pip install 'litellm[proxy]'
LiteLLM là phần mềm mã nguồn mở của bên thứ ba. Các lệnh và khóa cấu hình dưới đây khớp với tài liệu công khai của nó tại thời điểm viết, nhưng hãy kiểm tra tài liệu hiện tại của nó nếu một cờ đã thay đổi.
Bước 2: viết cấu hình
Tạo config.yaml. model_name là tên mà client gửi. Khối litellm_params chỉ định nơi chuyển tiếp nó. Tiền tố openai/ báo cho LiteLLM giao tiếp với máy chủ tương thích OpenAI.
cat > config.yaml <<'EOF'
model_list:
- model_name: claude-sonnet
litellm_params:
model: openai/uncensored
api_base: https://api.claudecodeproxyapi.com/v1
api_key: os.environ/UPSTREAM_KEY
EOF
Alias claude-sonnet chỉ là ví dụ, không bắt buộc. Claude Code có thể gửi nhiều tên mô hình khác nhau, ví dụ một mô hình chính và một mô hình nhỏ hơn cho các tác vụ nền. Hãy thêm một mục model_list cho mỗi tên bạn thấy trong log proxy, tất cả đều trỏ về cùng một upstream. Trỏ mọi alias vào uncensored là được, vì chỉ có một mô hình.
Khóa được đọc từ biến môi trường nên nó không bao giờ xuất hiện trong tệp bạn có thể commit.
Bước 3: khởi động proxy
export UPSTREAM_KEY="YOUR_KEY"
litellm --config config.yaml --port 4000
Hãy giữ terminal này mở. Bạn sẽ thấy máy chủ đang lắng nghe trên cổng 4000. Bây giờ hãy kiểm tra đường dẫn upstream từ phía proxy bằng một yêu cầu kiểm thử ở định dạng Anthropic, đây là định dạng mà Claude Code sẽ gửi:
curl http://localhost:4000/v1/messages \
-H "content-type: application/json" \
-H "x-api-key: sk-local-anything" \
-H "anthropic-version: 2023-06-01" \
-d '{
"model": "claude-sonnet",
"max_tokens": 200,
"messages": [{"role": "user", "content": "Reply with the word ready."}]
}'
Một phản hồi JSON có nội dung chứa từ "ready" có nghĩa là việc chuyển đổi hoạt động từ đầu đến cuối: định dạng Anthropic vào, định dạng OpenAI đến https://api.claudecodeproxyapi.com/v1, và quay lại. Nếu bạn đặt khóa master trong cấu hình LiteLLM, hãy dùng nó thay cho sk-local-anything.
Bước 4: trỏ Claude Code vào proxy
Claude Code đọc địa chỉ API và token từ các biến môi trường. Hãy đặt chúng trong shell nơi bạn khởi động CLI:
export ANTHROPIC_BASE_URL="http://localhost:4000"
export ANTHROPIC_AUTH_TOKEN="sk-local-anything"
export ANTHROPIC_MODEL="claude-sonnet"
claude
Hãy dùng địa chỉ proxy mà không có hậu tố /v1 ở đây, vì CLI tự thêm đường dẫn của nó. Token chỉ cần thỏa mãn proxy, vì khóa upstream thực tế là khóa bạn đã xuất dưới dạng UPSTREAM_KEY. Nếu bạn sử dụng tệp cài đặt của CLI cho các giá trị biến môi trường thay vì shell, hãy đặt cùng ba tên đó ở đó. Tên biến môi trường cho Claude Code có thể thay đổi giữa các bản phát hành, vì vậy hãy xác minh chúng với tài liệu Claude Code hiện tại nếu có thứ gì đó bị bỏ qua.
Bước 5: chạy tác vụ đầu tiên và theo dõi log
Hãy bắt đầu nhỏ. Hãy yêu cầu CLI giải thích một tệp hoặc thêm nhận xét vào một hàm. Trong terminal proxy, bạn sẽ thấy một yêu cầu cho mỗi bước. Hãy ghi chú tên mô hình xuất hiện; nếu một tên không có trong model_list của bạn, proxy sẽ trả về lỗi, vì vậy hãy thêm nó và khởi động lại.
Gọi hàm rất quan trọng ở đây, vì CLI đọc tệp và chỉnh sửa mã thông qua các công cụ. API hỗ trợ tools, tool_choice và tool_calls được truyền phát, và proxy chuyển đổi chúng. Việc tuân thủ lược đồ công cụ kém hơn sẽ thể hiện qua việc chỉnh sửa thất bại hoặc lặp lại bước. Khi xảy ra sự cố đó, hãy rút ngắn tác vụ và thử lại trước khi quyết định quy trình cài đặt bị hỏng.
Cửa sổ ngữ cảnh là 100.000 token, bao gồm prompt và kết quả cùng nhau. Các phiên dài vượt quá giới hạn này sẽ thất bại, vì vậy hãy bắt đầu một phiên mới cho một nhiệm vụ mới. Chi phí rất nhỏ ở mức $0,15 cho mỗi 1 triệu token đầu vào và $0,50 cho mỗi 1 triệu token đầu ra: một yêu cầu với 20.000 token đầu vào và 800 token đầu ra tốn $0,003 + $0,0004 = $0,0034. Xem trang giá cả để nạp tiền, trên trang web này thanh toán bằng crypto (USDT trên TRC20, USDC trên Base).
Khắc phục sự cố
| Những gì bạn thấy | Nguyên nhân | Cách khắc phục |
|---|---|---|
| Kết nối bị từ chối | Proxy không chạy hoặc cổng khác biệt | Hãy khởi động nó và khớp cổng trong ANTHROPIC_BASE_URL |
| Proxy 404 hoặc "không tìm thấy mô hình" | Tên mô hình mà CLI gửi không có trong cấu hình | Hãy thêm tên đó vào model_list |
| Upstream 401 | UPSTREAM_KEY sai hoặc trống | Hãy xuất lại khóa trong shell của proxy và khởi động lại |
429 với concurrency | Hơn 8 yêu cầu đồng thời (2 trên bản dùng thử) | Hãy giảm số lượng agent đồng thời |
429 với rate_limited | Quá 300 yêu cầu mỗi phút (60 trên dùng thử) | Giảm tần suất và thử lại |
429 với Retry-After: 5 | Quá tải tạm thời | Hãy thử lại sau năm giây |
| Luồng bị treo | Một yêu cầu truyền phát giữ slot của nó cho đến khi kết thúc | Hãy hủy nó trong CLI để giải phóng slot |
Đối với bất kỳ nội dung nào không được đề cập ở đây, hãy bao gồm tiêu đề phản hồi X-Request-Id khi bạn liên hệ hỗ trợ. Tài liệu liệt kê mọi tham số được hỗ trợ.
Cài đặt vĩnh viễn
Việc gõ lệnh export mỗi lần sẽ gây mệt mỏi. Hãy đặt lệnh khởi động proxy trong một script nhỏ và các biến client trong một alias, để một lệnh duy nhất kích hoạt mọi thứ:
cat > ~/start-proxy.sh <<'EOF'
. ~/litellm-env/bin/activate
export UPSTREAM_KEY="YOUR_KEY"
exec litellm --config ~/config.yaml --port 4000
EOF
chmod +x ~/start-proxy.sh
alias claude-uncensored='ANTHROPIC_BASE_URL=http://localhost:4000 ANTHROPIC_AUTH_TOKEN=sk-local-anything ANTHROPIC_MODEL=claude-sonnet claude'
Vì các biến chỉ được đặt cho lệnh đó, lệnh claude bình thường của bạn vẫn hoạt động với các cài đặt mặc định của nó. Thêm alias vào cấu hình shell của bạn. Bảo vệ script bằng quyền tệp như chmod 700, vì nó chứa khóa của bạn.
Chuyển đổi lại
Nếu bạn đã xuất các biến trong shell hiện tại, hãy chạy unset ANTHROPIC_BASE_URL ANTHROPIC_AUTH_TOKEN ANTHROPIC_MODEL và khởi động lại CLI. Không có gì thay đổi ở phía API, vì vậy không có gì cần hoàn tác.
Theo dõi số dư và chi tiêu của bạn
Mỗi phản hồi từ API đều mang theo X-Balance-USD, số tín dụng còn lại trên khóa của bạn. LiteLLM có thể chuyển các tiêu đề upstream trong một số cấu hình, nhưng cách chắc chắn nhất để xem số dư là gọi trực tiếp upstream định kỳ:
curl -i https://api.claudecodeproxyapi.com/v1/models \
-H "Authorization: Bearer YOUR_KEY" | grep -i x-balance-usd
Phiên agent tăng dần một cách âm thầm. Mỗi bước gửi lại ngữ cảnh đang hoạt động, nên một phiên dài sẽ tốn nhiều hơn mỗi yêu cầu so với phiên ngắn. Bắt đầu một phiên mới cho mỗi tác vụ giúp giữ đầu vào nhỏ và hóa đơn thấp. Với giá công bố ($0.15 cho mỗi 1M input và $0.50 cho mỗi 1M output), một yêu cầu với 50.000 token đầu vào và 1.000 token đầu ra tốn 50.000 x $0.15 / 1M = $0.0075 cộng thêm $0.0005, tức là $0.008. Hai mươi yêu cầu như vậy cộng lại là $0.16.
Các khoản nạp tiền chạy từ $20 đến $500 với số nguyên và được thanh toán bằng crypto (USDT trên TRC20 hoặc USDC trên Base) trên trang web này. Tín dụng không bao giờ hết hạn, nên một khoản nạp tiền lớn hơn với bonus +5%, +10% hoặc +15% không đặt đồng hồ đếm ngược cho số dư của bạn.
