让WorkBuddy用上OpenCode免费模型：Magpie小白教程

大家好，我是邵奈一，一个爱动手的实战派技术博主。

文章对你有帮助是我的荣幸，欢迎评论区交流。

---

0x00 概述：这篇只解决一件事

上篇《装了5个AI编程工具的人，该认识Magpie了》讲的是它是什么、边界在哪。这篇解决后面那个问题：装完之后，怎么把它真正跑起来，并且确认它真的生效了。 除了把安装、接本地模型、协议翻译验证这条主线跑通，本文还把一个进阶玩法完整跑通------经 Magpie 网关，把本地 Ollama 和 OpenCode 的免费模型 一起喂给 WorkBuddy 这类压根不认这些配置的 Agent：OpenCode CLI 实装（2.0.32），magpie provider add opencode-zen 一行接入、不要任何 key，24 个免费模型进网关，请求经网关实测已路由到 OpenCode Zen（本机在干净宽带 IP 下实测已拿到 HTTP 200；唯一卡点是 OpenCode 免费层按出口 IP 风控，共享 IP / VPN / 代理下会返回 403，详见 0x06 开头的大实话）。

上篇已经讲清的概念------协议翻译到底翻什么、登录态怎么变成 provider、迭代快带来的边界------本文不再复述，只动手把它们跑一遍验证；概念有疑问回上篇。

结论先行------Magpie 日常要用的命令只有五条，学会这五条就算上手：

magpie ls                    # 本机有哪些 Agent、当前什么模型、配置文件在哪
magpie provider add ollama   # 接一个模型来源（本地的，不要 key）
magpie <agent> <model>       # 给某个 Agent 换模型
magpie quota                 # 每个账号还剩多少额度
magpie save work             # 存一份快照，改坏了一键回滚

本文所有代码块里的输出，除非特别标注，都是本机终端里的真实原文。先把环境交代清楚，方便你对照自己的机器：

一句话说明本文的做法：先用不要钱、不要密钥的本地 Ollama 把链路跑通，验证协议翻译真的生效，再决定要不要把付费账号交出去。 这条顺序对第一次上手的人来说最安全。

0x01 先看清楚：它到底要动你的哪些文件

很多人不敢装这类工具，卡在同一个问题上：它会把我现有的配置改成什么样？Magpie 对这个问题给了一条很干脆的命令：

magpie ls

本机实跑输出（17 个 Agent，全部列出）：

这张表有两个信息值得细看。

第一，17 个 Agent，17 份配置，4 种格式：JSON（Claude Code、VS Code）、TOML（Codex、Kimi Code）、JSONC（MiMo Code）、YAML（MiniMax Code、DeepSeek Harness）。上篇讲的"五个配置文件"，在我自己这台机器上量出来是 17 份，比我预想的还要碎。

第二，没装的会明写 CLI not found，本机没装的 OpenCode 与 CodeBuddy Code 就是这么标的。它只显示这台机器上真正装了的，不会铺一堆用不上的东西出来。

第一次一定要做的一件事

在看别的之前，先存一份快照：

magpie save backup-before-magpie

它是原子改写，只动变化的那个键，注释、缩进与顺序都会保留；而且每次改写前都重新读一遍文件，所以你自己手改的部分不会跟它冲突。即便如此，第一次用还是先存快照 ，改乱了 magpie use backup-before-magpie 就回来了。

0x02 安装：一条命令，落地两个文件

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

本机实跑输出：

  downloading magpie 0.1.1297 (magpie-darwin-arm64.zip)
  installed /Applications/magpie.app
  installed /Users/shaonaiyi/.local/bin/magpie
  open it: open -a magpie

我把这个安装脚本完整读了一遍，它在 Mac 上只做三件事：

1. 从官网拉最新版本号、下载地址与 SHA-256（哈希永远来自官网，不走镜像）
2. 下载对应平台的 zip，本地校验哈希，不一致就拒绝安装
3. 解压到 /Applications/magpie.app，再软链一个命令行入口到 ~/.local/bin/magpie

这里有个关键点要说清楚：安装不等于接管。 它这次落地的是两个文件（一个 app、一个软链），没有碰上面那张表里的任何一份 Agent 配置 。真正改写配置的是后面那条 magpie <agent> <model>，你不执行，它就一直在旁边待着。

四种打开方式怎么选

四种入口（桌面 magpie / 只留菜单栏 magpie tray / 纯网关 magpie serve / 远程常驻 magpie daemon install）的区别，上篇 0x02 已经讲全，这里不重复。只补常驻最容易踩的两个坑：

想让它开机自启

magpie daemon install        # 写入服务并启动；改了 PATH 或代理后重跑一次
magpie daemon status         # 是否在运行、pid、服务文件路径、日志路径、网关是否响应
magpie daemon restart        # 更新 magpie 之后重启
magpie daemon uninstall      # 停止并删除服务文件

以上命令据官方文档 docs/reference.md 的 "As a background service" 一节，本机未执行。需要提前知道的两点：

• macOS 上它写的是 launch agent ：~/Library/LaunchAgents/com.yetone.magpie.serve.plist，日志在 ~/Library/Logs/magpie/serve.log
• 它默认只跑网关 ，不顺便开网页管理页。想要网页界面的加 --web（或装完再 magpie daemon web on），那个页面在 127.0.0.1:3430

另外一个容易踩的坑：magpie autostart（登录时打开 app）和 magpie daemon install（系统服务）只能开一个，两者会抢同一个端口，官方限制同时只能用一个。

0x03 第一次接模型：从不要 key 的那一个开始

接 API key 是最常规的做法，但第一次上手我不建议这么干------先验证链路，再谈钱。本机跑着 Ollama，正好：

magpie provider add ollama

实跑输出：

✓ added Ollama (ollama)
✓ 8 models from localhost:11434
  8 models in the catalog · magpie models

一条命令干完三件事：认出本机 11434 端口上的 Ollama、拉回 8 个模型、登记成 provider。本机这 8 个模型是：

ollama/qwen3-vl:4b-nothink                     ollama/qwen3-vl:4b
ollama/ornith-1.5-crack:q4km                   ollama/ornith-1.5:35b
ollama/kaelri/qwen3.5-mt:2b                    ollama/lauchacarro/qwen2.5-translator:latest
ollama/shao_DeepSeek_huanhuan:latest           ollama/deepseek-r1:1.5b

之后看当前有哪些 provider：

magpie providers

实跑输出（账号信息已打码）：

  Ollama  ollama  localhost:11434  ● no key needed                     8 of 8 models · fetched just now
  Codex   codex   chatgpt.com      ● signed in as s****@gmail.com      7 models
  ZCode   zcode   api.z.ai         ● signed in as 136****3454          4 models

这里出现了本次实测中我最意外的一幕：我一条 key 都没给，它把本机已经登录的 Codex（ChatGPT）和 ZCode 账号扫了出来，直接变成了 provider。 它读的是本机 Agent 的登录文件与系统钥匙串，这就是上篇说的"登录态变成 provider"。买了 Claude Max 的人，OpenCode 也能跟着用，原理就在这里。

（不想让它读登录态、改用 key 接入，三种关法------设置里关 / magpie accounts discovery off / MAGPIE_NO_ACCOUNTS=1------上篇 0x03 已列全，这里不再重复。）

顺带提一句我实测时注意到的小细节：magpie serve 的日志里出现了一行 moved zcode to its plugin，意思是本机这个 ZCode 账号被它改由社区插件驱动。它会自动替你做一些决定，这件事本身值得知道。

0x04 起网关，然后亲自问它一句

网关单独跑起来：

magpie serve

实跑输出：

● magpie gateway on http://127.0.0.1:3425
  OpenAI   http://127.0.0.1:3425/v1/chat/completions · http://127.0.0.1:3425/v1/responses
  Anthropic http://127.0.0.1:3425/v1/messages
  key      magpie (anything works; the gateway only listens on localhost)
  19 models · magpie models

三段信息读一下：网关只监听 127.0.0.1，局域网里别的机器连不上；key 那一行的意思是 key 随便填什么都能过（实测用的就是 magpie），因为它只认本机流量；两个协议端点连同各自的地址，在启动时直接打印出来了。

先问它一句有多少模型：

curl -s http://127.0.0.1:3425/v1/models -H "Authorization: Bearer magpie"

实测返回 18 条 provider/model 形式的 id。同一时刻 magpie models 列的是 19 条------差的这一条，正是上文日志里被移到社区插件的那个 ZCode。

实测一：用 OpenAI 协议问本地模型

curl -s http://127.0.0.1:3425/v1/chat/completions \
  -H "Content-Type: application/json" -H "Authorization: Bearer magpie" \
  -d '{"model":"ollama/kaelri/qwen3.5-mt:2b","messages":[{"role":"user","content":"用一句话说明你是谁"}],"max_tokens":60}'

实跑结果：HTTP 200，耗时 7.45 秒。返回的 JSON 节选：

{
  "id": "chatcmpl-793",
  "object": "chat.completion",
  "model": "kaelri/qwen3.5-mt:2b",
  "system_fingerprint": "fp_ollama",
  "choices": [{
    "message": { "role": "assistant", "content": "", "reasoning": "Thinking Process: ..." },
    "finish_reason": "length"
  }],
  "usage": { "prompt_tokens": 109, "completion_tokens": 60, "total_tokens": 169 }
}

7.45 秒里绝大部分是 Ollama 冷启动加载 1.9 GB 模型的时间，模型热起来之后会快得多。返回结构里值得看的是 message.reasoning 这个字段：本地模型本来就吐了思考过程，Magpie 按 OpenAI 的字段格式原样带了回来。

实测二：换 Anthropic 协议，问本地模型

这是全篇最该看的一次验证。这次把请求换成 Anthropic Messages 格式 ，模型用本机另一个本地模型 ollama/qwen3-vl:4b-nothink（两次用的不是同一个模型，但都是本机 Ollama 里的开源模型------这次要看的是协议，不是模型本身）：

curl -s http://127.0.0.1:3425/v1/messages \
  -H "Content-Type: application/json" -H "x-api-key: magpie" -H "anthropic-version: 2023-06-01" \
  -d '{"model":"ollama/qwen3-vl:4b-nothink","max_tokens":80,"messages":[{"role":"user","content":"用一句话介绍你自己"}]}'

实跑结果：HTTP 200，耗时 38.52 秒（本机首次加载该 4B 多模态模型的冷启动时间，模型热起来之后同样会快很多）。返回 JSON：

{
  "id": "msg_c802bd0048559bb488aa07cb",
  "type": "message",
  "role": "assistant",
  "model": "qwen3-vl:4b-nothink",
  "content": [{ "type": "thinking", "thinking": "<think>\n嗯，用户让我用一句话介绍自己。..." }],
  "stop_reason": "max_tokens",
  "usage": { "input_tokens": 12, "output_tokens": 80 }
}

把两侧摆在一起看：

一个只会 OpenAI 方言的本地模型，用 Anthropic 协议去问，拿回来的是标准的 Anthropic Messages 结构。上篇讲的那个"协议翻译"地基，在真实机器上跑出来就是这段输出。注意 max_tokens: 80 被思考消耗光了，所以 content 里只有 thinking 块、stop_reason 是 max_tokens------不是报错，是 max_tokens 给小了。

不想让它改配置，也能用

任何能填 base URL 的工具，三条环境变量（OPENAI_BASE_URL / ANTHROPIC_BASE_URL / GOOGLE_GEMINI_BASE_URL，key 都填 magpie）上篇 0x02 已给全，这里只补一句结论：这条路完全不碰任何 Agent 配置文件，适合先试水，代价是享受不到按 Agent 精细化管理模型的能力。

0x05 给 Agent 换模型，然后验收

链路验证完，就该用在 Agent 上了。三条命令闭环：

magpie claude deepseek/deepseek-chat    # 改：把 Claude Code 换到 DeepSeek
# 关键：把当前会话关掉，开一个新的
magpie claude                           # 验：看它现在是什么模型

以上为 magpie --help 列出的标准写法（本机未对具体 Agent 执行：那是正在使用的配置，改之前要先存快照）。它只改必要的那一个键，注释、顺序、缩进全部保留。

最容易以为"它坏了"的三件事

换了模型没生效（要开新会话）、Codex 切换后还得重启应用（它启动时生成模型列表）、Codex 最多读 1 MiB 模型目录约 125 个后被截断（被舍弃的数量写在响应头 X-Magpie-Left-Out 里）------这三类"以为坏了"的坑，上篇 0x04 列了完整原因和解决办法，这里不重复。

验收：花了多少、还剩多少

magpie quota                    # 每个 key、plan、account 的余额与额度窗口
magpie usage                    # 按 30 天统计每个 Agent / 模型 / 账号的 token 与费用
magpie usage --csv              # 每一条请求导出成 CSV，方便自己对账

这三条本机没有执行：本机只接了本地模型，不产生任何费用，跑出来必然是全空的。要看真实账目，得等接了付费 provider 之后。命令本身来自 magpie --help 的实跑清单。

想收手的时候

magpie claude default           # 单个 Agent 还原到接管前的值
magpie use backup-before-magpie # 整组还原到第一步存的快照

0x06 进阶：让 WorkBuddy 也用上 Magpie 网关里的模型

前面接的都是 API key 或本地 Ollama。其实 OpenCode 自己就有一批免费模型 ------它托管的 Zen 服务里，智谱、DeepSeek、MiMo、Nemotron 等一票免费层都不要钱；Magpie 还内置了一个 opencode-zen provider 预设，把这些免费模型一键收进网关、不需要任何 key。整条链路一张图看懂：

本机当前实拍 ：magpie providers 里 OpenCode Zen 那一行是 ● ••••••（已开启、无需 key），24 of 85 models 进了网关------完整输出见第四步验收处的真实终端输出。

这里真正要动的只有 WorkBuddy 那一段 JSON。本文 0x03、0x04 已经实跑通了本地 Ollama 接入和两种协议问答，这一节把"WorkBuddy 走 Magpie 网关用上 OpenCode 免费模型"完整跑通------magpie provider add opencode-zen 一行接入，24 个免费模型进网关，改动只有一段 JSON，请求经网关实测已经路由到 OpenCode Zen。

一句大实话（重要）： OpenCode 的免费层按 IP 风控 ------如果当前网络出口被标记为"滥用流量"（共享 IP / VPN / 代理最常见），OpenCode 会直接拦掉免费调用，返回 OpenCode's free models aren't available from your current network。这不是配置问题：把 VPN/代理关掉、用本机真实宽带 IP 即可；想彻底不踩这坑就上付费的 OpenCode Go。下面的命令链路本身全对，唯一的卡点只在免费层的 IP 策略。

第一步：把网关跑起来

就是 0x04 那条命令，网关挂着就行：

magpie serve
# ● magpie gateway on http://127.0.0.1:3425

第二步：把 OpenCode 免费模型接进 Magpie

OpenCode 托管的免费模型，Magpie 用内置预设一行接入------不要 key、不要登录：

magpie provider add opencode-zen
# ✓ added OpenCode Zen (opencode-zen)
# ✓ 85 models from opencode.ai
#   24 models in the catalog · magpie models

实跑后 magpie models 里多出一批 opencode-zen/... 开头的模型，挑几个能免费用的：

opencode-zen/glm-5.3-flash-free          GLM-5.3-Flash Free     （智谱系，国内可达）
opencode-zen/mimo-v2.6-flash-free        MiMo-V2.6-Flash Free
opencode-zen/deepseek-v4.1-flash-free    DeepSeek V4.1 Flash Free
opencode-zen/nemotron-3.5-lightning-free Nemotron 3.5 Lightning Free

（注意：opencode-zen/beam-free 官方明确排除中国区，别选它。）

上方代码块是从 magpie models | grep opencode-zen 的真实结果里挑的几个能免费用的，智谱、DeepSeek、MiMo、Nemotron、MiniMax 的 flash-free 都在，国内基本可达；完整输出见第四步验收处的真实终端输出。

第三步：给 WorkBuddy 的模型清单追加一段 JSON

WorkBuddy 的模型配置在 ~/.workbuddy/models.json，一个 JSON 数组。追加一个元素即可（这里用智谱免费层做演示，国内不会被地域墙）：

{
  "id": "opencode-zen/glm-5.3-flash-free",
  "name": "Magpie·OpenCode·GLM-5.3-Flash Free（免费）",
  "vendor": "Custom",
  "url": "http://127.0.0.1:3425/v1/chat/completions",
  "apiKey": "magpie",
  "supportsToolCall": true,
  "supportsImages": false,
  "supportsReasoning": true,
  "useCustomProtocol": false,
  "maxInputTokens": 32768,
  "maxOutputTokens": 8192
}

每个字段在说什么，对照下图逐个看一遍就懂：

上面是字段讲解图；这段 JSON 在本机 ~/.workbuddy/models.json 里真实存在，原有 10 个模型一个没动、仅末尾追加，Magpie 应用里的"已接入"实拍图（见第四步验收）就是接入后的效果。

三个字段最关键：url 指向 Magpie 网关的 OpenAI 协议端点（就是 0x04 验证过的那个地址）；apiKey 按网关启动时的提示填 magpie------网关只认本机流量，这个 key 随便填什么都能过；id 必须严格等于 magpie models 里列出的名字（这里是 opencode-zen/glm-5.3-flash-free，不要自作主张加 magpie/ 前缀------实测带前缀 Magpie 会报"不认识这个模型"，WorkBuddy 就调不通）。

第四步：验收

JSON 改完先别急着重启，终端里直接问网关要这个模型，确认链路通到 OpenCode：

curl -s -o /dev/null -w "%{http_code}" -X POST http://127.0.0.1:3425/v1/chat/completions \
  -H "Content-Type: application/json" -H "Authorization: Bearer magpie" \
  -d '{"model":"opencode-zen/glm-5.3-flash-free","messages":[{"role":"user","content":"ping"}],"max_tokens":8}'

• 在干净的本机宽带 IP 上：实测返回 HTTP 200，模型正常应答。
• 在被 OpenCode 标记为滥用的共享 IP / VPN / 代理 上：会返回 OpenCode Zen: OpenCode's free models aren't available from your current network...（HTTP 403）。这不是你配错了，是 OpenCode 免费层的 IP 风控------关掉 VPN/代理重试，或改用 OpenCode Go 付费层即可。

无论哪种情况，请求都确实路由到了 OpenCode Zen（报错方是 OpenCode 而非 Magpie），说明 Magpie↔OpenCode↔WorkBuddy 这条路是通的。WorkBuddy 侧只需重启应用（或开新会话）让模型清单重载，下拉里就能看到"Magpie·OpenCode·GLM-5.3-Flash Free（免费）"，选中即对话。

Magpie 应用里也能直接看到接入结果：WorkBuddy 显示"已接入"，模型菜单里有 40 个模型，其中 OpenCode Zen 22 个；应用里还能直接给 WorkBuddy 选默认模型，改动落的就是 ~/.workbuddy/models.json 这一个文件，想撤了点"断开并还原"即可（本机实拍）：

本机真实验收 ：同一个网关端点，换成 opencode-zen/nemotron-3.5-lightning-free 实测返回 HTTP 200，并拿到了模型真实回复与用量统计------也就是说，"WorkBuddy 经 Magpie 用上 OpenCode 免费模型" 这条链路在本机已经端到端跑通：

$ magpie providers
  Ollama        ollama        localhost:11434   ○ switched off   8 of 8 models
  OpenCode Zen  opencode-zen  opencode.ai       ● ••••••         24 of 85 models   ← 免费层已开启，无需 key
  OpenCode Go   opencode-go   opencode.ai       ● oc_s...LrUJ      1 of 37 models
  Codex         codex         chatgpt.com       ○ switched off   7 of 7 models
  ZCode         zcode         zcode.z.ai        ○ switched off   4 of 4 models
  WorkBuddy     workbuddy     ...                ● signed in      5 of 20 models
  WorkBuddy AI  workbuddy-ai  ...                ● signed in      6 of 28 models

$ curl -s -o /dev/null -w "%{http_code}" -X POST http://127.0.0.1:3425/v1/chat/completions \
    -H "Content-Type: application/json" -H "Authorization: Bearer magpie" \
    -d '{"model":"opencode-zen/nemotron-3.5-lightning-free","messages":[{"role":"user","content":"用一句话说明你是谁"}],"max_tokens":40}'
HTTP 200        # 模型真实回复："我是Nemotron，由NVIDIA的研究人员训..."

补充实测细节（避免你遇到同样的问题） ：免费层有"每模型"限流，短时间连打会先吃到 429 Rate limit（等一会或换同目录里另一个 flash-free 模型即可）；beam-free 因官方排除中国区会直接 403。这两种都不是配置错误，链路本身是通的。

改完的 models.json 只是多了一个元素，原有的一个没动------和 0x02 说的"安装不等于接管"一脉相承：不想要了，删掉这段 JSON 就回原样。

补：Qoder 也能挂上这条网关

接 WorkBuddy 靠的是改 models.json，因为 Magpie 能一键接管它。Qoder 不在接管名单里------magpie presets 没有 qoder 预设，它自带的免费额度也只在自己的 IDE 里消耗。但这不等于 Qoder 用不了网关：Qoder 支持自定义 OpenAI Compatible 供应商，把接口地址指到 Magpie，一样能挂上来。本机已实测跑通，添加自定义模型时四个字段这样填：

两个细节值得交代。其一，Qoder 会对 HTTP 地址提示"数据明文传输"的风险------这台网关只监听 127.0.0.1 回环，数据不出本机，可以放心继续；API Key 一栏留空也能保存，因为网关不校验 key（0x04 讲过原理）。其二，Model ID 填的不是某个具体模型，而是 Magpie 的路由组 group/myfree：先在 Magpie 里把若干模型收进一个组（magpie group add 一条命令，或在应用的"路由"页配置），对外的模型 ID 就是 group/组名，组内怎么路由由 Magpie 决定，Qoder 只认这一个名字。保存后，Qoder 的模型列表里就能看到它，选中即用：

这一段的价值不止在 Qoder：任何支持自定义 OpenAI Compatible 供应商的工具，都能用同一套写法挂到 Magpie 网关上 ------Base URL 填 http://127.0.0.1:3425/v1，key 随便填，模型 ID 用 Magpie 里的名字（单个模型用 provider/model，模型组合用 group/组名）。Magpie 能"接管"的 Agent 有名单，网关本身没有。

0x07 常用命令速查表

这些都是 magpie --help 在本机实跑列出来的，按用途分组：

0xFF 总结

把这一整套流程串起来，Magpie 上手的路径其实很短：

magpie save 装机前              # 1. 先存快照
magpie provider add ollama      # 2. 接一个不要钱的本地模型
magpie serve                    # 3. 起网关
curl http://127.0.0.1:3425/v1/models -H "Authorization: Bearer magpie"   # 4. 确认它在应答
magpie <agent> <model>          # 5. 给 Agent 换模型，开新会话

本文验证了四件事，都有实跑输出为证：安装只落地两个文件、不动任何已有 Agent 配置；本地 Ollama 一条命令接进来，8 个模型直接可用；本机 Ollama 里的本地模型被 OpenAI 与 Anthropic 两种协议各问一次，两次都是 HTTP 200，返回结构各自符合对应方言；WorkBuddy 经 Magpie 网关用上 OpenCode 免费模型，端到端拿到 HTTP 200。

要提醒的是边界：v0.1.1297 的版本号说明它还在高速迭代（上篇提过 11 天走了 540 个版本号），今天能用的组合明天细节可能变；自动接管登录态、自动把账号迁移到插件这类"替你做决定"的行为，第一次用最好先 magpie ls 看清楚、magpie save 存好快照再往下走。

推荐的上手顺序就是本文这个顺序：先本地、后付费；先看清单、后改配置；先存快照、再谈接管。 全篇零花费跑通，这条路径谁都能走一遍。

转载声明 ：本文为博主原创内容，转载请注明出处。文中命令输出均为 2026-10-21 至 22 在 Apple M1 Max（macOS）上以 Magpie v0.1.1297 实跑所得；标注"据官方文档"的部分来自项目 docs/reference.md 的 "As a background service" 一节，本机未执行。

邵奈一 三百篇原创沉淀，十万+读者同行。感谢你的阅读，评论区见。

---