Skip to main content
Version: Claude Desktop 2025.6 and above (native third-party inference/Gateway support, no repackaging or reverse proxy required).

​
1. Configuration Steps

​
Step 1: Enable Developer Mode

  1. Open Claude Desktop.
  2. Top menu bar → Help → Troubleshooting → Enable Developer Mode.
  3. After enabling, Claude Desktop will automatically restart. The Developer menu will appear in the top menu bar.

​
Step 2: Go to Third-Party Inference Configuration

  1. Menu bar → Developer → Configure third-party inference.
  2. In the popup window, select Gateway as the connection type.
Enable Developer Mode and enter third-party inference configuration Select Gateway as connection type

​
Step 3: Fill in Gateway Information

Fill in Gateway information
Gateway base URL filling rules (most common mistake):
  • Final request = your base URL + "/v1/messages"
  • If the actual endpoint is https://api.gravitex.ai/v1/messages, then base URL should be https://api.gravitex.ai
  • Do not add /v1/messages suffix yourself, otherwise it will become .../v1/messages/v1/messages resulting in 404.

​
Step 4: Configure the Model

There are 2 ways to choose from: Option 1 (recommended): Enable Model discovery:
  • Check “Auto-populate the model picker from {base URL}/v1/models at launch”.
  • Click Test model discovery to confirm the supported model list can be fetched.
  • The model dropdown will automatically show only supported models, avoiding incorrect model names.
Option 2: Manual specification. Click + Add in the Model list and fill in: Configure Model Discovery Why is Tier alias important? Claude Desktop internally uses opus / sonnet / haiku / fable tier aliases to allocate different types of calls (e.g., lightweight summary tasks may use haiku, complex reasoning uses opus). If you set claude-opus-4-8’s Tier alias to opus, the client knows to treat it as the Opus tier; leaving it empty or selecting incorrectly will cause an “Invalid: Model list” error. 📌 The first item in the Model list is the default model. It’s recommended to place your most frequently used model (e.g., Sonnet) at the top.
Common error: “Invalid: Model list” at the bottomUsually caused by one of the following:
  • Tier alias not selected;
  • Model ID duplicates an existing entry;
  • Model ID format not accepted by the client (contains spaces, special characters, etc.).
After fixing, click Save Changes first, then Apply Changes.

​
Step 5: Apply and Restart

  1. Click Apply Changes.
  2. Completely exit Claude Desktop (macOS: Claude menu → Quit Claude / Cmd+Q, and use Activity Monitor to confirm no Claude process is running).
  3. Reopen Claude Desktop.
  4. Send a test message to verify.

​
2. Verify Success

  • Claude Desktop starts normally, showing Your Account · Gateway in the bottom left.
  • No errors such as authentication / invalid api key / gateway unavailable / model_not_found after sending a message.

​
3. Troubleshooting

​
4. Security Notes

  • API Key is equivalent to a password — do not include it in public documents, screenshots, or code repositories.
  • Exported configuration files (.mobileconfig / .reg / .json) may contain plaintext keys. Store them only briefly on trusted devices and delete after use.
  • If your Key has been exposed in chats, screenshots, or logs, revoke it immediately and regenerate.