Claude Desktop Developer Mode:
trỏ API endpoint sang gateway riêng

Vì sao có người muốn đổi API endpoint của Claude Desktop

Mặc định Claude Desktop nói chuyện trực tiếp với endpoint chính thức của Anthropic. Với phần lớn người dùng thì không có gì phải bàn. Nhưng có ba tình huống lặp lại đủ nhiều để sinh ra cả một thị trường gateway trung gian:

Ý tưởng của hướng dẫn gốc rất đơn giản: thay vì cấu hình proxy ở tầng hệ điều hành, ta trỏ thẳng baseURL của client sang một API aggregation gateway — nghĩa là sửa một file JSON, restart app, xong. Tác giả quảng cáo mất khoảng 5 phút, và MCP tools / Projects / Artifacts vẫn hoạt động bình thường.

Developer Mode là gì

Developer Mode không phải một runtime riêng. Nó chỉ là cái cửa để mở file cấu hình claude_desktop_config.json. Có hai đường vào, dùng đường nào cũng ra cùng một file:

File này điều khiển ba thứ:

• MCP server definitions — Claude được gọi những local tool server nào
• Environment variables — trong đó có ANTHROPIC_BASE_URL và ANTHROPIC_API_KEY
• Log verbosity — để debug MCP tool call

Mọi thay đổi chỉ có hiệu lực sau khi thoát app hoàn toàn rồi mở lại. Đóng cửa sổ là chưa đủ — trên macOS app vẫn nằm ở menu bar, trên Windows vẫn nằm ở system tray.

Điều kiện cần

• Claude Desktop đã cài — khuyến nghị bản 0.10 trở lên
• Một endpoint gateway + API key — ví dụ bên dưới dùng CodeGateway: https://api.codegateway.dev/v1
• Bất kỳ text editor nào — VS Code, Notepad++, hoặc editor mặc định mà Settings mở ra

Cấu hình trên macOS

Đường dẫn mặc định của file:

macOS — config path
~/Library/Application Support/Claude/claude_desktop_config.json

# Mở nhanh từ Terminal
open ~/Library/Application\ Support/Claude/claude_desktop_config.json

Cấu hình tối giản:

claude_desktop_config.json
{
  "mcpServers": {},
  "env": {
    "ANTHROPIC_BASE_URL": "https://api.codegateway.dev/v1",
    "ANTHROPIC_API_KEY": "your-codegateway-api-key"
  }
}

Nếu đang có MCP server rồi thì thêm khối env vào, đừng ghi đè phần còn lại:

Giữ nguyên MCP, thêm env
{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/Users/yourname/Documents"]
    }
  },
  "env": {
    "ANTHROPIC_BASE_URL": "https://api.codegateway.dev/v1",
    "ANTHROPIC_API_KEY": "your-codegateway-api-key"
  }
}

Cấu hình trên Windows

Quy trình y hệt macOS, chỉ khác đường dẫn và cách thoát app. Dán đường dẫn dưới đây vào address bar của File Explorer rồi Enter là nhảy thẳng tới file:

Windows — config path
%APPDATA%\Claude\claude_desktop_config.json

Nội dung JSON không đổi so với macOS. Riêng đường dẫn filesystem trong args của MCP server phải escape bằng double backslash:

Windows path trong JSON
"args": ["C:\\Users\\yourname\\Documents"]

Thoát app: right-click icon Claude ở system tray → Exit, rồi mở lại.

Cách 2: biến môi trường hệ thống

Nếu quản nhiều máy, hoặc không muốn API key nằm trong file config, thì set ở tầng OS. Key sẽ không bao giờ chạm vào claude_desktop_config.json.

macOS / Linux — ~/.zshrc hoặc ~/.bashrc
export ANTHROPIC_BASE_URL="https://api.codegateway.dev/v1"
export ANTHROPIC_API_KEY="your-codegateway-api-key"

# Phải launch từ terminal để app thừa hưởng biến của shell
open -a "Claude"

Thứ tự ưu tiên: khối env trong claude_desktop_config.json thắng biến môi trường hệ thống khi cả hai cùng được set.

Verify: xác nhận traffic thật sự đi đúng đường

Đây là bước hay bị bỏ qua nhất, và cũng là bước quan trọng nhất — vì nếu config không có tác dụng, app vẫn chạy bình thường qua endpoint cũ mà không báo lỗi gì. Sau khi restart, gửi một message rồi mở dashboard của gateway: request phải xuất hiện trong usage log sau vài giây.

Kiểm tra endpoint độc lập bằng dòng lệnh:

Bash — kiểm tra endpoint
curl -s https://api.codegateway.dev/v1/models \
  -H "Authorization: Bearer your-codegateway-api-key" \
  | python3 -m json.tool | head -20

MCP tools vẫn chạy song song

Điểm này đáng nhớ: đổi API endpoint không ảnh hưởng MCP, vì đây là hai kênh hoàn toàn khác nhau.

Một config hoàn chỉnh dùng cả hai:

Config đầy đủ — 2 MCP server + custom endpoint
{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/Users/yourname/projects"]
    },
    "postgres": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-postgres", "postgresql://localhost/mydb"]
    }
  },
  "env": {
    "ANTHROPIC_BASE_URL": "https://api.codegateway.dev/v1",
    "ANTHROPIC_API_KEY": "your-codegateway-api-key"
  }
}

Theo số liệu CodeGateway tự công bố: chạy đồng thời 4 MCP server thì tool-call latency gần như không đổi, còn time-to-first-byte có cải thiện khi đi qua edge network của Cloudflare — kèm ghi chú rõ đây là small-sample internal test, mang tính minh hoạ, không phải benchmark chính thức.

FAQ