DEV Community

Cover image for Cách sửa lỗi Invalid custom3p enterprise config trong Claude Code
Sebastian Petrus
Sebastian Petrus

Posted on • Originally published at apidog.com

Cách sửa lỗi Invalid custom3p enterprise config trong Claude Code

Nếu bạn trỏ Claude Code tới DeepSeek V4, OpenRouter hoặc một nhà cung cấp mô hình bên thứ ba khác và gặp lỗi Invalid custom3p enterprise config, nguyên nhân thường nằm ở cấu hình URL, token, JSON settings hoặc policy doanh nghiệp. Bài viết này hướng dẫn cách hiểu “custom3p”, kiểm tra từng nguyên nhân phổ biến và áp dụng các cấu hình chạy được cho OpenRouter, LiteLLM và vLLM.

Thử Apidog ngay hôm nay

TL;DR

Invalid custom3p enterprise config nghĩa là Claude Code không xác thực được cấu hình nhà cung cấp bên thứ ba của bạn.

“custom3p” là nhãn nội bộ của Claude Code cho các endpoint API không phải Anthropic được cấu hình qua ANTHROPIC_BASE_URL.

Các lỗi phổ biến nhất:

  1. ANTHROPIC_BASE_URL có /v1 thừa ở cuối.
  2. Dùng sai biến xác thực: ANTHROPIC_API_KEY thay vì ANTHROPIC_AUTH_TOKEN, hoặc ngược lại.
  3. ~/.claude/settings.json sai định dạng JSON.
  4. Cài đặt Claude Code mới chưa hoàn tất onboarding.
  5. Gateway không chuyển tiếp các header cần thiết.
  6. Managed settings hoặc policy doanh nghiệp ghi đè cấu hình cục bộ.

Hãy kiểm tra URL trước. Đây là lỗi thường gặp nhất.

“custom3p” thực sự là gì?

Claude Code định tuyến request qua một trong các chế độ sau:

Chế độ Cách kích hoạt
API Anthropic mặc định Không có cấu hình ghi đè
Amazon Bedrock CLAUDE_CODE_USE_BEDROCK=1
Google Vertex AI CLAUDE_CODE_USE_VERTEX=1
Microsoft Foundry CLAUDE_CODE_USE_FOUNDRY=1
Bên thứ ba tùy chỉnh ANTHROPIC_BASE_URL trỏ tới endpoint khác

Dòng cuối là “custom3p”: custom third-party provider.

Khi bạn đặt ANTHROPIC_BASE_URL tới LiteLLM, OpenRouter, vLLM cục bộ hoặc một LLM gateway nội bộ, Claude Code gắn nhãn route đó là custom3p và chạy bước xác thực trước request API đầu tiên.

Nếu bước xác thực này thất bại, bạn sẽ thấy:

Invalid custom3p enterprise config
Enter fullscreen mode Exit fullscreen mode

Đây là lỗi xác thực cấu hình, không phải chặn policy. Vì vậy bạn có thể debug và sửa được.

Vì sao nhiều developer gặp lỗi này?

Vào tháng 4 năm 2026, Anthropic đã chặn quyền truy cập Claude Pro và Max đối với các công cụ agent bên thứ ba giả mạo client ID của Claude Code. Các công cụ như OpenClaw, vốn định tuyến phiên Claude Code qua backend riêng, đã ngừng hoạt động.

Đó là một vấn đề khác với lỗi trong bài này.

Sau đó, nhiều developer chuyển sang dùng cơ chế nhà cung cấp bên thứ ba chính thức của Claude Code để định tuyến qua backend rẻ hơn. Ví dụ, một chủ đề trên Reddit ghi lại việc chạy vòng lặp agent của Claude Code qua DeepSeek V4 Pro trên OpenRouter, với chi phí 0.87 USD cho mỗi triệu output token so với 15 USD của Anthropic, tức giảm khoảng 17 lần. Các dự án như DeepClaude đóng gói thiết lập này thành một lệnh.

Vấn đề: cấu hình third-party provider chính thức yêu cầu enterprise config hợp lệ. Sai một trường là Claude Code báo Invalid custom3p enterprise config.

Nguyên nhân 1: ANTHROPIC_BASE_URL có /v1 thừa

Claude Code tự thêm /v1/messages vào URL cơ sở.

Nếu bạn đặt URL đã có /v1, endpoint cuối cùng sẽ thành:

/v1/v1/messages
Enter fullscreen mode Exit fullscreen mode

Kết quả thường là 404.

Sai 

export ANTHROPIC_BASE_URL="https://api.openrouter.ai/api/v1"
Enter fullscreen mode Exit fullscreen mode 
export ANTHROPIC_BASE_URL="https://litellm.yourcompany.com/v1"
Enter fullscreen mode Exit fullscreen mode

Đúng 

export ANTHROPIC_BASE_URL="https://api.openrouter.ai/api"
Enter fullscreen mode Exit fullscreen mode 
export ANTHROPIC_BASE_URL="https://litellm.yourcompany.com"
Enter fullscreen mode Exit fullscreen mode

Cách kiểm tra nhanh

Chạy request tới endpoint mà Claude Code sẽ gọi:

curl -s -o /dev/null -w "%{http_code}" \
  -H "Authorization: Bearer $ANTHROPIC_AUTH_TOKEN" \
  "${ANTHROPIC_BASE_URL}/v1/messages" \
  -d '{"model":"claude-sonnet-4-6","max_tokens":1,"messages":[{"role":"user","content":"hi"}]}'
Enter fullscreen mode Exit fullscreen mode

Diễn giải kết quả:

  • 200: endpoint tồn tại và request hợp lệ.
  • 400: endpoint tồn tại, body có thể chưa đúng.
  • 404: URL sai, thường do /v1 bị lặp.

Nguyên nhân 2: Dùng sai biến xác thực

Claude Code có hai biến xác thực khác nhau:

Biến Header được gửi Khi nào dùng
ANTHROPIC_API_KEY x-api-key Gateway tương thích Anthropic và mong đợi API key
ANTHROPIC_AUTH_TOKEN Authorization: Bearer Gateway kiểu OAuth, LiteLLM, phần lớn thiết lập OpenRouter

Nếu gateway mong đợi bearer token nhưng bạn dùng ANTHROPIC_API_KEY, Claude Code sẽ gửi sai header và quá trình xác thực enterprise config thất bại.

OpenRouter

OpenRouter thường dùng bearer token:

export ANTHROPIC_AUTH_TOKEN="sk-or-your-openrouter-key"
export ANTHROPIC_BASE_URL="https://openrouter.ai/api"
Enter fullscreen mode Exit fullscreen mode

LiteLLM 

export ANTHROPIC_AUTH_TOKEN="sk-litellm-your-virtual-key"
export ANTHROPIC_BASE_URL="https://your-litellm-server:4000"
Enter fullscreen mode Exit fullscreen mode

Gateway DeepSeek hoặc vLLM dùng API key 

export ANTHROPIC_API_KEY="your-key-here"
export ANTHROPIC_BASE_URL="https://your-vllm-server"
Enter fullscreen mode Exit fullscreen mode

Nếu chưa chắc gateway cần header nào, hãy kiểm tra tài liệu xác thực của gateway hoặc log request phía gateway.

Nguyên nhân 3: settings.json sai định dạng

Nếu bạn đặt cấu hình trong ~/.claude/settings.json, chỉ cần JSON sai cú pháp là Claude Code không đọc được config.

Sai: dấu phẩy thừa 

{
  "env": {
    "ANTHROPIC_BASE_URL": "https://openrouter.ai/api",
    "ANTHROPIC_AUTH_TOKEN": "sk-or-your-key",
  }
}
Enter fullscreen mode Exit fullscreen mode

Sai: dấu ngoặc kép “thông minh” 

{
  "env": {
    “ANTHROPIC_BASE_URL”: “https://openrouter.ai/api”
  }
}
Enter fullscreen mode Exit fullscreen mode

Đúng 

{
  "env": {
    "ANTHROPIC_BASE_URL": "https://openrouter.ai/api",
    "ANTHROPIC_AUTH_TOKEN": "sk-or-your-openrouter-key"
  }
}
Enter fullscreen mode Exit fullscreen mode

Validate JSON trước khi chạy Claude Code

Dùng Python:

python3 -c "import json, os; json.load(open(os.path.expanduser('~/.claude/settings.json')))" && echo "Valid JSON"
Enter fullscreen mode Exit fullscreen mode

Hoặc dùng jq:

jq . ~/.claude/settings.json
Enter fullscreen mode Exit fullscreen mode

Nếu lệnh trên báo parse error, Claude Code sẽ không thể đọc enterprise config.

Nguyên nhân 4: Cài đặt mới chưa hoàn tất onboarding

Claude Code kiểm tra ~/.claude.json để tìm:

"hasCompletedOnboarding": true
Enter fullscreen mode Exit fullscreen mode

Nếu cờ này chưa có, Claude Code có thể bỏ qua custom provider config trong settings.json và đi qua luồng xác thực mặc định.

Kiểm tra trạng thái hiện tại:

cat ~/.claude.json | python3 -m json.tool 2>/dev/null | grep hasCompletedOnboarding
Enter fullscreen mode Exit fullscreen mode

Nếu khóa này thiếu hoặc là false, thêm vào ~/.claude.json:

{
  "hasCompletedOnboarding": true,
  "primaryApiKey": "sk-placeholder"
}
Enter fullscreen mode Exit fullscreen mode

primaryApiKey chỉ là giá trị giữ chỗ. Cấu hình enterprise của bạn sẽ ghi đè nó. Sau khi lưu file, khởi động lại Claude Code.

Nguyên nhân 5: Gateway không chuyển tiếp header cần thiết

Claude Code có bước feature handshake. Trong bước này, nó gửi các header như anthropic-beta để thương lượng capability.

Nếu gateway hoặc reverse proxy loại bỏ header này, Claude Code có thể nhận response không đúng kỳ vọng và báo:

Invalid custom3p enterprise config
Enter fullscreen mode Exit fullscreen mode

Các header nên được chuyển tiếp:

anthropic-beta
anthropic-version
X-Claude-Code-Session-Id
Enter fullscreen mode Exit fullscreen mode

Với LiteLLM, việc này hoạt động mặc định từ v1.82.9 trở lên. Với proxy tùy chỉnh hoặc nginx, cấu hình rõ ràng:

location /v1/ {
  proxy_pass http://backend;
  proxy_set_header anthropic-beta $http_anthropic_beta;
  proxy_set_header anthropic-version $http_anthropic_version;
  proxy_set_header X-Claude-Code-Session-Id $http_x_claude_code_session_id;
}
Enter fullscreen mode Exit fullscreen mode

Nếu bạn không thể sửa gateway để chuyển tiếp beta header, đặt biến sau trước khi chạy Claude Code:

export CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS=1
Enter fullscreen mode Exit fullscreen mode

Cách này bỏ qua các tính năng cần beta header. Vòng lặp agent cốt lõi vẫn hoạt động, nhưng một số tính năng thử nghiệm có thể không khả dụng.

Nguyên nhân 6: Policy doanh nghiệp ghi đè cấu hình cục bộ

Nếu bạn dùng Claude Team hoặc Enterprise và admin đã triển khai managed settings, cấu hình đó có thể ưu tiên hơn:

  • biến môi trường,
  • ~/.claude/settings.json,
  • custom base URL của bạn.

Kiểm tra managed settings:

ls ~/.claude/managed-settings.json 2>/dev/null && echo "Managed settings found"
Enter fullscreen mode Exit fullscreen mode

Hoặc trong Claude Code:

/status
Enter fullscreen mode Exit fullscreen mode

Nếu “Managed settings” đang hoạt động, bạn cần admin hỗ trợ. Họ có thể:

  • thêm domain gateway vào danh sách base URL được phép,
  • tạo availableModels bao gồm model ID từ gateway,
  • miễn trừ bạn khỏi hạn chế custom base URL.

Với triển khai doanh nghiệp bạn kiểm soát, managed settings thường nằm ở:

/Library/Application Support/ClaudeCode/managed-settings.json
Enter fullscreen mode Exit fullscreen mode

trên macOS, hoặc đường dẫn tương đương trên Windows/Linux.

Cấu hình chạy được

Claude Code + OpenRouter + DeepSeek V4 Pro

OpenRouter cung cấp API tương thích Anthropic. Cấu hình sau chạy vòng lặp agent của Claude Code qua DeepSeek V4 Pro.

Trong ~/.claude/settings.json:

{
  "env": {
    "ANTHROPIC_BASE_URL": "https://openrouter.ai/api",
    "ANTHROPIC_AUTH_TOKEN": "sk-or-your-openrouter-key",
    "ANTHROPIC_DEFAULT_SONNET_MODEL": "deepseek/deepseek-v4-pro",
    "ANTHROPIC_DEFAULT_OPUS_MODEL": "deepseek/deepseek-v4-pro",
    "ANTHROPIC_DEFAULT_HAIKU_MODEL": "deepseek/deepseek-v4-pro"
  }
}
Enter fullscreen mode Exit fullscreen mode

Việc ghi đè model là quan trọng. Nếu không, Claude Code vẫn có thể gửi claude-sonnet-4-6 tới OpenRouter. Tùy gói và routing, request có thể đi sai model.

Lưu ý: OpenRouter không triển khai đầy đủ đặc tả streaming của Anthropic cho một số tool call. Function call arguments có thể trống trong vài trường hợp ngoại lệ. Vòng lặp agent chính vẫn hoạt động, nhưng chuỗi multi-tool phức tạp có thể lỗi. Theo dõi trạng thái tương thích của OpenRouter để cập nhật.

Claude Code + LiteLLM

LiteLLM là gateway phù hợp nếu bạn muốn route qua nhiều provider. Nó xử lý header forwarding và model routing qua OpenAI, Anthropic, Vertex, Bedrock, Hugging Face và các backend khác.

config.yaml của LiteLLM:

model_list:
  - model_name: claude-sonnet-4-6
    litellm_params:
      model: deepseek/deepseek-v4
      api_key: "sk-your-deepseek-key"
  - model_name: claude-opus-4-7
    litellm_params:
      model: deepseek/deepseek-v4-pro
      api_key: "sk-your-deepseek-key"
Enter fullscreen mode Exit fullscreen mode

~/.claude/settings.json của Claude Code:

{
  "env": {
    "ANTHROPIC_BASE_URL": "http://localhost:4000",
    "ANTHROPIC_AUTH_TOKEN": "sk-litellm-your-key"
  }
}
Enter fullscreen mode Exit fullscreen mode

Với thiết lập này, Claude Code vẫn gửi model như claude-sonnet-4-6. LiteLLM nhận request đó và route sang DeepSeek V4. Bạn không cần override model name trong Claude Code.

Claude Code + vLLM cục bộ

Để chạy suy luận cục bộ với vLLM, khởi động server:

python -m vllm.entrypoints.openai.api_server \
  --model deepseek-ai/DeepSeek-V3 \
  --dtype auto \
  --api-key local-key \
  --port 8000
Enter fullscreen mode Exit fullscreen mode

Sau đó cấu hình Claude Code:

export ANTHROPIC_BASE_URL="http://localhost:8000"
export ANTHROPIC_API_KEY="local-key"
export ANTHROPIC_DEFAULT_SONNET_MODEL="deepseek-ai/DeepSeek-V3"
Enter fullscreen mode Exit fullscreen mode

Quy trình debug

Nếu các cách trên chưa giải quyết được lỗi, chạy Claude Code ở chế độ debug:

claude --debug 2>&1 | head -100
Enter fullscreen mode Exit fullscreen mode

Tìm các dòng sau:

  • Sending request to: — xác nhận URL thực tế.
  • Response status: — HTTP status từ gateway.
  • enterprise config error: — lỗi xác thực nội bộ.

Bạn cũng có thể tái tạo request bằng curl:

curl -v -X POST "${ANTHROPIC_BASE_URL}/v1/messages" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer ${ANTHROPIC_AUTH_TOKEN}" \
  -H "anthropic-version: 2023-06-01" \
  -H "anthropic-beta: max-tokens-3-5-sonnet-2024-07-15" \
  -d '{
    "model": "claude-sonnet-4-6",
    "max_tokens": 10,
    "messages": [{"role": "user", "content": "hi"}]
  }'
Enter fullscreen mode Exit fullscreen mode

Diễn giải nhanh:

  • 200: gateway hợp lệ.
  • 401 hoặc 403: lỗi xác thực hoặc quyền truy cập.
  • 404: sai base URL.
  • 422: body hoặc model không đúng format gateway mong đợi.

Kiểm tra API với Apidog

Khi debug tích hợp nhà cung cấp bên thứ ba, Apidog giúp bạn kiểm tra request và response đi qua LLM gateway mà không cần chạy lại Claude Code mỗi lần.

Cách làm thực tế:

  1. Tạo collection mới cho gateway của bạn.
  2. Thêm endpoint POST /v1/messages.
  3. Đặt các header sau làm collection variables:
    • anthropic-version
    • anthropic-beta
    • Authorization
  4. Tạo một request mẫu tương tự request của Claude Code.
  5. Thay đổi base URL hoặc token để so sánh response giữa các gateway.

Cách này đặc biệt hữu ích khi bạn nghi ngờ gateway không chuyển tiếp header. Bạn có thể xác nhận header nào được gửi và response nào được trả về trước khi sửa cấu hình Claude Code.

Các cấu hình Claude Code nên biết

Tắt phụ thuộc vào beta header

Nếu gateway doanh nghiệp không chuyển tiếp được custom header:

export CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS=1
Enter fullscreen mode Exit fullscreen mode

Vòng lặp agent vẫn hoạt động. Bạn chỉ mất một số tính năng được bảo vệ bởi beta header, ví dụ một số biến thể extended thinking hoặc format tool call nhất định.

Bật model discovery từ gateway

Từ Claude Code v2.1.129, bạn có thể để Claude Code truy vấn model từ gateway:

export CLAUDE_CODE_ENABLE_GATEWAY_MODEL_DISCOVERY=1
Enter fullscreen mode Exit fullscreen mode

Claude Code gọi /v1/models khi khởi động và thêm model phát hiện được vào selector /model.

Lưu ý: chỉ các model ID bắt đầu bằng claude hoặc anthropic được thêm tự động. Với DeepSeek hoặc model khác, hãy pin thủ công bằng:

export ANTHROPIC_DEFAULT_SONNET_MODEL="deepseek/deepseek-v4-pro"
Enter fullscreen mode Exit fullscreen mode

Thêm một model tùy chỉnh vào selector 

export ANTHROPIC_CUSTOM_MODEL_OPTION="deepseek/deepseek-v4-pro"
export ANTHROPIC_CUSTOM_MODEL_OPTION_NAME="DeepSeek V4 Pro"
export ANTHROPIC_CUSTOM_MODEL_OPTION_DESCRIPTION="17x cheaper than Claude Opus"
Enter fullscreen mode Exit fullscreen mode

Model này sẽ xuất hiện ở cuối selector /model, giúp bạn chuyển đổi dễ hơn trong phiên làm việc.

Các hướng dẫn liên quan

Nếu bạn đang khám phá Claude Code với backend model tùy chỉnh, các bài sau có thể hữu ích:

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

Dùng nhà cung cấp bên thứ ba với Claude Code có vi phạm điều khoản của Anthropic không?

Không. Anthropic có tài liệu hóa và hỗ trợ mẫu ANTHROPIC_BASE_URL để định tuyến qua Bedrock, Vertex AI, Foundry và các gateway tùy chỉnh.

Thứ bị chặn vào tháng 4 năm 2026 là các công cụ bên thứ ba giả mạo client ID của Claude Code để truy cập API Anthropic bằng giá gói đăng ký. Dùng gateway riêng hoặc provider như OpenRouter với API key của bạn là trường hợp khác.

Vòng lặp agent của Claude Code có hoạt động với DeepSeek V4 Pro không?

Vòng lặp cốt lõi hoạt động: chỉnh sửa file, chạy shell command và xử lý tác vụ nhiều bước.

Hai nhóm tính năng không hoạt động qua một số provider bên thứ ba:

  • công cụ MCP server,
  • input hình ảnh/thị giác.

Nếu workflow cần các tính năng này, bạn nên dùng API Anthropic hoặc Bedrock/Vertex.

Vì sao lỗi ghi “enterprise config” dù tôi không dùng gói Enterprise?

Claude Code dùng nhãn “enterprise config” cho thiết lập provider bên thứ ba, không phụ thuộc gói đăng ký. Đây là nhãn nội bộ trong code, không phải giới hạn của gói Enterprise.

Có thể chuyển giữa Anthropic và provider bên thứ ba trong cùng phiên không?

Không. Base URL được đọc khi Claude Code khởi động.

Để đổi provider:

  1. Thoát Claude Code.
  2. Đổi biến môi trường hoặc settings.json.
  3. Khởi động phiên mới.

Công cụ DeepClaude đóng gói thao tác này bằng flag CLI như --backend ds hoặc --backend anthropic.

Gateway nằm sau firewall công ty thì sao?

Claude Code hỗ trợ proxy qua biến môi trường:

export HTTPS_PROXY="http://your-proxy:8080"
export ANTHROPIC_BASE_URL="https://your-internal-gateway"
Enter fullscreen mode Exit fullscreen mode

Nếu proxy công ty chặn TLS, thêm CA certificate:

export NODE_EXTRA_CA_CERTS="/path/to/corporate-ca-bundle.pem"
Enter fullscreen mode Exit fullscreen mode

curl hoạt động nhưng Claude Code vẫn lỗi. Vì sao?

Claude Code có thêm request preflight để xác thực enterprise config. Request curl đơn giản có thể chưa tái tạo đủ.

Chạy:

claude --debug
Enter fullscreen mode Exit fullscreen mode

Sau đó so sánh request preflight với request curl. Các khác biệt thường gặp:

  • thiếu anthropic-beta,
  • thiếu X-Claude-Code-Session-Id,
  • body JSON không đúng format,
  • model ID không được gateway hỗ trợ.

Kết luận

Invalid custom3p enterprise config là lỗi xác thực cấu hình. Cách xử lý hiệu quả nhất:

  1. Bỏ /v1 khỏi ANTHROPIC_BASE_URL.
  2. Dùng đúng biến xác thực: ANTHROPIC_AUTH_TOKEN hoặc ANTHROPIC_API_KEY.
  3. Validate ~/.claude/settings.json.
  4. Đảm bảo onboarding đã hoàn tất trong ~/.claude.json.
  5. Kiểm tra gateway có chuyển tiếp anthropic-beta, anthropic-version và X-Claude-Code-Session-Id.
  6. Kiểm tra managed settings nếu bạn dùng môi trường Team/Enterprise.

Sau khi cấu hình hợp lệ, vòng lặp agent của Claude Code có thể chạy qua backend bạn chọn. DeepSeek V4 Pro qua OpenRouter hoặc LiteLLM đáp ứng phần lớn use case Claude Code với chi phí thấp hơn API Anthropic, nhưng các tính năng như MCP server tools và input hình ảnh/thị giác vẫn có thể cần API Anthropic.

Top comments (0)