magpie Claude Code setup: install the local gateway and pick models (Nov 2026)
As of 2026-11-10, magpie's official docs (usemagpie.ai) put Claude Code on magpie in three steps: run the install command and start magpie; add a provider under Providers with your own API key; then run magpie claude with a provider/model name, and the model applies from the next session (for Codex, run magpie codex and restart the Codex app). magpie (yetone/magpie) is a gateway on your own computer at 127.0.0.1:3425 that translates between OpenAI Chat, OpenAI Responses, Anthropic Messages and Gemini; it is MIT-licensed and not affiliated with Apache Magpie. The three QCode addresses and commands are below.
Updated 2026-11-10
Point this tool at the QCode endpoint — one key for Claude, GPT and Chinese models.
- Billed per token — live rates on /models
- Pay by card (Visa / Mastercard), Apple Pay, Google Pay or crypto
- Self-service: top up and activate instantly
Four points from the official sources
Open source under the MIT License, by yetone
The yetone/magpie repository carries the MIT License (Copyright (c) 2026 yetone). The README closes with: magpie is not affiliated with Apache Magpie or the Apache Software Foundation.
The local gateway address
The gateway speaks OpenAI Chat, OpenAI Responses, Anthropic Messages and Gemini and translates between them, with streaming, tool calls and reasoning included.
Platforms and forms
The README says it runs on macOS, Windows and Linux (menu bar app, window, TUI, web UI and CLI), in Docker, and on Termux.
Where your keys live
Keys live in ~/.config/magpie/providers.json, readable by you alone. magpie never reads keys from your shell environment: what you add is what it uses.
What is magpie?
As of 2026-11-10, magpie's docs describe it as one place to choose the model each of your agents uses. You add the providers you have, pick a model per agent, and magpie writes it into that agent's own config. Behind it is a small gateway on your machine at 127.0.0.1:3425 that speaks the OpenAI, Anthropic and Gemini APIs and translates between them, so an agent that speaks only Anthropic Messages, such as Claude Code, can also use GPT or Chinese models. The author is yetone, the site is usemagpie.ai and the repository is yetone/magpie.
Install and uninstall commands
As of 2026-11-10, the official install command is curl -fsSL https://usemagpie.ai/install.sh | sh. It puts the magpie command in ~/.local/bin and the app in /Applications on a Mac or your app menu on Linux; go install github.com/yetone/magpie@latest works too. On Windows, download magpie-windows-amd64.exe (magpie-windows-arm64.exe for ARM) from the latest release; magpie.exe takes the same commands, and magpie-cli-windows-amd64.exe is the terminal-only build. There is also a Docker image, ghcr.io/yetone/magpie; see the official Docker docs. To uninstall, run curl -fsSL https://usemagpie.ai/install.sh | sh -s -- --uninstall: magpie first disconnects every agent and puts back what each had; your settings and providers in ~/.config/magpie stay, and --purge deletes them too.
Timeline
The yetone/magpie repository is created on GitHub.
QCode's docs finish testing magpie with Claude Code and Codex, and publish the magpie setup article on docs.qcode.cc.
QCode re-tested with that day's magpie terminal build: one magpie provider add command added QCode, and provider test got answers from all three addresses. The same day: checked the README, the official docs (Get started, Add to magpie, Docker, and the Claude Code and Codex model pages), the reference and the GitHub releases; the docs say magpie ships several times a day.
What the docs state, and what they leave open
Stated in the official docs
① For a model through magpie, the gateway runs with the app. ② A running session keeps the model it started with; agents read their config when they start, so a new model applies from the next session, and Codex needs its app restarted too. ③ Picking a model changes only the keys magpie needs in the agent's config; comments, ordering and indentation stay, and writes are atomic. ④ Claude Code: magpie writes ANTHROPIC_BASE_URL and ANTHROPIC_AUTH_TOKEN in ~/.claude/settings.json, and the token is the gateway's key, not your provider key; Codex: a [model_providers.magpie] table and the model in ~/.codex/config.toml. ⑤ You do not need to export OPENAI_BASE_URL or ANTHROPIC_BASE_URL yourself. ⑥ An import link saves nothing until you press Add, and when the id is already taken the button reads Replace. ⑦ magpie's models also show up in the /model lists of Claude Code and Codex (marked via magpie in Claude Code), so you can switch from inside the agent too.
What the docs leave open
As of 2026-11-10: ① The official home page words the minimum macOS version two ways (macOS 12+ and macOS 11 or later), so follow the requirement shown when you download. ② The README's list of supported agents is longer than the one in Get started and keeps growing; whether your agent is recognised is shown by the output of magpie ls. ③ The official import page says that without a models parameter magpie lists the models the provider's /v1/models returns; in QCode's test on 2026-11-10, a provider added without models= exposed only the first 24 (the output read 24 exposed of 28), so choose the models you need with magpie provider models after adding it.
Three ways to add a provider
Import link or the app
An import link is magpie://import? plus parameters; on the web use https://usemagpie.ai/import# with the same parameters, every value URL-encoded. The fields include name (or preset), chat, responses, anthropic, gemini, key and models. If the link has no key, you paste one in the dialog. In the app the entry is Providers → Add provider.
One command in the terminal
A preset needs only magpie provider add with the preset id and key (the official example: deepseek and sk-…); a custom address takes url= (OpenAI-compatible), anthropic= (Anthropic-compatible), responses=, models= and key=. In a terminal, magpie import with a link shows a summary and asks first, and -y skips the question; QCode's docs found that a link without a key is only previewed there, not saved, so in a terminal magpie provider add does it in one step.
magpie setup: install, add a provider, pick a model for Claude Code and Codex
① Install: on macOS and Linux run curl -fsSL https://usemagpie.ai/install.sh | sh; on Windows download magpie-windows-amd64.exe; then start magpie so the gateway is running. ② Add a provider: in the Providers tab press ＋ Add provider, paste a key for a preset, or choose Custom · any compatible URL for any other address; the terminal form is in the card above, and the full QCode command is further down. ③ Pick a model: on the Agents tab click the agent's model, or run magpie claude deepseek/deepseek-v4-pro or magpie codex deepseek/deepseek-v4-pro; models through magpie are named provider/model. ④ Start a new session so the agent reads the new config; Codex needs its app restarted too. ⑤ Check: magpie ls lists each agent's current settings, and magpie provider test with a provider id sends one tiny request per API and shows the latency. ⑥ To go back to the agent's own setup: magpie claude default or magpie codex default.
Adding QCode to magpie
As of 2026-11-10, QCode's magpie article gives three addresses: anthropic is https://api.qcode.cc/api, chat is https://api.qcode.cc/openai/v1, and responses is https://api.qcode.cc/openai (magpie's examples end responses in /v1; QCode's endpoint page states that /openai/responses and /openai/v1/responses are equivalent). Claude goes through the anthropic address, GPT through chat and responses, and Chinese models through anthropic or chat; for the Asia and North America access points, replace the domain with asia.qcode.cc or us.qcode.cc and keep the paths. The easiest route is the console button Import to CC Switch / magpie: click Import to magpie there and Claude and GPT are set up in one go, then pick models with magpie claude qcode/claude-sonnet-5-5 or magpie codex qcode/gpt-6.1-sol. Setting only the main model puts Claude Code's opus slot on the same model; to give it Opus, also run magpie claude opus qcode/claude-opus-5-5. QCode keys are protocol-agnostic, so one key serves both the Anthropic and the OpenAI-compatible interfaces for Claude Code, Codex and other tools, billed per token, with per-model rates on /models. Not ready for a monthly plan? Pay-as-you-go Packs start at $4 for a one-time quota you use within 7 days; if you already have a Personal Plan, add a booster pack when you need more quota.
Frequently asked questions
Why doesn't magpie take effect after I switch?
Most likely the session has not been restarted: a running session keeps the model it started with, the new model applies from the next session, and Codex needs its app restarted too. Then confirm the gateway is running: for a model through magpie the gateway runs with the app, and magpie healthcheck exits 0 while the gateway answers. magpie ls shows each agent's current settings, and magpie provider test checks whether a provider answers; other errors are covered on /magpie-errors-and-fixes.
Does magpie have to stay open?
For a model through magpie, yes: the gateway runs with the app. Closing the window leaves it running in the menu bar or tray; magpie tray starts the icon alone, magpie serve runs just the gateway, and magpie daemon install keeps it running as a service (systemd on Linux, launchd on the Mac). An agent on its own model does not go through magpie.
Where does magpie store my key, and is it safe?
Keys live in ~/.config/magpie/providers.json, readable by you alone, and magpie never reads keys from your shell environment. The docs say agents never see your keys: the ANTHROPIC_AUTH_TOKEN in Claude Code's config is the gateway's key. A web import link keeps its parameters after the #, which browsers do not send to a server. There is also privacy masking: with it on, keys, passwords and emails in a prompt are replaced with placeholders on your computer before the request leaves it, and put back in the reply; it is off by default and turned on in Settings → Privacy.
How do I uninstall magpie or restore my original config?
To restore: run magpie claude default or magpie codex default; magpie removes what it wrote and restores the values it replaced, such as an ANTHROPIC_BASE_URL you had before. To uninstall a script install, run curl -fsSL https://usemagpie.ai/install.sh | sh -s -- --uninstall; your settings and providers stay in ~/.config/magpie, and --purge deletes them too.
Can magpie and CC Switch be used together?
Yes, they can be installed side by side: on 2026-11-09 magpie's author yetone replied on X that using both together is fine, and the README says magpie's Import brings in the providers from CC Switch. Both tools write the config files of Claude Code and Codex; how they divide the work and which settings to watch when you run both are on the comparison page /magpie-vs-cc-switch.
How do I add QCode in magpie?
Pick any of three ways. The fastest is the console button Import to magpie; in a terminal, run magpie provider add QCode anthropic=https://api.qcode.cc/api url=https://api.qcode.cc/openai/v1 responses=https://api.qcode.cc/openai key=cr_xxx, which added QCode in one go in QCode's test on 2026-11-10; in the app, choose Custom under Providers → Add provider and enter the OpenAI-compatible base URL (the chat address), the Anthropic-compatible one (the anthropic address) and your cr_ key. Without models=, magpie exposes only the first 24 models, so pick the ones you use with magpie provider models qcode gpt-6.1-sol claude-sonnet-5-5 claude-opus-5-5 claude-haiku-5-5 (without a +, the list is replaced as a whole); with a GPT model first, magpie provider test shows ✓ on all three rows: chat, responses and anthropic. To replace the key of a saved QCode provider, run magpie provider key with qcode and the new key.
Sources
The README, LICENSE and reference of the yetone/magpie repository on GitHub, the GitHub API, the release information of magpie-releases, the usemagpie.ai home page, and the official docs Get started, Add to magpie, Docker, and the Claude Code and Codex model pages, all read on 2026-11-10; magpie author yetone's reply on X of 2026-11-09. QCode: the magpie article and the access-point page on docs.qcode.cc, qcode.cc/models and qcode.cc/pay-as-you-go, retrieved on 2026-11-10, and QCode's test with the magpie terminal build on 2026-11-10; the wording of the console import button comes from QCode's own site text.
Claude and GPT in magpie on one key
One QCode API key for Claude Code, Codex and more, billed per token; per-model rates are on /models.
Related reading
Pay-as-you-go Packs
One-time quota packs valid for 7 days, no subscription; per-model rates are on /models.
magpie vs CC Switch: how to choose
How the two differ in operation, clients, protocol translation, failover, privacy masking and license, and how each connects to QCode.
magpie not working: 401 and 405 errors and fixes (2026-11)
The official cause and fix for common magpie errors: a switch that does not apply, 401 in Docker, ZCode 405, the 400 in provider test and missing models.
Crypto payment guide
Nine coins, 56 networks, zero platform fee for AI coding API credits.
Statements on this page were checked on 2026-11-10 against the magpie repository, site and docs; the official pages prevail. Version checked: QCode's test on 2026-11-10 used magpie 0.1.3533; magpie ships several times a day, so menu names and commands follow the version you install. QCode model availability follows /models.