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

配置预设、运行模式与个性化

利用 Profiles 快照一键穿梭工作与个人环境，支持 Headless 守护进程、Docker 部署与端口定制。

在日常开发中，很多工程师会同时面临多种不同环境的切换需求：

  • 工作与个人项目隔离：在公司做业务开发时，必须使用企业内部部署的模型或已通过合规审批的模型端点；而在个人开源项目中，更倾向于使用 DeepSeek V4 或前沿推理大模型；
  • 远程与容器化部署：在云端开发机（Remote Dev Server）、Docker 容器或 NAS 环境下运行，需要 Magpie 以 Headless 无头常驻守护进程的形式运行，并对外暴露局域网监听；
  • 多设备与多工作空间同步：希望用一条命令瞬间将所有 AI Agent 的模型路由切换为当前任务所需的预设组合。

Magpie AI 提供了轻巧而强大的 Profiles（配置预设）机制、环境变量定制、守护进程管理与 TUI 键盘自定义，帮助你把工具调校到最适合自己工作流的状态。

核心功能一：Profiles（环境与配置预设）

Magpie AI 的 Profile 机制允许你将当前所有 Agent 的绑定关系、供应商配置以及路由组状态保存为一个命名的快照。

1. 保存当前工作快照

当你当前配置好了一套理想的环境（例如已将 Claude Code 绑定到 DeepSeek，Codex 绑定到 Kimi）：

bash
# 将当前环境保存为名为 "work" 的预设
magpie save work

# 为个人独立开发保存另一套预设
magpie save personal

2. 跨场景一键无缝切换

切换开发场景时，只需输入 magpie use <profile>，Magpie 会在毫秒级内通过 AST 批量重写所有受管应用的底层配置：

bash
# 一键切换至工作模式
magpie use work

# 一键切换至个人模式
magpie use personal

3. 查看与管理已有预设

bash
# 列出所有已保存的配置预设
magpie profiles

# 删除不再需要的旧预设
magpie profile delete client-legacy

核心功能二：网关参数与环境变量定制

Magpie AI 的本地代理网关默认监听在 http://127.0.0.1:3425。你可以通过配置文件（~/.magpie/config.yaml）或系统环境变量灵活重写核心参数：

环境变量 / 配置项默认值作用说明
MAGPIE_PORT3425本地网关监听端口。如果与本地其他开发服务冲突，可修改为如 8080
MAGPIE_HOST127.0.0.1监听地址。在容器或局域网共享场景下可设置为 0.0.0.0
MAGPIE_LOG_LEVELinfo日志级别，支持 debug、info、warn、error
MAGPIE_CONFIG_DIR~/.magpieMagpie 全局配置文件与本地数据存储目录

临时修改端口启动示例：

bash
# 指定自定义端口 5000 启动网关
MAGPIE_PORT=5000 magpie start

核心功能三：Headless 无头守护进程（Linux / 远程服务器）

如果你在没有桌面图形界面的远程 Linux 服务器、云主机或 NAS 上进行开发，Magpie AI 可以作为标准后台守护进程或 systemd 服务运行：

1. 守护进程启停指令

bash
# 启动后台守护进程
magpie daemon start

# 查看守护进程运行状态与 PID
magpie daemon status

# 停止后台守护进程
magpie daemon stop

# 重启守护进程并重载配置
magpie daemon restart

2. 配置为 systemd 系统自启服务（Linux）

在 Linux 服务器上创建服务文件 /etc/systemd/system/magpie.service：

ini
[Unit]
Description=Magpie AI Model Router Gateway
After=network.target

[Service]
Type=simple
User=ubuntu
ExecStart=/usr/local/bin/magpie start --headless
Restart=always
RestartSec=5
Environment=MAGPIE_HOST=0.0.0.0
Environment=MAGPIE_PORT=3425

[Install]
WantedBy=multi-user.target

执行激活：

bash
sudo systemctl daemon-reload
sudo systemctl enable --now magpie

现在，远程开发机启动时就会自动加载 Magpie 网关，局域网内的所有开发终端均可共享该集中式模型路由。

3. Docker 容器化一键部署

官方提供了预构建的超轻量 Docker 镜像：

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

核心功能四：开机自启与系统菜单栏偏好

在桌面端（macOS / Windows），你可以通过系统偏好轻松设置常驻行为：

  1. 开机自启动（Launch at Login）： 在终端运行 magpie autostart enable 或在桌面控制台勾选「Launch at Login」，系统启动时会自动拉起菜单栏图标与本地网关，无需每次手动输入命令。
  2. 隐藏 Dock 图标（macOS 菜单栏纯净模式）： 在偏好设置中开启「Menu Bar Only」，Magpie 将完全隐去程序坞（Dock）图标，仅在顶部菜单栏以极小的常驻图标呈现，保持桌面清爽整洁。

常见问题解答

Q：修改了 MAGPIE_PORT 端口后，已经接管的 Agent 会自动更新吗？

A：当你通过 magpie claude ... 或 magpie use <profile> 重新应用配置时，Magpie 会自动读取当前的 MAGPIE_PORT 并将新端口注入到各 Agent 的配置文件中。

Q：多台电脑之间如何同步 Magpie 的配置？

A：Magpie 的所有供应商定义、路由组与脱敏规则均以纯文本 YAML 文件保存在 ~/.magpie/ 目录中。你可以将 ~/.magpie/config.yaml 纳入你的私有 Dotfiles Git 仓库进行多设备同步（请注意在共享前避免将含 API Key 的私有凭据提交到公开公共仓库）。

Q：在无桌面的 Linux 远程开发机上，如何保证 Magpie 长期高可用常驻？

A：推荐使用 Linux 原生 systemd 守护进程管理（配置 Restart=always 与 WantedBy=multi-user.target，如本指南第三节所示），或使用 Docker 容器配合 --restart unless-stopped 启动。这样即使云主机重启或进程异常退出，系统都会在秒级内自动拉起网关。