A developer of an AI app asked how to work with magpie and whether an app can register itself after one confirmation. The page says what exists: the gateway (find it via /api/hello and settings.json's port, the OpenAI, Anthropic, Responses and Gemini endpoints, /v1/models' fields), how a key magpie-<id> or the User-Agent's first word names the app in Usage, a row on the Agents page by an adapter PR in internal/agent (config-edit, Cindy-style own import link confirmed in the app, or a local API) with what the PR needs, what plugins can and can't do, and what isn't there: no link or API registers an app or installs a plugin, and magpie://import adds providers only. English and Chinese pages, linked from every docs page's nav and footer. TestThirdPartyAppIsCountedAsItself pins the attribution the page promises. go vet and the gateway tests pass; site node tests pass; pages checked in headless Chromium (no errors, TOC, no horizontal scroll at 390px).
302 lines
32 KiB
HTML
302 lines
32 KiB
HTML
<!doctype html>
|
||
<html lang="zh-CN">
|
||
<head>
|
||
<meta charset="utf-8">
|
||
<meta name="viewport" content="width=device-width, initial-scale=1">
|
||
<title>快速上手 · magpie 文档</title>
|
||
<meta name="description" content="magpie 的整体思路和配置方法:添加你已有的供应商,给每个 Agent 选模型,需要时再把多个账号组成路由组。">
|
||
<meta name="color-scheme" content="light dark">
|
||
<meta name="theme-color" content="#fafafa">
|
||
<script>
|
||
(() => {
|
||
let mode = "system";
|
||
try { mode = localStorage.getItem("theme") || "system"; } catch {}
|
||
const q = matchMedia("(prefers-color-scheme: dark)");
|
||
const apply = () => {
|
||
const t = mode === "system" ? (q.matches ? "dark" : "light") : mode;
|
||
document.documentElement.dataset.theme = t;
|
||
document.querySelector('meta[name="theme-color"]').content = t === "dark" ? "#0b0b0c" : "#fafafa";
|
||
document.querySelectorAll("button.theme").forEach((b) => { b.dataset.mode = mode; b.title = "Theme: " + mode; });
|
||
};
|
||
q.addEventListener("change", () => mode === "system" && apply());
|
||
window.setTheme = (m) => { mode = m; try { m === "system" ? localStorage.removeItem("theme") : localStorage.setItem("theme", m); } catch {} apply(); };
|
||
window.themeMode = () => mode;
|
||
apply();
|
||
})();
|
||
</script>
|
||
<script>try{if(/Linux/.test(navigator.userAgent)&&!/Android/.test(navigator.userAgent)||localStorage.getItem("omarchy")||/[?&]omarchy=/.test(location.search))document.write('<script src="/omarchy.js"><\/script>')}catch(e){}</script>
|
||
<link rel="icon" href="/favicon.png" type="image/png">
|
||
<link rel="apple-touch-icon" href="/img/icon-256.png">
|
||
<link rel="alternate" hreflang="en" href="https://usemagpie.ai/docs/start">
|
||
<link rel="alternate" hreflang="zh" href="https://usemagpie.ai/docs/zh/start">
|
||
<link rel="alternate" hreflang="ja" href="https://usemagpie.ai/docs/ja/start">
|
||
<link rel="stylesheet" href="/docs.css">
|
||
<meta property="og:title" content="magpie 快速上手">
|
||
<meta property="og:description" content="添加你已有的供应商,给每个 Agent 选模型。一步步配置。">
|
||
<meta property="og:image" content="https://usemagpie.ai/img/og.png">
|
||
<meta property="og:url" content="https://usemagpie.ai/docs/zh/start">
|
||
<meta name="twitter:card" content="summary_large_image">
|
||
</head>
|
||
<body>
|
||
|
||
<nav><div class="wrap">
|
||
<a class="brand" href="/zh/"><img class="bird" src="/img/magpie-small.svg" alt="">magpie <small>文档</small></a>
|
||
<div class="links">
|
||
<a href="/zh/">首页</a>
|
||
<a href="/docs/zh/start">快速上手</a>
|
||
<a href="/docs/zh/intent">意图路由</a>
|
||
<a href="/docs/zh/plugins">插件开发</a>
|
||
<a href="/docs/zh/import">Add to magpie</a>
|
||
<a href="/docs/zh/integrate">接入应用</a>
|
||
<a href="https://github.com/yetone/magpie-releases/releases">版本发布</a>
|
||
</div>
|
||
<div class="langs">
|
||
<button class="icon-btn lang" type="button" aria-label="语言" title="语言" aria-haspopup="true" aria-expanded="false" aria-controls="langs"><svg viewBox="0 0 16 16" fill="none" stroke="currentColor" stroke-width="1.4" aria-hidden="true"><circle cx="8" cy="8" r="6.25"/><path d="M1.75 8h12.5M8 1.75c1.7 1.75 2.55 3.83 2.55 6.25S9.7 12.5 8 14.25M8 1.75C6.3 3.5 5.45 5.58 5.45 8S6.3 12.5 8 14.25"/></svg></button>
|
||
<div class="lang-menu" id="langs" hidden>
|
||
<a href="/docs/start" hreflang="en" lang="en">English</a>
|
||
<a href="/docs/zh/start" hreflang="zh" lang="zh">中文</a>
|
||
<a href="/docs/ja/start" hreflang="ja" lang="ja">日本語</a>
|
||
</div>
|
||
</div>
|
||
<a class="icon-btn" href="https://discord.gg/vGSnD3ZKQF" aria-label="magpie on Discord" title="Join us on Discord"><svg viewBox="0 0 24 24" fill="currentColor" aria-hidden="true"><path d="M20.317 4.3698a19.7913 19.7913 0 00-4.8851-1.5152.0741.0741 0 00-.0785.0371c-.211.3753-.4447.8648-.6083 1.2495-1.8447-.2762-3.68-.2762-5.4868 0-.1636-.3933-.4058-.8742-.6177-1.2495a.077.077 0 00-.0785-.037 19.7363 19.7363 0 00-4.8852 1.515.0699.0699 0 00-.0321.0277C.5334 9.0458-.319 13.5799.0992 18.0578a.0824.0824 0 00.0312.0561c2.0528 1.5076 4.0413 2.4228 5.9929 3.0294a.0777.0777 0 00.0842-.0276c.4616-.6304.8731-1.2952 1.226-1.9942a.076.076 0 00-.0416-.1057c-.6528-.2476-1.2743-.5495-1.8722-.8923a.077.077 0 01-.0076-.1277c.1258-.0943.2517-.1923.3718-.2914a.0743.0743 0 01.0776-.0105c3.9278 1.7933 8.18 1.7933 12.0614 0a.0739.0739 0 01.0785.0095c.1202.099.246.1981.3728.2924a.077.077 0 01-.0066.1276 12.2986 12.2986 0 01-1.873.8914.0766.0766 0 00-.0407.1067c.3604.698.7719 1.3628 1.225 1.9932a.076.076 0 00.0842.0286c1.961-.6067 3.9495-1.5219 6.0023-3.0294a.077.077 0 00.0313-.0552c.5004-5.177-.8382-9.6739-3.5485-13.6604a.061.061 0 00-.0312-.0286zM8.02 15.3312c-1.1825 0-2.1569-1.0857-2.1569-2.419 0-1.3332.9555-2.4189 2.157-2.4189 1.2108 0 2.1757 1.0952 2.1568 2.419 0 1.3332-.9555 2.4189-2.1569 2.4189zm7.9748 0c-1.1825 0-2.1569-1.0857-2.1569-2.419 0-1.3332.9554-2.4189 2.1569-2.4189 1.2108 0 2.1757 1.0952 2.1568 2.419 0 1.3332-.946 2.4189-2.1568 2.4189Z"/></svg></a>
|
||
<a class="icon-btn" href="https://github.com/yetone/magpie" aria-label="magpie on GitHub" title="Source on GitHub"><svg viewBox="0 0 16 16" fill="currentColor" aria-hidden="true"><path d="M8 0C3.58 0 0 3.58 0 8c0 3.54 2.29 6.53 5.47 7.59.4.07.55-.17.55-.38 0-.19-.01-.82-.01-1.49-2.01.37-2.53-.49-2.69-.94-.09-.23-.48-.94-.82-1.13-.28-.15-.68-.52-.01-.53.63-.01 1.08.58 1.23.82.72 1.21 1.87.87 2.33.66.07-.52.28-.87.51-1.07-1.78-.2-3.64-.89-3.64-3.95 0-.87.31-1.59.82-2.15-.08-.2-.36-1.02.08-2.12 0 0 .67-.21 2.2.82.64-.18 1.32-.27 2-.27.68 0 1.36.09 2 .27 1.53-1.04 2.2-.82 2.2-.82.44 1.1.16 1.92.08 2.12.51.56.82 1.27.82 2.15 0 3.07-1.87 3.75-3.65 3.95.29.25.54.73.54 1.48 0 1.07-.01 1.93-.01 2.2 0 .21.15.46.55.38A8.013 8.013 0 0 0 16 8c0-4.42-3.58-8-8-8Z"/></svg></a>
|
||
<button class="icon-btn theme" type="button" aria-label="Theme" title="Theme: system"><svg class="i-system" viewBox="0 0 16 16" fill="none" stroke="currentColor" stroke-width="1.5"><rect x="1.75" y="2.75" width="12.5" height="8.5" rx="1.5"/><path d="M5.5 14h5M8 11.25V14"/></svg><svg class="i-light" viewBox="0 0 16 16" fill="none" stroke="currentColor" stroke-width="1.5" stroke-linecap="round"><circle cx="8" cy="8" r="3"/><path d="M8 1v1.5M8 13.5V15M1 8h1.5M13.5 8H15M3 3l1 1M12 12l1 1M3 13l1-1M12 4l1-1"/></svg><svg class="i-dark" viewBox="0 0 16 16" fill="none" stroke="currentColor" stroke-width="1.5" stroke-linejoin="round"><path d="M13.5 9.5A5.5 5.5 0 0 1 6.5 2.5a5.5 5.5 0 1 0 7 7Z"/></svg></button>
|
||
<a class="btn small" href="/#get">下载</a>
|
||
</div></nav>
|
||
|
||
<main class="wrap doc">
|
||
<aside class="toc">
|
||
<p>快速上手</p>
|
||
<a href="#overview">整体思路</a>
|
||
<a href="#providers">1 · 供应商</a>
|
||
<a href="#agents">2 · Agent</a>
|
||
<a href="#routing">3 · 路由组</a>
|
||
<a href="#usage">用量与方案</a>
|
||
<a href="#cli">命令行</a>
|
||
<a href="#faq">常见问题</a>
|
||
</aside>
|
||
|
||
<article>
|
||
<p class="eyebrow" id="overview">文档 · 指南</p>
|
||
<h1>快速上手</h1>
|
||
<p class="lede">magpie 是给你所有 Agent 统一选模型的地方。先把你有的供应商加进来,再给每个 Agent 选一个模型;magpie 会把它写进那个 Agent 自己的配置文件。</p>
|
||
|
||
<p>背后是一个跑在你本机 <code>127.0.0.1:3425</code> 的小网关。它同时支持 OpenAI、Anthropic 和 Gemini 三种 API,并在它们之间互相转换(流式输出、工具调用都支持),所以任何 Agent 都能用任何供应商的模型:Claude Code 用 ChatGPT 订阅里的 GPT 模型,Codex 用 DeepSeek,OpenCode 用你的 Claude 订阅。</p>
|
||
|
||
<div class="cards">
|
||
<div><h3>供应商</h3><p>模型从哪里来:登录的订阅、有 API 密钥的厂商、你自己的接口地址。每个模型都写作 <code>provider/model</code>。</p></div>
|
||
<div><h3>Agent</h3><p>使用模型的工具:Claude Code、Codex、Gemini CLI、OpenCode 等。每个一行,显示它当前用的模型。</p></div>
|
||
<div><h3>网关</h3><p>通过 magpie 选模型时,Agent 指向的本地地址。它把每个请求转给提供该模型的供应商。</p></div>
|
||
<div><h3>路由组</h3><p>可选。把多个模型或账号合成一个给 Agent 选,<code>group/<id></code>,一个额度用完时换下一个。</p></div>
|
||
</div>
|
||
|
||
<ol class="steps">
|
||
<li><b>添加供应商</b>登录你的订阅,粘贴 API 密钥。只需做一次。</li>
|
||
<li><b>给每个 Agent 选模型</b>点 Agent 的模型,选一个。magpie 改写那个 Agent 的配置。</li>
|
||
<li><b>开一个新会话</b>Agent 启动时读取配置,下一个会话就用上新模型。</li>
|
||
</ol>
|
||
|
||
<h2 id="providers"><a class="anchor" href="#providers">1 · 添加供应商</a></h2>
|
||
<p>打开 <span class="ui">供应商</span> 标签页,点 <span class="ui">+ 添加供应商</span>。点选一个卡片,或输入厂商名字查找。</p>
|
||
|
||
<figure class="figure">
|
||
<img class="for-light" src="/img/add-zh-light.png" width="2080" height="1250" loading="lazy" alt="添加供应商面板:订阅、厂商、中转、本机和自定义 URL">
|
||
<img class="for-dark" src="/img/add-zh-dark.png" width="2080" height="1250" loading="lazy" alt="添加供应商面板:订阅、厂商、中转、本机和自定义 URL">
|
||
<figcaption>添加供应商:登录订阅、选厂商,或填任意兼容的 URL。</figcaption>
|
||
</figure>
|
||
|
||
<h3>订阅 · 登录即可,无需密钥</h3>
|
||
<p>Claude(Pro、Max、Team)、ChatGPT(Plus、Pro、Business)、Cursor、Grok(SuperGrok)、Copilot 和 Devin。点卡片后 magpie 会在浏览器里打开厂商自己的登录页,登录完成后账号立刻出现(Copilot 会给你一个验证码,在 GitHub 页面上输入)。订阅是在 magpie 里添加的,不需要先去别的 Agent 里登录。</p>
|
||
<ul>
|
||
<li><b>多个账号。</b>再点一次 Claude 或 ChatGPT 卡片即可再加一个;它们都列在这个供应商下面,点一下就能切换使用哪个。</li>
|
||
<li><b>已经登录过?</b>本机上已经登录的 Agent 也会作为供应商出现,显示为 <em>已登录 …</em>。</li>
|
||
<li><b>所有 Agent 都能用。</b>订阅里的模型在其他 Agent 的选择列表里写作 <code>claude/…</code>、<code>codex/…</code>、<code>copilot/…</code>。Claude 订阅的请求通过本机安装的 Claude Code 运行,所以请保留 Claude Code。</li>
|
||
</ul>
|
||
|
||
<h3>供应商(厂商预设)</h3>
|
||
<p>Anthropic、OpenAI、Google Gemini、DeepSeek、Kimi、Zhipu GLM、MiniMax、Qwen、Mistral、Groq、xAI 等。选一个,粘贴密钥(<span class="ui">获取密钥 ↗</span> 会打开厂商的密钥页面),保存。magpie 会向厂商询问它提供哪些模型并列出来;展开供应商那一行可以选择给 Agent 暴露哪些模型,或点 <span class="ui">测试</span>。</p>
|
||
|
||
<h3>本机</h3>
|
||
<p>Ollama 和 LM Studio,无需密钥。</p>
|
||
|
||
<h3>自定义 · 任意兼容的 URL</h3>
|
||
<p>其他接口都走这里:填 <span class="ui">名称</span>、<span class="ui">OpenAI 兼容</span> 地址(以 <code>/v1</code> 结尾)、<span class="ui">Anthropic 兼容</span> 地址(根地址,即 <code>ANTHROPIC_BASE_URL</code> 的值),或两个都填,再填密钥。接口支持几种 API 就填几种;每个 Agent 用它原生的那种,其余由 magpie 转换。</p>
|
||
|
||
<div class="callout"><b>之前在 Claude Code 或 Codex 里配过供应商?</b>面板顶部的 <span class="ui">导入…</span> 会读取 Claude Code 的 <code>settings.json</code> 和 Codex 的 <code>config.toml</code>,不改动它们,把你勾选的供应商导入进来。</div>
|
||
<p>密钥保存在 <code>~/.config/magpie/providers.json</code>,只有你自己可读。magpie 从不读取 shell 环境变量里的密钥:你添加什么,它就用什么。</p>
|
||
|
||
<h2 id="agents"><a class="anchor" href="#agents">2 · 给每个 Agent 选模型</a></h2>
|
||
<p><span class="ui">Agent</span> 标签页里,本机装了或配置过的每个 Agent 各占一行。magpie 支持 Claude Code、Codex、Gemini CLI、OpenCode、MiMo Code、Pi、Goose、Cursor、Copilot CLI、Crush、DeepSeek Harness、Command Code、omp、OmO、Devin、Hermes Agent、MiniMax Code、Grok Build、ZCode、OpenHanako 和 Alma。</p>
|
||
|
||
<figure class="figure">
|
||
<img class="for-light" src="/img/agents-zh-light.png" width="2080" height="1058" loading="lazy" alt="Agent 页:每个 Agent 一行,显示当前模型,底部是保存的方案">
|
||
<img class="for-dark" src="/img/agents-zh-dark.png" width="2080" height="1058" loading="lazy" alt="Agent 页:每个 Agent 一行,显示当前模型,底部是保存的方案">
|
||
<figcaption>每个 Agent 一行,可以选任意供应商的模型;方案一键切换全部设置。</figcaption>
|
||
</figure>
|
||
<ul>
|
||
<li><b>点模型</b>打开选择列表。模型分组显示:Agent 自带的、你的路由组、再是你添加的每个供应商。输入可以筛选,也可以直接输入列表里没有的模型 ID。</li>
|
||
<li><b>推理强度</b>:Agent 有这个选项时(Codex 的 <em>推理强度</em>、Pi 的 <em>思考</em>),列表下方会出现滑块。</li>
|
||
<li><b>Claude Code 通过 magpie 使用模型时</b>,opus、sonnet、haiku 各档还可以单独指定模型;默认跟随主模型。</li>
|
||
</ul>
|
||
<p>选好的模型会写进 Agent 自己的配置文件。只改 magpie 需要的那几个键;注释、顺序、缩进都保留,写入是原子的。</p>
|
||
<div class="table-wrap"><table>
|
||
<tr><th>Agent</th><th>通过 magpie 选模型时写入什么</th></tr>
|
||
<tr><td>Claude Code</td><td><code>~/.claude/settings.json</code>:<code>env</code> 里的 <code>ANTHROPIC_BASE_URL</code>、<code>ANTHROPIC_AUTH_TOKEN</code> 和模型变量</td></tr>
|
||
<tr><td>Codex</td><td><code>~/.codex/config.toml</code>:一个 <code>[model_providers.magpie]</code> 表和模型,模型列表写在 <code>magpie-models.json</code>。你的 ChatGPT 登录不受影响</td></tr>
|
||
<tr><td>OpenCode、MiMo Code、Pi、Crush</td><td>一个 <code>magpie</code> 供应商条目,以及 <code>magpie/provider/model</code></td></tr>
|
||
<tr><td>AtomCode</td><td><code>~/.atomcode/config.toml</code>:一个 <code>magpie</code> 供应商账号,以及目录中每个模型各自的条目</td></tr>
|
||
<tr><td>Gemini CLI</td><td><code>GOOGLE_GEMINI_BASE_URL</code> 指向网关、API 密钥认证,以及模型</td></tr>
|
||
</table></div>
|
||
<p><b>已在运行的会话保持它启动时的模型。</b>Agent 启动时读取配置,所以改动从下一个会话生效。Codex 也在启动时生成模型列表:切换后请重启 Codex 应用和已打开的 <code>codex</code> 会话。</p>
|
||
<div class="callout"><b>Paseo、编辑器插件等</b>替你运行 Claude Code 或 Codex 的前端,启动的是同一个 CLI,读的也是同一份 <code>~/.claude</code> 或 <code>~/.codex</code> 配置。在 magpie 里设一次模型,它们从下一个会话起也会用上。</div>
|
||
|
||
<h2 id="routing"><a class="anchor" href="#routing">3 · 可选:路由组</a></h2>
|
||
<p>每个供应商只有一个账号时可以跳过这一步。等你有了多个——比如两个 ChatGPT 账号,或者同一个模型既有订阅又有密钥——再来设置。</p>
|
||
|
||
<figure class="figure">
|
||
<img class="for-light" src="/img/routing-zh-light.png" width="2080" height="1960" loading="lazy" alt="路由页:四个 Agent 同时经三个路由组发请求,被限流的供应商暂时让开">
|
||
<img class="for-dark" src="/img/routing-zh-dark.png" width="2080" height="1960" loading="lazy" alt="路由页:四个 Agent 同时经三个路由组发请求,被限流的供应商暂时让开">
|
||
<figcaption>路由组:多个模型或账号合成一个名字,按智能或顺序切换。</figcaption>
|
||
</figure>
|
||
|
||
<h3>一个供应商里的多个账号或密钥</h3>
|
||
<p>展开供应商那一行,勾选要用的每个账号或密钥。<span class="ui">路由</span> 决定请求怎么分给它们:<span class="ui">智能</span>(默认)、<span class="ui">按顺序</span>、<span class="ui">轮流</span>、<span class="ui">用量少的优先</span> 或 <span class="ui">重置前用完</span>。<span class="ui">备用</span> 里列出这个供应商额度用完、被限流或不可用时改用的模型。</p>
|
||
|
||
<h3>跨供应商的同一个模型</h3>
|
||
<p>路由组是几个模型(来自一个或多个供应商),Agent 把它当作一个来选:<code>group/<id></code>,在选择列表的 <em>路由组</em> 下面。两个供应商用同一个名字提供的模型会自动成组;在 <span class="ui">路由</span> 标签页点 <span class="ui">新建组</span> 可以把任意模型组到一起。排第一的模型决定这个组对外的能力。</p>
|
||
<div class="callout"><b>不用手动建的组。</b>再加一个供应商,只要它提供的模型和已有的同名(比如 Claude 订阅和 Copilot 都有 Claude Opus,DeepSeek 官方 API 和 OpenRouter 都有 DeepSeek),magpie 就会自动把它们组成一个路由组:<code>group/auto-<模型></code>,包含所有提供这个模型的供应商。名字按各家不同的写法匹配(<code>deepseek/deepseek-chat</code> 和 <code>deepseek-chat</code> 算同一个)。给 Agent 选这个组,请求就会分摊到这些供应商上;不想要的可以用 <code>magpie group rm</code> 隐藏。</div>
|
||
<div class="table-wrap"><table>
|
||
<tr><th>路由</th><th>谁排在前面</th></tr>
|
||
<tr><td>智能 <code>smart</code></td><td>默认。把成员的账号和 Key 放在一起排(组里的路由组算一个,见下文):还有余量的订阅里,额度最先重置的排第一。看周额度的重置时间;只有 5 小时额度、没有周额度的账号(如 Claude Enterprise)看它的 5 小时重置,所以排在所有更晚重置的周额度前面。失败后在休息的排最后。</td></tr>
|
||
<tr><td>按顺序 <code>order</code></td><td>先用第一个模型,它答不了再换下一个。</td></tr>
|
||
<tr><td>轮流 <code>rotate</code></td><td>会话的每一轮交给下一个成员的账号或 Key,均摊负载。</td></tr>
|
||
<tr><td>最少使用 <code>usage</code></td><td>剩余额度最多的账号或 Key 排第一。</td></tr>
|
||
<tr><td>重置前用完 <code>pace</code></td><td>每周剩余额度除以距重置的小时数,最高的账号排第一——重置时损失最多的那个——少让成员的周额度到重置时作废;只有 5 小时额度、没有周额度的账号(如 Claude Enterprise)按 5 小时窗口的剩余额度除以距它重置的小时数算,所以几乎总排第一。用到 90% 以上的等其他账号都答不了时才用。Key 按最近发给它的 token 数排。</td></tr>
|
||
</table></div>
|
||
<div class="table-wrap"><table>
|
||
<tr><th>会话保持</th><th>会话在回答过它的账号或 Key 上留多久</th></tr>
|
||
<tr><td>自动 <code>auto</code></td><td>默认。一轮之内总是保持,跨轮则在厂商缓存还值得保留时保持。</td></tr>
|
||
<tr><td>整个会话 <code>session</code></td><td>整个会话,只要它还能回答。</td></tr>
|
||
<tr><td>一轮之内 <code>turn</code></td><td>Agent 回传工具结果时不换;你再次发言时,路由重新决定。</td></tr>
|
||
<tr><td>关闭 <code>off</code></td><td>每个请求都重新路由。</td></tr>
|
||
</table></div>
|
||
<h3 id="rules">规则 · 把某类对话交给指定模型</h3>
|
||
<p>路由组的 <span class="ui">规则</span> 把符合条件的一轮对话交给组里指定的模型:够长(<code>tokens ≥ N</code>)、带图片、要求推理(开启,或不低于某个强度)、来自某些 Agent,用户想做的事符合你描述的<em>意图</em>,或者 Agent 正在压缩上下文。每次你发新消息时从上往下检查,第一条命中的规则把它的模型排在最前,其余成员排在后面做故障转移。没有命中任何规则的一轮照组本来的方式路由,并保持在原来的账号上。</p>
|
||
<ul>
|
||
<li>规则只在一轮开始时决定;Agent 回传工具结果的过程中一直留在那个模型上,不会半途换掉而丢掉厂商的缓存。唯一例外:这一轮涨到超过所在模型的上下文,会换到装得下的成员。</li>
|
||
<li>token 数取请求大小的估算与厂商对这个会话上一个请求的计数中较大的一个。请留出余量:给 200k 的模型设 150k,而不是 199k。</li>
|
||
<li>子 Agent 是单独的会话,规则可以把它发到别处,主 Agent 仍留在原处。</li>
|
||
<li>意图是用几个词描述用户想做什么,例如“写或修测试”“一个简单问题”。每一轮开始时,magpie 会问一次组里指定的意图判断模型:用户这条消息属于哪个可能命中的意图。这个模型可以是 magpie 里的任意模型,建议选小而快、不带推理的。发过去的只有这条消息,不包括整段对话。它出错、超时(8 秒)或给不出答案时,意图条件都不命中,这一轮按其他规则走。如果前面有不带意图的规则已经能决定,就不会去问;同一条消息也不会问两次。它的调用在用量里显示为 magpie 自己的调用。它具体被问了什么、回答怎么用、失败时怎么办,详见<a href="/docs/zh/intent">意图路由</a>。</li>
|
||
<li><span class="ui">压缩上下文时</span>:Agent 压缩对话上下文时命中——Claude Code 的 <code>/compact</code> 和自动压缩、Codex、OpenCode、Pi、Gemini CLI、Qwen Code、Kimi Code——让更便宜、更快的模型来写总结,对话本身仍留在原来的模型上。压缩请求单独决定:它所在的这一轮和缓存都留在原处。对话比规则里的模型能装下的还长时,改由下一条命中的规则或组本来的顺序决定。</li>
|
||
<li>路由标签页会显示每一轮是被哪条规则送到哪里的,以及意图判断模型给出的答案。</li>
|
||
</ul>
|
||
<h3 id="nested">路由组里放路由组</h3>
|
||
<p>路由组的成员也可以是另一个路由组:在 <span class="ui">添加模型</span> 的 <em>路由组</em> 分类里选它,或者在终端里用 <code>models+=group/<id></code>。子组占据它在顺序里的位置,在自己的模型之间按自己的路由方式和规则分配。比如 Coder 可以是 <code>deepseek-v4-pro</code>,然后是 <em>Fast</em>,而 Fast 是几个便宜模型的顺序。Coder 的规则可以把一轮对话交给 <code>group/fast</code>,再由 Fast 自己的规则决定它里面哪个模型排第一。</p>
|
||
<ul>
|
||
<li><b>不会无限递归。</b>一个组不能包含它自己,无论是直接包含,还是经由它里面的组间接包含。Coder 已经包含 Fast 时,再把 Coder 放进 Fast 会被拒绝,选择器里也不会列出这样的组。最多嵌套 8 层。一个组被别的组包含时不能删除,要先从那个组里移除它。</li>
|
||
<li><b>每一层按自己的路由。</b>外层组不管用什么路由,都不会伸进它里面的组:智能、轮流、最少使用、重置前用完都把子组当作一个成员,拿子组自己会先用的那个账号或 Key 来比;排到它时,子组按自己的顺序整体尝试。Coder 设为智能、里面放 Claude(按顺序)和 GPT(按顺序)两个组时,比较的是 Claude 组的第一个和 GPT 组的第一个,不会把两组的账号混在一起排。</li>
|
||
<li><b>故障转移照常。</b>子组里的模型全部失败时,由外层组的下一个成员接手,和其他成员一样。</li>
|
||
<li>同一个模型出现两次(单独一次,子组里一次)时只问一次,按它第一次出现的位置。</li>
|
||
</ul>
|
||
<figure class="figure">
|
||
<img class="for-light" src="/img/nested-routing-zh-light.png" width="2080" height="1294" loading="lazy" alt="路由标签页里的嵌套路由组:Coder 包含 deepseek-v4-pro 和路由组 Fast,Fast 的 deepseek-v4-flash 与 kimi-k2.5 列在它下面;Kimi 回答了请求">
|
||
<img class="for-dark" src="/img/nested-routing-zh-dark.png" width="2080" height="1294" loading="lazy" alt="路由标签页里的嵌套路由组:Coder 包含 deepseek-v4-pro 和路由组 Fast,Fast 的 deepseek-v4-flash 与 kimi-k2.5 列在它下面;Kimi 回答了请求">
|
||
<figcaption>Coder 的规则把一个简单问题交给路由组 Fast,Fast 自己的规则又把 Kimi 排在组内第一。路由记录会写明每一层的规则和意图判断模型分别做了什么决定。</figcaption>
|
||
</figure>
|
||
<p><span class="ui">路由</span> 标签页实时显示网关的决定:每个请求由谁回答、为什么。在终端里也能管理路由组:</p>
|
||
<div class="code">
|
||
<span class="lang">终端</span>
|
||
<button class="copy" data-copy="ex-group">复制</button>
|
||
<pre id="ex-group">magpie groups <span class="c"># 先列你建的,再列 magpie 自动发现的</span>
|
||
magpie group add <span class="s">"Opus anywhere"</span> models=claude/claude-opus-5-5,copilot/claude-opus-5.5 routing=order stays=session
|
||
magpie group set opus-anywhere models+=openrouter/anthropic/claude-opus-5.5
|
||
magpie group rule add opus-anywhere use=openrouter/anthropic/claude-opus-5.5 tokens=150k <span class="c"># 长对话优先发给它</span>
|
||
magpie group rule add opus-anywhere use=copilot/claude-opus-5.5 intent=<span class="s">"一个简单问题"</span> classifier=groq/llama-3.1-8b-instant
|
||
magpie group rule add opus-anywhere use=deepseek/deepseek-v4-flash compact <span class="c"># /compact 的总结交给便宜的模型</span>
|
||
magpie group set coder models+=group/opus-anywhere <span class="c"># 路由组里放路由组</span>
|
||
magpie group rule opus-anywhere <span class="c"># 查看规则;rule rm|mv <n>,rule classifier <组> <模型> 换判断模型</span>
|
||
magpie group rm opus-anywhere <span class="c"># 自动发现的组会被隐藏;magpie group restore <id> 恢复</span>
|
||
magpie claude group/opus-anywhere <span class="c"># 使用它</span></pre>
|
||
</div>
|
||
|
||
<h2 id="usage"><a class="anchor" href="#usage">用量与方案</a></h2>
|
||
<p><b>用量。</b><span class="ui">用量</span> 标签页按 Agent 和模型统计每次经过网关的调用的 token、缓存命中和费用,可选 <span class="ui">今天</span>、<span class="ui">7 天</span>、<span class="ui">30 天</span> 或 <span class="ui">全部</span>;最上面是各订阅已用的额度和重置时间。Agent 直接发给自己厂商的请求不经过 magpie,不会计入。</p>
|
||
|
||
<figure class="figure">
|
||
<img class="for-light" src="/img/usage-zh-light.png" width="2080" height="842" loading="lazy" alt="用量页:剩余余额、token 与费用汇总,以及 30 天趋势图">
|
||
<img class="for-dark" src="/img/usage-zh-dark.png" width="2080" height="842" loading="lazy" alt="用量页:剩余余额、token 与费用汇总,以及 30 天趋势图">
|
||
<figcaption>经过网关的每次调用的余额、token、缓存命中和费用。</figcaption>
|
||
</figure>
|
||
<p><b>方案。</b>在 <span class="ui">Agent</span> 标签页底部点 <span class="ui">+ 保存当前</span>,把所有 Agent 的设置存成一个方案;之后点这个方案就能一键全部切回。</p>
|
||
|
||
<h2 id="cli"><a class="anchor" href="#cli">命令行</a></h2>
|
||
<p><code>magpie tui</code> 是终端里的完整界面,上面每一步也都有对应命令。<code>magpie help</code> 列出全部命令。</p>
|
||
<div class="table-wrap"><table>
|
||
<tr><th>命令</th><th>作用</th></tr>
|
||
<tr><td><code>magpie ls</code></td><td>列出找到的每个 Agent 及其设置</td></tr>
|
||
<tr><td><code>magpie presets</code></td><td>magpie 内置的厂商预设</td></tr>
|
||
<tr><td><code>magpie provider add deepseek sk-…</code></td><td>用密钥添加一个预设</td></tr>
|
||
<tr><td><code>magpie accounts add codex</code></td><td>再登录一个 Claude 或 ChatGPT 订阅</td></tr>
|
||
<tr><td><code>magpie providers</code></td><td>你的供应商:地址、密钥、模型、谁在用</td></tr>
|
||
<tr><td><code>magpie models</code></td><td>Agent 能选的所有模型,写作 <code>provider/model</code></td></tr>
|
||
<tr><td><code>magpie claude codex/gpt-5.5</code></td><td>设置 Agent 的模型</td></tr>
|
||
<tr><td><code>magpie codex effort high</code></td><td>设置其他字段</td></tr>
|
||
<tr><td><code>magpie codex default</code></td><td>恢复 Agent 自己的默认值,移除 magpie 的接入</td></tr>
|
||
<tr><td><code>magpie save work</code> · <code>use work</code></td><td>保存、应用方案</td></tr>
|
||
<tr><td><code>magpie usage 7d</code></td><td>按 Agent 和模型统计 token 与费用</td></tr>
|
||
<tr><td><code>magpie tray</code></td><td>只启动菜单栏图标</td></tr>
|
||
</table></div>
|
||
|
||
<h2 id="faq"><a class="anchor" href="#faq">常见问题</a></h2>
|
||
<h3>需要自己 export <code>OPENAI_BASE_URL</code> 或 <code>ANTHROPIC_BASE_URL</code> 吗?</h3>
|
||
<p>不需要。对 magpie 列出的 Agent,它会把网关地址和令牌直接写进 Agent 自己的配置文件。这些环境变量只用于 magpie 不管理的、带 base URL 设置的其他工具:<span class="ui">网关</span> 标签页的 <span class="ui">接入</span> 部分有一键复制和示例代码。</p>
|
||
<h3>magpie 必须一直开着吗?</h3>
|
||
<p>通过 magpie 使用的模型需要:网关随应用一起运行。关掉窗口后它仍留在菜单栏或托盘里;<code>magpie tray</code> 只启动图标(可以放进登录项),<code>magpie serve</code> 只运行网关。Agent 用它自己的模型和自己的登录时,不经过 magpie。</p>
|
||
<h3>怎么把 Agent 恢复原样?</h3>
|
||
<p>在选择列表里选 Agent 自带的模型,或运行 <code>magpie <agent> default</code>。magpie 会删掉它写入的内容,并恢复被它替换掉的值,比如你原来的 <code>ANTHROPIC_BASE_URL</code>。</p>
|
||
<h3>换了模型,Agent 还在用旧的?</h3>
|
||
<p>已在运行的会话保持启动时的模型。开一个新会话;如果是 Codex,也请重启 Codex 应用。</p>
|
||
<h3>手动改 Agent 的配置会冲突吗?</h3>
|
||
<p>不会。magpie 每次都重新读取文件,只动它设置的那几个键,你的其他设置和注释都会保留。用 <span class="ui">导入…</span> 带进来的供应商是一份拷贝:之后在 Agent 里的改动不会再同步过来。</p>
|
||
<h3>没有梯子,安装或更新连不上 GitHub 怎么办?</h3>
|
||
<p>给安装脚本和 <code>magpie update</code> 加代理:<code>curl -fsSL https://usemagpie.ai/install.sh | sh -s -- --proxy http://127.0.0.1:7890</code>,或 <code>magpie update --proxy socks5://127.0.0.1:1080</code>(支持 http、https、socks5、socks5h;环境变量 <code>HTTPS_PROXY</code>、<code>ALL_PROXY</code> 同样生效)。<code>--mirror <前缀></code> 从你指定的 GitHub 下载镜像取发布文件,即 <code><前缀>https://github.com/…</code>;<code>magpie update mirror <前缀></code> 让之后每次更新(包括应用自己的更新)都用它,<code>magpie update mirror off</code> 取消。不指定就不用任何镜像;文件的 SHA-256 始终来自 usemagpie.ai,而不是镜像,镜像改过的文件会被拒绝安装。应用自己的更新走 <span class="ui">设置</span> → <span class="ui">代理</span>。</p>
|
||
|
||
<p style="margin-top:48px">遇到问题,或者有值得分享的配置?来 <a href="https://discord.gg/vGSnD3ZKQF">Discord</a> 聊。想给自己的用户一键添加供应商的厂商,请看 <a href="/docs/zh/import">Add to magpie</a>。</p>
|
||
</article>
|
||
</main>
|
||
|
||
<footer><div class="wrap">
|
||
<span>© 2026 magpie · MIT</span>
|
||
<div class="links">
|
||
<a href="/zh/">首页</a>
|
||
<a href="/docs/zh/intent">意图路由</a>
|
||
<a href="/docs/zh/plugins">插件开发</a>
|
||
<a href="/docs/zh/import">Add to magpie</a>
|
||
<a href="/docs/zh/integrate">接入应用</a>
|
||
<a href="https://github.com/yetone/magpie">GitHub</a>
|
||
<a href="https://discord.gg/vGSnD3ZKQF">Discord</a>
|
||
<a href="https://github.com/yetone/magpie-releases/releases">版本发布</a>
|
||
</div>
|
||
</div></footer>
|
||
|
||
<script>
|
||
(() => {
|
||
const next = { system: "light", light: "dark", dark: "system" };
|
||
document.querySelectorAll("button.theme").forEach((b) => {
|
||
b.dataset.mode = themeMode();
|
||
b.title = "Theme: " + themeMode();
|
||
b.addEventListener("click", () => setTheme(next[themeMode()]));
|
||
});
|
||
|
||
document.querySelectorAll(".copy").forEach((b) => b.addEventListener("click", async () => {
|
||
try {
|
||
await navigator.clipboard.writeText(document.getElementById(b.dataset.copy).textContent);
|
||
b.textContent = "已复制"; setTimeout(() => (b.textContent = "复制"), 1400);
|
||
} catch {}
|
||
}));
|
||
})();
|
||
</script>
|
||
<script src="/docs.js"></script>
|
||
</body>
|
||
</html>
|