Base URL của Claude Code: cách đặt ANTHROPIC_BASE_URL đúng

Wokey Team · 2026-09-24

Trả lời ngắn: base URL của Claude Code được đặt bằng biến môi trường ANTHROPIC_BASE_URL. Chỉ dùng origin của gateway, không kèm /v1. Với Wokey, đó là https://api.wokey.ai; Claude Code tự nối thêm /v1/messages. Đặt khóa của bạn vào ANTHROPIC_AUTH_TOKEN, biến này được gửi dưới dạng Authorization: Bearer. Nếu bạn đặt base URL mà không đặt khóa, Claude Code vẫn tiếp tục dùng phiên đăng nhập claude.ai đã lưu.

Thiết lập tối thiểu

export ANTHROPIC_BASE_URL="https://api.wokey.ai"
export ANTHROPIC_AUTH_TOKEN="your Wokey API key"
claude

Trong Claude Code, chạy /status. Yêu cầu đang đi qua Wokey khi tab Status hiển thị:

• Anthropic base URL được đặt thành https://api.wokey.ai
• một dòng Auth token ghi tên ANTHROPIC_AUTH_TOKEN

Nếu không có dòng Anthropic base URL, biến môi trường chưa hề đến được phiên làm việc.

Vì sao thêm /v1 lại gây lỗi

Claude Code coi ANTHROPIC_BASE_URL là tiền tố và gọi $ANTHROPIC_BASE_URL/v1/messages. Nếu đặt thành https://api.wokey.ai/v1, yêu cầu sẽ đi đến /v1/v1/messages, và Wokey trả lời:

{"message":"Route POST:/v1/v1/messages not found","error":"Not Found","statusCode":404}

Các client tương thích OpenAI như Cursor hay Cherry Studio theo quy ước nhận .../v1. Claude Code thì theo quy ước của Anthropic, và hai quy ước này không trộn lẫn được. Cũng đừng thêm /v1/messages hay dấu gạch chéo ở cuối.

AUTH_TOKEN hay API_KEY

Wokey chấp nhận cả hai header. Khác biệt nằm ở phía Claude Code:

• ANTHROPIC_AUTH_TOKEN có hiệu lực ngay lập tức.
• ANTHROPIC_API_KEY cần phê duyệt một lần ở chế độ tương tác trước khi được dùng. Một khóa bạn từng từ chối sẽ bị âm thầm bỏ qua.

Đừng đặt cả hai với giá trị khác nhau. Khi hai header mang hai khóa khác nhau, Wokey từ chối yêu cầu:

{"error":{"code":"conflicting_api_key_headers","message":"conflicting_api_key_headers","type":"invalid_request_error"}}

Cùng một khóa trong cả hai header thì không sao.

Chuyện gì xảy ra khi chỉ đặt base URL

Base URL không phải là thông tin xác thực. Khi chỉ đặt ANTHROPIC_BASE_URL mà không có AUTH_TOKEN hay API_KEY, Claude Code vẫn gửi yêu cầu bằng phiên đăng nhập claude.ai đã lưu. Wokey không nhận ra đó là khóa Wokey và trả về 401.

Khi đã đặt thông tin xác thực của gateway, phiên đăng nhập claude.ai vẫn được lưu nhưng không được dùng; bỏ đặt biến để quay lại dùng nó.

Bạn có thể thấy một cảnh báo khi khởi động kết thúc bằng auth may not work as expected. Các phiên bản cũ hơn thì hiển thị Auth conflict: Both a token (SOURCE) and an API key (SOURCE) are set. Cả hai đều có nghĩa là đang có đồng thời thông tin xác thực của gateway và một phiên đăng nhập đã lưu. Để chỉ dùng gateway, hãy chạy /logout trong Claude Code để xóa phiên đăng nhập đã lưu.

Lưu cố định trong settings.json

Lệnh export chỉ có tác dụng trong terminal hiện tại, và các trình soạn thảo mở từ Dock hay menu Start không nhìn thấy nó. Để dùng hằng ngày, hãy đặt các giá trị vào khối env của ~/.claude/settings.json:

{
  "env": {
    "ANTHROPIC_BASE_URL": "https://api.wokey.ai",
    "ANTHROPIC_AUTH_TOKEN": "your Wokey API key"
  }
}

• Khi shell và một tệp thiết lập cùng đặt một biến, tệp thiết lập được ưu tiên. Nếu bạn đổi biến shell mà dường như không có tác dụng, hãy kiểm tra ở đây trước.
• Cho một dự án riêng, hãy dùng .claude/settings.local.json của dự án đó, và đảm bảo tệp này nằm trong gitignore.
• Không bao giờ đặt khóa trong .claude/settings.json của dự án. Tệp đó được commit vào repository.

Chọn mô hình

Wokey dùng cùng ID mô hình Claude như Anthropic, chẳng hạn claude-opus-5, claude-sonnet-5 và claude-haiku-4-5. Đổi mô hình trong phiên bằng /model. Để cố định mô hình cho từng cấp Opus, Sonnet và Haiku của Claude Code, thêm vào env:

{
  "env": {
    "ANTHROPIC_DEFAULT_OPUS_MODEL": "claude-opus-5",
    "ANTHROPIC_DEFAULT_SONNET_MODEL": "claude-sonnet-5",
    "ANTHROPIC_DEFAULT_HAIKU_MODEL": "claude-haiku-4-5"
  }
}

ANTHROPIC_DEFAULT_HAIKU_MODEL cũng quy định mô hình cho các tác vụ nền như đặt tiêu đề phiên.

Tiện ích VS Code và ứng dụng desktop

Tiện ích VS Code không dùng biến shell cho bước kiểm tra đăng nhập. Thay vào đó, hãy đặt chúng trong thiết lập người dùng của chính VS Code: chạy Preferences: Open User Settings (JSON) từ command palette và thêm:

{
  "claudeCode.environmentVariables": [
    { "name": "ANTHROPIC_BASE_URL", "value": "https://api.wokey.ai" },
    { "name": "ANTHROPIC_AUTH_TOKEN", "value": "your Wokey API key" }
  ]
}

Các giá trị trong ~/.claude/settings.json đến được tiến trình mà tiện ích khởi chạy, nhưng không đến được bước kiểm tra đăng nhập của chính tiện ích. Nếu tiện ích cứ yêu cầu bạn đăng nhập, hãy dùng thiết lập ở trên.

Ứng dụng Claude desktop không đọc ANTHROPIC_BASE_URL lẫn settings.json. Để đặt gateway:

1. Mở Help → Troubleshooting → Enable Developer Mode.
2. Mở Developer → Configure Third-Party Inference và nhập địa chỉ gateway.

Xem hướng dẫn cài đặt Claude Desktop để biết đầy đủ các bước.

Kiểm tra bằng curl trước

Từ cùng terminal đó, hãy thử mà không có Claude Code tham gia:

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":"claude-sonnet-5","max_tokens":1,"messages":[{"role":"user","content":"."}]}'

Phản hồi cho bạn biết:

• Bắt đầu bằng {"id":"msg_: URL và khóa đều ổn; vấn đề nằm ở cấu hình Claude Code của bạn.
• 401 với code invalid_api_key: khóa bị thiếu, gõ sai hoặc đã bị xóa.
• 404 có nhắc đến /v1/v1/messages: base URL bị thừa /v1.
• curl chạy được nhưng Claude Code vẫn yêu cầu đăng nhập: Claude Code không có thông tin xác thực của riêng nó. Hãy kiểm tra các biến đã được đặt trong cùng terminal đã khởi chạy claude chưa, hoặc chuyển chúng vào ~/.claude/settings.json.