首页
教程
立即安装
GitHub
English
快速入门

Magpie AI 快速开始

先理解 Magpie AI 的角色，再用最短路径完成第一次安装和配置闭环。

什么是 Magpie AI

Magpie AI（由 yetone 开发，开源于 GitHub）是一款面向现代 AI 编程终端的统一模型调度中心与本地网关。它的核心定位非常纯粹：“Every agent's model. One place.”——让开发者无需在散落各处的配置文件中反复折腾，就能自由为任意 AI 编程助手分配最合适的底层大模型。

无论你是在使用：

  • Claude Code（Anthropic 官方编码智能体）
  • Codex（OpenAI 编码助手）
  • Gemini CLI（Google 命令行开发工具）
  • OpenCode / OpenClaw / Cursor / Copilot 等

Magpie AI 都能为你提供全平台统一的管理入口，支持系统菜单栏应用、终端 TUI、全功能 CLI 命令行以及高性能本地网关（127.0.0.1:3425）。

解决什么痛点

如果你长期在终端使用 AI 编程助手，通常会面临以下现实痛点：

1. 配置散落各处，修改极易出错

每个工具都有自己独立的配置路径（~/.claude.json、~/.codex/config.toml、~/.gemini/settings.json 等）。手动去改动这些文件不仅极其繁琐，而且容易破坏手写的注释或因语法错误导致工具无法启动。

2. 无法随心所欲使用高性价比模型

Claude Code 默认仅支持 Anthropic 协议，无法原生直连 DeepSeek、Kimi 等高性价比模型。普通的中转工具往往因为无法转译 Tool Use（工具调用）和 Thinking（推理链）而频繁报错。

3. 长任务频控（HTTP 429）打断开发心流

长时间运行自动化测试或重构时，一旦触碰到官方账号频控，整个 Agent 会话直接挂掉，上下文现场全部丢失。

4. 商业 API 成本居高不下

虽然拥有 Claude Pro 或 ChatGPT Plus 网页会员，但在终端里却必须额外花钱充值昂贵的商业 API Token。

极速 3 分钟上手闭环

跟随以下四步，即可用最短路径完成第一次接入闭环：

第一步：安装 Magpie AI

在终端中运行官方一键安装脚本（适用于 macOS 与 Linux）：

bash
curl -fsSL https://usemagpie.ai/install.sh | sh

macOS 用户亦可通过 Homebrew 极速安装：

bash
brew install --cask magpie-app

安装完成后，在终端中输入 magpie 即可验证命令就绪。

第二步：添加你的第一个供应商

你可以使用内置预设添加常用 API Key，也可以挂载已有网页订阅：

bash
# 添加 DeepSeek 官方 API Key
magpie provider add deepseek sk-xxxxxxxxxxxxxxxxxxxxxxxx

# 或者挂载已有的 Claude 订阅会话
magpie accounts add claude

第三步：为 AI 代理绑定模型

只需一条简短命令，将 Claude Code 的后端指向刚配好的 DeepSeek 模型：

bash
magpie claude deepseek/deepseek-v4-pro

Magpie 会自动通过 AST 语法树无损改写 ~/.claude.json，并把请求导向本地网关 http://127.0.0.1:3425。

第四步：启动你的 AI 编码助手

现在，打开新的终端窗口启动 Claude Code：

bash
claude

向它发起一次真实的编程任务：

text
> 请重构当前目录下的 utils.ts，并编写覆盖边界情况的单元测试

你会发现 Claude Code 已经完全由 DeepSeek 强力驱动，文件读取、命令执行等 MCP 工具调用丝滑无阻，而 Token 开销直接下降 90%！

核心交互形态推荐

  • 偏好终端操作：随时运行 magpie tui，通过键盘方向键直观切换模型、查看实时请求流与配额图表。
  • 偏好图形交互：点击 macOS 顶部菜单栏的 Magpie 图标，在下拉菜单中一键完成秒级模型切换。
  • 偏好脚本自动化：使用 magpie ls 查看状态，使用 magpie save <profile> / magpie use <profile> 在工作与个人环境间瞬间穿梭。

下一步进阶阅读

常见问题

Q：第一次接入后，Claude Code 发起请求报错连接拒绝（Connection Refused）？

A：这通常是因为本地网关尚未启动。请运行 magpie ls 查看网关状态，或运行 magpie daemon start 启动本地服务；也可以直接打开桌面菜单栏应用，确认 127.0.0.1:3425 显示为运行中。

Q：我必须购买商业 API Key 才能使用 Magpie AI 吗？

A：不一定。除了添加商业 API Key 之外，Magpie 还支持共享网页订阅（Shared Subscriptions）。你可以通过 magpie accounts add claude 或 magpie accounts add chatgpt 挂载已有的 Claude Pro 或 ChatGPT Plus 会员账号，直接在终端中复用网页端额度。

Q：后续如果想还原回工具的官方默认连接，该怎么操作？

A：你可以随时运行 magpie reset [agent-name]（例如 magpie reset claude）快速解除网关接管，将配置文件一键还原为官方出厂默认值；若需全部恢复，运行 magpie reset --all 即可。