Llama Hot Swap

mcp-llama-swap

在正在运行的 Claude Code 会话中热切换 llama.cpp 模型。上下文不丢失。一条命令即可完成。

使用推理模型进行规划，再用编码模型实现。相同的会话、相同的上下文，无需手动操作。

支持 macOS（launchctl）和 Linux（systemd）。

为什么选择它

运行本地 LLM 意味着必须在强大的推理模型和快速的编码模型之间做出选择。你无法在一台机器上同时加载两者。手动切换模型会破坏对话上下文和工作流程。

mcp-llama-swap 通过为 Claude Code 提供一个工具来解决这个问题：它通过系统的服务管理器（macOS 上为 launchctl，Linux 上为 systemd）切换 llama-server 背后的模型，同时在客户端保留完整的对话历史。

快速开始

安装

# Option A: Run directly with uvx (no install needed)
uvx mcp-llama-swap

# Option B: Install from PyPI
pip install mcp-llama-swap

配置 Claude Code

添加到 ~/.claude.json：

{
  "mcpServers": {
    "llama-swap": {
      "command": "uvx",
      "args": ["mcp-llama-swap"],
      "env": {
        "LLAMA_SWAP_CONFIG": "/path/to/config.json"
      }
    }
  }
}

配置模型

创建 config.json（macOS）：

{
  "plists_dir": "~/.llama-plists",
  "health_url": "http://localhost:8000/health",
  "health_timeout": 30,
  "models": {
    "planner": "qwen35-thinking.plist",
    "coder": "qwen3-coder.plist",
    "fast": "glm-flash.plist"
  }
}

或者在 Linux 上：

{
  "services_dir": "~/.llama-services",
  "health_url": "http://localhost:8000/health",
  "health_timeout": 30,
  "models": {
    "planner": "llama-server-planner.service",
    "coder": "llama-server-coder.service"
  }
}

使用

在 Claude Code 中：

You: list models
You: swap to planner
You: <discuss architecture, define interfaces>
You: swap to coder and implement the plan

就是这样。切换模型后，上下文仍会保留。

你也可以直接生成新的模型配置：

You: create a model config named "reasoning" for /models/qwen3-30b.gguf with 8192 context

工作原理

Claude Code CLI
    |
    | Anthropic Messages API
    v
LiteLLM Proxy (:4000)         <-- translates Anthropic -> OpenAI format
    |
    | OpenAI Chat Completions API
    v
llama-server (:8000)          <-- model weights swapped via service manager
    ^
    |
mcp-llama-swap                <-- this project (launchctl or systemd)

Claude Code 使用 Anthropic 格式。LiteLLM 会将其转换为 llama-server 使用的 OpenAI 格式。此 MCP 服务通过 launchctl（macOS）或 systemd（Linux）管理加载的模型服务。

切换模型后，对话上下文仍会保留，因为 Claude Code 会在客户端保存完整的消息历史，并在每次请求时重新发送。

模型配置

映射模式（推荐）

为模型定义别名。只有已映射的模型可用。目录中的其他服务配置会被忽略。

macOS：

{
  "plists_dir": "~/.llama-plists",
  "health_url": "http://localhost:8000/health",
  "health_timeout": 30,
  "models": {
    "planner": "qwen35-35b-a3b-thinking.plist",
    "coder": "qwen3-coder.plist",
    "fast": "glm-4-7-flash.plist"
  }
}

Linux：

{
  "services_dir": "~/.llama-services",
  "health_url": "http://localhost:8000/health",
  "health_timeout": 30,
  "models": {
    "planner": "llama-server-planner.service",
    "coder": "llama-server-coder.service"
  }
}

使用别名切换模型，例如：“切换到 coder”“切换到 planner”。

目录模式

将 "models": {} 设置为自动发现所有服务配置。文件名（不含扩展名）将成为别名。

macOS：

{
  "plists_dir": "~/.llama-plists",
  "models": {}
}

Linux：

{
  "services_dir": "~/.llama-services",
  "models": {}
}

MCP 工具

工具	描述
list_models	列出所有已配置的模型、加载状态和当前模式
get_current_model	返回当前已加载模型的别名
swap_model	卸载当前模型，加载指定模型，并等待健康检查
create_model_config	为模型生成新的 launchd plist（macOS）或 systemd unit（Linux）

MCP 资源

资源	描述
llama-swap://config	当前配置的 JSON 格式
llama-swap://status	当前模型状态、健康状况和平台信息

MCP 提示词

提示词	描述
swap-workflow	引导式“先规划、后实现”工作流模板

完整设置指南

前置条件

• 安装了 launchctl 的 macOS，或安装了 systemd 的 Linux
• 已安装 llama-server（llama.cpp）
• 模型配置为服务文件（launchd plists 或 systemd units）
• Python 3.10+
• Claude Code CLI 已指向 LiteLLM 代理

1. 安装 mcp-llama-swap

pip install mcp-llama-swap

2. 安装并启动 LiteLLM 代理

pip install litellm

创建 litellm_config.yaml：

model_list:
  - model_name: "*"
    litellm_params:
      model: "openai/*"
      api_base: "http://localhost:8000/v1"
      api_key: "sk-none"

litellm_settings:
  drop_params: true
  request_timeout: 300

启动它：

litellm --config litellm_config.yaml --port 4000

在 macOS 上，你可以使用随附的 ai.litellm.proxy.plist.template 将其作为持久运行的 launchd 服务（参见 setup.sh）。

3. 将 Claude Code 指向 LiteLLM

添加到 ~/.zshrc（macOS）或 ~/.bashrc（Linux）：

export ANTHROPIC_BASE_URL="http://localhost:4000"
export ANTHROPIC_API_KEY="sk-none"
export ANTHROPIC_MODEL="local"

4. 将 MCP 服务添加到 Claude Code

添加到 ~/.claude.json：

{
  "mcpServers": {
    "llama-swap": {
      "command": "uvx",
      "args": ["mcp-llama-swap"],
      "env": {
        "LLAMA_SWAP_CONFIG": "/absolute/path/to/config.json"
      }
    }
  }
}

5. 创建你的 config.json

复制 config.example.json（macOS）或 config.example.linux.json（Linux），并编辑模型别名和服务文件名。

6. 创建模型服务配置

你可以手动创建服务配置，也可以在 Claude Code 中使用 create_model_config MCP 工具：

You: create a model config named "coder" for /path/to/model.gguf with 8192 context

此工具会在你的服务目录中生成相应的 launchd plist（macOS）或 systemd unit 文件（Linux）。

自动设置（macOS）

如果你想在 macOS 上一键完成设置，请克隆此仓库并运行：

git clone https://github.com/oussama-kh/mcp-llama-swap.git ~/mcp-llama-swap
cd ~/mcp-llama-swap
chmod +x setup.sh
./setup.sh

该脚本会创建虚拟环境、安装依赖、配置 LiteLLM launchd 服务，并打印需要添加的确切配置。

配置参考

config.json 字段：

字段	默认值	说明
services_dir	~/.llama-plists（macOS）/ ~/.llama-services（Linux）	包含模型服务配置的目录
plists_dir	—	services_dir 的 macOS 别名（向后兼容）
units_dir	—	services_dir 的 Linux 别名
health_url	http://localhost:8000/health	llama-server 健康检查端点
health_timeout	30	加载后等待健康检查的秒数
models	{}	别名到文件名的映射。留空 = 目录模式
platform	auto	服务管理器：auto、launchctl 或 systemd
launchctl_mode	legacy	仅限 macOS：legacy（load/unload）或 modern（bootstrap/bootout）

通过 LLAMA_SWAP_CONFIG 环境变量覆盖配置路径。

平台详情

macOS（launchctl）

模型通过 plist 文件作为 launchd 服务进行管理。launchctl 提供两种模式：

• Legacy（默认）：使用 launchctl load/unload/list。适用于所有 macOS 版本。
• Modern：使用 launchctl bootstrap/bootout/print。这是较新 macOS 上官方支持的 API。在配置中设置 "launchctl_mode": "modern" 即可启用。

Linux（systemd）

模型作为 systemd 用户服务进行管理。services_dir 中的 unit 文件会被符号链接到 ~/.config/systemd/user/，并通过 systemctl --user start/stop 进行管理。

故障排除

LiteLLM 翻译不正确： 检查 /tmp/litellm.stderr.log。确认 llama-server 正在运行：curl http://localhost:8000/health。

模型切换超时： 增大 config.json 中的 health_timeout。大型模型可能需要 30 秒以上才能将权重加载到内存中。

Claude Code 找不到 MCP 服务： 确认 LLAMA_SWAP_CONFIG 路径为绝对路径。直接测试：python -m mcp_llama_swap。

找不到映射的模型： models 中的服务文件名必须与服务目录中的实际文件名一致。

systemd 服务无法启动： 检查 journalctl --user -u llama-server-<name> 中的错误。确保 llama-server 位于 PATH 中。

launchctl modern 模式问题： 如果 bootstrap/bootout 命令失败，请在配置中改用 "launchctl_mode": "legacy"。

开发

# Install with test dependencies
pip install -e ".[test]"

# Run tests
pytest -v

使用场景

此项目可在本地硬件上实现完整的两阶段 AI 编码工作流：

1. 规划阶段： 加载推理模型（例如，启用思考模式的 Qwen3.5-35B-A3B）。讨论架构、定义接口、分解需求。
2. 实现阶段： 切换到编码模型（例如 Qwen3-Coder-30B）。保留规划阶段的完整对话上下文，逐个文件执行计划。

无需云端 API。数据不会离开你的设备。阶段之间不会丢失上下文。

许可证

Apache-2.0