Khóa API Claude Code — lấy ở đâu, đặt ở đâu và vì sao biến sai không báo lỗi

Claude Code có thể xác thực theo hai cách khác nhau, và cách bạn cần dùng sẽ quyết định mọi phần còn lại. Đăng nhập bằng gói claude.ai bao phủ mức sử dụng trong gói Pro hoặc Max của bạn. Khóa API tính phí theo token mà không có giới hạn của gói. Hướng dẫn này giải thích nơi lấy khóa, chính xác vị trí đặt khóa, hai biến thông tin xác thực và lý do chọn sai biến sẽ gây lỗi im lặng, cũng như cách kiểm soát chi phí sau khi thiết lập xong.

Có thực sự cần khóa không?

Điều cần biết trước khi bắt đầu: đặt khóa sẽ tạm dừng gói đăng ký của bạn. Khi một biến thông tin xác thực đang hoạt động, Claude Code sẽ dùng biến đó thay cho thông tin đăng nhập claude.ai đã lưu, các giới hạn của gói sẽ không còn áp dụng, và mức sử dụng sẽ được tính cho chủ sở hữu khóa. Bỏ đặt biến thì Claude Code sẽ quay lại dùng gói đăng ký.

Tùy chọn 1 — khóa Anthropic chính thức

1. Đăng nhập tại console.anthropic.com (tài khoản riêng với claude.ai).
2. Nạp tiền trong Billing. API là dịch vụ trả trước và tách biệt với mọi gói đăng ký — gói Pro không thanh toán cho dịch vụ này.
3. Tạo khóa trong API Keys. Khóa bắt đầu bằng sk-ant- và chỉ được hiển thị một lần.

export ANTHROPIC_API_KEY=sk-ant-...
# Then approve it once, interactively:
#   /config  ->  Use custom API key
claude

Lưu ý bước thứ hai trong đoạn mã đó. ANTHROPIC_API_KEY được gửi trong tiêu đề x-api-key và cần phê duyệt tương tác một lần trước khi Claude Code sử dụng. Nếu lời nhắc đó từng bị từ chối, khóa sẽ bị bỏ qua về sau mà hoàn toàn không hiển thị lời nhắc nào — trông hệt như biến không được đọc. Bật lại trong /config → Use custom API key.

Tùy chọn 2 — khóa có chi phí trên mỗi token thấp hơn

Claude Code đọc trực tiếp ANTHROPIC_BASE_URL, vì vậy nó hoạt động với mọi endpoint cung cấp Anthropic Messages API — không cần plugin, proxy hay binary đã vá. Đây là cách được hỗ trợ cho các gateway, và là cách chạy cùng các model Claude với mức phí thấp hơn:

export ANTHROPIC_BASE_URL=https://api.kunavo.com
export ANTHROPIC_AUTH_TOKEN=sk-kn-...
export ANTHROPIC_MODEL=claude-sonnet-5
export ANTHROPIC_DEFAULT_OPUS_MODEL=claude-opus-5-5
export ANTHROPIC_DEFAULT_SONNET_MODEL=claude-sonnet-5
export ANTHROPIC_DEFAULT_HAIKU_MODEL=claude-haiku-4-5

ANTHROPIC_BASE_URL chỉ là origin — Claude Code tự thêm /v1/messages. Giữ nguyên các dòng mô hình: mặc định tích hợp sẵn của Claude Code và bí danh opus đều trỏ đến Opus mới nhất; nếu Kunavo chưa cung cấp mô hình đó, yêu cầu đầu tiên sẽ trả về 404. Dòng opus ghim mô hình vào Claude Opus 5.5, yêu cầu Claude Code v2.1.280 trở lên (hãy chạy claude update trên phiên bản cũ hơn). Bí danh sonnet yêu cầu Sonnet 5.5, mô hình Kunavo không cung cấp, vì vậy nếu không có ANTHROPIC_DEFAULT_SONNET_MODEL, /model sonnet, giai đoạn thực thi của opusplan và các subagent được đặt thành sonnet đều trả về 404. Hãy tạo khóa sk-kn- trong bảng điều khiển sau khi đăng ký và nạp $10. Không có phí hàng tháng và số dư không hết hạn.

Mức này thấp hơn khoảng 30% so với giá niêm yết của model chính. Bảng giá đầy đủ có trong hướng dẫn giá Claude API, còn giá Claude Code so sánh tuyến này với phí gói Pro và Max; toàn bộ thiết lập, bao gồm định tuyến model theo từng tác vụ và những thay đổi khi đi qua gateway, có trong hướng dẫn định tuyến Claude Code. Nếu CLI chưa được cài đặt, hãy bắt đầu tại cài đặt Claude Code.

Khóa thực sự được đặt ở đâu

Hai biến, hai tiêu đề HTTP khác nhau. Khóa trong tiêu đề mà máy chủ không đọc sẽ thất bại với 401:

Nếu bạn không được cho biết mình có loại nào, hãy bắt đầu với ANTHROPIC_AUTH_TOKEN, loại này không cần bước phê duyệt. Trên Kunavo, cả hai biến đều cho phép Claude Code phát hiện danh sách model, vì /v1/models đọc khóa từ cả hai tiêu đề.

Export trong shell so với tệp settings

Export trong shell chỉ áp dụng cho terminal đó và các tiến trình con. Trình soạn thảo được khởi chạy từ dock sẽ không nhìn thấy biến này, và các agent chạy nền cũng vậy. Để thiết lập lâu dài, hãy dùng khối env của ~/.claude/settings.json — cùng các khóa, áp dụng ở mọi nơi Claude Code chạy. Đừng đặt khóa trong .claude/settings.json của dự án; tệp đó được commit và chia sẻ với mọi người clone repository.

Chạy /status để xác nhận thông tin xác thực nào đang hoạt động. Dòng Auth token hoặc API key có tên biến của bạn nghĩa là khóa đang hoạt động; dòng Login method có tên tài khoản claude.ai nghĩa là khóa không hoạt động.

Luân phiên khóa mà không sửa tệp

Nếu thông tin xác thực hết hạn theo lịch hoặc lấy từ vault, hãy trỏ apiKeyHelper đến một lệnh in ra khóa hiện tại:

#!/bin/bash
# Any command that prints the current key to stdout works.
vault kv get -field=api_key secret/claude-code

Tham chiếu nó dưới dạng "apiKeyHelper": "~/bin/get-key.sh" trong tệp settings. Claude Code lưu kết quả trong năm phút và chạy lại sau mỗi 401; điều chỉnh bằng CLAUDE_CODE_API_KEY_HELPER_TTL_MS. Giá trị được gửi trong cả hai tiêu đề, nên hoạt động theo cả hai cách.

Giữ chi phí có thể dự đoán

Lập trình dạng agent tiêu tốn nhiều token — mỗi bước gửi lại system prompt, lịch sử tác vụ và ngữ cảnh tệp mới. Bốn điều quan trọng hơn mọi thứ khác:

1. Giữ dòng Haiku. Nếu thiếu ANTHROPIC_DEFAULT_HAIKU_MODEL=claude-haiku-4-5, bí danh haiku của Claude Code sẽ yêu cầu một model ID mà Kunavo không cung cấp (Haiku 5.5 từ v2.1.293), khiến /model haiku và các tác tử con được đặt dùng haiku trả về 404. Dòng này cũng chuyển phần tóm tắt và tiêu đề mà Claude Code tự tạo khỏi mô hình chính của bạn; khoản tiết kiệm sẽ tăng lên khi công việc được phân thành nhiều tác vụ, như thể hiện trong chi phí của một quy trình Claude Code.
2. Cùng hai biến đó định tuyến Agent SDK. Nó không có tùy chọn base-URL riêng — nó khởi chạy CLI này và truyền thẳng môi trường của bạn, vì vậy một chương trình Agent SDK được định tuyến chính xác theo cấu hình trên.
3. Bắt đầu tác vụ mới thay vì kéo dài một tác vụ mãi. Ngữ cảnh được gửi lại ở mỗi bước, nên một phiên dài sẽ tốn chi phí theo cấp số nhân. Việc chọn tier nào cho model chính được phân tích trong Opus so với Sonnet so với Haiku, theo chi phí cho mỗi tác vụ hoàn tất thay vì chi phí cho mỗi token.
4. Để bộ nhớ đệm prompt hoạt động. Input được lưu trong bộ nhớ đệm được tính phí bằng 10% mức phí input, và tuyến Messages API nguyên bản truyền cache_control mà không dịch (chi tiết).
5. Cấp cho trình soạn thảo khóa riêng với giới hạn chi tiêu trong trang quản trị, sau đó kiểm tra mức sử dụng sau một tuần. Giới hạn theo từng khóa biến một vòng lặp chạy mất kiểm soát thành vòng lặp có mức trần.

Khắc phục sự cố

Câu hỏi thường gặp