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

Magpie AI 安装指南

按系统和安装方式选对入口，并在安装完成后立刻进入可验证状态。

系统要求

请只从官方网站 usemagpie.ai、GitHub Releases（github.com/yetone/magpie）或官方渠道获取 Magpie AI。任何要求付费、充值，或索取登录凭据的第三方网站，都不应视为官方渠道。

系统最低版本架构
WindowsWindows 10 及以上x64
macOSmacOS 12 (Monterey) 及以上Intel (x64) / Apple Silicon (arm64)
Linux见下方发行版说明x64 / ARM64

如果你不想比较太多，安装方式可以直接这样选：

  • 终端极速安装（macOS / Linux）：直接跑官方 curl 一键脚本
  • macOS 桌面用户：Homebrew Cask（brew install --cask magpie-app）或下载 DMG
  • Go 开发者 / 全平台：直接通过 go install github.com/yetone/magpie@latest
  • Windows：优先 MSI 安装包，临时试用再考虑便携版
  • Linux / 服务器 / NAS：优先 curl 脚本或 Docker 容器镜像

极速安装：官方自动化脚本（macOS / Linux）

这是最简便的部署方式，脚本会自动判断当前 CPU 架构（Apple Silicon / Intel / Linux x64 / ARM64）并自动下载配置：

bash
# 官方一键安装
curl -fsSL https://usemagpie.ai/install.sh | sh

如果你在国内网络环境下遇到连接超时或 GitHub 访问缓慢，可追加代理参数（替换为你本地实际的代理端口）：

bash
# 国内代理加速模式
curl -fsSL https://usemagpie.ai/install.sh | sh -s -- --proxy http://127.0.0.1:7890

安装完成后，直接在终端输入 magpie 或 magpie tui 即可开始使用。

前置要求

Magpie AI 管理的 CLI 工具，例如 Claude Code、Codex、Gemini CLI，都依赖 Node.js 环境。

推荐版本：

  • Node.js 18 LTS 或更高版本

如果你只是先装 Magpie AI 桌面应用本体，Node.js 不是桌面程序能否打开的前提；但如果你装完马上就要管理 Claude Code、Codex 或 Gemini CLI，最好先把 Node.js 准备好。

Windows 安装 Node.js

  1. 访问 Node.js 官网
  2. 下载 LTS 版本安装包
  3. 运行安装程序并完成安装
  4. 安装后验证：
bash
node --version
npm --version

如果这两个命令都能正常输出版本号，就说明 Node.js 和 npm 已经可用。

macOS 安装 Node.js

bash
# 使用 Homebrew 安装
brew install node

# 或使用 nvm（更灵活）
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.0/install.sh | bash
nvm install --lts

如果你后面可能切多个 Node 版本，nvm 更灵活；如果只是想尽快装好，Homebrew 更直接。

Linux 安装 Node.js

bash
# Ubuntu / Debian
curl -fsSL https://deb.nodesource.com/setup_lts.x | sudo -E bash -
sudo apt-get install -y nodejs

# 或使用 nvm
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.0/install.sh | bash
nvm install --lts

如果你已经有自己的 Node 安装习惯，就继续沿用原方案；这里给的是第一次安装时最短的一条路径。

安装 CLI 工具

这一步不需要一次把所有 CLI 都装齐。先准备一个你接下来打算交给 Magpie AI 管理的工具就够了。

Claude Code

macOS 可优先尝试：

bash
brew install claude-code

通用 npm 安装方式：

bash
npm install -g @anthropic-ai/claude-code

# 国内网络较慢时可使用镜像
npm install -g @anthropic-ai/claude-code --registry=https://registry.npmmirror.com

安装后建议运行一次：

bash
claude

确认命令本身可启动。

Codex

macOS 可优先尝试：

bash
brew install codex

通用 npm 安装方式：

bash
npm install -g @openai/codex

# 国内网络较慢时可使用镜像
npm install -g @openai/codex --registry=https://registry.npmmirror.com

安装后建议运行一次：

bash
codex

确认命令可启动。

Gemini CLI

macOS 可优先尝试：

bash
brew install gemini-cli

通用 npm 安装方式：

bash
npm install -g @google/gemini-cli

# 国内网络较慢时可使用镜像
npm install -g @google/gemini-cli --registry=https://registry.npmmirror.com

安装后建议运行一次你本机对应的启动命令，确认它已经在 PATH 中。

如果你经常遇到 npm 下载慢的问题，可以先设置镜像源：

bash
npm config set registry https://registry.npmmirror.com

Windows安装Magpie AI

安装包方式

  1. 打开 Releases 页面
  2. 下载 Magpie-v{版本号}-Windows.msi
  3. 双击运行安装程序
  4. 按提示完成安装
  5. 从开始菜单或桌面启动 Magpie AI

适合：

  • 大多数第一次安装的用户
  • 希望按 Windows 标准流程安装的人
  • 希望后续更新和卸载也更省心的人

绿色版（免安装）

  1. 下载 Magpie-v{版本号}-Windows-Portable.zip
  2. 解压到任意目录
  3. 运行 Magpie.exe

注意：

  • 最好解压到固定目录，不要放在下载临时目录里
  • 更适合试用，不一定是长期使用的首选方式

macOS安装Magpie AI

方式一：Homebrew (官方 Cask)

bash
# 直接安装 Magpie macOS 菜单栏应用
brew install --cask magpie-app

更新到最新版本：

bash
brew upgrade --cask magpie-app

适合：

  • 本来就用 Brew 管理开发工具
  • 习惯通过命令行更新应用

方式二：手动下载

  1. 下载 Magpie-v{版本号}-macOS.dmg 推荐优先选择 DMG，也可以下载 Magpie-v{版本号}-macOS.zip
  2. 打开 DMG，或解压 zip 得到 Magpie AI.app
  3. 将应用拖入“应用程序”文件夹

macOS 版本已完成 Apple 代码签名和公证，正常情况下可直接打开。

如果你只是第一次安装并希望步骤最少，DMG 通常比先准备 Brew 更直接。

Linux安装Magpie AI

Arch Linux

可使用 AUR 助手安装：

bash
# 使用 paru
paru -S magpie-bin

# 或使用 yay
yay -S magpie-bin

如果你本来就在用 paru 或 yay 管理桌面工具，这会是最自然的方式。

Debian / Ubuntu

  1. 根据架构下载： Magpie-v{版本号}-Linux-x86_64.deb 或 Magpie-v{版本号}-Linux-arm64.deb
  2. 安装：
bash
sudo dpkg -i Magpie-v{版本号}-Linux-*.deb

# 如果有依赖问题
sudo apt-get install -f

建议：

  • x86_64 机器下载 x86_64.deb
  • ARM 设备下载 arm64.deb
  • 安装后直接从应用菜单或命令行尝试启动

AppImage（通用）

  1. 根据架构下载： Magpie-v{版本号}-Linux-x86_64.AppImage 或 Magpie-v{版本号}-Linux-arm64.AppImage
  2. 添加执行权限：
bash
chmod +x Magpie-v{版本号}-Linux-*.AppImage
  1. 运行：
bash
./Magpie-v{版本号}-Linux-*.AppImage

适合：

  • 不想区分发行版包格式
  • 只是想先把程序快速跑起来

如果后面准备长期使用，再换成更贴近发行版的安装方式也不迟。

Docker 容器化运行（服务器与 NAS）

如果你的环境是无桌面的 Linux 服务器、私有 NAS 或容器集群，可以使用官方 Distroless 极简镜像运行 Magpie 本地网关：

bash
docker run -d \
  --name magpie \
  --restart unless-stopped \
  -p 3425:3425 \
  -v ~/.magpie:/root/.magpie \
  ghcr.io/yetone/magpie

容器常驻运行后，本机或同一内网的智能体均可将 Base URL 指向 http://127.0.0.1:3425/v1。

Android Termux 终端运行

Magpie 支持在 Android 设备的 Termux 环境中运行，让移动端开发者也能享受统一的模型调度能力：

bash
# 1. 安装基础依赖
pkg update && pkg install golang git

# 2. 编译安装最新版本
go install github.com/yetone/magpie@latest

# 3. 启动终端交互界面
magpie tui

验证安装

安装完成后，建议依次执行以下基础检查，确认系统环境与网关均已就绪：

  1. 终端命令验证：
    bash
    # 查看当前安装的 Magpie 版本号
magpie --version

# 查看已检测到的本地 AI 代理
magpie ls
  2. 终端 TUI 仪表盘启动： 运行 magpie tui，确认分屏面板正常渲染，按 q 退出。
  3. 系统菜单栏检查（桌面端）： macOS 顶部菜单栏或 Windows/Linux 托盘中能看到 Magpie 图标，点击可展开代理状态。
  4. 网关连通性探测： 在浏览器或终端中访问 http://127.0.0.1:3425/health，若返回 {"status":"ok"}，说明本地转译网关已就绪。

验证完成后，下一步通常就是添加第一个供应商并测试一次真实请求。

自动更新

Magpie AI 内置自动更新能力：

  • 启动时自动检查更新
  • 有新版本时在界面显示更新提示
  • 点击提示即可下载并安装

你也可以在：

  • 设置 → 关于

里手动检查更新。

卸载

Windows

  • 通过 设置 → 应用 卸载
  • 或运行安装目录中的卸载程序

macOS

  1. 将 Magpie AI.app 移到废纸篓
  2. 如需彻底清理，可选删除配置目录：
bash
~/.magpie/

Linux

bash
# Debian / Ubuntu
sudo apt remove magpie

# Arch Linux
paru -R magpie-bin

如果你只是升级，不需要先卸载；除非当前安装已经明显异常，或者你准备切换安装方式。

常见问题

Q：macOS 提示“已损坏，打不开”或“无法验证开发者”怎么办？

A：这是系统层面对未在 App Store 注册的应用的安全限制。请前往系统的「系统设置 -> 隐私与安全性」，拉到中下部找到拦截记录，点击「仍要打开」并输入密码验证即可。

Q：Windows 安装时 SmartScreen 提示阻止运行？

A：这是正常的系统防护提示。请点击弹窗中的“更多信息”，随后点击右下角出现的“仍要运行”按钮，即可顺利完成安装。

Q：运行 curl 一键安装脚本提示网络连接超时怎么办？

A：国内网络环境下访问 GitHub 偶尔会遇到阻断或限速。你可以在脚本命令末尾追加代理参数：curl -fsSL https://usemagpie.ai/install.sh | sh -s -- --proxy http://127.0.0.1:7890（请替换为你本地实际的代理端口），或者通过 Go 编译安装：go install github.com/yetone/magpie@latest。