# Claude Desktop Setup

[Claude Desktop](https://claude.com/download) is Anthropic's official desktop application (Windows / macOS / Linux), a local alternative to the claude.ai web app for handling PowerPoint, Excel, document, and MCP workflows. The desktop app recently added a **Configure Third-Party Inference** entry point that lets you point any Anthropic-compatible gateway as the inference backend without signing in to an Anthropic account. This guide shows how to wire QCode.cc into Claude Desktop so you can **skip the Pro subscription and reuse your existing QCode quota**.

## Why Use a Third-Party API

- **Save on Pro**: Run desktop PowerPoint / Excel / MCP workflows against your QCode plan instead of paying for Pro separately
- **Unlock Cowork**: [Claude Cowork](https://support.claude.com/en/articles/14680741-install-and-configure-claude-cowork-with-third-party-platforms) (sandbox + Skills + MCP + file operations) was originally a Pro / Team feature — once you connect QCode.cc you can **use Cowork without a Pro subscription**. See the Cowork section below
- **Unified quota**: Claude Desktop, Claude Code, Codex CLI, and Gemini CLI all draw from the same QCode API Key
- **Full model matrix**: The QCode.cc gateway exposes 25+ models across Anthropic (Opus 5 / 4.7, Sonnet 5 / 4.6, Haiku 4.5), OpenAI, and Google Gemini
- **Team rollout**: The configuration panel can Export a JSON profile that you push to team members via Jamf, Intune, or Group Policy

## Prerequisites

- Claude Desktop installed ([official download](https://claude.com/download), Windows / macOS / Linux)
- A QCode.cc API Key (starts with `cr_`), available from the [dashboard](https://qcode.cc/dashboard)
- Windows 10/11 users: a first-time install may prompt you to enable Virtual Machine Platform and reboot (one-time only)

## Configuration Steps

### Step 1: First Launch — Do Not Sign In

> Tip: in the signed-out state, the menu button in the top-left corner may not respond to clicks. Click into the email input field to give it focus, then press **Tab** to jump to the menu button and hit Enter to open it.

### Step 2: Enable Developer Mode

Click **Menu → Help → Troubleshooting → Enable Developer Mode**.

![Enable Developer Mode](/static/images/claude-desktop/1-help-menu.png)

Once enabled, a new **Developer** entry appears in the top menu bar.

### Step 3: Open Third-Party Inference Configuration

Click **Menu → Developer → Configure Third-Party Inference...**.

![Open third-party inference configuration](/static/images/claude-desktop/2-dev-menu.png)

### Step 4: Fill In Gateway Credentials

In the Connection section, select **Gateway** (Anthropic-compatible) mode and fill in the fields as shown:

![Fill in Gateway credentials](/static/images/claude-desktop/3-config.png)

| Field | Value |
|-------|-------|
| Gateway base URL | `https://asia.qcode.cc/api` |
| Gateway API key | Your QCode.cc API Key (starts with `cr_`) |
| Gateway auth scheme | **Leave as default `bearer`** (the QCode.cc gateway accepts both bearer and x-api-key, no change needed) |
| Gateway extra headers | Leave empty |

> Do **not** add a trailing `/` to the base URL — Claude Desktop appends `/v1/messages`, `/v1/models`, and other paths automatically.

### Step 5: Apply the Configuration

Click **Apply locally** in the bottom-right corner. The configuration is written to your machine and takes effect immediately, and the model dropdown will auto-populate with the 25+ models exposed by QCode.cc. Open a new conversation in the main window to start using it.

## Choosing the Gateway base URL

> **Note**: Pick the endpoint that matches your location:

| Your location | Gateway base URL |
|----------|------------------|
| Mainland China (recommended) | `https://asia.qcode.cc/api` |
| Mainland China (fallback) | `https://api.qcode.cc/api` |
| Outside mainland China | `https://api.qcode.cc/api` |

For the full endpoint reference, protocol paths, and geo-routing rules, see [Endpoints and API Paths](/docs/getting-started/endpoints-and-api-paths).

## Notes on the Model List

Under normal conditions, Claude Desktop calls `/v1/models` and the dropdown populates automatically with the full list. **No extra steps are needed.**

If the dropdown stays empty (rare, depends on the environment), you can populate it manually:

1. In the configuration panel, click **Export ▾ → Open in file manager** and locate the Claude Desktop JSON config
2. Add an `inferenceModels` array to the JSON:

```json
{
  "inferenceProvider": "gateway",
  "inferenceGatewayBaseUrl": "https://asia.qcode.cc/api",
  "inferenceGatewayApiKey": "cr_xxxxxxxx",
  "inferenceModels": [
    "claude-opus-5",
    "claude-opus-4-7",
    "claude-sonnet-5",
    "claude-haiku-4-5"
  ]
}
```

3. Save and **fully quit and relaunch** Claude Desktop (not just close the window)

## Team Deployment (MDM)

The **Export ▾** button in the bottom-right corner exports the current configuration as JSON, which pairs with enterprise MDM tools for bulk rollout — no manual setup per team member:

- macOS: push a user-level configuration profile via Jamf or Mosyle
- Windows: push to `%APPDATA%\Claude\` via Intune or Group Policy
- Linux: write to `~/.config/Claude/` via Ansible or Puppet

For detailed MDM integration, follow the [official Anthropic documentation](https://support.claude.com/en/articles/14680741-install-and-configure-claude-cowork-with-third-party-platforms).

## Shared Quota

Claude Desktop, the Claude Code CLI, the Codex CLI, and the Gemini CLI all use the same QCode.cc API Key and **share the same plan quota**. Signing in from multiple clients does not double-bill you. See [Billing](/docs/reference/billing) for the full pricing rules.

## Claude Cowork

[Claude Cowork](https://support.claude.com/en/articles/14680741-install-and-configure-claude-cowork-with-third-party-platforms) is the collaborative sandbox mode in Claude Desktop. It lets Claude execute Skills, run MCP servers, read and write local files, and run shell commands inside an isolated Linux environment — well suited for PPT / Excel / PDF processing, batch file work, and code-sandbox style flows. Cowork was previously oriented at Pro / Team subscribers.

> Anthropic now officially supports [running Cowork against a third-party inference gateway](https://support.claude.com/en/articles/14680741-install-and-configure-claude-cowork-with-third-party-platforms). Once you have followed this guide, QCode.cc users can **use Cowork without a Pro subscription**.

### What you can do once QCode is connected

- **Run Skills**: use the Cowork sandbox to drive the official Skills library (PowerPoint, Excel, PDF, image processing, etc.), with Opus 5 / Sonnet 5 from QCode underneath
- **MCP workflows**: load MCP servers (local files, GitHub, custom tools) inside Cowork and have them collaborate with QCode-hosted models
- **File and terminal operations**: Claude reads and writes files and runs shell commands inside the sandbox — great for cleaning up dumped text, batch renaming, running scripts
- **Shared quota**: Cowork inference draws from your QCode plan, sharing the same balance with Claude Code, Codex, and Gemini CLI

### Boundaries and tips

- **Some connectors still require an Anthropic account**: higher-level connectors such as Google Drive or Notion may still need an Anthropic sign-in. See the [official support article](https://support.claude.com/en/articles/14680741-install-and-configure-claude-cowork-with-third-party-platforms) for the authoritative list
- **Pick a model**: inside a Cowork task, manually pick `claude-opus-5` or `claude-sonnet-5` (`claude-opus-4-7` remains on sale) rather than relying on the default
- **First launch**: the Cowork sandbox downloads a runtime (a few hundred MB) on first use — be patient

## Limitations and Differences

- **The claude.ai web app is not supported**: third-party API support is a Desktop-only feature; the browser still routes to your Anthropic account
- **Windows first-time enable**: may prompt you to enable Virtual Machine Platform and reboot (one-time only)

## FAQ

### The model dropdown is empty

1. Check that the base URL has **no** trailing `/`
2. Confirm the API Key is complete and starts with `cr_`
3. If it is still empty, follow "Notes on the Model List" and populate `inferenceModels` manually in the JSON

### 401 Unauthorized error

1. The API Key must start with `cr_` and have no leading or trailing whitespace
2. Verify at [qcode.cc/dashboard](https://qcode.cc/dashboard) that the key is still valid
3. Leave Gateway auth scheme as the default `bearer` — do not switch to `x-api-key`

### Difference between "Apply locally" and "Export"

- **Apply locally**: writes to the local config file and takes effect immediately for the current user
- **Export**: exports a JSON file for team MDM rollout or backup

### Can I run the desktop app and the CLI at the same time?

Yes. Claude Desktop and the Claude Code / Codex CLI each read their own configuration independently (the desktop app reads its own JSON; the CLI reads `~/.claude/settings.json` or `~/.codex/config.toml`). They share the same QCode API Key and quota without conflict.

### How does this relate to CC Switch?

[CC Switch](/docs/ide/cc-switch) manages base URL and credential switching for CLI tools (Claude Code, Codex, etc.); Claude Desktop runs its own developer-mode configuration independently. The two target different client form factors and operate separately.

## Next Steps

- [Endpoints and API Paths](/docs/getting-started/endpoints-and-api-paths) — Full reference for QCode.cc's three protocols and four ingress domains
- [Claude Code Tutorial](/docs/getting-started/claude-code-tutorial) — Master the CLI workflow end-to-end
- [CC Switch Setup](/docs/ide/cc-switch) — Manage multiple CLI base URLs from one app
- [Billing](/docs/reference/billing) — Understand plans and quota