localagents

把 Claude Code 的杂活交给运行在你自有硬件上的模型。

localagents 是一个 MCP 服务器，为 Claude Code 提供 run_agent 工具。每次调用都会启动一个完整的无头 Claude Code 会话——相同的工具、相同的 CLAUDE.md、相同的工作树——只不过它的 API 流量不是发往 Anthropic，而是发往你自行运行的 llama.cpp 或 vLLM 服务器。Claude 编写任务简报，本地模型执行工作，Claude 审查结果。你的 Anthropic token 预算只花在需要它的地方。

单块 GPU 上的 27B Qwen 完全能胜任“为这个模块添加 CLI 并配上相应测试”；Opus 更适合花在设计对话上，而不是盯着 pytest 运行。两个本地代理可以并行地针对一个固定的接口分别构建一个包的两半。

状态：早期。 它能用，我每天都在用，但接口会变动。它专门针对 llama.cpp 和 vLLM；Ollama 不是目标。

工作原理

Claude Code (your session)
   │  MCP: run_agent(task, model=...)
   ▼
localagents ── spawns ──▶ headless `claude` (Agent SDK)
   │                          │  ANTHROPIC_BASE_URL
   │                          ▼
   └──── in-process shim ◀────┘   normalises requests, logs them,
              │                   translates backend errors
              ▼
   llama-server / vllm   (/v1/messages, on your machine or your LAN)

有三件事让它不仅仅是一个环境变量：

1. 实时探测的注册表。 models.yaml 列出服务器所在位置和模型名称菜单。每次调用都会发现每台服务器当前实际提供什么、真实上下文窗口大小以及有多少个槽位被占用。你手动启动和停止模型——服务器从不启动任何东西——当 Claude 需要一个未运行的模型时，它会按名称向你请求。

2. Claude Code 与后端之间的垫片（shim）。 Claude Code 会发送本地聊天模板拒绝的内容，而本地服务器也会以 Claude Code 无法识别的方式失败。垫片对两个方向都做了修复（详见下文），并为每个任务写入一个 requests.jsonl，这样你就能确切看到线上传输了什么。

3. 与 Claude 自己的子代理相同的隔离模型。 默认情况下，任务在你的工作树中运行，就像 Agent 工具那样。isolation: worktree 会在 local-agent/<job> 分支上为它创建一个全新的 git worktree，并且仅当它修改了内容时才保留，同时在任务记录中附带 diffstat，以便 Claude 以 diff 形式审查。

Related MCP server: Ollama MCP Server

环境要求

• Python 3.12+ 和 uv

• Claude Code。Agent SDK 自带 claude 二进制文件，因此无需安装其他任何东西。

• 一个支持 Anthropic /v1/messages 接口的服务器：

  • llama.cpp llama-server — 用 --jinja 启动；加上 --slots --metrics 可在工具输出中获取占用率和缓存统计。

  • vLLM，带 --enable-auto-tool-choice --tool-call-parser <parser>。

• 一个能真正驱动 Claude Code 的模型：扎实的原生工具调用能力，以及每次请求 128k 或更大的上下文窗口。Qwen3.8-27B 表现良好。更小的窗口也能用，但会频繁压缩；参见上下文窗口。

安装

git clone https://github.com/ccebelenski/localagents.git && cd localagents
uv tool install -e .                  # `localagents` on PATH; editable, so repo edits apply
cp models.example.yaml models.yaml    # edit for your servers (gitignored)
claude mcp add --scope user local -- localagents --config "$PWD/models.yaml"

用户级作用域意味着每个项目都能获得 local 服务器。它会继承启动它的 Claude Code 会话的 cwd，因此 run_agent 默认使用该项目的目录树。项目可以自带 ./models.yaml 来覆盖注册表。

如果你希望只保留在一个项目中，请将其放入该项目的 .mcp.json：

{"mcpServers": {"local": {"command": "localagents", "args": ["--config", "/path/to/models.yaml"]}}}

添加后重启 Claude Code（或 /mcp → 重新连接）；MCP 服务器在启动时加载。

使用方法

Claude 会像使用任何工具一样使用它。按名称请求它，它就会做正确的事：

使用本地代理为 CLI 添加 --json 标志，并在测试中覆盖它。

Claude 在背后做的是：调用 list_models 查看当前状态，调用 run_agent(task=…) 获取任务 id，然后使用 wait_job / job_status / job_log 直到完成，接着读取 files_touched（或 worktree diff）并检查工作。超过 Claude Code 2 分钟工具超时时间的任务会被放到后台，稍后再拾取；你无需做任何事。

如果没有合适的模型在运行，你会被要求启动一个：

qwen3.8-27b 没有在任何地方运行。请让用户把它启动起来。 备注：llama.cpp 上的默认中型编码模型；使用 --reasoning on 运行

按你通常的方式启动它，说“已经启动了”，Claude 就会重试。

工具

任务记录存放在 ~/.local/state/localagents/jobs/<job>/：transcript.txt（代理说了什么、做了什么）、events.jsonl（每条 SDK 消息）、requests.jsonl（每个后端请求及其时序、大小和用量），如果你开启请求转储，还会有 requests_full.jsonl。

配置：models.yaml

从 models.example.yaml 开始。它会在每次调用时重新读取，因此编辑会立即生效，而且服务器从不重写它——register_* 写入一个边车文件 models.local.yaml，该文件会被合并覆盖在其上。

endpoints:
  llamacpp:
    base_url: http://127.0.0.1:8080
    backend: llama.cpp
  gpu-server:
    base_url: http://gpu-server.lan:8000
    backend: vllm
    host: gpu-server

models:
  qwen3.8-27b:
    notes: default mid-size coder on llama.cpp; run with --reasoning on
  deepseek-v4-flash:
    host: gpu-server
    notes: vllm needs --enable-auto-tool-choice --tool-call-parser deepseek_v3

• endpoints 是提供 /v1/messages 服务的位置。它们提供什么会被探测。

• models 只是名称。名称会与服务的 id 进行模糊匹配（qwen3.8-27b 能找到 unsloth/Qwen3.8-27B-GGUF:UD-Q4_K_XL），因此一个条目只需要 notes，也许还需要一个 host 用于在请求启动时转达。served_name（精确 id 或 glob）、endpoint、context（回退窗口）和 bring_up（启动命令）都可以作为覆盖项，如果你需要的话。启动命令很快就会过时；名称加备注通常更耐久。

• defaults 涵盖默认模型、permission_mode（acceptEdits）、允许和禁止的工具（子代理不能生成子代理）、要加载哪些 Claude 设置、max_turns、timeout_s，以及一个系统提示后缀，告诉代理它是被委派者以及如何汇报。

垫片的作用

llama.cpp 和 vLLM 都原生支持 /v1/messages，所以把 ANTHROPIC_BASE_URL 指向它们几乎就能工作。垫片弥补了这些差距：

对话中途的系统消息。 Claude Code 会在 messages 中放入 role: system 条目——技能列表、一个 token 预算标记，以及每轮一个。Qwen 的聊天模板会拒绝：“System message must be at the beginning”。垫片会将每一条就地折叠进相邻的用户消息，作为一个 <system>…</system> 文本块。如果改为把它们提升到顶层的 system 字段，每一轮都会改变提示词的开头，这会使服务器的 KV-cache 前缀失效，并每次重新评估整个约 35k token 的提示词（在 27B 上每轮 21–47 秒）。就地折叠则保持提示词只追加：llama-server 日志中 f_sim_best 为 0.88–0.99，每轮 2.5–14 秒。

上下文溢出。 Claude Code 对任何它不认识的模型都假定 200k 窗口；当槽位较小时，它会撞上 llama.cpp 的 exceed_context_size_error，而 Claude Code 无法理解这个错误，任务就会失败。参见下一节。

垫片所做的一切在不需要时都是空操作，而且每个请求都会被记录其时序、消息数量、字节大小和报告的用量。

上下文窗口

两层机制让会话保持在真实窗口之内：

1. 探测会读取它——llama.cpp 的 /props n_ctx（每个槽位：当统一 KV 关闭时，-c 除以 --parallel）、vLLM 的 max_model_len——然后会话会获得 CLAUDE_CODE_MAX_CONTEXT_TOKENS。Claude Code 自己的自动压缩随后会在正确的时机触发。低于 128k 时，输出预算也会缩小到 n_ctx/8，因为压缩阈值是 window − max_output，否则它会停留在零。

2. 如果请求仍然溢出，垫片会将后端的错误改写为 Anthropic 的 prompt is too long: N tokens > M maximum，Claude Code 会通过压缩并重试来应对。

在 64k 下这能用，但会剧烈抖动：Claude Code 约 20k 的固定提示词和工具模式，加上约 7k token 的压缩摘要（在 27B 上约 55 秒）以及它重新附加的文件，会在几轮内重新填满窗口，然后它的抖动保护会结束任务。给每个槽位 128k 或更多。

后端说明

• llama.cpp：llama-server -hf <gguf> --jinja -fa on --slots --metrics，再加上 --reasoning on 用于思考模型，--parallel N 用于并发任务。开启 /slots 后，list_models 会显示 {total, busy, free}，这样 Claude 就能知道第二个代理是会立即运行还是排队。开启 /metrics 后，每个任务都会记录已处理与已缓存的提示词 token、缓存命中率、提示词和生成的 tok/s，以及投机解码接受率——这些计数器是服务器级的，因此重叠的任务会共享增量。

• vLLM：vllm serve <model> --served-model-name <alias> --enable-auto-tool-choice --tool-call-parser <parser>。上下文窗口来自 /v1/models 中的 max_model_len；占用率（requests_running/waiting、kv_cache_usage）和每个任务的缓存统计来自其始终开启的 /metrics。vLLM 在 Anthropic 端点上将上下文溢出报告为 HTTP 500 internal_error；垫片也会转换这个错误。会话以 CLAUDE_CODE_ATTRIBUTION_HEADER=0 启动，因为每个请求的归因哈希会破坏前缀缓存。已用 DeepSeek-V4-Flash 验证：思考块会连同其签名一起重放，从第二轮开始每一轮都命中前缀缓存。

• 任务的第一个回合在冷槽位上大约消耗 20k token 的提示词（系统提示词加工具模式），在 27B 上约 10 秒。之后的一切都是缓存命中加上增量。

开发

uv sync --dev
uv run pytest -q

参见 CONTRIBUTING.md 了解项目结构以及如何针对真实服务器测试改动。

许可证

MIT。参见 LICENSE。

Copyright © 2026 Chris Cebelenski