Claude Code dùng subscription hay API key?

Phiên Claude Code của bạn đang dùng credential nào?

Đăng nhập Claude Code hoạt động theo một trong hai cách. Bạn đăng nhập bằng tài khoản subscription Claude trên claude.ai, hoặc xác thực với một organization trên Anthropic Console. Khi đó, mỗi token được tính vào hạn mức API (application programming interface) của organization đó. Chạy /status trong một phiên đang chạy để xem credential nào đang hoạt động: tab Status hiển thị một dòng Login method cho tài khoản bạn đã đăng nhập, và một dòng API key bổ sung xuất hiện khi API key đang cung cấp credential.

Việc tool có được plan của bạn chi trả hay không là một câu hỏi riêng. Câu trả lời nằm trong Claude Code có được bao gồm trong subscription Claude Pro hay không. Cơ chế sử dụng key với Claude API được trình bày trong xác thực Claude API hoạt động như thế nào. Phần dưới đây tập trung vào nội dung mà hai phần đó không đề cập: phiên thực tế đã chọn credential nào và cách thay đổi credential đó.

Hành vi dưới đây dựa trên tài liệu xác thực Claude Code của Anthropic, được đọc vào ngày 31 August 2026. Claude Code thường xuyên phát hành phiên bản mới và một số hành vi yêu cầu phiên bản tối thiểu cụ thể. Vì vậy, hãy chạy claude --version trước khi kết luận máy của bạn bị lỗi.

Hai tài khoản có thể dùng chung một địa chỉ email

Tài khoản claude.ai và tài khoản Claude Console tại platform.claude.com là hai tài khoản khác nhau. Chúng có thể dùng cùng một địa chỉ email nhưng vẫn là hai lần đăng nhập riêng, với số dư riêng và thuộc các organisation riêng. Tạo một tài khoản không tạo tài khoản còn lại. Thanh toán gói Max không cộng credit vào một Console organisation, và nạp tiền cho một Console organisation không bổ sung gì cho gói của bạn.

Số dư khác nhau vì hai mô hình billing khác nhau. Lần đăng nhập bằng subscription sử dụng hạn mức của gói, được reset theo cửa sổ 5 giờ trượt và cửa sổ hàng tuần; hạn mức này dùng chung với Claude trên web. Credential của Console được tính phí theo từng token cho organisation, và số liệu chính thức nằm trên trang usage của Console. Chi phí thực tế của khác biệt này khi làm việc là chủ đề của tính phí theo token so với trả tiền cho subscription.

Một loại tài khoản không thể dùng đường đăng nhập bằng subscription. Anthropic liệt kê các loại tài khoản có thể dùng để đăng nhập gồm subscription Pro hoặc Max, seat Claude for Teams hoặc Enterprise, tài khoản Claude Console và cloud provider. Tài khoản claude.ai miễn phí không nằm trong danh sách đó. Vì vậy, người dùng gói miễn phí không có credential subscription để đăng nhập, và gói Claude miễn phí có và không có những gì không áp dụng cho công cụ dòng lệnh. Lựa chọn còn lại là một Console organisation có API credit, tức một loại tài khoản trả phí khác.

Cách 1: đăng nhập bằng gói Claude của bạn

Chạy claude trong một thư mục project. Ở lần chạy đầu tiên, lệnh sẽ mở cửa sổ trình duyệt để bạn đăng nhập bằng tài khoản claude.ai đang có gói của bạn.

claude

Trên server, có 2 điểm hoạt động khác. Nếu trình duyệt không mở, nhấn c để copy URL đăng nhập vào clipboard, rồi dán URL đó vào trình duyệt trên máy của bạn. Nếu trình duyệt hiển thị mã đăng nhập thay vì chuyển bạn về terminal, hãy dán mã đó vào prompt đang yêu cầu mã. Trường hợp thứ hai là bình thường khi dùng SSH (secure shell), WSL2 và container, vì trình duyệt không thể truy cập callback server cục bộ mà Claude Code đã khởi động trên máy từ xa.

Sau khi đăng nhập xong, hãy kiểm tra thay vì mặc định cho rằng mọi thứ đã đúng. Bắt đầu một session và chạy /status. Tab Status hiển thị phương thức đăng nhập, cùng với organisation và địa chỉ email đã lưu. /login chạy lại quy trình với một account khác, còn /logout xóa credential đã lưu. Đăng xuất cũng reset trạng thái thiết lập lần chạy đầu tiên, vì vậy lần chạy claude tiếp theo sẽ hướng dẫn bạn thực hiện onboarding lại.

Bạn cần biết credential đó được lưu ở đâu khi rebuild một máy hoặc bàn giao máy cho người khác:

• Linux: ~/.claude/.credentials.json, với file mode 0600.
• macOS: Keychain được mã hóa. Khi Keychain từ chối ghi, thường xảy ra khi Keychain bị khóa trong một SSH session, Claude Code sẽ chuyển sang dùng cùng file 0600.
• Windows: %USERPROFILE%\.claude\.credentials.json, chỉ cho phép user của bạn truy cập thông qua access control của profile directory.
• Trên mọi platform khi đặt CLAUDE_CONFIG_DIR: file được chuyển vào thư mục đó, còn entry trong macOS Keychain được gắn với thư mục này. Vì vậy, session khởi động với CLAUDE_CONFIG_DIR khác sẽ đọc một credential khác.

Claude Code quản lý file đó thông qua /login và /logout. Tự chỉnh sửa file không phải là cách được hỗ trợ để chuyển account.

Đường 2: xác thực với một tổ chức trên Console

Quyền truy cập Console bắt đầu từ một administrator. Administrator mời bạn trong Console bằng cách vào Settings, rồi Members, sau đó chọn Invite. Administrator cũng gán một role: role Claude Code chỉ tạo được API key dành cho Claude Code, còn role Developer tạo được mọi loại key. Sau đó, bạn chọn tài khoản Anthropic Console tại prompt /login.

Từ Claude Code v2.1.242, có 2 route trên Console và chúng lưu các thông tin khác nhau. Khi đăng nhập bằng tài khoản Console, Claude Code giữ OAuth (open authorisation) token từ lần đăng nhập trên browser đó và lưu token này dưới dạng một Anthropic profile; thao tác này không tạo API key. Claude Code tự refresh lần đăng nhập đó. Khi refresh thất bại, các request sẽ fail cho đến khi bạn đăng nhập lại. Khi tạo API key, được prompt gắn nhãn legacy, Claude Code mint một Console key và lưu key đó cùng các credential khác. Static key không refresh, nên tiếp tục hoạt động cho đến khi có người revoke. Điều này hữu ích trên build server nhưng là một rủi ro trên laptop.

Unset ANTHROPIC_API_KEY trước khi bắt đầu đăng nhập Console không cần key. Khi biến này được set, Claude Code bỏ qua hoàn toàn login prompt và yêu cầu bạn approve key mà nó tìm thấy.

Bạn không phải lúc nào cũng có lựa chọn này. Claude Code tự tạo key mà không hỏi khi session chạy với cloud provider, khi bất kỳ settings file nào set forceLoginOrgUUID hoặc pin forceLoginMethod thành "claudeai" hoặc "console", hoặc khi trên máy có managed settings source nhưng Claude Code không đọc được source đó. Đây là các quyết định của administrator. Vì vậy, nếu tùy chọn không cần key không bao giờ xuất hiện, hãy hỏi người quản lý fleet. /status cũng in một dòng Setting sources, liệt kê tên của mọi settings file mà session đã load. Dòng này cũng nêu managed source khi source đó áp dụng cho bạn.

Lần đầu bạn xác thực Claude Code với một tổ chức trên Console, Console tạo một workspace có tên "Claude Code" cho tổ chức đó. Workspace này giúp theo dõi khoản chi của Claude Code tại một nơi. Bạn không thể tạo API key bên trong workspace đó.

Vì sao ANTHROPIC_API_KEY được ưu tiên sau khi bạn đăng nhập

Claude Code không hỏi bạn muốn dùng credential nào. Nó kiểm tra các nguồn theo một thứ tự cố định và dùng nguồn đầu tiên tìm thấy. Theo tài liệu vào tháng 08 năm 2026, thứ tự đó là:

1. Credential của cloud provider, khi CLAUDE_CODE_USE_BEDROCK, CLAUDE_CODE_USE_VERTEX hoặc CLAUDE_CODE_USE_FOUNDRY được thiết lập.
2. ANTHROPIC_AUTH_TOKEN, được gửi trong header Authorization: Bearer, dành cho gateway xác thực bằng bearer token.
3. ANTHROPIC_API_KEY, được gửi trong header X-Api-Key.
4. Output của một script apiKeyHelper được chỉ định trong file settings.
5. CLAUDE_CODE_OAUTH_TOKEN, token dài hạn từ claude setup-token.
6. Credential của Anthropic profile và federation.
7. Credential subscription được ghi bởi /login.

Credential subscription của bạn có mức ưu tiên thấp nhất. Vì vậy, một ANTHROPIC_API_KEY được export ở bất kỳ đâu trong process environment sẽ được ưu tiên hơn account bạn đã đăng nhập. Session sẽ tính phí vào một Console organisation trong khi bạn nghĩ nó đang dùng plan của mình. Không có gì bị hỏng. Thứ tự này hoạt động đúng như tài liệu mô tả, nên hệ thống không cảnh báo bạn.

Có 2 chi tiết khiến vấn đề này dễ bị bỏ sót. Trong session tương tác, Claude Code hỏi một lần bạn có muốn dùng key mà nó tìm thấy hay không, rồi ghi nhớ lựa chọn đó. Vì vậy, lựa chọn bạn đưa ra từ 1 tháng trước vẫn có thể được áp dụng hôm nay. Trong chế độ không tương tác với -p, hệ thống hoàn toàn không hiện prompt và luôn dùng key nếu key tồn tại. -p là chế độ mà cron job hoặc một bước CI (continuous integration) sử dụng. Vì vậy, job không có người giám sát chính là nơi credential sai bị bỏ sót lâu nhất.

Bạn có thể kiểm tra nhanh ngay trong session. Khi ANTHROPIC_API_KEY được thiết lập, /config sẽ hiển thị một toggle "Dùng custom API key". Toggle này chỉ xuất hiện khi biến được thiết lập. Vì vậy, nếu toggle không xuất hiện thì environment đã sạch.

Tìm key còn sót trên server

Một key đã export có thể còn tồn tại ở nhiều nơi hơn profile của shell:

• ~/.bashrc, ~/.bash_profile, ~/.profile hoặc ~/.zshrc, được đọc bởi mọi login shell mới.
• Một systemd unit, thông qua Environment= hoặc EnvironmentFile=, đối với mọi tiến trình bạn chạy dưới dạng service.
• tmux server, nơi giữ một bản sao của environment tại thời điểm server được khởi động. Một pane bạn mở hôm nay có thể kế thừa một biến mà bạn đã xóa khỏi profile từ tuần trước, vì server đã chạy từ trước khi bạn chỉnh sửa.
• Một container image hoặc CI job definition, nơi biến được đặt bên ngoài mọi file mà bạn có thể đọc từ trong shell.
• Block env trong file cài đặt Claude Code. Đây là một settings key thông thường và tuân theo thứ tự ưu tiên settings mặc định.

Hãy kiểm tra các vị trí này trước khi làm thêm việc gì:

[ -n "$ANTHROPIC_API_KEY" ] && echo "ANTHROPIC_API_KEY is set" || echo "not set"
env | grep -E '^(ANTHROPIC_|CLAUDE_CODE_)' | cut -d= -f1
grep -n 'ANTHROPIC_API_KEY' ~/.bashrc ~/.bash_profile ~/.profile ~/.zshrc 2>/dev/null
tmux show-environment 2>/dev/null | grep ANTHROPIC
grep -n 'ANTHROPIC_API_KEY\|apiKeyHelper' ~/.claude/settings.json .claude/settings.json .claude/settings.local.json 2>/dev/null

Lệnh thứ hai cố ý pipe qua cut để chỉ in tên biến, không in secret value lên màn hình mà bạn có thể đang chia sẻ hoặc ghi hình. Lệnh đầu tiên trả lời câu hỏi chính: nếu lệnh cho biết biến đã được set, claude tiếp theo bạn khởi động từ shell này sẽ dùng key đó. Nếu cả 5 lệnh đều không có output, không có credential nào trong environment. Khi đó, session khởi động từ đây sẽ chuyển sang dùng credential /login.

Thêm systemctl cat your-unit.service | grep -i environment cho mọi service chạy Claude Code, vì unit file tự đặt environment riêng và không đọc profile của shell.

Chuyển một session từ credential này sang credential khác

Để quay lại subscription của bạn:

unset ANTHROPIC_API_KEY
[ -n "$ANTHROPIC_API_KEY" ] && echo "still set" || echo "clear"
claude

Chờ clear, sau đó chạy /status trong session mới và xác nhận row API key đã biến mất. Việc bỏ set biến trong shell không ảnh hưởng đến tiến trình Claude Code đang chạy, vì tiến trình giữ nguyên environment tại thời điểm được khởi động. Hãy restart session.

Sau đó xóa dòng export khỏi file đã đặt biến đó. Nếu không, shell login tiếp theo sẽ đặt lại biến. Trong tmux, tmux set-environment -u ANTHROPIC_API_KEY sẽ xóa biến này cho các pane mở sau thời điểm đó trong session, còn các pane đã mở vẫn giữ bản sao riêng.

Để chuyển theo hướng ngược lại, hãy set ANTHROPIC_API_KEY trong environment, hoặc chạy /login rồi chọn account Console. Để xóa hoàn toàn login đã lưu, chạy /logout. Sau khi đăng nhập Console không cần key, /logout sẽ xóa và revoke credential mà lần đăng nhập đó đã ghi.

Nếu /status vẫn khác với kết quả bạn mong đợi, hãy chạy claude doctor. Lệnh này liệt kê các settings entry mà Claude Code đã từ chối. Nhờ đó, bạn có thể phát hiện settings file bị lỗi parse nên hoàn toàn không được áp dụng.

Xác thực khi không có browser

claude setup-token mở cùng luồng cấp quyền trên browser như /login và in OAuth token có thời hạn một năm ra terminal.

claude setup-token

Lệnh này không lưu token ở đâu, vì vậy hãy sao chép token ngay khi nó xuất hiện. Đặt token đó làm CLAUDE_CODE_OAUTH_TOKEN trên máy cần dùng. Token xác thực với subscription của bạn, nên cần gói Pro, Max, Team hoặc Enterprise và chỉ có thể gửi model request. Bare mode không đọc token này, vì vậy script truyền --bare cần ANTHROPIC_API_KEY hoặc một apiKeyHelper thay thế.

Thứ tự ưu tiên cũng có thể gây lỗi ở đây. Nếu CLAUDE_CODE_OAUTH_TOKEN nằm trong shell profile, chạy /login sẽ chuyển session hiện tại sang login mới. Mọi session mới cũng đọc lại biến này cho đến khi bạn xóa nó.

Nếu tổ chức của bạn chạy inference qua Amazon Bedrock, Google Cloud hoặc Microsoft Foundry, các credential đó đứng đầu thứ tự ưu tiên và hoàn toàn không xảy ra browser login. Cấu hình phần này là một công việc riêng, được trình bày trong chạy Claude Code với Bedrock hoặc Vertex.

Session chạy lâu trên VPS (virtual private server) là nơi các vấn đề này thường tập trung, vì shell đã khởi động session có thể được cấu hình từ nhiều tháng trước và chưa từng được restart. Chạy Claude Code trên VPS bên trong tmux trình bày phần session của thiết lập này.

Kiểm tra từng credential thực sự đã tiêu tốn bao nhiêu

Khi đăng nhập bằng subscription, /usage hiển thị các thanh mức sử dụng của plan và phân tích những thành phần đã tiêu tốn mức đó. Số tiền dollar trong block Session được tính cục bộ từ số lượng token theo giá niêm yết, nên hãy xem đây là con số ước tính dành cho người dùng API, không phải hóa đơn. Người đăng ký nên đọc các thanh mức sử dụng, không phải số tiền dollar.

Với Console credential, các số liệu cần xem nằm trong Console: trang usage để kiểm tra chi phí và dashboard Claude Code để xem số liệu theo từng member. Không có thông tin nào được in trong terminal của bạn là nguồn chính thức để tính billing đó.

Nếu các thanh mức sử dụng của plan không bao giờ thay đổi trong lúc bạn làm việc, một environment credential đang được ưu tiên. Đây là dấu hiệu đáng tin cậy nhất cho thấy credential không đúng đang có hiệu lực, và theo dõi chi phí của một session Claude Code sẽ đo lường chi tiết hơn. Nếu các thanh có thay đổi rồi dừng lại, thay vào đó bạn đã chạm giới hạn của plan; cách giới hạn usage của Claude và các khoảng thời gian reset hoạt động giải thích vấn đề này.

Các trường hợp lỗi và những gì cần kiểm tra

Mọi thứ đều hoạt động, nhưng mức sử dụng trong plan không bao giờ thay đổi. Một environment credential đang có hiệu lực. /status hiển thị một dòng API key, và lệnh kiểm tra shell ở trên hiển thị biến đó.

Request thất bại dù subscription của bạn vẫn còn hiệu lực. Một key thuộc Console organisation đã bị vô hiệu hóa hoặc hết hạn đang được ưu tiên hơn thông tin đăng nhập của bạn. Chạy unset ANTHROPIC_API_KEY, bắt đầu session mới rồi kiểm tra lại /status.

Có cảnh báo khi khởi động rằng thông tin đăng nhập của bạn sắp hết hạn. Các phiên bản gần đây sẽ cảnh báo khi credential /login còn 3 ngày là hết hạn. Khi đó, /status hiển thị dòng login ở trạng thái hết hạn, cùng với organisation và email đã lưu. Chạy /login để gia hạn. Cảnh báo này không bao giờ chặn request, nên rất dễ bị bỏ qua cho đến khi session không có người giám sát ngừng xử lý request.

apiKeyHelper chạy chậm hoặc thất bại. Theo mặc định, Claude Code chạy lại helper sau mỗi năm phút. Bạn có thể điều chỉnh khoảng thời gian này bằng CLAUDE_CODE_API_KEY_HELPER_TTL_MS. Claude Code hiển thị thông báo trên prompt bar khi một lần chạy mất hơn 10 giây. Helper không trả về key, dù do lỗi hay timeout, sẽ khiến request thất bại trong vòng 3 lần thử.

Credential đúng nhưng organisation sai. Một địa chỉ email có thể thuộc 2 organisation. /status cho biết organisation mà credential đã xác thực vào. Hãy đọc dòng này thay vì mặc định rằng bạn đã đăng nhập vào organisation nào.

FAQ

Làm thế nào để biết Claude Code hiện đang dùng account nào?

Chạy /status trong session. Tab Status hiển thị dòng Login method cho account bạn đã đăng nhập và thêm dòng API key khi API key cung cấp credential. Dòng Profile thay thế dòng login khi bạn chọn Anthropic profile hoặc federation credential. Bên ngoài session, kiểm tra ANTHROPIC_API_KEY có được set trong shell hay không để biết có environment credential nào đang được ưu tiên hơn login hay không.

Vì sao subscription Claude Pro hoặc Max của tôi bị bỏ qua?

Vì environment credential được ưu tiên hơn subscription đó. Claude Code lấy credential đầu tiên tìm thấy theo một thứ tự cố định. Credential của subscription /login đứng cuối, sau các biến của cloud provider, ANTHROPIC_AUTH_TOKEN, ANTHROPIC_API_KEY, apiKeyHelper và CLAUDE_CODE_OAUTH_TOKEN. Chạy unset ANTHROPIC_API_KEY, bắt đầu session mới rồi xác nhận bằng /status. Sau đó xóa export khỏi shell profile, systemd unit, môi trường tmux hoặc container definition đã set biến này. Nếu không, biến sẽ xuất hiện lại ở shell login tiếp theo.

Tôi có thể dùng Claude Code với account Claude miễn phí không?

Không. Các loại account mà Anthropic liệt kê để login gồm subscription Pro hoặc Max, seat Claude for Teams hoặc Enterprise, account Claude Console và cloud provider. Account claude.ai miễn phí không nằm trong danh sách này, nên Claude Code không có subscription credential để lưu cho account đó. Lựa chọn trả phí thay cho subscription là một Claude Console organisation có API credit, tính phí theo token. Đây là account riêng, ngay cả khi dùng cùng email address.

Account claude.ai và account Console của tôi có dùng chung một balance không?

Không. Đây là các account riêng với billing riêng, ngay cả khi cả hai dùng cùng email address. Usage của subscription trừ vào hạn mức của plan. Hạn mức này được dùng chung với Claude trên web và reset theo rolling window 5 giờ và weekly window. Usage của Console được tính phí theo token cho organisation và hiển thị trên trang usage của Console. Thêm credit vào account này không ảnh hưởng đến account kia.

Làm thế nào để authenticate Claude Code trên headless server?

Có 2 cách. Chạy claude qua SSH và hoàn tất browser login trên máy của bạn: nhấn c để copy URL, đăng nhập tại đó, rồi paste code trở lại terminal nếu browser hiển thị code thay vì redirect. Hoặc chạy claude setup-token trên máy có browser, copy token có thời hạn 1 năm được in ra, rồi set token đó làm CLAUDE_CODE_OAUTH_TOKEN trên server. Token này yêu cầu plan Pro, Max, Team hoặc Enterprise và chỉ có thể thực hiện model request. Vì vậy, script dùng --bare cần API key hoặc apiKeyHelper.