Skip to content

Every agent's model. One place. Codex on DeepSeek, Claude Code on Kimi, from the menu bar.

16.4 KB
Raw Blame
<!doctype html>
<html lang="zh-CN">
<head>
<meta charset="utf-8">
<meta name="viewport" content="width=device-width, initial-scale=1">
<title>远程 magpie · magpie 文档</title>
<meta name="description" content="在多台电脑上用同一个 magpie:在网络上共享它,在其他电脑上把它添加为远程 magpie(应用、TUI 或 CLI),以及能用到什么:模型、路由组、图像、System One、价格和额度。">
<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/remote">
<link rel="alternate" hreflang="zh" href="https://usemagpie.ai/docs/zh/remote">
<link rel="alternate" hreflang="ja" href="https://usemagpie.ai/docs/ja/remote">
<link rel="stylesheet" href="/docs.css">
<meta property="og:title" content="远程 magpie">
<meta property="og:description" content="一个 magpie 的供应商、账号和路由组,用在你的每台电脑上。">
<meta property="og:image" content="https://usemagpie.ai/img/og.png">
<meta property="og:url" content="https://usemagpie.ai/docs/zh/remote">
<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 class="toc-only" href="/docs/zh/remote">远程 magpie</a>
    <a class="toc-only" href="/docs/zh/docker">Docker</a>
    <a class="toc-only" href="/docs/zh/privacy">隐私</a>
    <a class="toc-only" href="/docs/zh/masking">本地脱敏</a>
    <a class="toc-only" href="/docs/zh/mcp-hub">MCP 聚合</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/remote" hreflang="en" lang="en">English</a>
      <a href="/docs/zh/remote" hreflang="zh" lang="zh">中文</a>
      <a href="/docs/ja/remote" 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>远程 magpie</p>
    <a href="#overview">概览</a>
    <a href="#share">1. 共享主 magpie</a>
    <a href="#add">2. 在其他电脑上添加</a>
    <a href="#models">能用到什么</a>
    <a href="#quotas">额度与用量</a>
    <a href="#trouble">出问题时</a>
  </aside>

  <article>
    <p class="eyebrow" id="overview">文档 · 共享</p>
    <h1>远程 magpie</h1>
    <p class="lede">一个 magpie 可以服务多台电脑。在保存供应商的那台电脑上(你的台式机、一台服务器、<a href="/docs/zh/docker">Docker 里的 NAS</a>)登录、配置一次供应商和路由组,然后在其他每台电脑上把这个 magpie 添加为一个供应商:<b>远程 magpie</b>(Remote magpie)。</p>

    <div class="table-wrap"><table>
      <tr><th></th><th>共享的 magpie</th><th>其他电脑上的 magpie</th></tr>
      <tr><td>供应商、订阅、密钥</td><td>保存并登录在这里</td><td>通过远程 magpie 使用</td></tr>
      <tr><td>路由组</td><td>在这里创建</td><td>以 <code>office/group/…</code> 选用</td></tr>
      <tr><td>Agent</td><td>它自己的</td><td>仍由本机的 magpie 配置</td></tr>
      <tr><td>用量与额度</td><td>在这里统计和读取</td><td>在这里显示,带上远程的名字</td></tr>
    </table></div>
    <p>你面前的电脑仍然运行 magpie:它配置本机的 Agent、为它们选模型、保存它们的会话。只有模型来自另一台。</p>

    <h2 id="share"><a class="anchor" href="#share">1. 共享主 magpie</a></h2>
    <ol class="steps">
      <li><b>打开共享</b>在保存供应商的电脑上:<span class="ui">设置</span> → <span class="ui">网络与共享</span> → <span class="ui">局域网共享</span> → <span class="ui">开启</span>。magpie 随即在局域网上监听,并生成一个名为 <span class="ui">Magpie</span> 的网关密钥。开关下方的 <span class="ui">地址</span> 一行显示其他电脑访问它的地址,例如 <code>http://192.168.1.20:3425</code>。</li>
      <li><b>给每台电脑一个密钥</b><span class="ui">网关</span> → <span class="ui">网关密钥</span>,或 <code>magpie gateway-key add "Laptop"</code>,它会打印 <code>sk-magpie-key-…</code>。每个密钥可以有自己的每日、每周或每月上限和可用模型,它的调用按它的名字统计。</li>
    </ol>
    <p>共享关闭时,桌面版 magpie 只在本机监听,其他电脑访问不到。Docker 里的 magpie 则通过发布的端口访问,不论是否共享,都会向容器外的每个调用方要网关密钥;见 <a href="/docs/zh/docker#share">Docker</a>。</p>

    <h2 id="add"><a class="anchor" href="#add">2. 在其他电脑上添加</a></h2>
    <p>需要第 1 步里的地址和一个密钥。以下任一方式都可以:</p>
    <ul>
      <li><b>应用:</b>在 <span class="ui">供应商</span> 页按 <span class="ui">+ 添加供应商</span>,在最后的 <span class="ui">另一台电脑上的 magpie</span> 下选 <span class="ui">Remote magpie</span>,填入地址和密钥。</li>
      <li><b>TUI</b>(<code>magpie tui</code>):在 Providers 页按 <code>a</code>,选 Remote magpie,输入地址和密钥。在它那一行,<code>w</code> 修改地址,<code>m</code> 重新获取列表。</li>
      <li><b>CLI:</b></li>
    </ul>
    <div class="code">
      <span class="lang">Shell</span>
      <button class="copy" data-copy="ex-add">复制</button>
      <pre id="ex-add">magpie provider add remote-magpie sk-magpie-key-… url=http://192.168.1.20:3425 id=office
magpie models            <span class="c"># office/… 是共享 magpie 的模型</span>
magpie provider refresh office   <span class="c"># 重新获取列表</span></pre>
    </div>
    <p><code>id=</code> 是这个供应商在本机的名字,也是它的模型 id 的开头(<code>office/…</code>)。地址可以写成 <code>192.168.1.20:3425</code>(默认 <code>http://</code>),后面带 <code>/v1</code>,或者写根地址:magpie 都会把各个 API 接到上面。每台共享出来的电脑添加一个远程 magpie,用不同的 id。</p>

    <h2 id="models"><a class="anchor" href="#models">能用到什么</a></h2>
    <ul>
      <li><b>它的模型</b>,和它自己的 Agent 看到的一样:<code>office/relay-a/claude-sonnet-5</code>,标签是 <code>Claude Sonnet 5 · Relay A · office</code>。id 不变,名字只出现在标签里。在本机像其他模型一样为 Agent 选用。</li>
      <li><b>它的路由组</b>,以 <code>office/group/…</code> 出现。路由在共享的 magpie 上用它的账号决定。</li>
      <li><b>所有 API。</b>请求按 Agent 使用的 API 原样转发(Anthropic Messages 和 token 计数、Responses、Chat Completions)。共享 magpie 的供应商只用另一种 API 提供的模型,只转换一次,不会在两台电脑上各转一次。Responses 走 HTTP(包括 SSE),不走 WebSocket。</li>
      <li><b>图像和视频。</b>它的图像和视频模型会被自动识别,经由它的图像生成、编辑和视频 API 提供。</li>
      <li><b>System One。</b>它的决策模型(Jev、Clef,以及你自己命名的模型)接到它的 <code>/v1/systemone</code>,作为决策模型而不是对话模型出现。刷新供应商列表可以发现新的。只写 <code>office</code> 时使用列表里的第一个决策模型。</li>
      <li><b>Embeddings、rerank、语音转文字和文字转语音</b>发往它对应的 API。它们在 Agent 列表里保持远程上的样子;出现在列表里并不代表能用来对话。</li>
      <li><b>价格。</b>每个模型在本机按共享 magpie 的计价(那边手动设的价格,否则是供应商的标价),两台电脑算出来一样。在本机设的价格优先。</li>
    </ul>

    <h2 id="quotas"><a class="anchor" href="#quotas">额度与用量</a></h2>
    <p>用量页、菜单栏和 <code>magpie quota</code> 会显示共享 magpie 的订阅卡片,带上它的名字(<code>Codex · office</code>,id <code>office/codex</code>),内容是那边最近一次读取的结果:只有保存登录的电脑去问厂商。在本机刷新卡片会让那边再读一次,最多每 30 秒一次。Codex 重置或 WorkBuddy 签到要在那台电脑上,用它自己的应用、TUI 或 CLI 来做。那边限了额度、模型或账号的密钥看不到它的任何卡片:本机只显示这把密钥自己的卡片和它的限额。</p>
    <p>共享的 magpie 把本机的请求记在本机所用网关密钥的名字下,并记下应答的账号。</p>

    <h2 id="trouble"><a class="anchor" href="#trouble">出问题时</a></h2>
    <div class="table-wrap"><table>
      <tr><th>看到的提示</th><th>怎么做</th></tr>
      <tr><td>“magpie isn’t shared on the local network” 或 “remote magpie isn’t shared”</td><td>在那台电脑上打开 <span class="ui">局域网共享</span></td></tr>
      <tr><td>“remote magpie didn’t take this key”(401)</td><td>用它的一个已启用的网关密钥:那边的 <span class="ui">网关</span> → <span class="ui">网关密钥</span></td></tr>
      <tr><td>某个模型 403</td><td>这个密钥可能只能用部分模型:在那台电脑上用 <code>magpie gateway-key models &lt;id&gt;</code> 查看或修改。只写 <code>office</code> 会请求 System One 的第一个决策模型,不管密钥允许什么;请用完整的 <code>office/provider/model</code> id</td></tr>
      <tr><td>“couldn’t reach the remote magpie”</td><td>检查地址、那边的 magpie 是否在运行并打开了共享、防火墙是否放行该端口</td></tr>
      <tr><td>没有 System One 模型,或 “doesn’t share its quotas”</td><td>更新那台电脑上的 magpie,再在本机刷新列表</td></tr>
    </table></div>
    <div class="callout"><b>不在家时</b>,通过 Tailscale 或 WireGuard 等 VPN、用它在 VPN 里的地址访问共享的 magpie。不要把它的端口开放到互联网。</div>

    <p style="margin-top:48px">遇到问题,或者有值得分享的配置?来 <a href="https://discord.gg/vGSnD3ZKQF">Discord</a> 聊。细节见<a href="https://github.com/yetone/magpie/blob/main/docs/reference.md">参考文档</a>(英文)。</p>
  </article>
</main>

<footer><div class="wrap">
  <span>© 2026 magpie · MIT</span>
  <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/remote">远程 magpie</a>
    <a href="/docs/zh/docker">Docker</a>
    <a href="/docs/zh/privacy">隐私</a>
    <a href="/docs/zh/masking">本地脱敏</a>
    <a href="/docs/zh/mcp-hub">MCP 聚合</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>