文档 · 指南

让 AstrBot 用任意模型

AstrBot（AstrBotDevs/AstrBot）是一个聊天机器人框架，把大模型接到 QQ、Telegram、Discord、飞书等平台。它的所有设置都在一个文件里：data/cmd_config.json。magpie 在这里加一个 OpenAI 兼容的 magpie 模型源，为 magpie 里的每个模型加一项，并把你选的那个设为 AstrBot 的默认对话模型。于是你的机器人能用 magpie 里的任何模型：DeepSeek、GLM、Kimi、Qwen、OpenAI 或 Anthropic Key，或 ChatGPT、Copilot 订阅，不用在 AstrBot 的 WebUI 里一个个填 Key。

接入 AstrBot

  1. 先启动一次 AstrBotAstrBot 第一次启动时写出 data/cmd_config.json。需要 4.10 或更新的版本（有 provider_sources 的那种配置）。
  2. 在 magpie 里添加供应商在 供应商 页添加 API Key，或登录一个订阅。
  3. 在 AstrBot 那一行选模型在 Agent 页给 AstrBot 选一个 magpie 模型。
  4. 重启 AstrBotAstrBot 只在启动时读配置，重启后机器人就用上新模型。
终端
magpie astrbot deepseek/deepseek-v4-pro
# 然后重启 AstrBot

magpie 按这个顺序找 AstrBot 的根目录：环境变量 ASTRBOT_ROOT；桌面版的 ~/.astrbot；你在主目录、~/astrbot 或 ~/AstrBot 里运行过 astrbot init（README 和源码克隆默认放在那里）。AstrBot 在别的文件夹里运行时，用 ASTRBOT_ROOT 指向它再启动 magpie。

cmd_config.json 里写了什么

从 4.10 起，AstrBot 把一个对话供应商拆成两张表：provider_sources 是端点和 Key，provider 里每一项是某个源的一个模型。magpie 加一个 id 为 magpie 的源（OpenAI Compatible，指向网关的 /v1，带一个标明 AstrBot 的 Key，所以它的请求在 magpie 的用量里算在 AstrBot 名下），再为每个模型加一项 magpie/<供应商>/<模型>，并把 agent_runner.config.model.provider_id 设为你选的那个（更早的配置文件里是 provider_settings.default_provider_id）。

终端
// /data/cmd_config.json
{
  "provider_sources": [
    …,
    {"id": "magpie", "provider": "openai", "type": "openai_chat_completion",
     "provider_type": "chat_completion", "enable": true,
     "key": ["…"], "api_base": "http://127.0.0.1:3425/v1", …}
  ],
  "provider": [
    …,
    {"id": "magpie/deepseek/deepseek-v4-pro", "provider_source_id": "magpie",
     "model": "deepseek/deepseek-v4-pro",
     "modalities": ["text", "tool_use"], "max_context_tokens": …}
  ],
  "agent_runner": {"runner_type": "local",
    "config": {"model": {"provider_id": "magpie/deepseek/deepseek-v4-pro"}}}
}

每个模型都标了 tool_use：没有它，AstrBot 会把工具调用去掉，而网关不管哪个模型都能转发工具调用。图片按 magpie 知道的这个模型能不能看图来标。magpie 不知道上下文窗口时写 0，AstrBot 会自己去查。

为什么要重启

AstrBot 启动时把整个文件读进内存，之后它的 WebUI 每次保存设置都会把整个文件写回去。所以 magpie 改完要重启 AstrBot；如果在重启之前在 WebUI 里保存了任何设置，就会盖掉 magpie 的改动。magpie 的检查会发现 magpie 的源不见了，提示你重新接入。

agent_runner.runner_type 不是 local 时（交给外部的 Agent 运行器），AstrBot 不问它的对话模型，magpie 的检查也会说出来。

你自己的设置

magpie 第一次写之前，把文件复制为 cmd_config.json.before-magpie。你自己的源和模型逐字节不动；你在 WebUI 里对 magpie 那几项的修改（源的 timeout 或 proxy、关掉某个模型、它的 extra body）也会保留。你用 /provider 给某个会话单独选的模型存在 AstrBot 自己的数据库里，那是你的，不受影响。AstrBot 写文件带 UTF-8 BOM，magpie 也保留它。

Docker 里的 AstrBot

Docker 里的 AstrBot 不是 magpie 能接的：它的 data 目录是一个 magpie 不知道的卷，而且本机回环地址上的网关不是容器里的回环地址。

切回

在 magpie 里把那一行切回默认，magpie 拿掉 magpie 的源和模型，并把默认对话模型还原成接入前的那个；如果你之后在 AstrBot 里自己换过默认模型，就保持你的选择。也可以直接选一个你自己的模型，magpie 的模型先留在列表里，直到断开。改完同样要重启 AstrBot。

终端
magpie astrbot default
# 然后重启 AstrBot

常见问题

AstrBot 能用 DeepSeek、GLM、Kimi 或 Qwen 吗？

能。magpie 在 cmd_config.json 里加一个 OpenAI 兼容的 magpie 源，为 magpie 里的每个模型加一项，并把你选的那个设为默认对话模型。重启 AstrBot 后生效。

为什么换了模型机器人还在用旧的？

AstrBot 只在启动时读 cmd_config.json，重启 AstrBot 即可。重启前别在 WebUI 里保存设置，否则会盖掉 magpie 的改动。

magpie 的源不见了怎么办？

多半是 AstrBot 的 WebUI 保存时把整个文件写了回去。在 magpie 里重新接入一次，然后重启 AstrBot。

Docker 部署的 AstrBot 能用吗？

magpie 不会自动接：它不知道容器的数据卷，本机的回环地址也不是容器的。

更多 Agent 用同样的模型：让 nanobot 用任意模型、让 QwenPaw 用任意模型、让 OpenClaw 用任意模型、通过 magpie 在 Cherry Studio 里用所有模型。遇到报错？见 常见错误排查，或到 Discord 提问。