# One-click setup with magpie

[magpie](https://usemagpie.ai) is an open-source desktop tool (MIT license). It runs a local gateway on your computer and connects dozens of tools, including Claude Code, Codex, Gemini CLI and OpenCode, to the providers you choose. Add 2api to magpie once. After that, switching tools or models takes a few clicks.

## One-click setup (recommended)

For Claude, click the first button and use a key in the `CC-Max` group. For GPT, click the second button and use a key in a GPT group (see [Groups](https://docs.2api.dev/en/start/endpoints/#groups)).

<MagpieButtons lang="en" />

After you click a button, magpie shows the confirmation dialog below. Click Get key (获取密钥) to open the 2api key page, copy your key, paste it back and click Add (添加). If you added 2api before, the button reads Replace (替换). To use both GPT and Claude, click each button once.

![magpie import confirmation dialog](../../../assets/magpie/import.png)

Once it is added, connect your tools to 2api on magpie's Agent page. See [Use 2api in your tools](#use-2api-in-your-tools) below.

## Install magpie

Download the macOS version from [usemagpie.ai](https://usemagpie.ai) and drag it into Applications. You can also install it with a command:

  ```bash
  curl -fsSL https://usemagpie.ai/install.sh | sh
  ```
  Download the Windows installer from [usemagpie.ai](https://usemagpie.ai). The installer is not signed. If SmartScreen appears the first time you run it, click More info, then Run anyway.
  ```bash
  curl -fsSL https://usemagpie.ai/install.sh | sh
  ```
  The GUI needs GTK3 and WebKitGTK 4.1. Without them you can only use the command line and `magpie tui`.
  If downloads are slow in mainland China, you can make the install script use a GitHub download mirror or a local proxy:

```bash
curl -fsSL https://usemagpie.ai/install.sh | sh -s -- --mirror https://gh-proxy.com/
curl -fsSL https://usemagpie.ai/install.sh | sh -s -- --proxy http://127.0.0.1:7890
```

## Use 2api in your tools

1. Open the Agent page, find Claude Code (or Codex), and turn on the Connect (接入) toggle on its right.

2. Open the model dropdown on the right and pick a model with the 2api icon: for Claude Code, one under 2api Claude; for Codex, one under 2api GPT. Don't choose `auto/...`. It routes requests to other providers.

3. Start a new session before you use it. Codex only picks up the change after you fully quit and reopen it.

![magpie Agent page](../../../assets/magpie/agents.png)

## Check that it works

- In Providers, open the 2api row → Endpoints (端点) → Test (测试). It sends one small real request, which uses a tiny amount of quota.
- Or send a message in Claude Code. magpie's Routing (路由) page shows which provider the request went through.

## Add manually

If the one-click buttons don't open magpie, add 2api by hand:

1. Open magpie and go to Providers (供应商) → Add provider (＋ 添加供应商) → Custom provider (自定义供应商).

2. Enter `2api Claude` or `2api GPT` as the name.

3. Enter the protocol and API address that match the key's group:

   | Key's group | Protocol | API address |
   | --- | --- | --- |
   | `CC-Max` | Anthropic-compatible | `https://2api.dev` |
   | A GPT group | OpenAI Responses | `https://2api.dev/v1` |

4. Paste the API key, click Fetch models (获取模型), then click Add.

:::caution[Two groups, two providers]
Each 2api key belongs to one group. Add the GPT key and the Claude key as two separate providers. Don't add them as several keys under one provider.
:::

## Notes

- **magpie must stay open.** Your tools connect to the magpie gateway on your computer. If you quit magpie, they can't connect. To have it run at startup: `magpie daemon install`.
- **Restoring your setup when you stop using it:** Run `magpie uninstall`. Each tool's config is restored. Don't just delete magpie. Your tools would keep pointing at a local address that no longer exists.
- **Proxy software:** If Clash, Surge or a similar app has TUN mode or the system proxy turned on, add direct rules for `127.0.0.0/8` and `::1`. Otherwise you get 502 errors.
- **Detect or test returns 503:** If the Claude group only allows the Claude Code client, magpie's Detect protocol (检测协议) and Test checks are rejected. This is normal. Real use in Claude Code is not affected.
- **Codex is charged more than expected:** Some users report a low cache hit rate when Codex goes through magpie. If Codex clearly costs more than a direct connection, use the [manual Codex setup](https://docs.2api.dev/en/clients/codex/) instead.

## Add from the command line

```bash
magpie provider add "2api Claude" id=2api-claude anthropic=https://2api.dev key=sk-your-cc-max-key
magpie provider add "2api GPT" id=2api-gpt url=https://2api.dev/v1 responses=https://2api.dev/v1 key=sk-your-gpt-key
magpie claude 2api-claude/model-name
magpie codex 2api-gpt/model-name
```

---

The steps on this page are adapted from the official magpie documentation. The screenshots show magpie's Chinese interface. magpie updates often, so the interface text may differ slightly.