Claude Desktop với API bên thứ ba: Configure Third-Party Inference và khắc phục sự cố

Wokey Team · 2026-09-24

Trả lời ngắn: ứng dụng Claude desktop chỉ có đúng một cách để dùng API bên thứ ba: Developer → Configure Third-Party Inference. Nó không đọc ANTHROPIC_BASE_URL lẫn ~/.claude/settings.json, nên một thiết lập chạy được trong terminal của bạn sẽ không có tác dụng gì trong ứng dụng desktop. Hướng dẫn này đi qua các vấn đề mọi người thường gặp: thiếu menu, thiết lập không có hiệu lực, danh sách mô hình trống, và các tính năng đơn giản là không có ở chế độ bên thứ ba. Để thiết lập đầy đủ lần đầu, xem hướng dẫn cài đặt Claude Desktop.

Thứ tự đúng

1. Mở ứng dụng desktop và không đăng nhập tài khoản Anthropic.

2. Mở Help → Troubleshooting → Enable Developer Mode.

3. Mở Developer → Configure Third-Party Inference….

4. Trong Connection, đặt Inference provider thành Gateway, rồi điền Gateway credentials:

   Trường	Giá trị
   Gateway base URL	https://api.wokey.ai (không có /v1)
   Gateway API key	Khóa API Wokey của bạn
   Credential kind	Static API key
   Gateway auth scheme	Bearer (Wokey cũng chấp nhận x-api-key; giữ mặc định)

5. Nhấn Apply Changes, rồi Save & Restart.

Yêu cầu hệ thống:

• macOS: 14 (Sonoma) trở lên, trên Apple silicon hoặc Intel.
• Windows: Windows 10 bản dựng 19041 trở lên, trên x64 hoặc Arm64.

Không thấy menu Developer

Menu Developer chỉ xuất hiện khi đã bật chế độ nhà phát triển: Help → Troubleshooting → Enable Developer Mode. Nếu mục đó cũng không có trong menu Help, hãy cập nhật ứng dụng lên phiên bản mới nhất; các phiên bản cũ không có thiết lập suy luận bên thứ ba.

Cửa sổ cấu hình ở chế độ chỉ đọc

Nếu máy đã có cấu hình do quản trị viên đẩy xuống, chẳng hạn một hồ sơ MDM của công ty, cửa sổ sẽ mở ở chế độ chỉ đọc và bạn không thể thay đổi tại máy. Hãy hỏi quản trị viên, hoặc dùng một máy không bị quản lý.

Biến môi trường không có tác dụng

Đây là lỗi phổ biến nhất. Ứng dụng desktop chỉ lấy thiết lập gateway từ cấu hình suy luận bên thứ ba. Nó không đọc ANTHROPIC_BASE_URL lẫn settings.json.

Tab Code của ứng dụng desktop cũng hoạt động như vậy. Nó chạy cùng engine Claude Code như CLI, nhưng địa chỉ gateway và thông tin xác thực được lấy thẳng từ cấu hình desktop. Thiết lập cấp người dùng trong ~/.claude/settings.json không ghi đè được chúng.

Chiều ngược lại cũng vậy: cấu hình desktop không ảnh hưởng đến claude trong terminal của bạn. Hãy thiết lập riêng từng bên; với terminal, xem hướng dẫn base URL cho Claude Code.

Danh sách mô hình trống hoặc thiếu mô hình

Khi không có danh sách mô hình riêng, ứng dụng gọi GET /v1/models của gateway và chỉ giữ lại những mô hình có ID nhận ra được là Claude. Vì vậy với Wokey, tính năng tự động phát hiện hiển thị các mô hình như claude-opus-5 và claude-sonnet-5, và lọc bỏ GPT, Grok cùng các mô hình khác. Điều đó là bình thường.

Để cố định danh sách hoặc chọn mô hình mặc định, hãy nhập đầy đủ ID mô hình vào danh sách mô hình trong cửa sổ cấu hình (Model list, khóa inferenceModels):

• Mục đầu tiên là mặc định, và các phiên mới trong tab Code cũng bắt đầu với nó.
• Khi mọi mục đều là ID đầy đủ, ứng dụng bỏ qua yêu cầu /v1/models.
• Nếu /v1/models thất bại và danh sách trống, bộ chọn mô hình sẽ trống.

Lỗi

Gateway was unreachable: ứng dụng không kết nối được đến gateway. Kiểm tra Gateway base URL xem có gõ sai không, rồi thử từ terminal bằng curl:

curl -X POST https://api.wokey.ai/v1/messages \
  -H "Authorization: Bearer your Wokey API key" \
  -H "anthropic-version: 2023-06-01" \
  -H "content-type: application/json" \
  -d '{"model":"claude-sonnet-5","max_tokens":1,"messages":[{"role":"user","content":"."}]}'

Nếu curl chạy được mà ứng dụng thì không, nguyên nhân thường là proxy: terminal đi qua proxy còn ứng dụng thì không, hoặc ngược lại.

401 với code là invalid_api_key: yêu cầu đã đến Wokey, nhưng khóa bị thiếu hoặc sai. Wokey chấp nhận cả hai cơ chế xác thực, nên không cần đổi thiết lập đó. Hãy dán lại khóa.

invalid x-api-key: yêu cầu đã đi đến Anthropic, nên cấu hình bên thứ ba chưa có hiệu lực. Thường là do chưa nhấn Save & Restart, hoặc sau đó đã chọn đăng nhập Anthropic ở màn hình đăng nhập. Xem hướng dẫn về invalid x-api-key.

Để xem chi tiết hơn: xuất báo cáo bằng Help → Troubleshooting → Generate Diagnostic Report. Ba tệp trong đó hữu ích:

• managed-config.txt: cấu hình đang có hiệu lực.
• provider-status.txt: trạng thái kết nối gateway.
• deployment-mode.txt: chế độ hiện tại.

Nhật ký nằm tại:

• macOS: ~/Library/Logs/Claude-3p/main.log
• Windows: %LOCALAPPDATA%\Claude-3p\Logs\main.log

Các tính năng không có ở chế độ bên thứ ba

Các tính năng này phụ thuộc vào tài khoản Anthropic hoặc dịch vụ đám mây của Anthropic, nên không dùng được với gateway. Đây không phải lỗi cấu hình:

• Truy cập từ điện thoại và web claude.ai
• Chế độ giọng nói
• Chia sẻ dự án và plugin
• Claude Design, Claude Security và Claude Tag
• Computer use
• Remote Control và các môi trường đám mây do Anthropic lưu trữ

Hai tính năng khác bị tắt mặc định:

• Tool search và các tính năng beta thử nghiệm. Ứng dụng tắt chúng để tương thích với các gateway nghiêm ngặt. Bật lại tool search bằng toolSearchEnabled.
• Phiên từ xa qua SSH. Tính năng này đang ở giai đoạn beta trong chế độ bên thứ ba và cần quản trị viên thiết lập danh sách host được phép.

Quay lại tài khoản Anthropic

Chọn tùy chọn đăng nhập Anthropic ở màn hình đăng nhập để quay lại ứng dụng Claude desktop tiêu chuẩn.