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.