Lỗi Claude Code ANTHROPIC_AUTH_TOKEN: Các cách sửa cấu hình đầy đủ

Khi Lỗi Claude Code ANTHROPIC_AUTH_TOKEN: Các cách sửa cấu hình đầy đủ là truy vấn, cách sửa thường bắt đầu bằng một câu hỏi: Claude Code có đang gửi thông tin xác thực trong tiêu đề mà gateway của bạn thực sự đọc không?

Đối với định tuyến gateway của Claude Code, ANTHROPIC_AUTH_TOKEN gửi Authorization: Bearer .... ANTHROPIC_API_KEY gửi x-api-key: .... Một token nằm trong biến sai có thể trông giống như key không hợp lệ, đăng nhập cũ, hoặc gateway bị lỗi, ngay cả khi giá trị của nó vẫn hợp lệ.

Hãy dùng quy trình này khi Claude Code thất bại sau khi bạn đặt ANTHROPIC_AUTH_TOKEN, ANTHROPIC_BASE_URL, một tệp cài đặt Claude Code, tiện ích mở rộng VS Code, hoặc một workflow CI.

Cách sửa nhanh

Bắt đầu với chẩn đoán nhỏ nhất có thể trước khi chỉnh sửa mọi tệp cài đặt trên máy của bạn.

1. Chọn một biến thông tin xác thực.
2. Export URL gốc của gateway và biến thông tin xác thực đó trong cùng một shell.
3. Chạy một yêu cầu curl với một token tới $ANTHROPIC_BASE_URL/v1/messages.
4. Khởi động Claude Code từ chính shell đó.
5. Chạy /status và xác nhận cả Anthropic base URL lẫn nguồn thông tin xác thực mong đợi đều xuất hiện.
6. Nếu curl thành công nhưng Claude Code vẫn yêu cầu bạn đăng nhập, hãy chuyển thông tin xác thực đến nơi mà Claude Code đọc trước khi thiết lập lần đầu, chẳng hạn như ~/.claude/settings.json, một shell export, hoặc các cài đặt được quản lý.

Đối với gateway dùng bearer token:

export ANTHROPIC_BASE_URL="https://llm-gateway.example.com"
export ANTHROPIC_AUTH_TOKEN="REPLACE_WITH_GATEWAY_TOKEN"

curl -X POST "$ANTHROPIC_BASE_URL/v1/messages" \
  -H "Authorization: Bearer $ANTHROPIC_AUTH_TOKEN" \
  -H "anthropic-version: 2023-06-01" \
  -H "content-type: application/json" \
  -d '{
    "model": "replace-with-a-gateway-supported-claude-model",
    "max_tokens": 1,
    "messages": [{"role": "user", "content": "."}]
  }'

Đối với gateway x-api-key:

export ANTHROPIC_BASE_URL="https://llm-gateway.example.com"
export ANTHROPIC_API_KEY="REPLACE_WITH_GATEWAY_KEY"

curl -X POST "$ANTHROPIC_BASE_URL/v1/messages" \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "content-type: application/json" \
  -d '{
    "model": "replace-with-a-gateway-supported-claude-model",
    "max_tokens": 1,
    "messages": [{"role": "user", "content": "."}]
  }'

Một phản hồi JSON có message id và content nghĩa là URL và thông tin xác thực hoạt động. 401 nghĩa là gateway đã từ chối thông tin xác thực hoặc đã nhận nó trong một tiêu đề mà nó không đọc.

Danh sách kiểm tra lỗi Claude Code ANTHROPIC_AUTH_TOKEN: Các cách sửa cấu hình đầy đủ

Dùng bảng này như chẩn đoán làm việc. Đừng xoay vòng key cho đến khi biết biến đang hoạt động, header, và thứ tự ưu tiên của cài đặt.

Chọn ANTHROPIC_AUTH_TOKEN hoặc ANTHROPIC_API_KEY

ANTHROPIC_AUTH_TOKEN dành cho bearer token. Claude Code gửi nó như sau:

Authorization: Bearer <token>

ANTHROPIC_API_KEY là dành cho một API key. Claude Code gửi nó dưới dạng:

x-api-key: <key>

Nếu nhóm gateway của bạn chỉ nói "token" hoặc "Authorization header," hãy bắt đầu với ANTHROPIC_AUTH_TOKEN. Nếu họ nói "API key" hoặc "x-api-key," hãy dùng ANTHROPIC_API_KEY. Nếu bạn đoán và nhận được 401, hãy đổi biến trước khi xoay vòng key.

Đừng đặt cả hai trong quá trình khắc phục sự cố. Đó là cách Lỗi Claude Code ANTHROPIC_AUTH_TOKEN: Các cách sửa cấu hình đầy đủ biến từ một vấn đề xác thực thành một vấn đề ưu tiên xác thực.

Đặt các biến ở nơi Claude Code thực sự đọc chúng

Export trong shell là tốt cho lần kiểm tra đầu tiên vì chúng dễ bỏ đặt:

export ANTHROPIC_BASE_URL="https://llm-gateway.example.com"
export ANTHROPIC_AUTH_TOKEN="REPLACE_WITH_GATEWAY_TOKEN"
claude

Chúng chỉ áp dụng cho phiên terminal đó và các chương trình được khởi chạy từ đó. Nếu bạn mở VS Code, một ứng dụng desktop, hoặc một agent nền từ nơi khác, export có thể sẽ không hiển thị.

Để cấu hình CLI bền vững ở cấp người dùng, hãy dùng ~/.claude/settings.json:

{
  "env": {
    "ANTHROPIC_BASE_URL": "https://llm-gateway.example.com",
    "ANTHROPIC_AUTH_TOKEN": "REPLACE_WITH_GATEWAY_TOKEN"
  }
}

Với một dự án, hãy dùng .claude/settings.local.json và đảm bảo nó được gitignore trước khi thêm thông tin xác thực. Đừng đặt thông tin xác thực trong .claude/settings.json, vì tệp này được thiết kế để chia sẻ với repo.

Khi một export trong shell và một khối env trong tệp cài đặt đặt cùng một biến, Claude Code sẽ dùng giá trị từ tệp cài đặt. Đó là lý do /status là nguồn sự thật tốt hơn echo $ANTHROPIC_AUTH_TOKEN.

Sửa tiện ích mở rộng VS Code

Tiện ích mở rộng Claude Code VS Code có các kiểm tra khởi chạy riêng. Cấu hình các biến gateway trong cài đặt người dùng VS Code dưới claudeCode.environmentVariables:

{
  "claudeCode.environmentVariables": [
    { "name": "ANTHROPIC_BASE_URL", "value": "https://llm-gateway.example.com" },
    { "name": "ANTHROPIC_AUTH_TOKEN", "value": "REPLACE_WITH_GATEWAY_TOKEN" }
  ]
}

Sử dụng lệnh VS Code Preferences: Open User Settings (JSON). Sau đó khởi động lại phiên tiện ích mở rộng và chạy /status. Nếu tiện ích mở rộng vẫn yêu cầu đăng nhập, nghĩa là nó không thấy thông tin xác thực tại chính bước kiểm tra đăng nhập của nó.

Sửa GitHub Actions

Claude Code GitHub Actions đọc ANTHROPIC_BASE_URL từ khối env của workflow. Với gateway x-api-key, hãy truyền key của gateway dưới dạng input của action:

env:
  ANTHROPIC_BASE_URL: https://llm-gateway.example.com

steps:
  - uses: anthropics/claude-code-action@v1
    with:
      anthropic_api_key: ${{ secrets.GATEWAY_API_KEY }}

Với gateway dùng bearer token, action vẫn cần anthropic_api_key để thỏa mãn kiểm tra khởi chạy của nó, trong khi ANTHROPIC_AUTH_TOKEN là giá trị mà Claude Code gửi dưới dạng Authorization: Bearer:

env:
  ANTHROPIC_BASE_URL: https://llm-gateway.example.com
  ANTHROPIC_AUTH_TOKEN: ${{ secrets.GATEWAY_API_KEY }}

steps:
  - uses: anthropics/claude-code-action@v1
    with:
      anthropic_api_key: ${{ secrets.GATEWAY_API_KEY }}

Giữ các giá trị đó trong GitHub Secrets. Không dán thông tin đăng nhập gateway vào nhật ký workflow, bình luận issue hoặc các tệp đã commit.

Dùng /status làm kiểm tra xác thực

Sau bất kỳ thay đổi cấu hình nào, hãy chạy:

/status

Đối với một gateway theo định dạng Anthropic, tab Status nên hiển thị:

Anthropic base URL: https://llm-gateway.example.com
Auth token: ANTHROPIC_AUTH_TOKEN

hoặc:

Anthropic base URL: https://llm-gateway.example.com
API key: ANTHROPIC_API_KEY

Nếu hàng base URL bị thiếu, ANTHROPIC_BASE_URL đã không đi vào phiên làm việc. Nếu nguồn thông tin xác thực là một lần đăng nhập đã lưu, Claude Code không đang dùng thông tin đăng nhập của gateway. Nếu cả hai đều trông đúng mà thông báo vẫn thất bại, vấn đề lúc này có thể nằm ở định tuyến gateway, khả năng tương thích upstream, hành vi proxy hoặc độ tin cậy của chứng chỉ.

Lưu ý về Flatkey cho định tuyến gateway của Claude Code

Flatkey hữu ích trong hai quy trình Claude Code khác nhau, và sự phân biệt này rất quan trọng.

Đối với các lời gọi mô hình tương thích OpenAI từ một project hoặc agent skill, base URL của Flatkey là:

https://router.flatkey.ai/v1

Đối với đường dẫn gateway riêng của Claude Code, hãy làm theo thiết lập gateway định dạng Anthropic Messages và không thêm /v1 vào ANTHROPIC_BASE_URL trừ khi hướng dẫn riêng của gateway về Claude Code nói rõ bạn nên làm vậy. Một mẫu nhà cung cấp điển hình là:

export ANTHROPIC_BASE_URL="https://router.flatkey.ai"
export ANTHROPIC_API_KEY="$FLATKEY_API_KEY"

Sau đó chạy /status, gửi một prompt ngắn, và kiểm tra sổ cái hoặc nhật ký của gateway. Giữ phần thiết lập Claude Code SKILL.md tách biệt với đường dẫn này: một skill dạy Claude Code cách gọi các mô hình và công cụ được Flatkey hỗ trợ từ repo của bạn; còn định tuyến gateway kiểm soát nơi Claude Code gửi lưu lượng Claude-family của chính nó.

Nếu bạn đang chuẩn hóa lưu lượng tác tử qua nhiều nhà cung cấp, hãy ghép bài viết này với các hướng dẫn Claude API proxy vs multi-model router và Flatkey API quickstart.

Kiểm tra của quản trị gateway khi token không phải là vấn đề thực sự

Một số tìm kiếm về Lỗi Claude Code ANTHROPIC_AUTH_TOKEN: Các cách sửa cấu hình đầy đủ ban đầu bắt đầu như một vấn đề thiết lập cục bộ và kết thúc ở gateway. Nếu lệnh curl với một token xác thực được và /status trông đúng, hãy kiểm tra các điều kiện phía gateway sau:

Nếu gateway của bạn đứng trước một nhà cung cấp không chấp nhận đầy đủ cấu trúc request của Anthropic Messages, hãy dùng các biến dành riêng cho nhà cung cấp thay vì ANTHROPIC_BASE_URL, hoặc chuyển đổi schema bên trong gateway. Đừng xóa trường một cách mù quáng; làm vậy chỉ đổi một lỗi hiển thị thành một lỗi chức năng muộn hơn.

Bản ghi debug có thể sao chép

Hãy dùng bản ghi này khi chuyển vấn đề cho đồng đội hoặc người vận hành gateway:

claude_code_auth_debug:
  date_checked: 2026-09-22
  surface: cli # cli | vscode | github_actions | agent_sdk | desktop
  claude_code_version: ""
  expected_gateway_base_url: "https://llm-gateway.example.com"
  variable_used: "ANTHROPIC_AUTH_TOKEN"
  expected_header: "Authorization: Bearer"
  status_tab_base_url_seen: false
  status_tab_credential_source: ""
  curl_status_code: ""
  curl_response_shape: "json_message | 401 | html_200 | dns_error | tls_error | other"
  settings_files_checked:
    - "~/.claude/settings.json"
    - ".claude/settings.local.json"
    - ".claude/settings.json"
  shell_started_claude: false
  saved_login_present: unknown
  gateway_logs_received_request: unknown
  suspected_fix: ""

Bản ghi đó buộc quá trình điều tra phải tách biệt ba thứ: Claude Code đã đọc cấu hình ở đâu, nó đã gửi header nào, và gateway đã trả về gì.

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

Nên dùng ANTHROPIC_AUTH_TOKEN hay ANTHROPIC_API_KEY?

Dùng ANTHROPIC_AUTH_TOKEN khi gateway mong đợi bearer token hoặc header Authorization. Dùng ANTHROPIC_API_KEY khi gateway mong đợi x-api-key. Nếu bạn không chắc, hãy bắt đầu với ANTHROPIC_AUTH_TOKEN, xác minh bằng yêu cầu curl, và đổi sang biến khác nếu bạn nhận được 401.

Tại sao /status không hiển thị base URL của tôi?

ANTHROPIC_BASE_URL đã không đến được tiến trình Claude Code. Hãy khởi động claude từ cùng một shell, chuyển giá trị vào đúng file settings, hoặc cấu hình trên bề mặt bạn đang dùng, chẳng hạn như cài đặt VS Code hoặc env của GitHub Actions.

Tại sao curl hoạt động nhưng Claude Code vẫn yêu cầu tôi đăng nhập?

URL cơ sở có thể truy cập được, nhưng Claude Code không có thông tin xác thực sẵn có vào đúng thời điểm nó cần. Hãy đặt ANTHROPIC_AUTH_TOKEN hoặc biến thông tin xác thực đúng vào một lệnh export của shell, cài đặt người dùng, hoặc cài đặt được quản lý mà Claude Code đọc trước khi thiết lập lần đầu.

Tôi có thể đặt token trong .claude/settings.json không?

Không đặt bí mật trong .claude/settings.json vì đây là tệp dự án dùng chung. Hãy dùng ~/.claude/settings.json, .claude/settings.local.json, cài đặt được quản lý, trình quản lý bí mật, hoặc bí mật CI.

ANTHROPIC_AUTH_TOKEN có chuyển Claude Code sang các mô hình không phải Claude không?

Không. Nó chỉ thay đổi cách Claude Code xác thực với cổng Anthropic theo định dạng đã cấu hình. Cổng này có thể định tuyến hoặc cầu nối các yêu cầu theo cách triển khai riêng của nó, nhưng Claude Code vẫn mong đợi dạng API Claude trên đường dẫn ANTHROPIC_BASE_URL.

Xác minh cuối cùng an toàn nhất là gì?

Chạy yêu cầu curl một token, khởi động Claude Code từ bề mặt đã cấu hình, chạy /status, gửi một prompt ngắn, và xác nhận sổ cái hoặc nhật ký của cổng hiển thị yêu cầu. Bài kiểm tra bốn bước đó là bản sửa lỗi bền vững đứng sau Lỗi Claude Code ANTHROPIC_AUTH_TOKEN: Các cách sửa cấu hình đầy đủ.

Các nguồn đã kiểm tra

• Tài liệu Anthropic Claude Code: Kết nối Claude Code với một cổng LLM, truy cập 2026-09-22.
• Tài liệu Anthropic Claude Code: Các tệp cài đặt và thứ tự ưu tiên, truy cập 2026-09-22.
• Tài liệu Anthropic Claude Code: Hướng dẫn tương thích cổng Claude Code, truy cập 2026-09-22.
• Trung tâm trợ giúp Claude: Quản lý biến môi trường khóa API trong Claude Code, truy cập 2026-09-22.
• SKILL.md công khai của Flatkey, truy cập 2026-09-22.
• Cơ sở tri thức Flatkey: Tổng quan sản phẩm, Chiến lược tiếp thị, Giọng điệu thương hiệu.